How to use assembly redirection in WSP’s

This article was posted on my previous blog located at in February. I moved it here.

Assembly redirection, a technique already introduced and available since the first versions of the .NET framework, is in my opinion not widely used in our line of work.
Sure, product suppliers like Microsoft itself use it frequently during updates, but somehow I have not come across this too often in my career.

To explain the concept of assembly redirection is a little bit beyond the scope of this blog, but I would like to elaborate on using this when using it with SharePoint 2007 WSP’s.

In large projects, especially with a lot of users in an already live environment, executing updates on the platform should be done with care and clear preparation. This is even truer when the update at hand involves shared frameworks, which multiple other projects use and you do not have direct control over. Of course, one could update the component without changing its version number and strong name, but this would not be very good practice, as version management and maintenance become much harder, if not impossible. The answer, of course, is assembly redirection.

Assembly redirection involves a technique to forward a particular method call to another assembly at runtime. For example, an application is bound to version of your component. When updating, you increment the version number to When published, the application will still use version of the assembly if it is still available. If not, it will break. Using assembly redirection, you can forward the call to your version and even remove the version. This would automatically upgrade any application that referenced it and in the process, you make sure the latest version is used.

One very important aspect of this method, is that you have to ensure, no guarantee, that you are backwards compatible.  Not doing this is bound to introduce problems. Secondly, you should not change the definition of the method in doing something completely different than its original scope, which could lead to unexpected behavior of its clients.

That said, how does this relate to SharePoint 2007? Well, suppose I have a SharePoint middleware layer that executes various common functions, on top of which SharePoint application are build. Using good practice, I publish this layer to the SharePoint platform using a WSP (or multiple), which in turn configures SharePoint (for example the SafeControls) and publishes the assemblies to the Global Assembly Cache. When time passes, I would like to update the framework by introducing new features (which would lead to a version increment) and bug fixes. I would then publish an updated WSP, which will retract the old one (and thus removing the configuration and the assemblies from the GAC) and install the new one. Doing this without assembly redirection will break all applications that reference the assemblies.

Ok, so, just include an assembly redirection policy, you think. That is where the trouble starts. To install an assembly redirection policy in the GAC, you need to convert it into an assembly, as the GAC only accepts assemblies. There are many articles on the internet that describe how to create such an assembly, so I will not go into that here. I use, like many others, WSP Builder (or its Visual Studio Extension) to create my WSP’s. If I include the policy assemblies in the GAC folder, WSP builder will also package that. Well, so far so good. When I install this WSP into SharePoint, it will result in an error, stating that the policy assemblies could not be published into the GAC. This is caused by a simple caveat in using policy assemblies. Because they are not ‘real’ assemblies in the true sense of the word, they are only allowed to be published to the GAC, if the original configuration file that was used to create the assembly, is located in the same directory. And the WSP omits this file. The current version of WSP builder does not include .config files when packaging, even if they are located in the same directory.

There are several ways in solving this problem. You could create your WSP manually, be writing the correct DDL that does includes the config files in the root of the WSP. You could modify WSP builder (as it is open source) to include these config files in the root of the WSP. I however, choose the outside approach. As a WSP is just a cabinet file with a different extension, I created a small app that uses cablib.dll (just like WSP Builder) to modify the created wsp and insert the config files at the root. This has two advantages:

  1. The config files are only needed during install, so using this method would avoid the config files being included in the manifest.xml and therefore permanently stored on the file system.
  2. I can choose whether or not to include the config files, or even update them afterwards, without rebuilding the WSP.

After this, the WSP installs just fine and the policy assemblies are included in the GAC, ensuring proper rerouting of method calls to old assemblies, therefore automatically upgrading any dependent applications in the SharePoint landscape.

A couple of final notes on the redirection part:

  1. Create one policy assembly for each version you wish to reroute. You cannot reroute multiple versions from within a single policy assembly.
  2. The naming of the policy redirection assembly is very strict and follows naming conventions. Not following these conventions will result in your assembly not being redirected.
    policy.<major>.<minor>.<assembly name>.dll
  3. Ensure that you only use the major and minor versions in the AssemblyVersion attribute. Build and revision numbers should never be included in the AssemblyVersion attribute, but in the AssemblyFileVersion attribute. For example:
    AssemblyVersion, AssemblyFileVersion 1.0.010043.0 (day 43 in the year 2010)
    AssemblyVersion, AssemblyFileVersion 2.1.010043.1

Assembly references are made using the AssemblyVersion attribute, thus giving you the possibility to publish bug fixes (which only increment the build and revision numbers), without the need for a policy redirection assembly.

Hope this can be of use to you. Let me know your thoughts! Any comments are appreciated.

How to add the quick launch to the default Web Part Page templates

This article was published on my previous blog located at in January. I moved it here.

One day, one of our end-users raised the question why the quick launch navigation bar was not visible when adding a new page to an existing site. The user chose the Web Part Page in the Create menu to create a new web part page on the site. After creation, the new page did not show the quick launch bar.

 When diving into the issue, indeed, the standard out-of-the-box page templates (8 templates) do not include this bar. To me, this was quite strange, as I could not think of any reason why this would be desired. Nevertheless, when researching the page templates, the default templates override the master page to omit the quick launch navigation bar. And so, the journey to have them added begins.

 How are the standard Web Part Page templates called and referenced?

Upon first research I found that the standard 8 templates are hard referenced in a page called spcf.aspx by the create.aspx page. The create.aspx page is the page shown when clicking Create from the Site Settings menu. The Web Part Page option points to a file called spcf.aspx which shows the New Web Page dialog that includes the page layout selection. On this page, 8 page layout options are available by default, dividing the available space in several web part zones in different layouts. The available templates are hardcoded in this page.

 Possible approaches

There are several approaches one could take in solving this. For example:

1.       Locate the standard page templates on disk and modify them

This involves opening the standard page templates in an editor like Visual Studio, look up the overrides off the content placeholder where the quick launch navigation bar resides in the master page and remove them.

2.       Keep the existing page templates, but make copies

This involves copying the existing page templates, rename them and then edit them and remove the overrides. Disadvantage would be that we have to change the spcf.aspx page to reference the new templates instead of the standard ones, as these are hard-coded.

3.       Keep existing page templates and spcf.aspx, but make copies

Same approach as option 2, but also copying the spcf.aspx page and rename it. This would introduce another disadvantage that we have to change the create.aspx as the spcf.aspx is hard referenced in there.

Several other approaches using Javascript on the client with iframes are also an option, but I was looking for a neat solution on the server, without using Javascript. All of these options involve changing default out-of-the-box files of SharePoint, which could lead to problems when applying service packs or hot fixes, as well could cause limited support on the standard installation by Microsoft. Option 3 is described by Paul Papanek in his blog found here:

 How to do it without changing any of the standard SharePoint files?

At my current customer, we have several restrictions when applying modifications to the SharePoint landscape. First, none of the out-of-the-box files are allowed to be touched. Secondly, any modifications to the system must be done through a feature packaged in a WSP.

These restrictions rule out all the approaches described above. Secondly, it removes the possibility for creating Web Part Pages without the navigation, for which there could be valid reasons. I have found a way to include them, without touching the OOB files and still honoring the restrictions I had. To be fair though, it is a mere extension of the approach that Paul describes in his blog, so also credits to him. Now, without further due, let us continue to the solution.


There are several steps that need to be taken, which I will describe in detail below. Let us first outline the steps:

1.       Create a new Visual Studio empty solution that will host your new feature.

2.       Copy the standard page templates and rename them

3.       Edit the renamed templates to include the quick launch again

4.       Save the preview images for all the standard templates to a location which you can find later

5.       Create a new spcf.spx page based on the standard one and modify it to reference the new layouts

6.       Create an additional menu option on the Create page to point to your new spcf.aspx page

7.       Package all the files into a feature

8.       Package the feature in a WSP

 Create a new Visual Studio empty project that will host your new feature

Within Visual Studio, create a new empty project to host your new feature. You can use any project type you are accustomed with to create SharePoint features, I just use an empty project. I also use the WSPBuilder extensions to create a WSP, but creating the WSP is out of scope of this blog.

Within your project, create a folder structure to represent your 12 hyve that includes all the locations where we will deploy files, as shown in the attachement PageLayouts Image 1.png

Copy the standard page templates and rename them

The standard Web Page Page Layouts are located in the 12\Templates\1033\STS\DOCTEMP\SMARTPGS directory, where 1033 stands for English. If you have another language version installed, please replace 1033 with the language identifier installed.

In there, you will find 9 files, of which 8 are aspx pages, called spstd1.aspx through to spstd8.aspx. Make a copy of these files and include them in your project in the same folder. Make sure you rename them to any name you wish, but keep the number suffix, for example, avanade1.aspx.


Edit the renamed templates to include the quick launch again

Open each file in Visual Studio and remove the following lines to add the quick launch again:

asp:Content ContentPlaceHolderId=”PlaceHolderLeftNavBar” runat=”server”>asp:Content>

asp:Content ContentPlaceHolderId=”PlaceHolderNavSpacer” runat=”server”>asp:Content>

Save and close each file.


Save the preview images for all the standard templates

To preserve the preview image for each page template, we copy the preview images for each template to our solution. The preview images are located at 12/TEMPLATES/LAYOUTS/1033/IMAGES and are called SPSTD1.gif to SPSTD8.GIF. Rename the images to the same name used for the templates in previous steps, for example avanade1.gif.


Create a new spcf.aspx page based on the standard one and modify it to reference the new layouts

 Paul Papanek included a custspcf.aspx on his blog that also removes the limitation of 8 templates, as the current 2007 implementation of spcf.aspx does. It is therefore recommended to use the one provided by Paul as the basis. You can download it from here You can also copy the existing one from 12/TEMPLATES/LAYOUTS/1033, where again, 1033 is your language identifier.

 Include the file in your project and open it in the editor. You may rename the file to any name you want, I just use custspcf.aspx to keep the relationship to spcf.aspx intact. There are a couple of things that you need to change in this file to make it work with your newly created template and images. Do a search on ‘custom1’ and replace all the references to this with the name of your own custom templates, in our example I would replace ‘custom1’ with ‘avanade1’ and so on. 

Also find the

 SELECT id=”onetidWebPartPageTemplate” name=”WebPartPageTemplate” size=”2″ onchange=”DoTemplateOptionChange()”>

 tag, which includes all the possible template options. In the file downloaded from Paul, only two exist. If you take the one from the original spcf.aspx, you will find 8 options.  Modify the ‘size’ attribute to reflect the number of copied templates, in our case 8. I added the options exactly as they were in the original file, just renamed the template names, as shown below:

 SELECT id=”onetidWebPartPageTemplate” name=”WebPartPageTemplate” size=”8″ onchange=”DoTemplateOptionChange()”>

  OPTION value=”avanade1″>Full Page, VerticalOPTION>

  OPTION value=”avanade3″>Header, Left Column, BodyOPTION>

  OPTION value=”avanade4″>Header, Right Column, BodyOPTION>

  OPTION value=”avanade2″ selected=”true”>Header, Footer, 3 ColumnsOPTION>

  OPTION value=”avanade5″>Header, Footer, 2 Columns, 4 RowsOPTION>

  OPTION value=”avanade6″>Header, Footer, 4 Columns, Top RowOPTION>

  OPTION value=”avanade7″>Left Column, Header, Footer, Top Row, 3 ColumnsOPTION>

  OPTION value=”avanade8″>Right Column, Header, Footer, Top Row, 3 ColumnsOPTION>


 In fact, most of the work is now done. The only thing left is ensure that we can call our new pages from the Create page in the SharePoint UI.

Create an additional menu option on the Create page to point to your new spcf.aspx page

Most menus in SharePoint can be extended with custom actions, like context menus, the Site Actions and so on. This is because these menus also use the FeatureLinks feature that allows additions to this menu. We will use this to add our custom option to the Create page.

Create a feature.xml within our feature folder in our solution, in my case called Avanade.PageLayouts.  The contents of the feature.xml is shown below:

<?xml version=”1.0″ encoding=”utf-8″?>
  Title=”Avanade – Custom Web Pages Menu Option”
  Description=”Enables a custom menu item for creating Web Part Pages with quick Launch navigation.”
    <ElementManifest Location=”CustomWebPages.xml” />

The feature refers to an ElementManifest called CustomWebPages.xml which will include the menu option. In my case, I scoped the feature to Farm, enabling the custom templates across all sites in the Farm. You can use WebApplication, Site or Web scope if desired.

The contents of CustomWebPages.xml is shown below.

<xml version=”1.0″ encoding=”utf-8″?>
<Elements xmlns=”“>
        Title=”Web Part Page with Quick Launch”
        Description=”Create a Web Part Page with quick launch navigation”
    <UrlAction Url=”_layouts/custspcf.aspx” />

 Within this file, we define a custom action with the following attributes:

Id: Identifies your custom action
Title: Is shown in the user interface as the menu option
Description: Is shown on top of the page as description of the menu option
Location: Determines the location (page) to apply the custom action on. In our case, this refers to the Microsoft.SharePoint.Create location, which is the Create.aspx page.
GroupId: Identifies the menu (column) to add the option to, in our case the ‘WebPages’ column.
UrlAction: Identifies the page called when clicking the menu option, in our case, this should point to our newly created custspcf.aspx page, which completes the circle.

 That’s it! Only thing left is to package the feature into a WSP to facilitate easy distribution and installation. If you do not use a WSP, you should also include an ElementManifest to deploy the different files to their location. When creating a WSP from this folder structure, WSPBuilder will take care of the deployment of the files for you.

I hope this could be of use to you.  Happy coding!

SharePoint's Booming world

%d bloggers like this: