Adding and Updating Configuration Settings

The IConfigManager interface defines a single method named SetInPropertyBag that you can use to store configuration data at any level of the SharePoint hierarchy. The following code shows how to use the SetInPropertyBag method to add or update a configuration setting. It is important to note that items stored as configuration settings can be read by all users that have permissions on the object containing the property bag, such as the SPWeb or the SPFarm objects. As such, you should not store sensitive or personal information as configuration settings without first encrypting them.

Note

SharePoint 2010 does not allow you to write to the farm-level configuration from a content Web application. If you want to use the Application Setting Manager to store farm-level settings, your code must run from a feature receiver, the command line, or the Central Administration Web application.

using Microsoft.Practices.ServiceLocation;            
using Microsoft.Practices.SharePoint.Common.Configuration;
using Microsoft.Practices.SharePoint.Common.ServiceLocation;
using Microsoft.SharePoint.Administration; 
using Microsoft.SharePoint; 

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

// Store configuration data at the SPWeb level.
bag = configManager.GetPropertyBag(ConfigLevel.CurrentSPWeb);
configManager.SetInPropertyBag("MyApplications.WorkgroupName", 
                                                                    "Customer Service",
                               bag);

// Store configuration data at the SPSite level.
bag = configManager.GetPropertyBag(ConfigLevel.CurrentSPSite);
configManager.SetInPropertyBag("MyApplications.DivisionName", 
                                                                    "Pharmaceuticals", 
                               bag);

// Store configuration data at the SPWebApplication level.
bag = configManager.GetPropertyBag(ConfigLevel.CurrentSPWebApplication);
configManager.SetInPropertyBag("MyApplications.CompanyName", 
                                                                    "Contoso", 
                               bag);

// Store configuration data at the SPFarm level.
// Note that you cannot do this from a content Web application.
bag = configManager.GetPropertyBag(ConfigLevel.CurrentSPFarm);
configManager.SetInPropertyBag("MyApplications.FarmLocation", 
                                                                    "Redmond", 
                               bag);

Before you use the SetInPropertyBag method, you must retrieve the property bag in which you want to store your application setting. The ConfigManager class provides a method named GetPropertyBag that returns an IPropertyBag instance. The GetPropertyBag method accepts an argument of type ConfigLevel. This is an enumeration that allows you to specify the level in the SharePoint hierarchy that you want to target. The GetPropertyBag method returns the property bag at the appropriate level in the current hierarchy.

Note

Typically, the ConfigManager class builds a hierarchy of SharePoint objects from the SPContext.Current property. Alternatively, you can manually specify an SPWeb object as a starting point for the hierarchy, if the SharePoint context is unavailable. For more information, see Using the Application Setting Manager Interfaces.

The first argument to the SetInPropertyBag method is the key that defines the configuration setting. If this is a null string, an exception is thrown. Because there might be name collisions with properties that were set by other applications or by SharePoint itself, it is recommended that you fully qualify the key for each configuration setting with the namespace of the code that defines the setting.

The second argument to the SetInPropertyBag method is the new value of the configuration setting. This value must be an object that is serializable to XML. If a key already exists at the specified location, the existing value is overwritten. Otherwise, a new key/value pair is added to the property bag. Finally, the third argument is the property bag in which you want to store your application setting.

Remember that if the SharePoint context is unavailable, you must provide the ConfigManager class with an SPWeb object as the starting point for the current SharePoint hierarchy (SPWeb, SPSite, SPWebApplication, and SPFarm). To do this, call the ConfigManager.SetWeb method. The following code example shows how you could use this approach to store configuration data at the SPSite level.

using(SPSite remoteSite = new SPSite ("http://intranet.contoso.com/sites/pharm"))
{
  configManager.SetWeb(remoteSite.RootWeb);
  IPropertyBag bag = configManager.GetPropertyBag(ConfigLevel.CurrentSPSite);
  configManager.SetInPropertyBag("MyApplications.DivisionName", 
                                 "Pharmaceuticals", 
                                 bag);
}

Note

Various key namespaces and suffixes are reserved for use by the Application Setting Manager. The Application Setting Manager will throw an exception if you attempt to set a property that starts with the reserved key namespace (PnP.Config.Key). The library provides a full-trust proxy that allows sandbox applications to read Web application–level settings and farm-level settings when installed. The prefix ensures that the sandbox code will only read settings created through the Application Setting Manager.
The Application Setting Manager will also throw an exception if you attempt to set a property that ends with the suffix that distinguishes a site collection setting (.Site). This suffix is used internally to distinguish between site collection settings and site settings in the SPWeb property bag at the root of a site collection.

The following table shows SharePoint groups and the default permission levels that apply when adding and updating configuration settings, where site name is the actual name of the site.

Group (default permission level)	Can set site configuration	Can set site collection configuration	Can set Web application configuration	Can set farm configuration
Site name Visitors (Read)	No	No	No	No
Site name Members (Contribute)	No	No	No	No
Site name Owners (Full Control)	Yes	Yes	No	No
Farm Administrators (Full Control)	Policy dependent	Policy dependent	Yes	Yes

Note

Site name Owners is a SharePoint group that is created by default with the site collection. The Site name Owners group has Full Control permissions. The site administrator is a member of this group. For more information about SharePoint permissions, see Permission Levels and Permissions on the Microsoft Office Online Web site.

Note

Note: Members of the Farm Administrators group may or may not have automatic rights to manage site configuration data and site collection configuration data, depending on the policy configuration in your SharePoint environment. Changes to farm configuration are not allowed from content Web applications.