What Does the Application Setting Manager Do?

The Application Setting Manager is a set of utility classes that you can use to store and retrieve configuration settings for your SharePoint applications. The Application Setting Manager provides a uniform, type-safe approach for managing configuration settings at the following levels of the SharePoint hierarchy:

• Farm (SPFarm class)
• Web application (SPWebApplication class)
• Site collection (SPSite class)
• Site (SPWeb class)

You can use the Application Setting Manager to store simple types, such as integers or strings, as well as more complex types that can be serialized to XML. The Application Setting Manager manages the serialization and deserialization of data types to and from XML.

The Application Setting Manager provides a hierarchical model for the storage and retrieval of configuration settings. This enables you to create an application setting at a broad scope (such as the farm level) and override that setting at a narrower scope (such as the site level). When you retrieve a setting, using a key string, the Application Setting Manager will first look for that key at the site (SPWeb) level of the current execution context. If the configuration key is not found, the Application Setting Manager will look for the configuration setting at a progressively broader scope, up to and including the farm level. For example, you could use the following code to locate a configuration setting of type DateTime, without knowing the level in the SharePoint hierarchy at which the setting is stored.

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

DateTime timeApproved;
if (config.ContainsKey("approvedTime"))
   timeApproved = config.GetByKey<DateTime>("approvedTime");

Note

As illustrated by the code example, you are encouraged to use the SharePoint Service Locator to retrieve and instantiate instances of the interfaces provided by the Application Setting Manager. For more information about the SharePoint Service Locator, see The SharePoint Service Locator.

Understanding the SharePoint Hierarchy

All the components of the Application Setting Manager rely on building a hierarchy of SharePoint objects, from SPWeb to SPFarm, in which to store and retrieve application settings. For example, if you tell the Application Setting Manager to store an application setting at the site collection level, it needs to know which site collection is relevant to your solution. In most cases, the key element of this hierarchy is the SPWeb object—if you provide the Application Setting Manager with a relevant SPWeb object, it can deduce the current SPSite, SPWebApplication, and SPFarm objects by walking up the hierarchy. This is shown in the following illustration.

Building a SharePoint hierarchy

The Application Setting Manager components allow you to identify the relevant hierarchy of SharePoint objects in two ways:

You can allow the component to build the current hierarchy from the current SharePoint context (the SPContext.Current property).

You can provide the component with an SPWeb object from which to build a SharePoint hierarchy. The component will deduce the relevant SPSite, SPWebApplication, and SPFarm objects from the SPWeb object you provide. This approach is useful in scenarios where the SharePoint context is unavailable, such as in command-line applications or test classes, feature receivers, or when you want to manage application settings for SharePoint objects that are external to your current context.

Note

What does "code that runs in the SharePoint context" mean? It means that when your code is invoked synchronously by a user action, such as clicking a button on a Web Part or selecting an item on the Site Actions menu, you have access to an object of type SPContext using the SPContext.Current property. This represents the context of the current HTTP request, and provides information about the current user, the current site, and so on. SharePoint solutions that are not invoked synchronously by a user action, such as timer jobs, service applications, and feature receivers, are not associated with an HTTP request; therefore, they do not have access to an SPContext object. These solutions are said to run outside the SharePoint context.

If you use an Application Setting Manager component without providing a starting SPWeb object, it will automatically attempt to build a hierarchy from the current SharePoint context.