Design of the Application Setting Manager

The Application Setting Manager includes the following features:

• It provides a uniform interface for reading and writing application settings into the property bags associated with each level of the SharePoint hierarchy.
• It provides a type-safe way to read configuration settings.
• It provides automatic serialization of complex data types.
• It provides the ability to read configuration settings in a hierarchical way. Settings defined at a lower or more specific level can override settings at a higher or more general level.

Design Highlights

The following class diagram illustrates the design of the Application Setting Manager.

The Application Setting Manager

The functionality of the Application Settings Manager is exposed through two key interfaces:

• IHierarchicalConfig. This interface consumes configuration settings.
• IConfigManager. This interface manages and can consume configuration settings.

In most cases, you should locate and instantiate these interfaces through the SharePoint Service Locator. The SharePoint Service Locator includes a default type mapping that maps the IHierarchicalConfig interface and the IConfigManager interface to their default implementations—the HierarchicalConfig class and the ConfigManager class, respectively.

Design Details

To store and retrieve application settings, the Application Settings Manager must build a hierarchy of storage levels. At each level of the hierarchy, the configuration store is represented by an implementation of IPropertyBag. This interface defines a collection of key-value pairs. The Application Setting Manager defines the following implementations of the IPropertyBag interface.

IPropertyBag implementation	Description
SPWebPropertyBag	The property bag that stores settings at the site (SPWeb) level. This implementation uses the property bag of the underlying SPWeb object to store application settings. This property bag is accessible from sandboxed code.
SPSitePropertyBag	The property bag that stores settings at the site collection (SPSite) level. This implementation uses the property bag of the root Web (SPSite.RootWeb) to store application settings, because the SPSite object does not include a property bag. Site collection–scoped keys have the suffix _Site_ appended to the key name internally to differentiate them from similarly-named Web-scoped keys in the root Web. An exception is thrown if you attempt to set a property that has the _Site_ suffix in its key string. This property bag is accessible from sandboxed code.
SPWebAppPropertyBag	The property bag that stores settings at the Web application level. This implementation uses a custom configuration object, WebAppSettingStore, to store settings. This store derives from SPPersistedObject and is stored as a child object of the SPWebApplication instance. This property bag is not accessible from sandboxed code.
SPFarmPropertyBag	The property bag that stores settings at the farm level. This implementation uses a custom configuration object, FarmAppSettingStore, to store settings. This store derives from SPPersistedObject and is stored as a child object of the SPFarm instance. This property bag is not accessible from sandboxed code.
SandboxWebAppPropertyBag	A read-only property bag that enables you to read Web application-scoped application settings from sandboxed code. This implementation requires that you install the full-trust proxy for reading Web application-scoped settings from the sandbox environment.
SandboxFarmPropertyBag	A read-only property bag that enables you to read farm-scoped application settings from sandboxed code. This implementation requires that you install the full-trust proxy for reading farm-scoped settings from the sandbox environment.
SPListBackedPropertyBag	A property bag that enables you to store application settings in a SharePoint list. The configuration list is stored at the root web level and can store values scoped to any level in the hierarchy. Internally, values stored in the list are retrieved based upon the key and a unique context ID that represents the hierarchy level, such as the ID property for an SPWeb object. This class is provided to help developers build list-based property bags as an alternate approach to the storage of application settings. This property bag is accessible from sandboxed code.
SPListBackedUrlPropertyBag	A property bag that enables you to store application settings in a SharePoint list. This class is intended for managing settings at the Web application and farm level, where settings must be stored in a central list. The class sets AllowUnsafeUpdates=true when updating or deleting a value, because the list may reside on a site collection outside the current context. Because of this, this property bag cannot be used from sandboxed code.

The Application Setting Manager must build a hierarchy of property bags to suit your execution context. The IPropertyBagHierarchy interface represents an ordered collection of property bags. The Application Setting Manager includes the following implementations of IPropertyBagHierarchy, each of which is targeted to a different execution context.

IPropertyBagHierarchy implementation	Description
PropertyBagHierarchy	Provides the base functionality for all property bag hierarchy implementations.
FarmPropertyBagHierarchy	Provides a property bag hierarchy when only farm configuration is available, such as when your code runs in a timer job. Contains an SPFarmPropertyBag.
FullTrustPropertyBagHierarchy	Provides a property bag hierarchy for full-trust solutions. Contains an SPWebPropertyBag, an SPSitePropertyBag, an SPWebAppPropertyBag, and an SPFarmPropertyBag.
SandboxPropertyBagHierarchy	Provides a property bag hierarchy for sandboxed solutions. Contains an SPWebPropertyBag and an SPSitePropertyBag.
SandboxWithProxyPropertyBagHierarchy	Provides a property bag hierarchy for sandboxed solutions when the full-trust proxy for reading Web application–scoped and farm-scoped settings is installed. Contains an SPWebPropertyBag, an SPSitePropertyBag, a SandboxWebAppPropertyBag, and a SandboxFarmPropertyBag.

The HierarchyBuilder class is responsible for selecting the right IPropertyBagHierarchy implementation for a particular execution context. Both the HierarchicalConfig class and the ConfigManager class rely on the HierarchyBuilder class to select and populate a suitable implementation of IPropertyBagHierarchy.

The ConfigSettingSerializer class implements the IConfigSettingSerializer interface. This class enables the HierarchicalConfig class and the ConfigManager class to serialize and deserialize application settings. Simple values, such as enumerations, strings, and primitive types, are converted to strings if necessary and stored directly. More complex objects are serialized and stored as XML representations.

Both the IConfigManager interface and the IHierarchicalConfig interface expose a SetWeb method that enables you to provide an SPWeb object from which to derive the storage hierarchy. This is an example of a method injection pattern. The default implementing classes, ConfigManager and HierarchicalConfig, also support a constructor injection pattern whereby you can pass an SPWeb object to the class constructor. Use the method injection approach if you are using service location to load the Application Setting Manager classes and you are running in an environment where the SharePoint context is unavailable, such as in a feature receiver or a timer job. The constructor injection approach provides an additional alternative if you want to directly instantiate the Application Setting Manager classes instead of by using service location.

Reserved Key Terms

Various key prefixes and suffixes are reserved for internal use by the Application Setting Manager:

• All keys are prefixed with PnP.Config.Key. This distinguishes configuration settings that are managed by the Application Setting Manager from other configuration data in the SharePoint property bags.
• All keys for site collection-scoped settings include a _Site_ suffix. This distinguishes site collection–scoped settings from Web-scoped settings in the root Web property bag.

If you attempt to use a key that includes a reserved prefix or suffix, the Application Setting Manager throws a configuration exception.