Reading Configuration Data in a SharePoint Web Part

Typical Goals

Your application may need to retrieve configuration settings at various points in its execution. To determine where your application should be deployed, a deployment package might need to retrieve global configuration settings as part of the installation process. A Web Part or an application page might need to retrieve configuration settings as part of the page load life cycle, or in other words, whenever a user requests the page. If your application contains more complex logic, it might need to retrieve configuration settings regularly in response to user interface events.

In any of these situations, it is useful to have a consistent, type-safe approach to the retrieval of configuration data.

Solution

This scenario continues to use the example of a Web Part that provides a map view of customer locations, based on geo-coded data from a SharePoint list. Every time the Web Part loads, it must retrieve the URL of the customer location list from the configuration settings for the SharePoint environment.

The IHierarchicalConfig interface defines a generic method named GetByKey that you can use to retrieve configuration settings from any level of the SharePoint hierarchy. When you use the GetByKey method, the HierarchicalConfig class will first look for the setting in the current SPWeb object. If the specified key cannot be found at the SPWeb level, the HierarchicalConfig class will next look in the root web of the current SPSite object (as the SPSite object does not include a property bag), then in the current SPWebApplication, and finally in the SPFarm object.

Using the GetByKey Method

The following code example shows how to use the IHierarchicalConfig interface to retrieve a configuration setting from within a Web Part class.

This example assumes that you have added a reference to the Microsoft.Practices.SharePoint.Common.dll assembly, the Microsoft.Practices.ServiceLocation.dll assembly, the Microsoft.SharePoint.dll assembly, and the System.Web.dll assembly.

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

[Guid("70ACDCFF-A253-4133-9064-25DB28F17514")]
public class CustomerLocationsWebPart : System.Web.UI.WebControls.WebParts.WebPart
{
 protected override void OnLoad(EventArgs e)
 {
 IServiceLocator serviceLocator = 
                   SharePointServiceLocator.GetCurrent();
 IHierarchicalConfig config = 
 serviceLocator.GetInstance<IHierarchicalConfig>();

 string locationsListUrl;
if(config.ContainsKey("Contoso.Sales.CustomerLocationsListUrl"))
 {
 locationsListUrl = config.GetByKey<string>
 ("Contoso.Sales.CustomerLocationsListUrl");
}

}
}

You can also retrieve hierarchical configuration settings from outside a SharePoint context. In this case, you must provide the HierarchicalConfig instance with an SPWeb object from which to build the configuration hierarchy.

using(SPSite mySite = new SPSite("http://intranet.contoso.com/sites/sales"))
{
   IHierarchicalConfig config = serviceLocator.GetInstance<IHierarchicalConfig>();
   config.SetWeb(mySite.RootWeb);
    locationsListUrl =  
           config.GetByKey<string>(“Contoso.Sales.CustomerLocationListUrl”);
}

Usage Notes

Beyond simple developer convenience, there are sound design reasons to use an application settings manager that searches up the SharePoint hierarchy for specific configuration keys. In the customer locations example, the URL of the customer locations list was initially stored at the site collection level. Suppose a specialized sales team wanted to use the same Web Part within their own individual site. However, they want to use a different customer locations list to drive the Web Part. By adding a configuration setting with the same key at the SPWeb level, their Web Part will use the customized local list, while any other instances of the Web Part within the site collection will be unaffected.

The use of generics in the GetByKey method forces you to retrieve configuration values as strongly-typed objects. You will receive a ConfigurationException at run time if you attempt to read a configuration setting with the wrong type. For example, if you read a configuration setting as type Int32, but it was stored as type DateTime, an exception would be raised.

For more information about how to retrieve configuration settings, including how to retrieve settings from outside the SharePoint context, see Retrieving Configuration Settings.