Using SPWebConfigModification to Update the Web.config in SharePoint 2013

Seven months ago I wrote an article on Jumping the Hurdles of using SPWebConfigModification to Update the Web.config - that article was based on my experiences in SharePoint 2010 and having researched the topic thoroughly at the time I was interested to see how things fared in SharePoint 2013. Thankfully I had the opportunity to architect a solution from the ground up in 2013 which gave me the opportunity to once again adhere to the vow I made in Application Settings in SharePoint to never manually modify the web.config file.

While this post has not been as thoroughly researched at the time of writing as I usually would like, a quick search on SPWebConfigModification in SharePoint 2013 brought up few results and when I was looking into it for the project mentioned above, little had been written about it. A recent question on the OZMOSS mailing list showed that there were still some questions around how SPWebConfigModification did (or didn’t) work so I thought it would be useful to document my findings here for anyone wanting to ‘do the right thing’ and keep their hands off the web.config file.

For a bit of background for this post I’d thoroughly recommend you read the article I link to above – the purpose of this post is to compare the behaviour of the functionality between versions of the platform and it will make far more sense if you understand my (and others) previous findings.

However for those of you who care little about the past and just want to know what the deal is in 2013 – here is the quick summary:

SPWebConfigModification in SP2010 came with a number of issues however none which were completely insurmountable with a little work. The majority were already documented by others (and I link to them in that post) however one phenomenon had little written about it and even less in terms of a solution.

This problem was that even though the removal code ran successfully and even removed the entry from the modification collection, the element in the web.config file still physically existed. I came up with a workaround where  in the removal code I first applied another modification reverting the entry back to its original state, then ran the code to remove all modifications.

So how did this fair in SP2013? There was good news and bad news. On the plus side, this issue had been fixed! Removing the entry from the modification collection successfully removed the entry from the web.config file. On the negative side it came with a nasty side effect – if the modification you were removing was a change to an attribute on a pre-existing element then that whole element was removed from the web.config, not just your change.

This was clearly unacceptable behaviour particularly if the entry being removed was essential to successfully loading the website.

Once again however I managed to jump the hurdles that always seem to exist with this tricky class. The workaround this time was to remove all the customisations by default at the beginning of both the FeatureActivated and FeatureDeactivating functions and then add the customisation required. In FeatureActivated this would be your customised entry. In FeatureDeactivating this would be the original entry (if it existed in the web.config before your modifications). Again this solution isn’t full-proof and is prone to falling over in future iterations of the platform, however it is a solid workaround as things stand now. I’ve provided a code snippet to achieve this below:

public class WebConfigModificationsFeatureEventReceiver : SPFeatureReceiver
{
	// Due to what appears to be a bug or just and unfortunate side-effect in SP2013, using SPConfigModification on an existing element
	// replaces that element with a new one. When removing the customisation, that element is removed, hence meaning that the original
	// entry no longer exists. To counter this we will re-add the original values in the deactivating feature.

	public override void FeatureActivated(SPFeatureReceiverProperties properties)
	{
		SPWebApplication webApp = properties.Feature.Parent as SPWebApplication;
		RemoveAllCustomisations(webApp);

		#region Enable session state

		httpRuntimeModification = new SPWebConfigModification();
		httpRuntimeModification.Path = "configuration/system.web/pages";
		httpRuntimeModification.Name = "enableSessionState";
		httpRuntimeModification.Sequence = 0;
		httpRuntimeModification.Owner = "WebConfigModifications";
		httpRuntimeModification.Type = SPWebConfigModification.SPWebConfigModificationType.EnsureAttribute;
		httpRuntimeModification.Value = "true";
		webApp.WebConfigModifications.Add(httpRuntimeModification);

		httpRuntimeModification = new SPWebConfigModification();
		httpRuntimeModification.Path = "configuration/system.webServer/modules";
		httpRuntimeModification.Name = "add[@name='Session']";
		httpRuntimeModification.Sequence = 0;
		httpRuntimeModification.Owner = "WebConfigModifications";
		httpRuntimeModification.Type = SPWebConfigModification.SPWebConfigModificationType.EnsureChildNode;
		httpRuntimeModification.Value = "<add name='Session' type='System.Web.SessionState.SessionStateModule' preCondition='' />";
		webApp.WebConfigModifications.Add(httpRuntimeModification);

		#endregion

		/*Call Update and ApplyWebConfigModifications to save changes*/
		webApp.Update();
		webApp.Farm.Services.GetValue<SPWebService>().ApplyWebConfigModifications();
	}

	public override void FeatureDeactivating(SPFeatureReceiverProperties properties)
	{
		SPWebApplication webApp = properties.Feature.Parent as SPWebApplication;
		RemoveAllCustomisations(webApp);

		#region Revert session state

		httpRuntimeModification = new SPWebConfigModification();
		httpRuntimeModification.Path = "configuration/system.web/pages";
		httpRuntimeModification.Name = "enableSessionState";
		httpRuntimeModification.Sequence = 0;
		httpRuntimeModification.Owner = "WebConfigModifications";
		httpRuntimeModification.Type = SPWebConfigModification.SPWebConfigModificationType.EnsureAttribute;
		httpRuntimeModification.Value = "false";
		webApp.WebConfigModifications.Add(httpRuntimeModification);

		#endregion

		/*Call Update and ApplyWebConfigModifications to save changes*/
		webApp.Update();
		webApp.Farm.Services.GetValue<SPWebService>().ApplyWebConfigModifications();
	}

	private void RemoveAllCustomisations(SPWebApplication webApp)
	{
		if (webApp != null)
		{
			Collection<SPWebConfigModification> collection = webApp.WebConfigModifications;
			int iStartCount = collection.Count;

			// Remove any modifications that were originally created by the owner.
			for (int c = iStartCount - 1; c >= 0; c--)
			{
				SPWebConfigModification configMod = collection[c];

				if (configMod.Owner == "WebConfigModifications")
				{
					collection.Remove(configMod);
				}
			}

			// Apply changes only if any items were removed.
			if (iStartCount > collection.Count)
			{
				webApp.Update();
				webApp.Farm.Services.GetValue<SPWebService>().ApplyWebConfigModifications();
			}
		}
	}
}

So once again we’re left with an option to do things right which doesn’t quite act the way you’d expect, but as you can see, can still be used to achieve the end result desired. For all its ills in both versions of the products i’d still strongly recommend taking this approach to making changes to the web.config file over making manual modifications any day. I hope this post has made doing so a little easier moving forward.

UPDATES

We shouldn’t be surprised, but over time new hurdles have presented themselves which need documenting (and I apologise, the first one I mention I should have covered a long time ago when I encountered it!).

The approach documented above worked fine in my single-server development environment. As soon as we tried activating the feature in a multi-server farm test environment all sorts of issues occurred. This has been documented however and you can read about it in Jeremy Jameson’s post Waiting for SharePoint Web.config Modifications to Finish and Simon Doy’s post PowerShell to Detect Web Configuration Modification jobs.

The code changes required include a few functions to be added and a slight modification to the ApplyWebConfigModifications call as indicated in the below code.

        private static bool IsJobDefined(SPFarm farm)
        {
            SPServiceCollection services = farm.Services;

            foreach (SPService service in services)
            {
                foreach (SPJobDefinition job in service.JobDefinitions)
                {
                    if (string.Compare(job.Name, jobTitle, StringComparison.OrdinalIgnoreCase) == 0)
                        return true;
                }
            }

            return false;
        }

        private bool IsJobRunning(SPFarm farm)
        {
            SPServiceCollection services = farm.Services;

            foreach (SPService service in services)
            {
                foreach (SPRunningJob job in service.RunningJobs)
                {
                    if (string.Compare(job.JobDefinition.Name, jobTitle, StringComparison.OrdinalIgnoreCase) == 0)
                        return true;
                }
            }

            return false;
        }

        private void WaitForOneTimeJobToFinish(SPFarm farm)
        {
            float waitTime = 0;

            do
            {
                if (!IsJobDefined(farm) && !IsJobRunning(farm))
                    break;

                const int sleepTime = 500; // milliseconds

                Thread.Sleep(sleepTime);
                waitTime += (sleepTime / 1000.0F); // seconds

            } while (waitTime < 20);
        }

        /*Call Update and ApplyWebConfigModifications to save changes*/
        webApp.Update();
        WaitForOneTimeJobToFinish(webApp.Farm);
        webApp.Farm.Services.GetValue<SPWebService>().ApplyWebConfigModifications();

The second issue is one we’ve encountered more recently. The issue was in regards to the inability to successfully extend a web application which already had the web.config modifications applied. There’s 2 ways to approach this one – if you know before the fact, then make sure you extend your web application before applying any of the web.config modifications. Otherwise, hope that you’ve implemented decent deactivation code and be sure to deactivate the features before extending, and then reapply after the fact.

Jumping the Hurdles of using SPWebConfigModification to Update the Web.config

In my Application Settings in SharePoint post earlier in the year I vowed that on any new project I would ensure that the web.config file would never be (ab)used with manual modifications to store application settings. I’m happy to say that I stuck to that goal, and this post is a reflection on my experience since of avoiding any manual intervention with the file. As I discovered there are a number of potential issues and gotchyas with using the SPWebConfigModification class including one particular bug which will be discussed later – it is important that one has read the numerous informative and valuable posts on the topic before endeavouring to ‘do things the right way’ when making updates or changes to the web.config.

You could be excused for thinking that with the myriad of issues that seem to exist when using SPWebConfigModification that it couldn’t possibly be a suitable method for making updates to the web.config. It is however generally considered a best practice and there is good reason for its use. Anyone who has studied for and sat the application development exam (70-576) would know that it is clearly positioned as the right way to modify values in the configuration file. It is listed as one of two available techniques in Managing Web.config Modifications, mentioned in the patterns & practices SharePoint Guidance in regards to adding entries into the web.config and referenced as one of the 10 Best Practices For Building SharePoint Solutions by having SharePoint Manage Custom Config Settings.

Rather than take it as gospel though there are some great posts out there that explain exactly why it should be used. One of the best is Charlie Lee’s What every SharePoint developer should know about the web.config file which sheds some light on how the web.config is pieced together while stressing the fact it should not be manually modified. Mark Wagner’s How To: Modify the web.config file in SharePoint using SPWebConfigModification, while being written for SP2007 and being a great resource in outlining exactly what SPWebConfigModification and its properties do, also discusses the advantage of having the class propogate your changes across the farm. Finally, Jonathon Le exposes some of the issues with making manual modifications in his post SPWebConfigModifications and Manual Config entries don’t mix.

But as I also mentioned in my Application Settings post, the internet is littered with issues and problems with using SPWebConfigModification. While this shouldn’t preclude its use, it’s important to understand everything that may go wrong and the things to pay particular attention to so any potential issues can be avoided. The first port of call here is Reza Alirezaei’s SPWebConfigModification’s Top 6 Issues. It highlights some of the common pitfalls that occur when trying to use it and how to work around them. One important thing to note here is a lot of the best resources around this topic were written for SharePoint 2007 and hence are not all still applicable in 2010, however a vast number of them still are.

So how did I implement it myself? As per numerous others I used a Web Application scoped feature with FeatureActivating and FeatureDeactivating event receivers to run the necessary code. MSDN’s How to: Add and Remove Web.config Settings Programmatically page proved reasonably useful however it’s important to note that the two code samples use different methods of applying the modifications – I adjusted the adding code to use the web application format present in the removing code. I also adjusted the removal code to ensure all modifications from a particular owner were removed, not just the most recent.

I was quick to learn however that using the Web Application scoped feature came with its own side effect – as soon as the solution file was deployed the feature was activated across all web applications automatically – not just the one I intended it for. A more in depth explanation and the resolution to this issue can be found at Waldek Mastykarz’s post Inconvenient SPWebConfigModification development with Visual Studio 2010 SharePoint Developer Tools and Nancy Brown’s SPWebConfigModification 2010: Change, Caveat, and Code – the latter also has a neat code sample on how to back up the web.config files before applying changes.

That wasn’t the only issue I ran into though. At one stage I was getting duplicate entries resulting in a configuration error when trying to load the site, and while I managed to resolve the reason for this on my own, was interested to see that Nancy had already documented the exact phenomenon in her article SPWebConfigModification Tool and Explorations under the How to Make the Removal Fail (or “How This Can Make You Nuts”) heading. This is another post worth reading as it includes a lot more valuable information within it.

The most intriguing issue overall however was the fact that my removal code didn’t seem to be taking effect although it was running without error and successfully removing the change from the modification collection. Essentially, it just wasn’t being reflected in the web.config. The change I had made was to add an attribute to an existing element within the file and while it added it fine it just wouldn’t revert back to its previous state after being ‘removed’. I stumbled across a couple of Technet forum posts; WebConfigModification Issues and Remove the web.config entries programmatically not working in sharepoint 2010 in which a Microsoft staffer, Rickee, indicated it was actually a bug in SharePoint 2010 and one which was not due to be fixed. He mentioned within those threads that it may be possible that while it visibly existed in the web.config file it may not have actually been taking affect – possibly a satisfactory conclusion to some but not something I was content with (as a side note, I never did end up testing whether that theory was correct – I wanted that attribute gone!).

I ended up coming up with my own solution – in the removal code I first applied another modification reverting the entry back to its original state, then ran the code to remove all modifications (including the one I had just run). This resulted in a clean modifications collection and a web.config entry which mirrored the initial value. While its not a perfect solution (that value could easily be set to something different in a subsequent version of SharePoint!) I figured it suited my immediate needs just fine.

As you can appreciate from this article there are a number of things you need to consider when modifying the web.config using SPWebConfigModification and you must take great care when doing so, lest you end up in a situation described in Michael Nemtsev’s post How SharePoint manages web.config via SPWebConfigModification! What’s important though is that you understand the risks and pitfalls but more pressingly understand the importance of using it to apply your configuration updates.

(Update: To see how SPWebConfigModification performs in SP2013, take a look at Using SPWebConfigModification to Update the Web.config in SharePoint 2013)

Provisioning SharePoint Features – Declaratively or Programmatically?

The question posed is often one which causes much debate. It’s one of those ready-made ‘Friday flame wars’ topics that could easily bait the uninitiated. Right from the outset I want to define some boundaries around this discussion. I’ll be approaching it predominantly from a content type and list definition/instance perspective more so than anything else. Obviously features can be used to provision much more, but those mentioned are some of the most common and often what is being referred to when this question arises.

While i’ve filed this under ‘best practices’ I must admit that I wouldn’t consider it ‘best practice’ as such. More to the point, this is my current personal preference and my reasons behind it. Like most things SharePoint, both standpoints could be argued and in different situations the alternate approach might be the right one.

I consider myself able to judge the merits of both having recently made the switch. For a long time – the majority of my SharePoint career – i’ve been firmly in the declarative camp. I wouldn’t say this was the case for any noble reason – it was the way I learnt it, the way in which it was being implemented where I first worked and hence the way I implemented it myself on numerous projects since. Recently however on a greenfields project I decided that programmatic provisioning would be the way to go. This decision was made for a couple of reasons. I had been burnt by declaratively provisioning list definitions in the past and wanted a first hand experience in programmatic provisioning to be able to make a more personally-educated decision for future endevours.

Before writing this post I decided to read anything I could find out there to get the wider community’s opinion on the subject matter. I’ll endevour to include all links that helped shape this post.

I remembered having a discussion with Jeremy Thake at the Perth SharePoint User Group a long time ago on the reasons why he favoured programmatic provisioning and while I couldn’t completely recall the conversation, knew that there was a resource on the old SharePoint Dev Wiki. Thankfully it still exists on NothingButSharePoint.com and still proves to be one of the most useful resources on the matter. Have a read of SharePoint Declarative (CAML) vs Imperative (Object Model) Provisioning to see some of the collaborative thought on the pro’s and con’s of both approaches.

When approaching SharePoint best practices one of my first stops is always to the patterns & practices SharePoint Guidance where I found buried in the documentation the following quote:

“There are various tradeoffs to consider when you choose whether to create content types declaratively or programmatically. You cannot update a content type that has been created declaratively—all content types must be upgraded programmatically. However, declarative approaches are simple; therefore, they are a better choice if your content types are not expected to evolve or change.”

Also worth a read are the opinions of highly respected SharePoint MVP, MCM and MCA Wictor Wilen in his post Avoiding Xml Based SharePoint Features – Use The API Way. The post is a few years old and it would be interesting to hear an updated opinion but it still strongly advocates the programmatic approach.

Finally a couple of forum postings influenced my view, particularly the comments by Scot Hillier in what is the best practice to deploy a list instance to a sharepoint site and Rob Windsor in Best way to package publishing content types.

My views and experience with the declarative approach

As previously mentioned I’ve been using this approach for a long time. Aside from the fact that this may have been so due to habit, there were factors that lead me to believe it was a fine approach and seeking an alternative was not necessary. As vindicated by the patterns and practices quote above – it can be a simple method of provisioning features. There are examples and documentation aplenty all over the internet and MSDN. Particularly for provisioning lists and content types, applications exist which allow you to essentially reverse engineer the XML required from those that were created/prototyped in SharePoint via the UI (in 2007 there was the Solution Generator and SPSource, in 2010 you can import site templates into Visual Studio and find the relevant files or use the Community Kit for SharePoint).

A lot of the often-mentioned downsides to declarative provisioning never really caused me any issues. There was the ‘inability’ to define lookup fields in lists declaratively (which I never had a problem with using something similar to that described in Peter Holpar’s post Declaratively adding a lookup field to a list schema using the name of the referenced list). There was the dreaded length of the Views component of the schema which was easily rectified using Oskar Austegard’s approach in MOSS: The dreaded schema.xml. Overall, I think I just got used to writing XML and how it all tied together and it never really seemed too difficult.

There was one incident however which started to change my mind a little. It was at a client where I had provisioned reasonably simple custom libraries using the declarative method which ended up behaving oddly. I can’t remember the exact issue but it had something to do with adding (seemingly random – not all) documents and issues with setting the metadata. The issue was not replicable in an identical list created through the UI, yet multiple sets of eyes couldn’t see any issues with the XML. Sure, the problem may have been caused by the definition, but that’s the problem – it’s hard to debug and hard to determine where issues may arise from. It’s also relatively easy to introduce them unknowingly.

I also, in hindsight, remember putting up with a lot of iterations to identify why features weren’t activating correctly or lists weren’t being provisioned correctly, usually all a result of manually typed XML errors. In development there was the constant process of making slight changes to the content types or lists, making sure all traces were removed from SharePoint then reploying and activating. It was a cycle I probably got used to and thought little of, but reflectively it really can be quite painful considering the alternative.

My views and experience with the programmatic approach

Having recently experienced using the programmatic approach to feature provisioning, I’d have to say i’ve been converted and can’t see myself going back. Sure it takes a little longer sometimes, but the level of control you have (checking to see if lists already exist, whether fields already exist, making conditional changes if desired) over everything is such a refreshing change. Everything is in the one location – no need to jump from XML file to XML file, making changes to Elements and Schemas and the like – everything can exist in the one feature receiver class. Whereas previously if you needed some code for things you just couldn’t do in the XML (cleaning up upon removal perhaps?) now it all just lived in the same place and you could easily get a picture of what the feature as a whole achieved.

The option is potentially only a valid one for developers – but at least in my experience it tends to be the developers doing the XML definitions anyway. It is far better to keep them to their strengths within the SharePoint API.

It also seems that the majority of the community seems to be behind the programmatic approach – at least from the readings I did for this post. There are some fairly respected names lending their weight of support to the method and it’s hard to ignore.

So to conclude it’s fair to say that i’m now firmly in the programmatic camp. While my experience using the approach is in its infancy and my opinion may end up changing as I stumble upon potential hurdles – I have had a LOT of experience manipulating SharePoint via the API in various applications, including building up entire sites from the ground up, and have yet to run into as many issues as I had with declaratively provisioned features. One thing that I wished I had the opportunity to view before writing this post is a presentation/debate delivered at the Tulsa SharePoint Interest Group by Corey Roth (declarative) and Kyle Kelin (programmatic). It was a slideless presentation and hence I wasn’t even able to view them, however they have made available their code examples which were used in the presentation which may be worth a look if you’re wanting to compare the two approaches to provisioning features in a SharePoint site. Take a look at Corey’s post Code Samples from our CAML vs API talk at Tulsa SharePoint Interest Group for the solution.

Error Logging in SharePoint

FRUB938D3AJG
As identified in my post Exception Handling in SharePoint it is important to determine the most appropriate form of logging for your situation and use it. My original intention for this post was to create more of a how-to for each possibility but in my research discovered that the number of quality resources on this topic is extensive. This being the case, the focus for this post will instead discuss the different options available, point out some of the best resources I found on the subject if appropriate and summarise what I think is the best overall option to use in most instances.

The forms of logging I identified and will discuss below include logging to the SharePoint ULS, to the Event Log, via email, a database, CRM or a SharePoint list.

SharePoint ULS

Logging to the SharePoint ULS is arguably the most logical option when it comes to logging exceptions in your custom code. It is most appropriate for developers or support staff if they have access to the files and are able to monitor them consistently. Ideally, the ULS should be monitored regardless to ensure the ongoing health of the site but under some scenarios the files may not be made available and hence logging here would go unnoticed – in this situation an alternative logging option should be considered.

The difficulty with logging to the ULS surrounds the different options available depending on what version of SharePoint you’re using. SharePoint 2010 makes this task a breeze with its SPDiagnosticsService functionality which is available in both the free (SPF) and licenced (SPS) versions of the product. The best articles I found on this topic were Tobias Zimmergren’s article on SP 2010: Developing for performance Part 4 – Logging and Waldek Mastykarz’s extension of this in Logging to ULS in SharePoint 2010.

The task is more difficult in SharePoint 2007. MOSS at least provides some functionality to write to the logs via Microsoft.Office.Server.Diagnostics.PortalLog.LogString (briefly documented in Clayton James’ post Log errors to SharePoint Log file) but that is not available in WSS. There are some examples listed including Eli Robillard’s SharePoint Trace Logs and the Unified Logging Service (ULS) however a number of links in that article are broken now. Gunnar Peipman’s SharePoint: Writing messages to ULS (Unified Logging System) is another quality post however a reasonably complicated solution. There is also a Codeplex SharePoint Logging Library by Ayman El-Hattab that may be able to be harnessed. As you’re probably appreciating now, logging to the ULS in WSS was not made easy.

There is however one saving grace for any version of SharePoint when it comes to logging to the ULS and that is the
patterns & practices SharePoint Guidance Library which i’ll discuss in more detail later.

The other possible qualm about logging to the SharePoint ULS is the difficulty in reading them. This is made easier in SharePoint 2010 by Microsoft’s ULS Viewer or Stefan Gordon’s SharePoint ULS Log Viewer on Codeplex. Tools also exist for SharePoint 2007 including Florin Muntean’s SPTraceView and Stuart Starrs’ WSS / MOSS Log File Reader – both on Codeplex.

Event Logs

The other logical place to log exceptions is the Event Log. It is most suitable for system administrators or developers and support staff who have access to the server (hopefully this isn’t the case in production environments!). Much like the ULS it is reliant on the logs being monitored on a consistent basis and also on the system administrators reporting any issues back to the development or support teams.

Again SharePoint 2010 steps up to the plate with it’s SPDiagnosticsService class, also documented in Tobias’ post outlined previously. SharePoint 2007 has to rely on core functionality in the System.Diagnostics namespace called EventLog.WriteEntry briefly documented in SharePoint King’s Event Log Access Denied : Sharepoint /.NET. As that article points out (to a degree), you need to ensure that access to write to the Event Log is granted to the relevant accounts.

One thing to point out here is, like the ULS logs above, the patterns & practices SharePoint Guidance Library provides the ability to write to the Event Logs as well.

Email

Logging exceptions via email is an interesting one. In my opinion, email should only be used hand in hand with another logging option primarily for the purposes of notification. It is mostly required if the primary log store isn’t checked on a regular basis. There are 2 options available here; either use the in-built SharePoint emailing capability of SPUtility.SendEmail or using .NETs SmtpClient class – both documented in Mohd Sukri At’s post Send Email in SharePoint via .NET SmtpClient Class and SharePoint SPUtility Class.

Database

I’m not a huge advocate of using a database logging mechanism in a SharePoint context however it may be appropriate if there is a need to aggregate exceptions from multiple (and non-SharePoint) applications across an organisation. If database logging is desired then a library should be used such as log4net or the Enterprise Library Application Block. There is a good article on Configuring Enterprise Library 4.0 for Exception handling and Logging by Suleman Ibrahim and some potential issues in Cory Roth’s How to get Enterprise Library working with SharePoint if you choose to go down this path. While on the topic of the Enterprise Library it may be worth pointing out that it is also possible to use it to log to the ULS logs demonstrated in Madhur Ahuja’s post Implementation of Logging and Instrumentation Application Blocks in MOSS 2007.

CRM

My opinions on logging to CRM are similar to that of a database. The most appropriate reason for this however would be in a tightly integrated SharePoint and CRM application where interaction mostly takes place on the CRM side. I’ve actually been involved in projects like this where logging exceptions to CRM was deemed more appropriate than SharePoint as it would aggregate issues from both systems and be more closely monitored. At the risk of exposing my lack of CRM knowledge and in lieu of providing a link to an example, the premise would be to have a log entity in CRM and have a library code-side which creates a dynamic entity of that type, populates the relevant fields, creates a TargetCreateDynamic object binding the dynamic entity and a request binding the target, then executing the request via the CrmService. Sounds easy, is relatively easy, but will leave this to the CRM experts.

SharePoint list

I find it interesting that I have yet to see an implementation of exception logging to a SharePoint list. It’s a highly visible and accessible location to monitor issues within a SharePoint site. Another plus to logging to a SharePoint list is that it is sandbox-friendly and hence a viable option for SharePoint 365. Timmy Gilissen identifies this in his post SharePoint 365 logging and the example is not restricted to just sandboxed solutions (note that if you’re going to take the code from that page you may also want to read Rob Garrett’s post Efficient way to add a new item to a SharePoint list).

On the topic of sandboxed solutions it is something worth pointing out in terms of the other logging mechanisms. It essentially makes them far more difficult to implement, for instance logging to the ULS or Event Logs in a sandbox requires a full-trust proxy due to the Microsoft.SharePoint.Administration namespace not being available in a sandboxed environment. The patterns & practices SharePoint Guidance Library however includes a full trust proxy which enables the use of it’s SharePoint Logger within the sandbox.

The patterns & practices SharePoint Guidance Library

I’ve been a little coy throughout this post regarding the patterns & practices SharePoint Guidance Library solely for the reason that I think it’s worthy of it’s own section in this post. The library is amazing on a number of fronts and this is no different when it comes to Logging. In fact, it is my most recommended option for logging exceptions assuming logging to the ULS and/or the Event Logs is suitable for your circumstances. I highly recommend you visit the page and read what the library offers both from a SharePoint 2007 and 2010 perspective. Another post worth reading in regards to the library is Alex Angas’ Intro to SharePoint 2010 patterns & practices – Logging.

As you can see there are a number of options when it comes to logging exceptions in SharePoint and depending on your circumstances, different ones may be the most suitable. The important part is that you use some form of exception logging and do it in a best practice manner.

Exception Handling in SharePoint

I feel like i’m going to be opening a can of worms with this one. I’ve given it a fair bit of thought over time and for this post specifically. I’ve read a lot of guidance around the topic. For the most part, best practice exception handling is reasonably well covered in the ASP.NET space but starts to become a bit murky when you delve into the SharePoint sphere. Some of my own personal preferences clash slightly with other advice that exists and like anything to do with SharePoint, often circumstances may dictate the path you need to take.

As such, I was slightly hesitant to write this post. The reason I have is because exception handling seems to be one of the most poorly implemented (or at least forgotten/ignored) tasks in SharePoint development. It’s also an important task when you factor in user experience, performance and ability to monitor your deployed applications. I’ve seen some shockers; from potential exception-throwing lines of code going unmanaged in web parts which could  bring down the entire page, to swallowed exceptions that you’ll never even know are there. I’ve seen catch (Exception ex) blocks scattered everywhere and try-catch blocks used to control execution flow or used in place of pre-exception checks.

There is a lot of good information out there. MSDN has version-specific editions regarding Handling and Throwing Exceptions. There are some good articles written for .NET in general including Scott Mitchell’s Exception Handling Advice for ASP.NET Web Applications, Daniel Turini’s Exception Handling Best Practices in .NET and Russell Allen’s C# .net Exception Handling Best Practice – As Easy as 1, 2, 3?.

The general consensus tends to boil down to a few rules. Generally, the base exception classes (Exception, ApplicationException) shouldn’t be caught or thrown. Exceptions should only be handled if you can add value to how they’re processed, otherwise they should be allowed to bubble up the chain. Finally, exceptions should be reported so corrective action can be taken if nececssary – preferably using an existing framework such as the Exception Management Application Block.

The question is how these rules and surrounding information can be tweaked to be suitable for SharePoint projects. I’ll structure my comments around this by identifying some general rules and outlining where they’re applicable in a SharePoint context.

1. Never, ever swallow an exception.

Pretty obvious, but the following is a definite no-no.

try
{
    // code
}
catch { }

At the very least the error should be reported using error logging functionality, if not handled sufficiently. I have seen an instance whereby the exception was expected and superfluous to report – I wish I could find it now or even remember why to explain – but if this unlikely case ever occurs it should be properly documented in the code.

2. If you’re going to throw an exception, use throw;

A common piece of code I see goes something along the lines of:

try
{
    // code
}
catch (Exception ex)
{
    throw ex;
}

This is actually quite bad practice. The reasons why were highlighted in some of the links I mentioned earlier, but essentially by doing this you clear the stack trace which is very useful when debugging the exception down the track. You’re better off using the following:

try
{
    // code
}
catch
{
    throw;
}

3. Wherever possible handle the specific exception.

The most common form of exception handling I see is something along the lines of:

try
{
    // code
}
catch (Exception ex)
{
    // handle exception
}

The problem is this goes against the general philosophy behind exception handling. Lee Dumond’s post Friends Don’t Let Friends catch (Exception) explains this nicely.

If you know the object model, or at least know where to go to find the information, you’ll be able to find out which exception/s you should be handling. Take the GetList function in SPWeb. That page identifies clearly the exceptions that may be thrown so you should handle them appropriately.

try
{
    spList = spWeb.GetList("/Path/List");
}
catch (FileNotFoundException ex)
{
    // handle exception
}
catch (ArgumentException ex)
{
    // handle exception
}

An important point to note is that your catch blocks must go in order of most specific to least specific.

4. If you can check for a condition before it throws an exception, do so.

A common block of code you may see is something along the lines of:

try
{
    myString = listItem["MyField"].ToString();
}
catch (Exception ex)
{
    // handle exception
}

Sure, if MyField was never populated in the list item it would throw an exception when you attempt to convert it to a string, but why not check to see if it was populated in the first place?

if (!string.IsNullOrEmpty((string)listItem["MyField"]))
{
    myString = listItem["MyField"].ToString();
}

5. You got to know when to hold ‘em, know when to fold ‘em.

Ok I may have stretched the poetic licence a bit there. What i’m talking about somewhat contradicts the rule regarding letting exceptions bubble up the chain to be handled at the application level. Consider you have a web part on a page, relatively non-critical to the page or application as a whole, a weather web part for instance. Do you really want the whole page to error out because it generated an exception? I wouldn’t begrudge you a global catch (Exception) in that instance.

On the flip side, imagine an event receiver that is processing a list item that is currently being added. The processing is necessary to complete the step of adding the list item, but the exception is caught, reported and held. The list item will exist, but the process did not complete, and depending on the level of reporting the user may never have a clue.

The point is you really need to use your best judgement when it comes to error handling in SharePoint. It’s hard to state a catch-all rule that can be applied across the board, often it will depend on context.

6. Determine the most appropriate form of logging and use it.

I would have preferred to state how errors should be logged in a SharePoint application much more definitively than this. The most important takeaway is to ensure that the errors are logged. The 2 most logical locations to log the errors would be the ULS or Event Log, however this may not always be appropriate. If these locations aren’t regularly monitored or accessible by the people who need to know about the errors, then it is essentially no better than swallowing the errors in the first place. Email, CRM, a database or even a SharePoint list are other potential locations that could be more accessible. Logging to a file on the file system makes little sense seeing if that is an accessible option you could just use the ULS. I write on this topic in more detail and explain my preference for logging to the ULS/Event Log using the SharePoint Guidance Library in my post Error Logging in SharePoint.

7. Use a custom error page.

Nothing looks worse on a public facing internet site or even an intranet application than when you get the ‘yellow screen of death’. Wherever possible you should display a user friendly message rather than an ugly generic error page. I explain the options available around this topic in my post Custom Error Pages in SharePoint.

That about covers it. Just thinking about this post made my head spin around in circles so it’s no wonder why a vast number of developers take the shortcut route and use global try-catch blocks with generic Exceptions. Hopefully this post sheds some light however on why doing so is a bad idea and that there are better options available to be leveraged. If anyone wishes to comment on the topic I’d be very interested in hearing opposing views and ideas – I’d still consider myself learning the best practice approach to exception handling at this point.

Content Security in SharePoint

Security is a polarising topic in the SharePoint community. It seems that everyone has a slight variation to what would be considered a best practice approach to implementing security across a site. There are so many conditions that determine which approach would be the best to use that it’s difficult to outline a best practice approach in the first place. This article, while filed under the Best Practices category, should only be considered my personal best practice approach to implementing a security model across a SharePoint 2007 or 2010 site.

If you have the time, there is a tonne of background reading to get through on the subject. Technet includes pages dedicated to both versions of SharePoint including Security and protection for Office SharePoint Server 2007  and Security and protection for SharePoint Server 2010. In this article i’m focussing on securing site content which is more specifically targeted in the Downloadable book: Security for Office SharePoint Server 2007 and Security planning for sites and content (SharePoint Server 2010).

I’ve always favoured a simplistic approach to site security. I used to advocate maintaining security groups in active directory, assigning those security groups to SharePoint groups and then assigning the relevant permissions to those groups across the site where necessary. The premise behind this methodology was to have one source of truth (AD) which was often maintained more religiously when staff joined or left the organisation. It was to allow a ‘set and forget’ approach to security within SharePoint – the security across the site would ideally never change, only the staff members assigned to the security groups. In reality, this approach is far too idealistic.

I’ve since realised that a lot of the time the security methodology will be largely influenced by the context of the organisation. Security groups may make a lot of sense throughout the organisation, but they may not map ideally to the SharePoint site. Some organisations may not and will not assign email addresses to security groups which renders them a tad ineffectual when it comes to workflow notifications. Some will refuse to create SharePoint-specific security groups in AD altogether. AD maintenance may be carried out solely by an over-worked IT department at a low priority, so getting a particular user added to a group may take longer than necessary. Or you may want to display the members of a given site using the Site Users web part and notice you end up with the security group listed rather than the individuals (there is a way around this in SP2010 however, check out Robi Voncina’s Display members of AD group in SharePoint 2010  solution on CodePlex). You get the idea – there’s not necessarily a one size fits all approach that will work in every scenario.

There are however a few golden rules which can be followed with a few potential caveats to implement a solid security methodology across a site.

1. Plan your security

One of the biggest issues with security in SharePoint is it seems to be done ad-hoc initially and grows wildly once the site is live. Security is granted on an as-needed basis with little fore-thought which generally results in a sprawling mess which is hard to track and maintain. Initially the security implementation should be well thought out and planned – identify the levels of access required, the users which will need those levels of access and identify the logical groupings of those users. When security needs to be modified, assess how the change fits in to the initial model and implement the most logical option to affect the change.

2. Document your security

This is particularly important in terms of tracking the customisations to security – preferably everything should be documented. It allows you to have an over-arching view of what is in place – determine what users have access to which portions of the site – something which is otherwise difficult to ascertain. At the very least where ever inheritance has been broken should be clearly identified, especially at more granular levels such as list or item level security (which preferably should be avoided).

3. Inherit permissions where ever possible

Aside from making the job far easier for point 2, it really keeps the security structure a lot more clear and clean to identify which users have certain levels of access across the site. Breaking inheritance at the sub-site level is not too much of a concern but at the list and item level should be avoided if possible. SharePoint helps out in this regard seeing inheriting permissions is the default.

4. Always use SharePoint groups when applying security across a site

You may not be able to only use AD security groups as identified above, but you should always use the SharePoint groups. Permissions should only be assigned to these groups rather than individuals – you are able to add both AD users and security groups to the SharePoint groups. It keeps everything a bit neater and consistent across the site rather than having some SharePoint groups, some security groups and some individuals. It’s worth preventing group-sprawl if possible – maintaining as few logically seperated groups as possible will ensure ease of maintenance.

5. Use AD security groups where appropriate

I still prefer using security groups to keep the SharePoint security structure clean and concise – but only when it makes sense to do so. Leverage the Domain Users group to provide global read access across a site for instance.

6. Use the principle of least-privilege

This is just good practice in all forms of IT. No user should ever have access to functionality that they don’t need. I’ve seen plenty of implementations which give site ownership to a wide range of users so they can edit a particular page of a sub-site, then wonder where a certain list item disappeared to.

The goal for any security implementation should be simplicity, understandability, maintenance efficiency and most importantly effectiveness in securing the content. The best way to get there is to plan and document the approach, for the time invested in the beginning will save a lot of headaches moving forward.

Application Settings in SharePoint

One of the most commonly neglected features in SharePoint I find across a number of different projects is the manner in which application settings are managed. Far too often it is left to manually modifying the <AppSettings> section of the web.config file for the relevant web application. Perhaps this is due to legacy behaviour of ASP.NET developers moving into the SharePoint sphere, perhaps its due to environments being small and the risks of manually modifying the file not being exposed. It may be due to organisational process or procedure, or (most likely) it may be because on face value it appears to be the most simple, quick and easy option to maintain some configuration values.

It’s ironic that in projects laced with features and solutions to deploy resources ‘the right way’ that configuration is overlooked and remains a manual process. Aside from wanting to avoid any manual modification of files directly on the server by principle, dangers exist in terms of ensuring the web.config files are the same on all web front end servers. Maintaining application settings this way also requires access to the web.config file (and hence server) itself which wouldn’t be considered best practice, and the act of changing a variable in the web.config directly would cause the application pool to refresh and cause the site to load slowly on the next hit.

I write this post with a tinge of regret – I too have been guilty on multiple occassions of maintaining the status quo and leaving (and even adding to) configuration values maintained manually in a web.config file. So not only should this post serve as a source of information regarding the best practice methods to maintain application settings, but it should also serve as a motivator to myself and others to practice what I/we preach on all future greenfield projects.

Anyone who has studied for or taken the application development exam (70-576) would have noticed that 4 main options consistently get presented for application configuration: web.config, lists, property bags and the hierarchical object store. I’ll discuss each option briefly and provide some situations where the method would be appropriate.

Web.config

Now it may seem like i’m beginning to contradict myself here – I previously mentioned that manually maintaining application settings in the web.config was a BAD idea. It is. The beauty of SharePoint though is that it provides a mechanism to maintain application settings in the web.config file automatically via the SPWebConfigModification class. If you’re wanting to store them in the web.config, then a feature should be created which on activation uses the SPWebConfigModification class to modify the web.config for you. This ensures that the same values are written to the web.config files on all front-end web servers and even ensures they’re consistent amongst new servers added to the farm.

You’re likely to want to use this option if you just can’t pull yourself away from the web.config for variable configuration. At least its a safer method. There are some valid reasons however – it’s reasonably simple to incorporate this functionality and then easy to program with seeing you’re probably used to it already. It ensures values are consistent across all front-end web servers and are available and consistent across the entire web application. It’s also fairly useful for ‘set and forget’ the values – if you’re unlikely to need to change them in the future, then you won’t run into the application pool refresh issue I mentioned previously and will get the performance benefits of the cached settings.

Before running off and using this method however, be warned that the web is littered with issues and problems with using SPWebConfigModification. I’d probably want to avoid making any ‘unnecessary’ changes to the web.config especially for the purposes of setting configuration values considering there are other options available.

SharePoint lists

It almost seems too easy and obvious. SharePoint provides us with these useful things called lists. Most of us would be familiar with or have used database-driven variable configuration mechanisms before. Lists, on face value, are reasonably similar to database tables. Why don’t we use lists for variable configuration? It’s not actually that silly a proposition and is in fact one of the more reasonable options. One of the beauties of using lists is that you get all that SharePoint listy goodness. Versioning, security and an out-of-the-box UI for example. You’re likely already familiar with list-based programming, so that isn’t too much of an inconvenience.

Using SharePoint lists is definitely one of the preferred methods. It’s probably easier to outline some of the reasons why you may not want to use it; a site with lax security restrictions would probably be wise to avoid this method – you wouldn’t want any user being able to modify or delete configuration items or the list itself. If you wanted the application settings to be available to multiple site collections/web applications then you’d potentially end up duplicating the list values across these sites.

There’s another huge advantage to choosing this method. An MVP named Chris O’Brien has written a Config store framework available on Codeplex which makes the option even more attractive and erases some of the drawbacks from choosing it. I’d definitely recommend reading a bit about it in his post A better Config Store for SharePoint sites.

Property bags

This option is perhaps a little less obvious but similarly powerful. A number of SharePoint objects contain a Properties property which stores a collection of key/value pairs. These obviously lend themselves towards being used for storing application settings.

This option is possibly the best one to harness when scope is an important consideration for configuration. It lends itself to being able to maintain numerous variables with different values on a per-scope basis (per web, per web application and so forth).

Like the SharePoint list option, this also benefits from addons which improve the usability and effectiveness of the option. The SharePoint Guidance Library provides the Application Setting Manager which is an API to read and write application settings. Codeplex also has the SharePoint Property Bag Settings project which provides a GUI in Central Administration to manage the settings.

Hierarchical Object Store

This is a farm-scoped store similar to a property bag. It requires custom code to create and is far more complex than the other options, however has the benefit of being able to store more complex types if that’s neccessary. Generally for the purpose of variable configuration though, in my opinion i’d go for one of the other options.

You’d possibly choose this option if you were looking for a global storage option for values or required complex values to be stored. If the values are simple key/value pairs however a farm-scoped property bag would probably be easier to use and do the trick.

WebPart properties

I know I said before there were 4 main options, but I wanted to briefly cover this one too. In the event that your custom web parts require configuration values specific to the web part then it will often make sense to include custom properties editable in the web part itself – they are then able to be set by modifying the settings of the web part.

My initial concept for this post was to include an array of advantages, disadvantages and code samples on each option to more completely highlight where each could be used and how they’re used, however during my research for this post came across an MSDN article written by David Mann titled Managing Custom Configuration Options for a SharePoint Application – it essentially covers in reasonable detail those points and I would strongly recommend reading.

Overall I’d have to say I prefer the SharePoint list method the best. I’m somewhat surprised, I remember thinking a while ago that using lists for application settings would be a bit primitive and that surely the other options which have been provided (obviously for the purpose of variable configuration?) like SPWebConfigModification, SPPersistedObject and the Properties collections would be the best practice method to use. I guess sometimes the easy option actually is the best, and it’s sandbox-friendly to boot.

Follow

Get every new post delivered to your Inbox.