Retrieving Configuration Settings

The Application Setting Manager provides two different models you can use to retrieve configuration settings:

• IHierarchicalConfig. This interface allows you to retrieve configuration settings from any level of the SharePoint hierarchy, without knowing the level at which your setting is stored. If the same configuration key is defined at more than one level of the hierarchy, the IHierarchicalConfig implementation will return the value defined at the most specific level.
• IConfigManager. This interface allows you to retrieve configuration settings at a specific level in the SharePoint hierarchy. For example, you can retrieve an application setting from a specified SPWeb object or a specified SPFarm.

The following sections describe how to use each of these approaches to retrieve configuration settings.

Note

Both of these interfaces rely on a hierarchy of SharePoint objects (from SPWeb to SPFarm) in order to manage configuration settings. You can either allow the interface implementations to use the hierarchy current SharePoint context via the SPContext.Current property, or you can provide an SPWeb object as the starting point for the hierarchy. For more information, see Using the Application Setting Manager Interfaces.

Using IHierarchicalConfig to Retrieve Configuration Settings

The IHierarchicalConfig interface defines methods that you can use to retrieve configuration settings from any level of the SharePoint hierarchy in which your code is running. The GetByKey generic method provides a strongly typed way to retrieve a configuration setting. Because this method throws an exception if the key cannot be found, you should first use the ContainsKey method to verify that the key exists. The following code shows how to retrieve a configuration setting using the ContainsKey and GetByKey methods.

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

string workgroupName;
if(config.ContainsKey("Contoso.Applications.WorkgroupName"))
   workgroupName = config.GetByKey<string>("Contoso.Applications.WorkgroupName");

The ContainsKey method and the GetByKey method take a single argument that contains the key string of the setting you want to retrieve. This should be a string that was previously used in a corresponding invocation of the SetInPropertyBag method, as described in Adding and Updating Configuration Settings.

You can also specify the level in the SharePoint hierarchy at which the ContainsKey method and the GetByKey method should start looking for a property key. To do this, pass a member of the ConfigLevel enumeration as a second argument to the ContainsKey method or the GetByKey method. The ConfigLevel enumeration defines the following values:

• ConfigLevel.CurrentSPWeb. This value indicates that properties of the current site, site collection, Web application, and farm are searched.
• ConfigLevel.CurrentSPSite. This value indicates that properties of the current site collection, Web application, and farm are searched.
• ConfigLevel.CurrentSPWebApplication. This value indicates that properties of the current Web application and farm are searched.
• ConfigLevel.CurrentSPFarm. This value indicates that properties of the current farm are searched.

For example, you could use the following code to look for and retrieve a property that could be defined at the Web application level or the farm level.

bool isInternetFacing;
if(config.ContainsKey("Contoso.Applications.IsInternetFacing", 
     ConfigLevel.CurrentSPWebApplication))
{
   isInternetFacing = config.GetByKey<bool>
                         ("Contoso.Applications.IsInternetFacing",
                          ConfigLevel.CurrentSPWebApplication);
}

If you do not provide a ConfigLevel argument to the ContainsKey method or the GetByKey method, the ConfigLevel.CurrentSPWeb value is used and the HierarchicalConfig class will start searching at the SPWeb level.

Note

In some circumstances, such as in a timer job, the local SPFarm object is the only available SharePoint context unless the application code sets the SPWeb instance to use with the SetWeb method. In this case, the HierarchicalConfig class will search only the farm-scoped property bag.

Using IConfigManager to Retrieve Application Settings

If you do not want to search up the SharePoint hierarchy, you can use the IConfigManager interface to retrieve configuration settings. The ContainsKeyInPropertyBag method enables you to check for a key value at a specific level of the SharePoint hierarchy. The generic GetFromPropertyBag method enables you to retrieve a strongly typed object from a specific level of the SharePoint hierarchy. Both methods take the following two arguments:

• The string key under which the configuration setting was stored
• The IPropertyBag instance in which the setting was stored

For example, you could use the following code to retrieve a configuration setting from a specific site collection.

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

double bonusMultiplier;
using(SPSite mySite = new SPSite("http://intranet.contoso.com/sites/sales"))
{
  configManager.SetWeb(mySite.RootWeb); 
  IPropertyBag bag = configManager.GetPropertyBag(ConfigLevel.CurrentSPSite);
  if(configManager.ContainsKeyInPropertyBag
    ("Contoso.Applications.BonusMultiplier", bag))
  {
    bonusMultiplier = configManager.GetFromPropertyBag<double>
      ("Contoso.Applications.BonusMultiplier", bag);
  }
}