Applying a Master Page Globally

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Module Url="_catalogs/masterpage" RootWebOnly="TRUE">
    <File Url="MyCustom.master"
      Name="MyCustom.master"
      Type="GhostableInLibrary"
      IgnoreIfAlreadyExists="FALSE">
      <Property Name="ContentType" Value="$Resources:cmscore,contenttype_masterpage_name;"/>
      <Property Name="PublishingPreviewImage" 
        Value="~SiteCollection/_catalogs/masterpage/Preview Images/Custom/CustomizedMasterPreview.gif, 
        ~SiteCollection/_catalogs/masterpage/Preview Images/Custom/CustomizedMasterPreview.gif" />
      <Property Name="Title" Value="MyCustom.master" />
    </File>
  </Module>
  <Module Url="_catalogs/masterpage/Preview Images/Custom" RootWebOnly="TRUE">
    <File Url="CustomizedMasterPreview.gif" Name="CustomizedMasterPreview.gif" Type="GhostableInLibrary">
      <Property Name="Title" Value="CustomizedMasterPreview.gif" />
    </File>
  </Module>
</Elements>

The next step is create a Feature Receiver. This is compiled code that will get fired when the feature gets activated and deactivated. Create a file called FeatureReceiver.cs in the root of your project. Add the following code:

using System;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Administration;

namespace GlobalMasterPage
{
  public class FeatureReceiver : SPFeatureReceiver
  {
    public override void FeatureInstalled(SPFeatureReceiverProperties properties) {}

    public override void FeatureUninstalling(SPFeatureReceiverProperties properties) {}

    public override void FeatureActivated(SPFeatureReceiverProperties properties) {}

    public override void FeatureDeactivating(SPFeatureReceiverProperties properties) {}
  }
}

The first thing to do is to create constants that point to the files we’ll be working with. We’ll be installing the custom master page in the same directory as the other site collection master pages, which is the /_catalogs/masterpage folder within SharePoint. (This is a virtual folder within the top level site; it doesn’t exist on the file system anywhere.) Add the following constants to your class:

const string defaultMasterUrl = "/_catalogs/masterpage/default.master";
const string customizedMasterUrl = "/_catalogs/masterpage/MyCustom.master";
const string previewImageName = "CustomizedMasterPreview.gif";

Now replace the FeatureActivating method with the following code:

public override void FeatureActivated(SPFeatureReceiverProperties properties)
{
  SPSite site = properties.Feature.Parent as SPSite;
  if (site == null)
    return;

    SPWeb rootWeb = site.RootWeb;
    rootWeb.AllProperties["OldMasterUrl"] = rootWeb.MasterUrl;
    rootWeb.AllProperties["OldCustomMasterUrl"] = rootWeb.CustomMasterUrl;
    rootWeb.MasterUrl = customizedMasterUrl;
    rootWeb.CustomMasterUrl = customizedMasterUrl;
    rootWeb.Update();
    foreach (SPWeb subWeb in rootWeb.Webs)
    {
      ProcessSubWebs(subWeb, true);
    }
}

private void ProcessSubWebs(SPWeb web, bool isActivation)
{
  if (isActivation)
  {
    web.AllProperties["OldMasterUrl"] = web.MasterUrl;
    web.AllProperties["OldCustomMasterUrl"] = web.CustomMasterUrl;
    web.MasterUrl = web.Site.RootWeb.MasterUrl;
    web.CustomMasterUrl = web.Site.RootWeb.MasterUrl;
  }
  else
  {
    DeactivateWeb(web);
  }
  web.Update();

  foreach (SPWeb subWeb in web.Webs)
  {
    ProcessSubWebs(subWeb, isActivation);
  }
}

First, we’re checkng to make sure the feature’s parent (in this case, site collection, exists. If not, exit and do nothing. The next step is record what the current master and custom master pages are for the top level site. We’ll add a property to the SPWeb to keep track of this information. Note: you do not want to use the Properties property of SPWeb, as this will only return a subset of properties. Instead, make sure you use AllProperties. By adding a property to the property bag, if it doesn’t exist, it will be created, and if it already exists, it will be overwritten. After we’ve done that, we can reset the root level site’s MasterUrl and CustomMasterUrl properties. You must call SPWeb.Update() or else the properties you added to the SPWeb will not be saved. Finally, after we’ve done that, we recursively iterate through all the child sites and point them to this top level site’s master page. (When you are finished, if you look at a child’s site’s Site Settings page for selecting a master page, you’ll see that the radio button is checked indicating it’s inheriting its master page from its parent.)

Easy enough. The next step is to write the code to deactivate the feature. This is slightly more complicated. Whereas we’re using the solution package to deploy the master page and preview image to the correct directory in the site collection, we’ll have to manually reset all the subsites back to their original master page (after we’ve determined if that master page still exists), then manually delete the custom master page and preview image.

Replace the FeatureDeactivating method with the following code:

public override void FeatureDeactivating(SPFeatureReceiverProperties properties)
{
  SPSite site = properties.Feature.Parent as SPSite;
  if (site == null)
    return;

  SPWeb rootWeb = site.RootWeb;
  DeactivateWeb(rootWeb);
  rootWeb.Update();

  foreach (SPWeb subWeb in rootWeb.Webs)
  {
    ProcessSubWebs(subWeb, false);
  }

  if (rootWeb.MasterUrl != customizedMasterUrl)
  {
    try
    {
      bool fileExists = rootWeb.GetFile(customizedMasterUrl).Exists;
      SPFile file = rootWeb.GetFile(customizedMasterUrl);
      SPFolder masterPageGallery = file.ParentFolder;

      SPFolder temp = masterPageGallery.SubFolders.Add("Temp");
      file.MoveTo(temp.Url + "/" + file.Name);
      temp.Delete();

      fileExists = masterPageGallery.SubFolders["Preview Images"].SubFolders["Custom"].Exists;
      SPFolder customFolder = masterPageGallery.SubFolders["Preview Images"].SubFolders["Custom"];
      if (customFolder.Files.Count == 1 && customFolder.Files[0].Name == previewImageName)
      {
        masterPageGallery.SubFolders["Preview Images"].SubFolders["Custom"].Delete();
      }
      else if (customFolder.Files.Count > 1 && customFolder.Files[previewImageName].Exists)
      {
        customFolder.Files[previewImageName].Delete();
      }
    }
    catch (ArgumentException)
    {
       return;
    }
  }
}

private void DeactivateWeb(SPWeb web)
{
  if (web.AllProperties.ContainsKey("OldMasterUrl"))
  {
    string oldMasterUrl = web.AllProperties["OldMasterUrl"].ToString();
    try
    {
      bool fileExists = web.GetFile(oldMasterUrl).Exists;
      web.MasterUrl = oldMasterUrl;
    }
    catch (ArgumentException)
    {
      web.MasterUrl = defaultMasterUrl;
    }

    string oldCustomUrl = web.AllProperties["OldCustomMasterUrl"].ToString();
    try
    {
      bool fileExists = web.GetFile(oldCustomUrl).Exists;
      web.CustomMasterUrl = web.AllProperties["OldCustomMasterUrl"].ToString();
    }
    catch (ArgumentException)
    {
      web.CustomMasterUrl = defaultMasterUrl;
    }

    web.AllProperties.Remove("OldMasterUrl");
    web.AllProperties.Remove("OldCustomMasterUrl");
  }
  else
  {
    web.MasterUrl = defaultMasterUrl;
    web.CustomMasterUrl = defaultMasterUrl;
  }
}

The first thing to do, as before, is make sure the parent site collection exist. Next, we’ll deactivate the top level site. Inside DeactivateWeb, what we’ll do is see if the “OldMasterUrl” property still exists in the web’s properties collection. If it doesn’t we have no alternative than to revert back to default.master. If we do find the OldMasterUrl property, check to make sure that the file it pointed to before still exists. (Note: although it would seem intuitive that accessing the Exists property on an SPFile object would return True or False, in fact, if a file doesn’t exist, it throws an ArgumentException error. Also, you can’t just call SPFile.Exists becuase it thinks you’re trying to set it’s value. That’s why I created a dummy boolean, simply as an excuse to trigger the error if the file (or SPFolder) doesn’t exist.) We follow the same exercise for the OldCustomMasterUrl property, (although we’re not explictly checking for existence. It seems safe to me if one of our custom properties are there, the other will be as well.) If one or both original master pages don’t exist in SharePoint any more at their old location, we revert back to default.master. Finally, we delete our custom properties because they are no longer needed. We then iterate through this same process for every child site.

Going back to our DeactivateFeature method, the next step is to delete our custom master page and icon from the /_catalogs/masterpage directory. Unfortunately, there seems to be an issue in SharePoint where you can not delete a master page that was installed by a feature, even if no one is referencing that master page. It will throw an error saying, “This item cannot be deleted because it is still referenced by other pages.” Luckily, I found a quick, although hackish, work around on “C-Dog’s .NET Tip of the Day” blog at http://www.dotnettipoftheday.com/Blog.aspx?Id=376. You have to move the page to another folder, then delete that folder. Also, we installed the preview image to a new folder called “Custom”. Although the foler is meant to house our custom image, it’s possible someone else could have added more content to it since it was created. If there’s nothing other than our custom image in it, delete the folder (along with the image); otherwise, just delete our image out of it. And that’s it… the feature receiver class is done.

Now it’s time to create the feature manifest. Create a file called feature.xml inside your GlobalMasterPage folder. Add the following XML:

<Feature xmlns="http://schemas.microsoft.com/sharepoint/"
  Id="400D8B01-1F64-46b4-A1DD-A1DA6A0E8E94"
  Title="Custom Master Page"
  Hidden="FALSE"
  Scope="Site"
  Version="1.0.0.0"
  ReceiverAssembly="GlobalMasterPage, Version=1.0.0.0, Culture=neutral, PublicKeyToken=a56f42ad8ea54585"
  ReceiverClass="GlobalMasterPage.FeatureReceiver">
  <ElementManifests>
    <ElementManifest Location="elements.xml" />
    <ElementFile Location="MyCustom.master" />
    <ElementFile Location="CustomizedMasterPreview.gif"/>
  </ElementManifests>
</Feature>

Several things to note: the Scope is “Site”, which means it’s applied at the Site Collection level. Secondly, notice that we are referencing our FeatureReceiver class, so that it’s fired when the feature is installed or uninstalled. You can also see that the custom master page and preview image files are being included in the ElementManifests section, along with the elements.xml manifest file itself.

Now it’s time to add the manifest file. It should look like this:

<Solution xmlns="http://schemas.microsoft.com/sharepoint/"
  SolutionId="AAB93B39-E127-4b90-B966-E6DC60D06C76"
  DeploymentServerType="WebFrontEnd"
  ResetWebServer="TRUE">
  <Assemblies>
    <Assembly DeploymentTarget="GlobalAssemblyCache" Location="GlobalMasterPage.dll">
      <SafeControls>
        <SafeControl Namespace="GlobalMasterPage" TypeName="*" Safe="True" />
      </SafeControls>
    </Assembly>
  </Assemblies>
  <FeatureManifests>
    <FeatureManifest Location="GlobalMasterPage\feature.xml"/>
  </FeatureManifests>
</Solution>

Looking at this, we can see that our DLL is being added to the GAC as well as the SafeControls node in the web.config, so it can be called and executed safely from within SharePoint. The manifest also points to the feature manifest.

Last but not least, modify your .ddf file so it looks like this:

.OPTION Explicit
.Set DiskDirectoryTemplate=CDROM
.Set CompressionType=MSZIP
.Set UniqueFiles=Off
.Set Cabinet=On

manifest.xml
bin\debug\GlobalMasterPage.dll GlobalMasterPage.dll

.Set DestinationDir=GlobalMasterPage
TEMPLATE\FEATURES\GlobalMasterPage\feature.xml
TEMPLATE\FEATURES\GlobalMasterPage\elements.xml
TEMPLATE\FEATURES\GlobalMasterPage\MyCustom.master
TEMPLATE\FEATURES\GlobalMasterPage\CustomizedMasterPreview.gif

Once you’ve finished compiling your code, you can load the .wsp file into SharePoint using the stsadm tool. When it’s time to deploy the solution, you can either deploy it to every web application in the farm, or to a particular site collection. Once it has been deployed to a site collection, you can browse to that particular site collection and activate the feature. You should see all the pages now skinned with your new master page. (Note: you can’t scope this feature for an entire farm, or even a web application, because the feature installs a master page into a particular top level site collection. If you try to scope it as “Farm”, SharePoint will throw an error. That means, the way this code works, you can deploy the code to every web application, but you have to activate the feature for each site collection. You could probably write another feature that activates this feature for each site collection, but that’s outside the scope of this blog post.)

You can download the source code here. Have fun and good luck.