Site Definitions vs. Web Templates

The site definition vs. web template vs custom code discussion is a very old and ever returning discussions. There are at least four different approaches:

  1. Creating full blown custom site definitions
  2. Creating custom empty or blank site definitions and provisioning those with (stapled) features and code
  3. Creating site templates
  4. Using custom code

I think it is safe to say that the first option is a bit out of date. Creating full blown site definitions requires writing a lot of tedious XML in the onet.xml and schema.xml files. Microsoft has advised against this approach for some time now and that message has gotten a lot stronger with SharePoint 2010 and the new WebTemplate feature.

The second option is still a valid option. This option means you strip a site definition to its bear minimum. All list instances, modules and web parts will be removed from the onet.xml to make the onet.xml as small and readable as possible. The functionality can be added to the empty site by using features in the site definition, stapled features or code in a feature receiver. The best options are the stapled features and the code in the feature receiver. A combination of the two can also be a good solution.

When choosing between defining a feature in the onet.xml and stapling a feature to a site definition you might want to consider the provisioning order of a site definition:

  1. Create the url for the site
  2. Provision the GLOBAL onet.xml
  3. When creating a new site collection - Activate site collection (SPSite) scoped features that are defined in the onet.xml, when creating a new sub site – verifying that all site collection scoped features are activated
  4. Activate site collection scoped stapled features in random order
  5. Activate sub site (SPWeb) scoped features that are defined in the onet.xml
  6. Activate sub site scoped stapled features in random order
  7. Create list instances defined in onet.xml
  8. Create modules defined in onet.xml

The third option is using site templates. In SharePoint 2007 site templates could only be created by using the “save site as template” option from user interface of the site settings menu. Saving a site as a template would create a .stp file, which was called a site template. In SharePoint 2010 we can still save sites as templates, but now it will create a .wsp file. Yep, that’s right, saving a site as a template creates a real SharePoint solution. The generated .wsp solution can be imported into Visual Studio 2010 and edited from there, but unfortunately the imported solution will contain all content types, site columns and properties that were available within the site, even if they weren’t actually used. This creates a lot of clutter and a pretty unmanageable solution. The novelty that makes saving a site as a .wsp solution possible is the WebTemplate feature element.

The WebTemplate feature element can also be used to create your own web templates, without saving a site as a template. Just like site definitions, site templates in SharePoint 2010 require an onet.xml file. However, instead of the webtemp.xml file you will use a feature with the WebTemplate element. In the WebTemplate element you will define a BaseTemplateName, a BaseTemplateID and a BaseConfigurationID. In the example below the BaseTemplateName is STS, the BaseTemplateID is 1 and the BaseConfigurationID is 0. Die-hard SharePointeers will recognize the template name and configuration id and know that the basis for the site template we’re creating is the Team Site. The name and title of this site template will be My Fancy Web Template, so this is what will be displayed as the title of the template when you’re creating a new site. The category where you can find the site template in is Fancy Sites. A lot of the other properties can be left out if you’re creating your own site template, I just wanted to list them all in here for your reference.

<Elements xmlns="">
    AlternateCssUrl =""
    AlternateHeader =""
    BaseConfigurationID ="0"
    BaseTemplateID ="1"
    BaseTemplateName ="STS"
    CalendarType ="1"
    ContainsDefaultLists ="TRUE"
    Description="Site with a lot of fancy features."
    DisplayCategory="Fancy Sites"
    Name="My Fancy Web Template"
    Title="My Fancy Web Template" 
    UIVersionConfigurationEnabled="FALSE" >    

A web template feature can be site or farm scoped. If it is site scoped it can be deployed as a sandboxed solution. This way you can easily create sub sites based on the site template. If a site collection has to be based on the site template and you still want to deploy the site template as a sandboxed solution you can use the following steps:

  • You can first create the site collection without a template by selecting Select template later in the Custom template category
  • After creating the site, browsing to the site will redirect you to the template selection page
  • At the bottom of the settings page a link to the Solution Gallery is displayed
  • Click on the link and upload the sandboxed solution containing the site template
  • Activate the solution
  • The site template can now be selected and the site creation will be finished

You can also create a site based on a web template by using custom code. You simply use [Feature Guid]#[Web Template Name]. Spaces in the web template name are no problem.

The good thing about web templates is that they are based on one of the standard SharePoint site definitions and that they are stored in the database. This means that they will be easier to upgrade then a site definition would probably be. Another advantage of site templates is that they can be deployed as sandboxed solutions. These should be your main drivers for using site templates.

There are a couple of things that you can use in site definitions that aren’t available in site templates.

  • Module elements
         * This means you can’t provision aspx pages by using the modules element in the onet.xml. Instead you can use features and feature receivers to provision your aspx pages and place web parts on them. This is a best practice anyway. Using features for you modules gives you more flexibility and also enables you to control the provisioning better. It will for instance enable you to make sure that adding the default.aspx page to the site isn’t the last step in the site creation process. Since using features is a great alternate approach for the modules in the site definition not being able to use modules in site templates is not a big deal.
  • Components elements. The components element can contain two child elements that are both optional and cannot appear more than once. Both elements are rarely used, so not being able to use them in site templates won’t be a problem for most people.
         * FileDialogPostProcessor – this is a class that is used to modify the file open and save dialogs on a document library. If you save a file directly from Office to a document library you will get a web interface and in the FileDialogPostProcessor you can declare a class that modifies that interface.
         * ExternalSecurityProvider – represents an interface that returns custom information about the security used in Microsoft SharePoint Foundation for indexing by a search crawler on a portal.
  • ServerEmailFooter
         * This element can be used to define a footer section for email sent from the server. This element is also rarely used, so not being able to use it won’t be a big disturbance.
  • Stapled features
         * Now this one is a bit nasty. When creating site definitions the advice is to use stapled features for adding features and functionality to sites that are created based on the site definition. The nice thing about this is that you don’t have to add the features to the onet.xml, you can simply create a stapling feature and link the site definition and the features in there. You can’t do this in site templates. I really hope this will be made possible later on, but for now we will have to add the features directly to the onet.xml of the site template. 

Because of these limitations the provisioning order of a site template will be:

  1. Create the url for the site
  2. Provision the GLOBAL onet.xml
  3. When creating a new site collection - Activate site collection (SPSite) scoped features that are defined in the onet.xml, when creating a new sub site – verifying that all site collection scoped features are activated
  4. Activate sub site (SPWeb) scoped features that are defined in the onet.xml
  5. Create list instances defined in onet.xml

The fourth option is to not create any custom site definitions and site templates and provision the whole site by using code. The nice thing about this is that it means not having to write any XML. Of course it does mean that you have to write a lot of custom code. You also need a way to trigger the code that will provision your site. This can be done in a feature receiver of a feature that is for instance added to the blank site definition (keep in mind that you can’t staple to the out of the box site definition). You can also create a custom site creation page that users will use to create their sites and that will fire of your code.
The all custom code approach is often used when sites are created by an automated process like a workflow, or for instance by a trigger from an external application. At Macaw we see a lot of use cases where the site creation process is triggered by a button or a change in Microsoft CRM.


Creating full blown site definitions and writing a lot of XML for the onet.xml file is not the best option. One of the reasons for this is of course that writing a lot XML is no fun, difficult to debug and very error prone. Another, perhaps even better reason, is that site definitions like this will almost certainly give you a headache when you want to upgrade to the next SharePoint version. Microsoft has been warning people for a while that eventually they will stop supporting site definitions. And it definitely looks like with the WebTemplate feature, they made the first step in that direction.

Using minimal site definitions with features and feature receivers is still an option that can be used. A reason for choosing this approach over the site templates approach could be if you need to use a lot of stapled features.

With the new WebTemplate feature in SharePoint 2010, the use of site templates will dramatically increase. If you are not bothered too much by the limitations of the site template this is a better bet than using site definitions. Mainly because it will make a future upgrade easier. The fact that you can deploy a site template as a sandboxed solution and thus only make a template available within a certain site collection can also be a benefit.

The custom code solution is also a valid approach. I would personally mainly use this when sites are created using automated processes. Of course approach two and three can also use custom code in feature receivers to add functionality to a site. A good reason to use this would be if you need to create list instances and add content types to them. I feel it is way easier to do this in code than to write that out using XML.


So..still not a clear and definitive answer, but I hope I was able to clarify the considerations for the different options in this post.

[Update] Microsoft Architect Vesa Juvonen also wrote a great blog post on site definitions and web templates I would advise you to read his post carefully..

Comments -
  1. Gravatar

    Well done. Great considerations. We need something that maps a set of requirements that takes us through when a site definition is required over when a site or web template will do.

    The debate continues...

  2. Gravatar

    Hi Joel (and Wouter),

    Thanks for the comments.

    I actually didn't mean for this post to be a discussion. As with everything in SharePoint I don't think there is a right or wrong. The right approach will depend on the scenario you're working on.


  3. Gravatar

    Hey Mirjam,

    great post! can you use web templates with my site host and my sites as well?


  4. Gravatar

    Well, looks like I need to use feature stapling for the personal sites. The My Site Host should work with the web template approach.


  5. Gravatar

    Hi Rob,

    Indeed you can use web templates for the My Site host, allthough you can't really remove anything from it, because you might break stuff. Also end users don't actually browse to this site, because they will be automatically redirected to their my sites if they try to.

    For the my sites itself you can use a couple of different approaches, depending on what you want to achieve. Indeed, feature stapling is one of them. Steve Peschka wrote a great post on thie for 2007. Most of what is in there is still valid.
    The post can be found here:

    Hope this helps.


  6. Gravatar

    Excellent post. Based on comments we'll need to continue explaining this provisioning option more detailed to ensure that advantages are truly understood.

  7. Gravatar

    &#191;Definiciones de sitio o plantillas de sitio? &#191;Ser o no ser? Una pregunta dif&#237;cil de responder. Recientemente

  8. Gravatar

    Hi Mirjam, nice overview. I was looking for info on webtemplate feature, and agree that not being able to staple features are really a show stopper for the usability of webtemplate feature.
    For the code option dont forget custom provisioning providers! They are real nice when you want to put "finishing touches" on your site after it was created. This could include setting policies, creating sub sites, setting default pages, activating features, page layout restrictions, configuring web parts etc.

  9. Gravatar

    I would be glad to ditch custom site definitions. What about good ol' WCM sites using publishing feature? There isn't Save as Template action avaible in site settings. _layouts/savetmpl.aspx url will save the wsp-template but creating news sites with this template breaks stuff. Is this supported? Do I need to go back to the custom site definitions - again?

  10. Gravatar

    Hi Jani,

    You can't safe a publishing site as a template, but you can create your own site templates that are based on publishing sites. Totally supported and no need to use custom site definitions if you don't want to.


  11. Gravatar

    Thanks Mirjam! I created webtemplate based on CMSPUBLISHING site definition and it worked :) I'm quite happy with this approach, it makes site deployment a lot easier than before.

  12. Gravatar

    your answer:
    Hi Jani,

    You can't safe a publishing site as a template, but you can create your own site templates that are based on publishing sites. Totally supported and no need to use custom site definitions if you don't want to.



    Hi Mirjam,

    do you have a good link or instructions how to create your own site templates based on publishing sites??
    Or even a Walkthrough lap??

    would be nice if you can help me :)

  13. Gravatar

    Hi Christian,

    Check out Vesa's blog post mentioned (and linked to) at the bottom of my post. That post has an overview of how to create a web template that uses publishing features.


  14. Gravatar

    I have a solution to make advantage of the site definition and the saved site template. Please check the acticle on MSDN:

    As you said, there is no much articles talked about the solution, so please help give your oppinions on this solution and suggestions also. Thanks.


  15. Gravatar

    I keep getting almost daily emails concerning WebTemplate element support and when it would be proper

  16. Gravatar

    Hi Mirjam,

    Thanks for sharing your thoughts on this matter, which is still rather confusing stuff for me ;-)

    An important reason for me to choose one solution over the other is the opportunity to later be able to automagically update/change (many) sub sites by chaging only one central code.

    In one site collection f.i. I have many sites initially based on a "master" site template.
    What I did was create the "perfect" site, save that site as template (.wsp) and create the other sites from that template.

    However, the "master" does not stand the test of time and is no longer "perfect", but is of course subject to change.
    Changing the master template however does not immediately change all the sub sites even if they are based on the same template.
    To realize this I have to use batch commands in Powershell in conjunction with lots of clicking in the GUI for each site...

    What setup would you advise for such a scenario in which you have to keep sites aligned and similar, which I think is rather common?
    Is it true that this can be realized by using site definitions instead, in the sense that whenever you change a site definition all sites based upon that site definition change accordingly automagically?

    Much much obliged,

  17. Gravatar

    Hi Waldemar,

    None of the approaches (web templates, site templates, site definitions, custom code) will automagically update existing sites when the template/definition/code is changed. For site definitions it is not even supported to change them after sites have been created based on it.
    The only way you can update existing sites is by writing a custom script that updates existing sites.
    You are right about the fact that this is a pretty common requirement, but unfortunately there is no easier way to achieve this.

    The best thing you can do is to create a scheduled task or timer job that iterates over all your sites checking the template and version that the site is based on and making the necessary updates to the site. Be aware that in a large environment this might take a significant amount of time and that you will have to store the template and the version of the template that the site is based on will have to be stored in the site somewhere. I recommend using a site property for this. Also, when you run the update script this will have to adjust the version number for each site.

    Hope that helps.

    Kind regards,

  18. Gravatar

    Hi Mirjam,

    Thanks a lot for your answer.

    A few last questions to completely understand:

    Apart from being supported or not, would changing site definitions indeed deliver the wanted functionality at all?
    I mean, is it thinkable that then sub sites indeed would automagically change?

    Is it also not supported to change CUSTOM made site definitions (instead of out-of-the-box site definitions)?


  19. Gravatar

    Hi Waldemar,

    Changing a site definition in most cases won't change an existing site that is based upon it. Pretty much the only thing that could change are the web parts zones defined in your default.aspx page if you are provisioning your default.aspx page from the sitetemplates folder. Everything you change in the ONET.XML won't be reflected in existing sites.

    It is not supported to change a custom site definition that has been used to create sites. It is not supported to change the out-of-the-box site definitions at all, regardless whether they have been used to create sites or not..


  20. Gravatar

    Thanks for detailed explanation of differences between Site Definitions and Web Templates. Nonetheless, I still prefer using approach based on Site Definition.

  21. Gravatar

    Hi Mirjam,

    Firstly, we all really appreciate the great posts you put together.

    Can you give me your quick 2 cents on this? I have a requirement to provision company sites (dozens) based off the team site definition, but it needs a customised master page, limit the sub site creation types, tweak permissions (so no one can enable features except the SCA), and have a custom default/home page with predefined web parts. Does Web Templales sound like the right approach to you? I'm drowning in options here and without actually having experience prototyping each one it makes it hard to decide.


  22. Gravatar

    Hi Mirjam,
    can you please able how we can test creation of my site as its taking the time a lot.
    please check the above question, give some guidance..


  23. Gravatar

    Hi Mirjam

    I have referenced this post. Thanks for Web Tempate info.


  24. Gravatar


    I'm trying to find out if I've misunderstood something I read from MS regarding the creation of site template solution packages (.wsp) created by customising a standard site definition and then using "save as template". I thought I'd understood that when you create new sites based on the saved template and then delete the original saved template (.wsp) from the solution gallery, that it may break the derived site and is not a supported scenario. However, when testing this, it doesn't appear to break the derived site. Any thoughts?

  25. Gravatar

    Hi Fox Man,

    After a site has been created it only has a reference to the site definition it refers to.
    This means that sites don't know about site templates (the ones where you saved your site as a template) and web templates (that you created in VIsual Studio using a web template feature, an elements.xml file and an onet.xml file). Because of this you can savely change or even remove site templates and web templates after you created a site based on them.

  26. Gravatar

    Hi Mirjam,
    Great post. Similar to some other folks who have commented, I am trying to use a Web Template to provision a customised site collection by building on the Team Site ONET.xml. As the Module elements no longer work as they did with site definitions the question I have is how to get a Feature to provision my own default.aspx and other pages in the new site? I followed Vesa Juvonen's walktrhu for publishing sites but the files are never copied across - should I do the copying/deploying programatically? I think I am missing something major......

    Kind Regards,

  27. Gravatar

    Hi Dave,

    If you use the team site template and you want to use publishing pages you will have to make sure that you also activate the "SharePoint Server Publishing Infrastructure" (site collections scoped) feature and the "SharePoint Server Publishing" (web scoped) feature on your web template. Otherwise the Pages library won't be there. If you don't want to use publishing you can deploy the page to the "SitePages" library, which will be there in a team site without publishing features as well.

    Hope that helps.


  28. Gravatar

    Sharepoint FAQs

  29. Gravatar

    to the highest degree of the players leaving to threefold, this may Conduct machines and these are as democratic On-line as they are in genuine casinos.

  30. Gravatar

    Hi Miriam,
    I am deploying my web templates (following Vesu article) and all works fine, deploying as a FARM scoped feature which puts the templates in the sharepoint root . I create some sites using the templates. All good. I retract the WSP. I can no longer browse to my sites (404 not found). I redeploy my WSP and I can browse again. What am I doing wrong? Is this expected behaviour? Thanks.

  31. Gravatar

    Further to my last post I have now identifieD problem. If I retract my WSP that REMOVES the web templates deployed to the 14 Root\FEATURES folder. Then I get the 404 error when trying to browse to my previously created sites. Redeploying my WSP puts those web templates back and then I can browse successfully. But that confuses me. I thought the whole point about web templates is that once created everything resides in the content database. So why should this occur?

  32. Gravatar

    Hi Maz,

    Please note that my name is Mirjam, with a j.

    If you deploy your web template in a sandboxed solution it is stored in the content database, along with the rest of the sandboxed solution.
    If you deploy your web template in a farm solution the web template (along with the feature that you use to deploy it) is stored in the 14 or 15 hive, depending on what version of SharePoint you are using.
    Regardless of where the web template is deployed, you can remove it after you have used it to create sites and the sites will continue to work.
    However..if, in the same .wsp file, you also deployed for instance the homepage, a master page or style sheet, or a web part, then the fact that you remove that particular component will break you site as it will always look for that component. This is the same as when you would deploy a custom page, master page, style sheet or web part in a .wsp file, use that in an out of the box site and then remove the .wsp file. This will throw errors when you try to access the out of the box site, but it's not the site that's the problem, it's one of the components on it.

    Hope that helps.

    Kind regards,

  33. Gravatar

    Hi Mirjam,

    Firstly, my apologies for mis-spelling your name!

    Thank you very much for your reply. Indeed my WSP, a Farm solution, contains page layouts, web parts, user controls etc as you say. So I have a couple of follow-on questions if you don't mind?

    1) Ok. So given what is occurring, as long as I deploy/retract the WSP (e.g. on initial deployment and then subsequent deployments that may be required if I need to update something such as an additional feature in the onet.xml of the web template), then this is acceptable?

    2). On my initial deployment, say I create a site from one of the web templates. then I retract the WSP, update the web template upon which the site is based, then redeploy it. Will any change in the web template effect only NEW sites created (my understanding) or would it affect the existing site I created?

    Thanks so much for your assistance, which is much appreciated.

    Kind regards,


  34. Gravatar

    Hi Maz,

    1. As long as you redeploy the solution containing all the elements that break you should be fine. Make sure though that you don't modify anything for which modifying is not supported. You could also consider to split up the solution into several smaller solutions. You can then have separate solutions for the web template itself, and for some of the features that need updating more often, or that together form a logical bit of functionality. There is not one right answer there, it depends on your solution and environment.

    2. Changes to the web templates only affect new sites and not existing sites. So for instance, if you add a feature to a web template existing sites will not get that feature activated, only new sites will.
    However, if you update some of the files that are used on your existing sites those changes might be visible on existing sites as well. If you deploy a new version of a user control that is used in a web part for instance, the new version of the user control will appear on existing sites as well.

    Kind regards,

  35. Gravatar

    That's great Mirjam, thank you once again.



  36. Gravatar

    Hi Mirjam,

    Thank you for the post. I'm hoping you can point me to the right direction with my question. I've created a Web Template based on a Team Site. Within the WebFeatures I've enabled "WikiPageHomePage Feature" which in turn creates the home page /SitePages/Home.aspx. The problem is the home page does not contain any OOB WebParts. Can I add the webparts via the ONET file(if so how) or do I have to create a feature that adds the webparts to the page. I've been battling this issue for a week now and would appreciate any help you can provide.

    Thank You,

  37. Gravatar

    Hi Franco,

    The right way to go about that is to create a feature to add web parts to the page.


  38. Gravatar

    Hi Mirjam,

    Thank you for the response. I went ahead and created a feature to add the Documents Web Part to my page and it works. The problem I'm seeing now is that when I go to edit the page, the webpart disappears and cannot be edited. As son as I get out of edit mode the webpart is back. It's almost like the webpart is part of the page and cannot be edited. I'm wondering if you have any ideas. I've pasted my code below in case it helps.

    public override void FeatureActivated(SPFeatureReceiverProperties properties)
    using (SPWeb web = (SPWeb)properties.Feature.Parent)
    using (SPLimitedWebPartManager webpartManager = web.GetLimitedWebPartManager("SitePages/Home.aspx", System.Web.UI.WebControls.WebParts.PersonalizationScope.Shared))
    SPList sharedDocList = web.Lists.TryGetList("Documents");
    XsltListViewWebPart webPart = new XsltListViewWebPart();
    webPart.ListName = sharedDocList.ID.ToString("B").ToUpper();
    webPart.ViewGuid = sharedDocList.DefaultView.ID.ToString("B").ToUpper();
    webpartManager.AddWebPart(webPart, "Left", 1);

  39. Gravatar


  40. Gravatar

    Site Definitions vs. Web Templates

  41. Gravatar

    Hi All,

    In fact I am able to create a complete web template solution which gets deployed on SharePoint on-line .Using this template I am able to create site collections .

    Thanks to Mirjam for fantastic Video on web templates -

    One thing I wanted to know is what happens if I deactivate wsp from solution gallery. I want make sure the web template artefacts stays back on the site after deactivating and removing the wsp from solution gallery .But in my case it removes custom fields and content types and leaves back all other artfacts like custom master-pages&page-layouts,Custom Images e.t.c,. Why is it removing deployed site columns and site content types ? What am I doing wrong? What is the expected behaviour? Let me know if any more information required .

  42. Gravatar


  43. Gravatar

    I would like to Design the entire page(i.e., Header, Left navigation, body and footer) as a template. Is it possible to achieve this using web template.. If u can please guide me to do this


Leave a Reply


Please add 8 and 6 and type the answer here: