Partager via

Using the Application Setting Manager Interfaces

  • Article

The Application Setting Manager exposes two interfaces that you can use in your SharePoint applications to store and retrieve configuration data:

  • IHierarchicalConfig. Implementations of this interface allow you to retrieve configuration setting data, regardless of the location of that data in the SharePoint hierarchy. By default, this interface is implemented by the HierarchicalConfig class.
  • IConfigManager. Implementations of this interface allow you to store, update, and delete configuration data. You can also retrieve settings from specific levels in the SharePoint hierarchy. By default, this interface is implemented by the ConfigManager class.

To use these interfaces and their default implementations in your solutions, add a reference to the Microsoft.Practices.SharePoint.Common.dll assembly and the Microsoft.Practices.ServiceLocation.dll assembly.

Using the IHierarchicalConfig Interface

Implementations of the IHierarchicalConfig interface retrieve application configuration settings from a hierarchical structure of storage, starting at the SPWeb level and culminating at the SPFarm level. The default implementation of the IHierarchicalConfig interface—the HierarchicalConfig class—can retrieve and build up this hierarchical storage structure in two ways.

  • By default, the HierarchicalConfig class uses the SPContext.Current property to retrieve the current SPWeb object. The remaining hierarchy structure—the local SPSite, SPWebApplication, and SPFarm objects—can be inferred from the SPWeb object.
  • Alternatively, the HierarchicalConfig class includes a method named SetWeb that you can use to specify an SPWeb object for the hierarchy structure. The HierarchicalConfig class then builds a hierarchical structure from the SPWeb object you provided. This approach is useful if a SharePoint context is unavailable or if you want to read from a hierarchy that differs from your current SharePoint context.

Note

If you do not specify an SPWeb object, and the HierarchicalConfig class is unable to retrieve a valid SharePoint context, calls to the IHierarchicalConfig interface will throw an exception.

You can also create an instance of the HierarchicalConfig and provide an SPWeb object as an argument to the constructor. You should use this approach or the SetWeb method in command-line applications, feature receivers, and test classes where the SharePoint context is unavailable.

When you use the HierarchicalConfig class to retrieve a configuration setting—regardless of how you instantiated it—the class first looks for the specified setting in the property bag of the SPWeb object. If it finds the setting at the SPWeb level, it uses it and stops searching. If a setting is not found at the SPWeb level, it next looks for the setting at the site collection level. If the setting is not found at the site collection level, it looks in the current SPWebApplication object, and then it looks in the current SPFarm object. For example, you could use the following code to retrieve a string-based configuration setting, regardless of the level in the SharePoint hierarchy at which it is stored.

using Microsoft.Practices.ServiceLocation;            
using Microsoft.Practices.SharePoint.Common.Configuration;
using Microsoft.Practices.SharePoint.Common.ServiceLocation;

IServiceLocator serviceLocator = SharePointServiceLocator.GetCurrent();
var config = serviceLocator.GetInstance<IHierarchicalConfig>();

string myValue;
if (config.ContainsKey("testKey"))
   myValue = config.GetByKey<string>("testKey");

As described earlier, if you are retrieving configuration settings when the context is not available, you must first provide an SPWeb object to the HierarchicalConfig class. The following example shows how to provide an SPWeb object from the properties passed into an event receiver. This must be done prior to retrieving a value from configuration; otherwise, the class will throw a NoSharePointContextException.

var config = serviceLocator.GetInstance<IHierarchicalConfig>();
config.SetWeb(properties.Web);

For more information about how to use the IHierarchicalConfig interface, see Retrieving Configuration Settings.

Using the IConfigManager Interface

The IConfigManager interface reads and writes configuration settings at specific locations in the hierarchy. Unlike the IHierarchicalConfig interface, the methods in this interface do not traverse the hierarchy—instead, you specify the level of the hierarchy that you want to work with.

By default, the IConfigManager interface is implemented by the ConfigManager class. Like the HierarchicalConfig class, you can provide context for the ConfigManager class in three ways:

  • You can allow the ConfigManager class to build the hierarchical storage structure from the SPContext.Current property.
  • You can call the ConfigManager.SetWeb method to provide the ConfigManager class with the starting point for the storage hierarchy.
  • You can manually instantiate the ConfigManager class and provide an SPWeb object as an argument to the constructor.

You should use one of the latter two approaches when your code runs outside the SharePoint context, such as in command-line applications, feature receivers, and test classes.

The Application Setting Manager stores application settings in purpose-built property bags. When you use the ConfigManager class to read or write application settings, you must first call the GetPropertyBag method to obtain an IPropertyBag instance from the current configuration hierarchy. This method accepts an argument of type ConfigLevel, which provides an enumeration of storage levels.

After you have a property bag instance, you can store application settings by providing the ConfigManager instance with a key, a value, and the target property bag. The key must be a string. The value can be any object that can be serialized to XML. The following example shows how to use the ConfigManager class without a SharePoint context.

using Microsoft.Practices.ServiceLocation;            
using Microsoft.Practices.SharePoint.Common.Configuration;
using Microsoft.Practices.SharePoint.Common.ServiceLocation;

IServiceLocator serviceLocator = SharePointServiceLocator.GetCurrent();
IConfigManager configManager = serviceLocator.GetInstance<IConfigManager>();

// Retrieve a site collection by URL.
using(SPSite site = new SPSite("http://intranet.contoso.com/sites/testzone"))
{
  // Store a configuration setting at the site collection level.

  configManager.SetWeb(site.RootWeb);
  IPropertyBag bag = configManager.GetPropertyBag(ConfigLevel.CurrentSPSite);
  configManager.SetInPropertyBag("testKey", "Test Value", bag);
}

Note

Under some circumstances, the GetPropertyBag method may throw an exception. For example, if you attempt to retrieve a farm-level property bag from a sandboxed solution, the method will throw a ConfigurationException because you are not permitted to access farm-level configuration settings from the sandbox.

You can also use IConfigManager to retrieve configuration settings from specific levels in the SharePoint hierarchy. This can be useful if you need to retrieve configuration settings in scenarios where the SharePoint context is unavailable, or if you need to retrieve settings from Web applications, site collections, or sites that are not in the current context.

For more information about how to use the IConfigManager interface, see Adding and Updating Configuration Settings and Removing Configuration Settings.