Joel's SharePoint Architect Blog

Continuing in my series of articles showing the many ways in which we can store configuration data for your SharePoint applications, this time we look at how to use SPPersistedObject to achieve this.

Don’t forget to check out part 1 of the series in which we find out how SPWebConfigModification can be used for persisting application configuration in SharePoint 2010.

Persistence Using SPPersistedObject

SPPersistedObjects let you store hierarchical configuration data for your application in SharePoint. An SPPersistedObject is a class you subclass. You can then add fields (not properties) to your class, attribute them with [Persisted], and SharePoint will serialise the object to Xml in the SharePoint Configuration database.

The above code creates a class with two fields (string Value1 and int Value2) which can be persisted for the current Web Application with the following code:

We can later retrieve – and optionally delete – the settings by calling GetChild<> on the WebApplication object.

As an alternative to storing at the Web Application level, you can use a Farm object instead.

Advantages

You configuration data is stored in the SharePoint Configuration database. This means it will be backed up along with the rest of your SharePoint data – assuming you perform SharePoint backups, of course.

Your data is also safe from prying eyes as there is no UI to edit these settings.

Disadvantages

There is no built in user interface to manage SPPersistedObjects. This is both a good and a bad thing: you have to provide your own way of editing the values you wish to store. To read and write these values you also need elevated privileges. There are some reports of SPPersistedObject use corrupting the Hierarchical Object Store; it’s unclear whether this is due to incorrect usage or something more flaky. Proceed with caution, and thoroughly test your code first on a virtual, scratch, SharePoint farm.

Technorati Tags: Development, SharePoint 2010, SharePoint Architecture

A common requirement in SharePoint 2010 and SharePoint 2007 developments is having somewhere to save your configuration data. Maybe you need to persist a SQL connection string, maybe you need to save the URL of your accounts system web service or perhaps you want to store settings for your web part that in some way alters the behaviour of your application.

SharePoint offers you many ways of doing this, and each has their merits. In this blog posting – the first in a series – we’ll be looking at persisting configuration data using web.config files.

Persistence Using Web.Config

This is a natural choice for ASP.NET developers. We tend to think in terms of config files when it comes to saving settings for our web-based applications.

Web.config files are also perfectly valid places to store this kind of data in SharePoint, but there are some gotchas.

Gotcha #1: When you make a change to a web.config file, it causes the app domain within the ASP.NET application pool to be recycled for that IIS application root. Any others that share the application pool will also get the rug pulled from under them – you’re effectively doing an IISRESET (albeit only on sites in your app pool), which causes an outage for several seconds, and forces ASP.NET to do a recompile next page load.

Gotcha #2: When you add a new web front end server to your SharePoint farm, it will lose settings that were manually keyed into the web.config on other servers. This is because of the Microsoft SharePoint Foundation Web Application service – the service in charge of keeping IIS in sync across your farm – can only restore web.config changes that it knows about.

Gotcha #3: In a multi-server farm, any changes you make to web.config on one of your web front end servers must be replicated across all web front end servers.

Gotcha #4: If you have extended your Web Application into other Zones, IIS will create multiple sites to host each Zone. Each IIS site will have its own web.config file for you to keep up to date.

So, how do we avoid these problems? Well, we can’t avoid Gotcha #1. It’s how .NET works. Any web.config changes trigger app pool recycling. But we can avoid Gotcha #2, #3 and #4.

The SPWebConfigModification Class

We can automate additions to, and removals from, the web.config file using the SPWebConfigModification class. It’s a SharePoint utility class that allows us to queue up changes to web.config, and then apply them asynchronously at SharePoint’s leisure, across each IIS site for your Web Application, and each server in your farm.

The most important benefit of doing this is that when I add a new server to my farm or otherwise have to restart the Microsoft SharePoint Foundation Web Application service, I’m guaranteed that all my web.config modifications will be applied to the server.

To use the SPWebConfigModification class, you create an instance of it and set the XPath expression to the target node in web.config you’re editing, then the name of the attribute or node to add, and lastly set the value we want to update.

Then it’s a simple matter of passing your SPWebConfigModification object to the Add()method of the WebConfigModifications collection on your target SPWebService (e.g. SPWebService.ContentService).

To write your changes to the batch, invoke Update() on your SPWebService. but note that nothing will happen until you call ApplyWebConfigModifications().

The code bellow shows the steps to add a new appSetting block to your web.config, adding a key called “mySetting” with the value “http://joelblogs.co.uk”:

   1: SPWebService service = SPWebService.ContentService;

   2:  

   3: SPWebConfigModification myModification = new SPWebConfigModification();

   4: myModification.Path = "configuration/appSettings";

   5: myModification.Name = "add [@key='mySetting'] [@value='http://joelblogs.co.uk']";

   6: myModification.Sequence = 0;

   7: myModification.Owner = "AD\JOELJ";

   8: myModification.Type = SPWebConfigModification.SPWebConfigModificationType.EnsureChildNode;

   9: myModification.Value = "<add key='mySetting' value='http://joelblogs.co.uk' />";

  10: service.WebConfigModifications.Add(myModification);

  11:  

  12: /*Call Update and ApplyWebConfigModifications to save changes*/ 

  13: service.Update();

  14: service.ApplyWebConfigModifications();

If you want to read this value later in your code, say for example in a WebPart, then you can use the ConfigurationManager.AppSettings[] collection to access configuration settings in the current web.config.

The code below shows retrieving the value of the “mySetting” key from the appSettings block of your web.config:

   1: string mySetting = ConfigurationManager.AppSettings["mySetting"].ToString();

Advantages

This technique allows you to keep your web.config files in sync, and backed up. Each time SharePoint makes a change to your web.config files, it will create a backup with a time-stamped name in the same folder. It will also ensure that any servers you add, or Zones into which you extend your Web Application, will get the correct web.config entries.

Disadvantages

There are reports that SPWebConfigModification can be flaky. It certainly had issues in SharePoint 2007; use of SPWebModification inside FeatureReceivers is discouraged as sometimes these can go awry. For use elsewhere, make sure the user running the code has administrative permissions to be able to edit the web.config files in the first place.

Links

For more information, have a look at the MSDN article on SPWebConfigModification.

Technorati Tags: Development, SharePoint 2010, SharePoint Architecture