Friday, July 9, 2010

Deploy a custom masterpage on SharePoint 2010 trough Visual Studio 2010 ! (Part-1)


Why the creators of SharePoint made it so hard to have an codebehind file for your master I really don’t get, but gladly there’s a way to do it.
This first part will describe how to deploy your own custom masterpage with Visual Studio. I'm not using SharePoint Designer and I like to code everything myself. With SharePoint 2010 and their masterpage uploading system I cannot easily use my own version-control system like subversion. With this work around it is possibleSmile

I will tell the steps I needed to do to get a codebehind file for my SharePoint 2010 masterpage.

Getting started

First of all, you need to get SharePoint 2010 installed and Visual Studio 2010.

Next open Visual Studio 2010 and create a new Project.
I choose the language Visual C# on the left, then selected SharePoint --> 2010 and then create an Empty SharePoint Project.
I named the project: MasterPageWithCodeBehind.

After clicking the OK button, you will be asked how and where you want to deploy it, I choose to Deploy it as a farm solution.


Right-click on the SharePoint Project in your Solution Explorer on the right then --> Add --> New Item.

You'll get a new window where you can choose multiple items. I created a module and called it MasterPageModule.

You'll see that the module is added to your project with a sample file called Sample.txt. There's also an Elements.xml file in the module, in this file the other files will be registered. I deleted the Sample.txt in my Solution Explorer and Visual Studio automatically removed it from the Elements.xml file.

The next step I did was copying my custom masterpage into the module. This can be done by copying the file from Windows Explorer en then right-click on your Module in the Solution Explorer. I used the masterpage from Randy Drisgill. You can get his minimal masterpage here: Starter Master Page. His blog with very useful tips is: Randy Drisgill SharePoint Branding and Design

After I paste it into my Module my Elements.xml looks like this:
xml version="1.0" encoding="utf-8"?>

<Elements xmlns="">

<Module Name="MasterPageModule">

<File Path="MasterPageModule\_starter.master" Url="MasterPageModule/_starter.master" />



In Module this attribute needs to be added: Url="_catalogs/sharepoint".
In File the Url attribute needs to be changed as follows: "_starter.master"
In File also this attribute needs to be added: Type="GhostableInLibrary".
This will make sure that the file will be cached. More info here.

My Element.xml looks like this now:

xml version="1.0" encoding="utf-8"?>

<Elements xmlns="">

<Module Name="MasterPageModule" Url="_catalogs/masterpage">

<File Path="MasterPageModule\_starter.master" Url="_starter.master" Type="GhostableInLibrary"/>




In this beta of Visual Studio 2010 a feature is automatically created when I added a Module into the solution. If not you have to create a feature yourself, here’s how you do it: (if there’s automatically added a feature you can skip it and move to the next part)

The final step to do is creating a feature that will configure the masterpage.
Right-click on Features in your Solution Explorer and click Add Feature.

Now a new Feature is created, and the properties window of that Feature has popped up. Underneath the Title, Description and Scope there are 2 large fields. On the left you'll see the created Module, add this to the left and it should look like this:


Next I right-clicked on the Feature1 and then --> Add Event Receiver.

A new window will be open with the content of Feature1.EventReceiver.cs.
Uncomment these methods:

  • FeatureActivated
  • FeatureDeactivating

The code underneath will overwrite the MasterPage variables.
When it is deactivated it will restore the values back to a default SharePoint masterpage.

The code:


// Uncomment the method below to handle the event raised after a feature has been activated.

public override void FeatureActivated(SPFeatureReceiverProperties properties)


SPWeb currentWeb = (SPWeb)properties.Feature.Parent;

currentWeb.MasterUrl = "/_catalogs/masterpage/_starter.master";

currentWeb.CustomMasterUrl = "/_catalogs/masterpage/_starter.master";



// Uncomment the method below to handle the event raised before a feature is deactivated.

public override void FeatureDeactivating(SPFeatureReceiverProperties properties)


SPWeb currentWeb = (SPWeb)properties.Feature.Parent;

currentWeb.MasterUrl = "/_catalogs/masterpage/nightandday.master";

currentWeb.CustomMasterUrl = "/_catalogs/masterpage/nightandday.master";




End of part 1

When this will be deployed, the custom masterpage is loaded instead of the default without uploading/publishing a masterpage trough the web interface, pretty neat huhSmile.

Your SharePoint 2010 site should look something like this now (if you used the same masterpage as I did):


This is the first part of how to create a code-behind file and this part is focused on how getting the fundamentals right. The result of following part 1 is a alternative manner to deploy a masterpage.

1 comment:

  1. Very cool article, let me introduce you this is an online tool where you can easily customize a theme for all SharePoint versions among other cms platforms, it doesn't require any code from the user and its very intuitive, take a look.