Partager via

Using the Application Setting Manager in Sandboxed Solutions

  • Article

In many SharePoint 2010 development scenarios, you will need to create solutions that run in the sandbox environment. This places certain limitations on how you can use the Application Setting Manager. This topic identifies these limitations and describes the actions you can take to mitigate them.

The security restrictions on the sandbox environment prevent sandboxed code from reading or writing configuration data at the Web application level or the farm level, and the Application Setting Manager is no exception. The Application Setting Manager will automatically detect whether it is running in the sandbox. If this is the case, it builds a reduced storage hierarchy that consists of the current SPWeb object and the current SPSite object. The HierarchicalConfig class will not search for settings beyond the SPSite level, and the ConfigManager class will not permit you to store settings beyond the SPSite level—any attempts to retrieve a Web application–scoped or farm-scoped property bag will return null.

Reading Farm-Level and Web Application-Level Configuration Data

The Application Setting Manager includes various full-trust proxies that allow you to read farm-level and Web application–level application settings from a sandboxed solution. These full-trust proxies will only allow you to retrieve settings that are managed by the Application Setting Manager, in order to avoid subverting the security restrictions of the sandbox environment. Furthermore, the proxies do not allow you to write any settings to Web application–level or farm-level storage.

The project Microsoft.Practices.SharePoint.Common.ConfigProxy defines the following full-trust proxy classes:

  • ContainsKeyOperation. This proxy allows you to check for a Web application or farm-scoped configuration setting from sandboxed code.
  • ReadConfigurationOperation. This proxy allows you to retrieve a Web application or farm-scoped configuration setting from sandboxed code.

The ConfigProxy project is scoped as a farm solution. If you deploy this solution to your server farm, both proxies are made available to the sandbox environment. The Application Setting Manager automatically detects whether the proxy is installed and will use it when appropriate—you can use the same code to interact with application settings that you would use in the full-trust environment.

Note

The SharePoint Guidance Library includes a static utility method, SharePointEnvironment.CanAccessFarmConfig, which you can use to determine whether your code has access to Web application–level or farm-level application settings.

Storing Complex Types from Sandboxed Solutions

The Application Setting Manager uses different techniques to store different types of data:

  • Simple types, such as strings, enumerations, and primitive values, are converted to strings if required and stored directly in the relevant property bag.
  • More complex types are serialized and stored as XML in the relevant property bag.

This can create difficulties when you attempt to store complex types from the sandbox environment. The Application Setting Manager uses the XmlSerializer class to serialize and deserialize complex types. By default, the XMLSerializer class dynamically generates assemblies to serialize and deserialize these types. When this occurs during sandbox execution, an error is raised because writing files and running the compiler is prohibited in the sandbox environment.

To work around this problem in the sandbox environment, you can configure your projects to automatically pre-generate serialization assemblies for specific types when the project builds. You can use the following procedure to pre-generate serialization assemblies for a Visual Studio 2010 project.

To pre-generate serialization assemblies

  1. In Visual Studio 2010, in Solution Explorer, right-click the project for which you want to generate serialization assemblies, and then click Unload Project.

  2. In Solution Explorer, right-click the project for which you want to generate serialization assemblies, and then click Edit <Project Name>.csproj.

  3. In the <Project Name>.csproj file, immediately after the <TargetFrameworkVersion>v3.5</TargetFrameworkVersion> element, add the following element.

    <SGenUseProxyTypes>false</SGenUseProxyTypes>

  4. Save and close the <Project Name>.csproj file.

  5. In Solution Explorer, right-click the project for which you want to generate serialization assemblies, and then click Reload Project.

  6. Open the properties page for the project, and then click the Build tab.

  7. In the Generate serialization assembly drop-down list box, click On.

This procedure generates an additional assembly named <Project Name>.xmlSerializers.dll in your bin\debug folder. You will need to deploy this assembly with your solution.

Occasionally, you may need to constrain the types that are added to the serialization assembly. This should only be necessary for assemblies that run both in full trust and in the sandbox and for assemblies that use types that are not permitted in the sandbox. If you include types in the serialization assembly that are not permitted in the sandbox environment, an exception will occur in the sandbox when the assembly is loaded.

To constrain the types that are added to the serialization assembly, add an SGenSerializationTypes element to the PropertyGroup node in your .csproj file. For example, the Microsoft.Practices.SharePoint.Common project includes the following element, which specifies that a serialization assembly is only pre-generated for the ServiceLocationConfigData type.

<SGenSerializationTypes>
  Microsoft.Practices.SharePoint.Common.ServiceLocation.ServiceLocationConfigData
</SGenSerializationTypes>

To add multiple entries to the SGenSerializationTypes element, use semicolons to delineate your type names.

Note

If you are deploying your assembly to the global assembly cache, you must first remove any existing versions of your assembly and the pre-generated serialization assembly from the global assembly cache in a pre-build step. If you do not remove the assemblies, the serialization assembly will be generated to your project directory instead of to the bin\debug folder, and subsequent compiles will fail.

Assembly Deployment

To use the Application Setting Manager in a sandboxed solution, you will need to deploy the following SharePoint Guidance Library assemblies within your sandboxed solution package (assuming that they have not already been deployed to the global assembly cache):

  • Microsoft.Practices.SharePoint.Common.dll
  • Microsoft.Practices.SharePoint.Common.XmlSerializers.dll
  • Microsoft.Practices.ServiceLocation.dll

If you pre-generated XML serialization assemblies for your own projects, be sure to deploy the <Project Name>.XmlSerializers.dll assembly with your solution. To deploy the assemblies with your project, click the Package node in your project, click the Advanced tab, click Add, and then click Add Existing Assembly. Select the deploy target as the global assembly cache (even though the assemblies won't actually be deployed there for a sandboxed solution).