Brett's SharePoint Blog : solutions

Managing Web.Config Customizations

bgeoffro — Mon, 06 Oct 2008 14:55:00 GMT

I'm back after a long hiatus - international relocations tend to consume a lot of your free time - so it's time to start dusting off some of the many learnings I've had over the past few months...

One important topic I've encountered with my current and previous customers is how to manage web.config updates when deploying customizations. If you've been playing around with the Solutions framework, you're probably familiar with the ease of adding SafeControls entries to your web.config via your solution definition file, but what about all those other configuration settings that inevitably come up with SharePoint customizations?

In my research, I found three tactics for implementing generic web.config customizations programmatically:

Install customizations in the \12\CONFIG directory as specified in the WSS SDK: http://msdn.microsoft.com/en-us/library/ms439965.aspx
Use the SPWebConfigModification class

As described in the WSS SDK: http://msdn.microsoft.com/en-us/library/bb861909.aspx
As implemented in the SharePointDebugger solution: http://tedpattison.net/downloads.aspx

Manipulate the web.config file directly as an XML file (yuck!)

Based on the respective capabilities and level of effort associated with each tactic, I assembled the following matrix of tactics to customization scenarios - hope this helps!

Customization Scope	Method	Example
All zones for all Web Applications (Content web apps and Central Administration)	Create a solution with a webconfig.customizationname.xml file in the \12\CONFIG directory. See http://msdn.microsoft.com/en-us/library/ms439965.aspx for details. Deploy this solution using an *ApplicationServer* deploymentservertype. Execute the stsadm –o copyappbincontent command on all web application hosts (and the Central Admin host, if applicable) to apply retroactively to all existing content web application zones. Notes: · Do not execute the copyappbincontent command multiple times on the same server, as this can create duplicate entries of the customizations. · You do not need to execute the copyappbincontent command to propagate the customization new zones/web apps.	A generic SPSite or SPWeb-scoped feature that is activated via a FeatureSiteTemplateAssociation.
All zones for all Web Applications (Content web apps only)	Create a solution with a webconfig.customizationname.xml file in the \12\CONFIG directory. See http://msdn.microsoft.com/en-us/library/ms439965.aspx for details. Deploy this solution using a *WebFrontEnd* deploymentservertype. Execute the stsadm –o copyappbincontent command on all web application hosts to apply retroactively to all existing content web application zones. Notes: · Do not execute the copyappbincontent command multiple times on the same server, as this can create duplicate entries of the customizations. · You do not need to execute the copyappbincontent command to propagate the customization new zones/web apps.	A generic SPSite or SPWeb-scoped feature that is activated manually by a site owner/administrator.
All zones for selected Content Web Application(s)	Create a solution with a feature based on the SharePointDebugger feature. See http://blog.tedpattison.net/default.aspx for a detailed overview and http://tedpattison.net/downloads.aspx to download. · FeatureReceiver.cs - Update the modification.Owner property as appropriate · FeatureReceiver.cs - Update the Entries property to capture all required modifications. Be sure to use the correct SPWebConfigModificationType for each entry. · Feature.xml –update the ID, Title, Description, ImageUrl, ReceiverAssembly, and ReceiverClass as appropriate Deploy this solution using a *WebFrontEnd* deploymentservertype. Activate this feature on the appropriate web application(s) via the stsadm –o activatefeature command.	An SPSite or SPWeb-scoped feature for personal sites (you did remember to put these on a separate web application, right?) that is activated manually by a personal site owner.
Selected zone(s) for selected Web Application(s)	A manual update is the best practice unless automation is absolutely required. It is *possible* to update the web.config for a specific zone on all servers through code, but this essentially requires direct manipulation of the web.config files as XML documents.	Configuration settings for forms authentication providers.

New Advanced SharePoint Webcasts...

bgeoffro — Thu, 05 Jun 2008 20:12:00 GMT

Three of the SharePoint Academy and BPIO University courses I taught earlier this year are now available in webcast format. Many thanks to the sponsors on our product team, the Microsoft Information Worker community (global and local), content contributors, and MS Studios for making these possible. Now you can see what I look like when I'm reading from a teleprompter. :)

These webcasts contain a mix of standard material from the respective courses, as well as a number of my own contributions. Many of my contributions focus on material from areas of focus in my blog - customization, master pages, features, solutions, etc. - so thanks to all of you who've helped me enhance the content by sharing feedback, questions, and corrections to the original blogs.

I'm sure they'll end up on a landing page somewhere soon, but here are the public links:

Microsoft SharePoint Technologies Solution Architecture

http://www.microsoft.com/winme/0805/32847/mod4/index.html

Customizing and Extending Microsoft SharePoint Products and Technologies

http://www.microsoft.com/winme/0805/32847/mod9/index.html

Configuring the Business Data Catalog

http://www.microsoft.com/winme/0805/32847/mod10/index.html

Enjoy!

Branding Design using Solutions

bgeoffro — Fri, 11 Apr 2008 01:12:00 GMT

In a previous post, I extolled the virtues of deploying our branding code in a solution. While I still make that recommendation without any reservations, it's important to note that you may need TWO solutions to deploy your branding customizations.

History

First, let's do a quick review of some of the generic components I used in branding our MOSS environment (using the HTTP module approach for LAYOUTS customizations):

Customizations to the GAC

Feature Receiver DLL for the branding features
Some custom web part assemblies
Redirect Module DLL

Customizations to the "12" directory:

Custom application.master (applied via a redirect)
Custom simple.master (applied via a redirect)
Custom images
Custom Theme
A branding feature for Meeting Workspaces
A branding feature for all the other site templates
Branding feature stapler

Customizations to web.config:

SafeControls entries for the custom web parts
Redirect module configuration info

Everything except the redirect module configuration info (which we configured manually) is easily accomodated by the Solution framework, so that's exactly what I put in the original SINGLE branding solution file. So deploy all that stuff to your Web Front End servers, and you're good to go, right? Not entirely...

The Problem...

Two odd symptoms occurred in our regression testing. When we created sites/site collections from self-service site creation, STSADM on the WFE servers, or from the Create Page in a site, branding was applied. This is good. :) However, when we created site collections via STSADM from an app server or from Central Administration > Application Management > Create Site Collection, the branding was missing. This is bad. :)

Why? The Central Admin server - and all non-WFE servers - were missing the branding code. The feature stapler and everything referenced by it - the branding features, the feature receiver (since the features referenced it), and the custom theme (since the feature receiver attempted to set a new site's theme to the custom theme) - need to be on these servers in order for the site creation to complete with all branding applied.

The Solution...

In case you didn't know already (I didn't, which was the cause of this issue), there are two types of Solution deployments - Web Front End (which only pushes the changes to servers hosting the web application role) and Application Server (which pushes changes to ALL SharePoint servers in the farm). I don't remember the complete solution manifest spec, but one other restriction that's relevant to this scenario is that only the Web Front End deployment type supports creation of SafeControl entries.

Since I had a set of code that needed to be on ALL the servers as well as a couple of SafeControl entries, the simplest thing to do was to divide the customizations into two separate solutions - "core" branding and "web server" branding. The core solution holds all the components that are required on all servers, while the web server contains only the components that are needed to render the branded sites (like images, web parts, and LAYOUTS customizations).

Here's the breakdown:

"Core" Branding Solution

Customizations to the GAC

Feature Receiver DLL for the branding features
Redirect Module DLL

Customizations to the "12" directory:

Custom Theme
A branding feature for Meeting Workspaces
A branding feature for all the other site templates
Branding feature stapler

"Web Server" Branding Solution

Customizations to the GAC

Some custom web part assemblies

Customizations to the "12" directory:

Custom application.master (applied via a redirect)
Custom simple.master (applied via a redirect)
Custom images

Customizations to web.config:

SafeControls entries for the custom web parts

For ease of maintenance, I still used WSPBuilder for creating the manifests and .WSP files - this just required a minor tweak to the build script, which now looks something like this:

REM build core server customizations
wspbuilder.exe -solutionid 12345678-1234-1234-1234-1234567890ab -deploymentservertype ApplicationServer -wspname core-branding.wsp -excludefiles "a_list_of_all_the_wfe_files.txt"

REM build web server customizations
wspbuilder.exe -solutionid 12345678-1234-1234-1234-1234567890ac -deploymentservertype WebFrontEnd -wspname webserver-branding.wsp -excludefiles "a_list_of_all_the_core_files.txt"

Enjoy...

Branding Mark II: Refining the HttpModule-based Approach

bgeoffro — Sat, 26 Jan 2008 20:40:00 GMT

So we've got another MOSS environment to brand for my customer. This time it's an extranet environment for partner collaboration that has some very minor changes from the Intranet branding implementation I've described in the initial series of posts. Changes are pretty superficial - swap the logo, remove certain components that are only applicable to the Intranet environment, and update the header and footer.

Implementing the actual branding tasks isn't anything new. What is new is that I've taken a different approach this time around to ease configuration management headaches - mostly due to having adequate time in the project schedule and complete ownership of the development tasks. The implementation design changes are based on two major changes:

Use of the ResourceRedirect module
Packaging of all branding components in the SharePoint Solution framework

I'll post the gory details in the next few weeks, once I've finished prepping for delivering SharePoint Academy classes, but below is a quick summary of the tactics and some lessons learned.

Using the ResourceRedirect Module

This is basically a revisit of the tactics described in part 3 of my initial series of branding posts. We used KB944105 method 1 (taking a backup copy of the LAYOUTS directory) for a handful of files that needed updating, like CORE.CSS, SPTHEMES.XML, some IMAGES files, and the various WEBTEMP*.xml files (there were a few sitedefs we wanted to hide from end users), but the branding of the LAYOUTS pages was accomplished via redirects.

We used the following set of redirects (read my previous posts and you'll see why these were selected):

</destinationRedirects>

</masterRedirects>

</Branding>

While unit-testing the ResourceRedirect, I found a couple of bugs and flaws in the approach:

The <destinationRedirect/> elements can only be used for ASPX pages. You can't use this for components that don't have a PreInit event, like CSS files, images, etc. You'll need something lower-level - like an ISAPI filter - for those. This revision to the approach has been noted in the original post.
The original code for ResourceRedirect.cs bombed when a page didn't have any master page. Forgot to check for nulls (DUH!), so pages like SiteManager.aspx caused ResourceRedirect to choke. The updated version of the code is now in the original post.
Templatepick.aspx and the ResourceRedirect don't play well together. The jury's out on how best to handle this issue for now. Try to use the ResourceRedirect module on templatepick.aspx, and although site provisioning seems to work fine, you'll get a "Vaule does not fall within the expected range" error upon site creation. The bug doesn't seem to be in the page itself, as following KB944105 method 1 with the updated page works fine. I'm hopeful that we can chase down the source of the issue, but the fallback is replacing the page and keeping the backup of LAYOUTS.

Deploying the Branding as a Solution

Important Update: Contrary to the contents of this post, you'll likely need to deploy your branding code as a combination of a Web Front End solution and an App Server solution. I'll have an updated post on this topic by late April.

I can't overstate how much easier this makes the deployment process, or how much I wish I would have had the time to implement this approach with the Intranet branding before handing off the prototype to the dev team... :( Anyways, I used WSPBuilder to prepare the solution, which saved many many hours of tweaking a solution manifest and reduced the activity of prepping a solution to copying a bunch of files to a temporary directory. It's my new hero.

You'll still need to perform a backup of any "12" directory files that you might customize. Beyond that, you've got several options for how you structure, deploy, and undeploy the solution. They differ in how you handle NEW components and REPLACEMENT components (overwriting OOTB files in the "12" directory):

Option 1: Only include NEW components in the solution. In this case, you'll have to create a backup of the "12" hive and update/restore the replacement components manually on each server.
Option 2: Include new AND replacement components in the solution. As with option 1, you'll have to create a backup of the "12" hive and update/restore the replacement components manually on each server. Here, you must create the backup before deploying the solution!!!
Option 3: Include new, replacement, AND backup components in the solution. To make this one work well, you perform two steps in structuring the solution to include the backups: add a ".bak" to each file's name AND store the backups in a new subdirectory (i.e. store a custom version of LAYOUTS\error.aspx as LAYOUTS\originals\error.aspx.bak. When it comes time to retract the solution, it's now a 3-phase process:

On all servers - Copy the *.bak files to their original locations (but don't change the names)
Retract the solution
On all servers - Rename the *.bak files to their original names

I'm sticking with Option 3 for now, since it puts the "12" hive originals in source control, spells out very clearly to the development team which components have been customized, and minimizes installation effort. Option 2 sounds a little dangerous, since you could destroy "12" hive files if you didn't capture the original backup.

Along with the solution, I wrote a simple batch file to install the solution and activate the feature stapler. There's still some manual effort involved in updating the web.config to include the ResourceRedirect configuraiton, but it's a very minimal amount of low-level configuration work. There's also an uninstall script that's step 2 from Option 3. Note that both include PAUSEs, since it's essential that you wait for the solution deployment/retraction to complete before the script executes all tasks. The install script also uses the BrandingUpdate application from my previous posts.

Install Script

The install script also uses the BrandingUpdate application from my previous posts. Note that you'll need to execute the IISRESET on ALL farm servers, so you might want to include another PAUSE there to allow admins to complete that step on all servers.

echo off

echo Adding solution to farm...

stsadm -o addsolution -filename customizations.wsp

echo Deploying solution...

stsadm -o deploysolution -name customizations.wsp -immediate -allowgacdeployment -allowcaspolicies -force -allcontenturls

echo Please navigate to "Central Administration > Operations > Solution Management" to confirm deployment.

echo Once Customizations.wsp indicates a status of 'Deployed', hit any key to proceed with the installation.

pause

echo Activating feature stapler...

stsadm -o activatefeature -name BrandingStapler -url http://sites.contoso.com

echo Resetting IIS...

iisreset /noforce

echo Updating branding on existing sites...

brandingupdate.exe

echo Branding installation complete. Please update web.config settings for branding redirects in all applicable web applications.

Uninstall Script

Note that you'll need to execute the IISRESET on ALL farm servers, so you'll need to perform that on any other WFEs after the script completes. You still need to manage the deployment of "12" directory replacements as described above, either manually or through other scripts.

echo off

echo Retracting solution...

stsadm -o retractsolution -name customizations.wsp -immediate -allcontenturls

echo Please navigate to "Central Administration > Operations > Solution Management" to confirm retraction.

echo Once Customizations.wsp indicates a status of 'Not Deployed', hit any key to proceed with the uninstall.

pause

echo Deleting solution...

stsadm -o deletesolution -name customizations.wsp

echo Resetting IIS...

iisreset /noforce

echo Branding uninstall complete.

echo Please update web.config on all applicable web applications to remove branding redirects.

echo Please restore all original "12" hive files from backup copies.