Deploying a custom master page in SharePoint 2010

Lately I’ve been playing around with Visual Studio 2010 tools for SharePoint. I’ve been trying to come up with examples on how to use each of the available item templates.
Today I created a Module. A module can be used to deploy files to your SharePoint environment and the scenario I came up with was to use a module to deploy a master page.

  • I started out by creating an Empty SharePoint project. This can have any name you like and it can be both a farm and a sandboxed solution
  • Next add an new item to the project and choose a module
  • You can rename the module if you want to, I will leave the name at Module1
  • After the module is created it contains an elements.xml file and a sample.txt file. The sample.txt file can be renamed to sample.master.

Project structure
Project structure after adding a module and renaming the sample file to sample.master

I’m not a designer, so I wasn’t interested in creating a brilliant new design (good job, because I wouldn’t be able to do that!).
For the purpose of this example I just took the standard SharePoint 2010 master page contents.

  • Open up SharePoint Designer and open the site you are working on
  • Choose Master Pages on the left side
  • Open v4.master

Don’t let SharePoint fool you. There is a default.master, but this is the old SharePoint 2007 master page that is used if you perform a visual upgrade. When creating a site in SharePoint 2010 the master page that will be used by default is v4.master. I know it’s a bit confusing, but if you have been working with SharePoint for a while you won’t be surprised by this.

  • Copy the contents of v4.master and past them in your sample.master file in Visual Studio. Make the changes you want to.
  • Note how the elements.xml file has changed to reference the sample.master rather than the sample.txt

Contents of the elements.xml file 
The contents of the elements.xml file

  • Make sure the module is added to a feature in your project that is scoped at the site (= site collection) level

You could stop here and this solution will deploy your sample.master master page to the master page gallery of your site collection.
This will not apply the master page to the site collection when the feature gets activated though. It will only make it available for selection.

  • If you the master page to be applied when the feature gets activated you right click on the Feature1 and you add an event receiver. This will add a feature receiver file to the feature.
  • In this file we will add some code that will apply the sample.master master page when the feature gets activated and it will apply the v4.master when the feature gets deactivated.


[Update 10/12/2010]: Code updated because of improperly disposed SPSite and SPWeb objects. Thanks Donald Hessing and Rhys for pointing it out.

Code used in the feature receiver

Now if you activate the feature the code in the feature receiver will run and will apply sample.master to the site. As you can see we change both the MasterUrl and the CustomMasterUrl. The MasterUrl is used on all pages that are not publishing pages. This means it is used on the pages in the sitepages library and on the pages in the _layouts directory like the settings page for instance. The CustomMasterUrl is only used on pages that are stored in the Pages library. This library is created when the SharePoint Server Publishing Infrastructure features is activated on the site collection and the SharePoint Server Publishing feature is activated on the site.

You can also use the SharePoint user interface to apply a new master page. The Site Master Page is the equivalent of the CustomMasterUrl and the System Master Page is what the object model calls the MasterUrl.

Changing the master page using the SharePoint UI
Changing the master page using the SharePoint user interface

Comments -
  1. Gravatar

    Great post Mirjam, how about rolling back the masterpage customization upon feature de-activation. I like to keep a minimum foot-print for custom development where possible :-)

  2. Gravatar

    Great Post !!!!

  3. Gravatar


    Thanks Mirjan. It helped me to deploy master page successfully. However I had to remove 'Type' attribute in File to successfully activate the master page.


  4. Gravatar

    Sorry, it was my bad.


  5. Gravatar

    Hey Mirjan,

    This is great! I was just curious how you would add your CSS and images file to the project in order to deploy them as well??

  6. Gravatar

    Great post very helpfull! Just like Mirjan I would also like to know how to add css and images to the project.

  7. Gravatar

    Once I deploy, and refresh my site, i get a file not found error. It appears I have to manually set the default master page via SPD. What am I doing wrong?


  8. Gravatar

    I'm having the same issue as Bryan. Any ideas what is wrong?

  9. Gravatar

    Okay - I figured it out. There were 2 issues:
    1. The article doesn't explicitly state to copy all the info in the elements.xml file - you need to do that.
    2. You need to make sure that the URL and Path parameters in the elements.xml match what you're actually using. So, if you rename Module1, then make sure you update your file element.

  10. Gravatar

    I have an issue. I cannot see my master in list. If I activate the feature, I get a file not found error

  11. Gravatar

    Hi Anil,

    All I can say without more information is that you can check whether the name of the Module matches the file paths mentioned in the elements.xml file.

    Also check whether the master page is actually deployed to the SharePoint root folder (14 hive) on the file system and the Master Page gallery in SharePoint. If the file is not there something went wrong in your deployment.

    Hope that helps.


  12. Gravatar

    Hi Mirjam,

    How do you handle custom images and custom css files for the master page you just created? Do you create a separate module? How do you reference them?


  13. Gravatar

    Hi Mirjam,

    How do you handle custom images and custom css files for the master page you just created? Do you create a separate module? How do you reference them?



  14. Gravatar

    Help....can you create a master page in designer 2007 without having the sharepoint server 2007? We are using this for basic web access but would like to create a frame that stays on all pages.

  15. Gravatar

    Hi Jamie,

    You can only use SharePoint Designer 2007 if you are using SHarePoint 2007.

  16. Gravatar


    Great post! Would be awesome if you added how to include custom CSS and image files as most people would be needing to deploy those to the server when using a solution like this, but it is a great starting point!

  17. Gravatar

    Thank you so much for posting this information. It is very helpful.

    Like a few of the others, I, too, was not able to get the master page file itself to load into the master page directory. What step exactly causes the .master file to be copied? Everything else works perfectly and I was able to us SharePoint Designer to upload the master page manually to resolve the error.

    Thank you for your time and assistance,

  18. Gravatar

    I figured it out. As someone else had mentioned, there are a few changes that needed to be made the the elements.xml file for the module to specify the path of the master page library. The code provided is correct, but we have to add the additional statements, not just look at it to confirm the name had changed. It's such a small file that I missed that before!

    Thanks again for the post! Laurie

  19. Gravatar


    great article...
    I have created custom master page in the gallery by following your procedure.
    I am creating Custom Web Template Feature for creating new site collections in sharepoint 2010. Can we create Feature Stappling in Custom Web Teamplate Feature in SharePoint 2010.

    Thanks in advance

  20. Gravatar


    Unfortunately it's not possible to use Feature Stapling with Web Templates in SharePoint 2010.
    Also check out this post:


  21. Gravatar

    You shouldn't be disposing of properties.Feature.Parent!! Disposing of that object will kill the thread that the feature receiver is running in. Try comparing that object to your current SPContext and you will see for yourself.

  22. Gravatar

    I have followed this procedure but I get 266 errors when I deploy it from Visual Studio to my local SP server.

    All of the errors are relating to the code I copied from v4.master into my sample.master. I didn't even make any changes to the v4.master text that I copied into sample.master.

    The output log shows that it failed at the activate features step with this error:

    Error occurred in deployment step 'Activate Features': Unable to cast object of type 'Microsoft.SharePoint.SPWeb' to type 'Microsoft.SharePoint.SPSite'.

    Is deploying it by right clicking and selecting deploy the right way to to deploy this? I am new to SharePoint & Visual Studio :(

  23. Gravatar

    Also what does this line mean? How do I do this?

    •Make sure the module is added to a feature in your project that is scoped at the site (= site collection) level

  24. Gravatar

    Hi Mirjam, nice article and good explaination! I used your feature receiver in a CodePlex project. Of course I referenced you and your blog :-)

    Greetz Nick

  25. Gravatar

    During posting the last comment I noticed your comment time is not GMT +1. Maybe a wintertime issue :-)

  26. Gravatar

    SharePoint 2010 Starter Masterpage Feature with Mega DropDown Navigation Menu

  27. Gravatar

    errr Mirjam, I think your post has been ripped off and used here

  28. Gravatar

    unbelievable but as well

  29. Gravatar

    Thanks for letting me know Harish!
    I left comments and emails on both of them to ask them to take the content down.

  30. Gravatar

    Hmm can't get the feature to auto enable and once I manually enable, it uploads custom master page to the library but doesn't set it as the 'active' one.

    I'll look over the code again but I had trouble with the event receiver so I'm sure its somewhere in there. I couldn't write the code like you have it in the picture for VS2010.

    Also can anyone point me in the right direction for allowing this solution to be upgraded. This way I can upgrade the solution with new changes to the master page and it will change it for all sites... or is that feature stapling?

  31. Gravatar

    Hi Mirjam. I have a question. May be you know, how can I set a custom Master Page and to save a system Master Page as v4.master. What I was trying is curWeb.CustomMasterUrl = my custom master url and curMaster.MasterUrl = v4.master url. However, it doesn't work. Both Masters still v4.master. If I change a curMaster.MasterUrl to my master, both of Masters become my custom Master.

    Thank you

  32. Gravatar

    Hi Dima,

    The approach you suggest should work. You can try to see if there's something wrong in your code, or whether there is some weirdness in your site collection by trying to see what happens if you set the masterpage through the UI.

    Hope that helps.

  33. Gravatar

    I had to add ("http://" + curWeb.Url .....) for the url strings in order for my project to deploy from VS 2010. Otherwise, you get a deploy error that the URI is incorrect.

  34. Gravatar

    Great post.
    However, when i make changes to the MasterPage and then i re-deploy (update) the solution, it doesn't replace the old MasterPage. (doesn't overwrite it).
    Any ideas why it happens?

  35. Gravatar

    Thank You Sir

  36. Gravatar

    Error 1 Error occurred in deployment step 'Activate Features': Unhandled exception was thrown by the sandboxed code wrapper's Execute method in the partial trust app domain: An unexpected error has occurred.

    can anyone please help me in solving this erroe?

  37. Gravatar

    Hi Mirjam,

    I used this in a sandboxed solution which works well... thank you very much.

    I still have one problem: how do I log errors? Of course using try catch works but I can't use the new logging methods since they aren't available in sandboxed solutions.

    Would you suggest an own logging mechanism?


  38. Gravatar

    Hi Andreas,

    Logging functionality for the sandbox would be an ideal candidate to build as a full trust proxy that can be used by all sandboxed solutions. This does require that you have the ability to deploy that proxy, so it will only work on an on-premise environment and not on Office 365.


  39. Gravatar

    Nice blog!!

  40. Gravatar

    Hello Mirjam
    Thanks for this great post
    I need to change the master page of the login form on sharepoint foundation .
    Do you think I could apply this? I read everywhere that the master page for this login should not be changed and in this case I should do a specific login page (Which frankly I do not want to do as I just want to insert 2 images...)


  41. Gravatar

    Shouldn't you also specify the UIVersion and the Content Type?

  42. Gravatar

    Hi Dominique,

    You shouldn't change the out of the box login page or its master page. Changing the out of the box files is not supported and in this case could also get your users in trouble as it could mean that they are no longer able to access the login page and because of that are not able to log in.
    Indeed creating your own login page is a much better idea. Or you could just use the out of the box login page and forget about the two images :-).


  43. Gravatar

    change from
    catalog to catalogs i.e

  44. Gravatar

    To everyone asking about images and resources + linking:

    SharePoint boils down to a giant exercise in relative url mapping. There's basically two ways to accomplish this, and they are:

    Mapped Folders

    Mapped folders are obvious: localized resources deploy to 14/template/layouts/[language name,i.e.1033]/resource, and are referenced as /_layouts/[language name,i.e.1033]/[resource]. Non-localized resources are just dumped in the 14/template/layouts/ folder, so I'd recommend a subfolder for them.

    Modules are easy, but differ in implementation. They're feature specific solutions that store their url-mapped resources in the 14/template/features/starblazers65elcamino[i.e. your feature]/ folder. Here's an example

    <Module Name="Resources" Url="_catalogs/wafflesaurus">
    <File Path="Resources\Images\banner.gif" Url="banner.gif" />

    Omg confusing:

    URL = your map
    Name = folder name inside feature folder

    Path = Location in the SOLUTION where the file resides
    URL = SITE RELATIVE link to the item in the folder for use in sharepoint.

    You can get at the above resource one of two ways, but you only want to use the first:

    <% SPUrl: ~sitecollection/_catalogs/wafflesaurus/resources/banner.gif %>
    <% SPUrl: ~sitecollection/resources/banner.gif %> // DO NOT USE THIS ONE UNLESS YOU WANT TO POTENTIALLY GRAB THE WRONG INSTANCE

    Both of these resolve to the same place in this instance, but the second instance is subject to retrieving the wrong object should you have two modules that conveniently have a resources folder holding a banner.gif.

    I'll see about writing doing a full write up on it and check back.

    Here's a demo proj:

    Play around with trying to grab the right image via the address bar and you'll get the idea

  45. Gravatar

    Very useful.thx for ur post.

  46. Gravatar

    i have an article with guide step by step done a master page and page layout from html page:

  47. Gravatar

    Nice post....

  48. Gravatar

    Dear all, I added a custom logo and a footer on my custom master page but it cannot be displayed on other users. only on my account can be seen but on other users even with full control cannot be seen.
    <div style="clear: both; text-align: center; padding: 10px; background-color: #E5E5E5; width:auto">

    Copyright © Service Desk portal. All Rights Reserved.


    <SharePoint:SiteLogoImage name="onetidHeadbnnr0" id="onetidHeadbnnr2" LogoImageUrl="/_layouts/siteassets/my-logo.jpg" runat="server"/>

  49. Gravatar

    Can we deploy wiki pages with web parts as a feature. do u have any article or help.

  50. Gravatar

    Very Usefull.
    Thanks a lot .

  51. Gravatar

    If somebody wants to create custom master page you can follow the steps described in the article - SharePoint: How to create a custom master page - to create a ghostable copy of a built-in master page and get a full access to the Controls-collection due to subclassing.

  52. Gravatar

    Great post...thank you so much :)

  53. Gravatar

    Hi there

    I try to change the custom master page from outofbox. The existing site pages are changed with the new masterpage but when I click Create Site. The custom master page is not applied on that its same v4.master. Please help me.

  54. Gravatar

    One flaw in the feature deactivating that I noticed...or perhaps I just missed something. It doesn't remove the custom master page from the gallery. So if you deactivate the feature and then activate it again, it throws an exception.

  55. Gravatar

    Actually, LuLu is correct on that as well. If deploying this only impacts the root web. Subsites do not inherit the master page.

  56. Gravatar

    Ok, maybe this will help someone. Change the elements.xml file property for IgnoreIfAlreadyExists to TRUE. This will prevent the exception being throw if you activate the feature, deactive and then reactivate.

    Then, to make this work for any site and not just the root site of the site collection, change the feature scope to Web (instead of Site). Then in your feature event receiver, use code something like this:

    using (SPWeb curWeb = properties.Feature.Parent as SPWeb)
    Uri masterUri = new Uri(curWeb.Url + "/_catalogs/masterpage/custom.master");
    curWeb.MasterUrl = masterUri.AbsolutePath;
    curWeb.CustomMasterUrl = masterUri.AbsolutePath;

    and then something similar in the deactivation method to revert back to v4.master.

    You could get fancy and have your feature activation update the master page in all subsites, but that could get hairy if you have users that do not want to use the default branding.

  57. Gravatar

    Deploying a custom master page in SharePoint 2010

  58. Gravatar

    [...] ges. This means it is used on the pages in the sitepages library and on the page [...]

Comments have been closed on this topic.