The Configuration Manager
Frequently, SharePoint applications retrieve configuration settings at run time that were set when the application was installed or configured. To do this, the applications must access the configuration information, which can be stored in several locations. For example, configuration information can be stored in the Web.config file, the SharePoint configuration database (for example, values in the SPFarm property bag are stored in this database), or in a content database (for example, in an SPList object are stored in the content database). There are many challenges associated with these techniques. For example, improper use of the SPFarm property bag can corrupt the SharePoint configuration database. Also, although you can easily change the Web.config file with a feature installer, it is much harder to make changes to the Web.config file after a feature is deployed.
The SharePoint Guidance Library includes a hierarchical configuration manager that can safely store and retrieve configuration settings at the following levels:
- Farm (SPFarm class)
- Web application (SPWebApplication class)
- Site collection (SPSite class)
- Site (SPWeb class)
The configuration manager is a reusable component that you can include in your own SharePoint applications. It can store simple types, such as integers or strings, as well as any type that can be serialized to XML.
The configuration manager is easier to use than the SharePoint API because the configuration manager offers a uniform and type-safe way to read and write configuration settings. Also, the configuration manager does not allow you to store non-serializable values. This prevents you from accidentally corrupting the content or configuration database.
The configuration manager exposes two interfaces that are named IHierarchicalConfig and IConfigManager. The IHierarchicalConfig interface is intended for readers of configuration information, such as Web Parts. The IConfigManager interface is intended for writers of configuration information, such as feature receivers.
The IHierarchicalConfig interface hierarchically reads the configuration settings in your current context, through the SPContext.Current property. If a setting is not in the property bag of the current SPWeb object, the configuration manager next looks in the current SPSite object, and then it looks in the current SPWebApplication object, and finally, it looks in the current SPFarm object. Calls to the IHierarchicalConfig interface throw an exception if the caller of the IHierarchicalConfig interface is not running in the context of a SharePoint Web application.
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. In addition, they do not require a SharePoint execution environment. You can pass in an arbitrary SPFarm, SPWebApplication, SPSite or SPWeb object in which to read or write the configuration settings. This means that the IConfigManager interface can be consumed from code, such as command line applications and feature receivers that do not run in a SharePoint context and do not have access to the SPContext.Current property.
Note
The SharePoint Guidance Library’s Configuration Manager provides an API to read and write configuration settings. It does not provide a user interface (UI) to read and write these configuration settings at run time. To do this, you either can create a custom UI for the configuration manager or you can use a general purpose property bag editor. For example, on CodePlex, there is a community-driven effort to create a property bag editor that allows you to change the raw property bag values.
This section includes the following topics to help you use and understand the configuration manager: