Home > Blogs > Eric Shupps | The SharePoint Cowboy > Posts > Site Definitions – the Good, the Bad, and the Ugly
Eric Shupps eshupps The SharePoint Cowboy is the founder and President of BinaryWave, a leading provider of operational intelligence solutions for Microsoft SharePoint. Eric Shupps eshupps The SharePoint Cowboy has worked with SharePoint Products and Technologies since 2001 as a consultant, administrator, architect, developer and trainer. he is an advisory committee member of the Dallas/Ft. Worth SharePoint Community group and participating member of user groups throughout the United Kingdom. Eric Shupps eshupps The SharePoint Cowboy has authored numerous articles on SharePoint, speaks at user group meetings and conferences around the world, and publishes a popular SharePoint blog at http://www.sharepointcowboy.com. Presentations by Eric Shupps eshupps The SharePoint Cowboy Webinar - Migrating Legacy On Premise Solutions to SharePoint Online and Windows Azure featuring Eric Shupps Who are you and what do you want - Working with OAuth in SharePoint 2013 SharePoint is Talking Are You Listening? Eric Shupps SharePoint 2013 Performance Enhancements Taking Advantage of the SharePoint 2013 REST API Eric Shupps on Improving Performance with New Features in SharePoint 2013 SharePoint 2013 New and Improved Migrating Legacy On Premise Solutions to SharePoint Online and Windows Azure Eric Shupps Presents SharePoint 2013 Real World Help Desk App End to End Windows Azure Apps for SharePoint 2013 Eric Shupps Demonstrates Customizing the Visual Studio 2010 SharePoint Deployment Process Introduction to SharePoint Development SharePoint 2010 Unit and Integration Testing with Eric Shupps Building Enterprise Records Management Solutions for SharePoint 2010 Taming Information Chaos in SharePoint 2010 SharePoint 2010 Performance and Capacity Planning Best Practices Building Dynamic Applications with the SharePoint Client Object Model Articles by Eric Shupps eshupps The SharePoint Cowboy Eric Shupps' Ten Steps to Optimize SharePoint Performance Webcasts by Eric Shupps eshupps The SharePoint Cowboy Secrets of SharePoint Part 5: Configuring Microsoft Office SharePoint Server 2007 for Optimal Performance Creating End User SharePoint Solutions for Performance and Scalability SharePoint 2010 Performance Enhancements for Administrators by Eric Shupps Microsoft SharePoint Server 2010 for the ASP.NET Developer Eric Shupps on Following Best Practices and Avoiding Common Errors with Microsoft Office SharePoint Server 2007 Development Eric Shupps - SharePoint Performance and Capacity Planning Essentials Troubleshooting Common Performance Problems in SharePoint 2010 Videos by Eric Shupps eshupps The SharePoint Cowboy Channel 9 Interview with Eric Shupps SharePoint TechTalk with Eric Shupps - Different Views on Social Computing SharePoint Post-Deployment Planning and Management with Eric Shupps SmartTrack for SharePoint Feature Overview SmartTrack for SharePoint Podcasts by Eric Shupps eshupps The SharePoint Cowboy SharePoint Pod Show - Design for Performance (Eric Shupps) SharePoint Pod Show - Test Driven Development with Andrew Woodward and Eric Shupps eshupps The SharePoint Cowboy Run As Radio - Eric Shupps Improves SharePoint Performance
SmartTrack for SharePoint

​The SharePoint Cowboy

photo of  Eric Shupps
611 S. Main St., Suite 400
Grapevine , TX , 76051 USA
October 28
Site Definitions – the Good, the Bad, and the Ugly

Recently there has been a great deal of attention devoted to SharePoint Site Definitions in the blogosphere. A month ago I posted an article to the ISPA web site regarding the pros and cons of SharePoint Designer versus Custom Site Definitions. Just a few days ago, Joel Oleson wrote a blog entry lamenting the use of Site Definitions and had some rather strong opinions against them. He referenced a post from Andrew Connell earlier this year in which AC concludes that they aren't perfect but sometimes necessary. This kicked off a firestorm of controversy, pitting developers against administrators, and resulted in tempers flaring up all around without really achieving anything of substance.

So what's the real story with Site Definitions? Are they evil incarnate or the greatest thing since barbecued brisket?

First, let's examine what a Site Definition is and what it does. A Site Definition is a collection of configuration and presentation files which comprise a "packaged" set of functionality. When you create a new site or site collection in SharePoint, the site creation page offers you a set of tabs with different options for how the site should look and feel – Team Site, Publishing Site, Search Center, etc. Each of these has a different set of functionality enabled when it is provisioned – layout pages, web parts, lists, and so on. The underlying structure that defines what components are activated and deployed when the site is instantiated is a site definition (not a Site Template, those are different). Microsoft was kind enough to provide a handful of these for us to use and we have the ability to create our own by mimicking those that come out of the box.

The basic components of a site definition are as follows:


Now, let's stop right here and talk about the MAJOR differences between Site Definitions in v2 (WSS v2.0 and SharePoint Portal Server 2003) and v3 (WSS v3.0 and MOSS) because this leads directly into the biggest complaint that many people seem to have with them. In v2, a Site Definition was a self-contained, inflexible, non-upgradeable collection of static files and configuration elements. Everything was included in one fixed structure – HTML pages, images, forms, lists, ONET.XML, SCHEMA.XML, the whole shebang. This made them nearly impossible to upgrade when v3 rolled around. This has led many people – mostly administrators – to complain that Site Defintions were B-A-D. But hang on a minute – the inability to transition from one version to the next wasn't the fault of the Site Definitions themselves, it was a lack of future planning on Microsoft's part – they simply did not envision the upgrade scenario when they coded v2 (even their own definitions had to be completely rewritten). The same can be said for FrontPage, as nothing modified with this tool would upgrade either, and for the whole upgrade process in general – almost nothing worked except plain out-of-the-box sites. You can't really blame them – after all, how many resources could they really dedicate to testing every possible upgrade scenario when they had a massive new version to get out the door?

In v3 this all changed with the advent of Features and Solution Packages. Instead of an inflexible, hard-coded, throw-it-all-together-in-one-big-mess method, we know have the ability to create a skeletal framework and use Feature Stapling to deploy and activate the functionality we need. In point of fact, if you look at the way in which Microsoft changed the OOTB Site Definitions in v3, you will see that they now serve only as a container to which just about any type of configuration and feature set can be applied. This is a quantum leap in functionality that many people have been slow to recognize. When done properly, Site Definitions (in conjunction with Features and Solution Packages) offer a flexible, repeatable, upgradeable platform for deploying packaged sets of functionality.

The key in all of this are the words "when done properly". This means that, if you previously developed Site Definitions in v2, you need to break out of the old mold and learn how to leverage the new Feature framework to your advantage. If you duplicate the way in which Microsoft created the OOTB definitions, then your custom definitions will function in EXACTLY THE SAME MANNER as those that ship as part of the core product. In fact, the SDK explicitly states the following:

"Certain kinds of customization to sites or lists require use of site definitions, such as introducing new file types, defining view styles, or modifying the Edit menu."

That's a powerful statement. I'll go even further and state that one of the core features of MOSS, custom content types, requires declarative creation as part of a site definition if you wish to deploy your solution to more than one farm instance (such as moving from development to staging to production) or across multiple site collections. While these may be created programmatically there is no way to insure the portability of the Content Type ID, which is key to binding layout pages and publishing libraries. So there is ample evidence that Microsoft understands the need for Site Definitions and supports them as part of the broader SharePoint framework (I don't mean support as in "customer support" – they're certainly not going to support your custom code but I have had PSS/CSS help clients on several occasions with the implementation and troubleshooting of custom definitions – your mileage may vary).

What seems to be the sticking point in all the discussions of where, how and why (or why not) to use Site Definitions is the whole issue of upgradeability. I caution you to take any advice on future upgrade paths with a gigantic grain of salt. First, nobody knows what the upgrade process is going to look like yet as Microsoft hasn't announced anything. Second, using the v2 -> v3 upgrade process as a benchmark is very misleading – there is absolutely no indication that the architectural guts of SharePoint will be ripped out and replaced in the same drastic manner as they were between the previous versions. Finally, anyone who truly understands the Feature framework would logically conclude that upgradeability was factored into the equation. The whole abstraction of Features from the underlying configuration was a truly inspired decision that indicates (at least to me) that the product team learned their lesson from the last go 'round.

Look at it this way. If your custom site definition (assuming it was built properly) works just like the OOTB definitions, and the OOTB definitions pass the upgrade test (as they surely will), then your custom definition should pass the test as well. In other words, if A = B, and B = C, then A = C. So any claims that custom site definitions in v3 will not upgrade is not based on fact but rather on conjecture and the painful memory of a prior bad experience. Don't assume that the next experience will be as bad as the last one.

So where does that leave us? Well, pretty much where we started, with one camp firmly entrenched against Site Definitions and one camp cheering their merits. In the end, it's up to the individual developer, designer or project manager to decide upon the best route. If you find yourself in this situation, consider the following reasons in favor of Site Definitions:

  • They provide a comprehensive framework for delivering packaged sets of functionality with a single click
  • They enable complex customizations to be migrated easily from one environment to another
  • They provide better performance than either SharePoint Designer customizations or Site Template (.stp) files
  • Certain functionality, such as declarative content types, custom file types and list views, can only be achieved within a Site Definition (or, more accurately, as Features stapled to a definition when a consolidated package is required; otherwise, these may be deployed as individual Features)
  • Automated deployment mechanisms, such as those used in Software-as-a-Service models and hosting providers, demand "no touch" provisioning that only Site Definitions can provide

Now, consider the disadvantages of using Site Definitions:

  • They are complex to create and, without sufficient experience, hard to get right
  • They require at least minimal developer skills – there is no "point and click" option
  • It's ridiculously easy to mess things up and back yourself into a corner
  • Deployment involves copying files directly to the server file system (as part of a retractable Solution Package, of course)
  • Post-deployment updates are challenging (requires upgrading the solution package)

Note that I didn't say anything about upgradeability; that's because we just don't know yet what Microsoft is going to come up with and rank speculation does a disservice to everyone. I should also elaborate on the "hard to get right" comment. If you don't fully understand how to leverage the Feature framework, you'll end up slipping back into the old method of hard-coding various pieces of functionality. By way of example, consider that the SDK mentions the inability of users to create two different lists of the same type with different default content as a drawback of custom Site Definitions. This is certainly true of the old v2 method but completely false in v3 if you understand how to use Features correctly. Instead of calling out list types in the ONET.XML configuration file, which, I'm afraid to say, some of the built-in definitions still do, create your List Instances as Features (derived, if using a custom list, from one or more List Template Features) and staple them to the Site Definition. This allows you to provision as many list instances as you want regardless of type and ensures future maintainability (you can always modify the Feature later if necessary without modifying the core definition).

Just because they're not the easiest thing to implement, or you don't quite understand them, doesn't mean you should avoid Site Definitions altogether. In my opinion, under the right circumstances, the use of Site Definitions is to be encouraged as a best practice. True, knowing when and where to use them requires research and due diligence, but the baby shouldn't be thrown out with the bath water, as the old saying goes, just because some administrators have their knickers in a twist over a bad upgrade experience or a wayward developer's handiwork. If you come across any advice that presents this is a black and white matter (as in "Don't use Site Definitions under any circumstances") rest assured that you are getting a biased opinion and that there are other experts who may offer an alternative viewpoint.

Now, what was I doing before I got off onto this tangent? Oh, yes – creating some custom Site Definitions… J


Templated SharePoint Sites

I wrote a similar set of posts here:


If you have a chance, I'd love to get your thoughts on my best practice post at the end of the series.


System Account on 10/29/2008 6:38 AM


Great job on your analysis. I think what you've stated here is reasonable, and sensible. And having to go through a few upgrades myself, it was a really painful experience.

I agree that MS learned a good lesson and have made significant changes to ensure that it doesn't happen again. And to say that a particular set of functionality should never be used is just bad judgment.

Anyway thanks for your comment on this and hopefully others will take this as an example of how to approach a topic on whether to use something or not.
System Account on 10/29/2008 10:16 AM

Site definitions are OK, when you have right tools

Hi Eric, great post. The truth is that without site definitions you actually have no Application Lifecycle Management and it's ok when you want to create a couple of collaboration workspaces but completely not ok when you have to create a massive site definition with many workflows, when changing even a single column can spoil everything.
Microsoft defined quite nice feature framework in WSS 3.0 but gave no tools to build nice things on top of it, so we did it for ourselves. The thing is called SharePoint DSL Toolkit for Visual Studio and makes many things as straight as they should be. You can create a site model, validate it, generate a .sln and deploy it to a local sharepoint.
Site definitions are not bad - the problem is in lack of tools which would help developers to create them on a slightly higher level of abstraction, validate, deploy and test, but this is what big consulting companies told Microsoft.
System Account on 11/6/2008 2:37 AM

Great perspective!


Can you recommend a GOOD guide to creating site definitions in Sharepoint 2007?


System Account on 12/15/2008 8:43 AM

Great perspective!


Can you recommend a GOOD guide to creating site definitions in Sharepoint 2007?


System Account on 12/15/2008 8:43 AM

Excellent Post...

As previously requested, could you recommend a decent comprehensive guide to creating site definitions AND creating using feature stapling.  I read your blog about creating a site definition here ....... http://www.binarywave.com/blogs/eshupps/Lists/Posts/Post.aspx?ID=75

I am looking for more info on feature stapling.  I was going to use a blank custom site definition with feature stapling on my next project to minimize problems upgrading to SPv14 when it is released....your thoughts on this approach?
System Account on 6/12/2009 11:50 AM

Excellent Post...

As previously requested, could you recommend a decent comprehensive guide to creating site definitions AND creating using feature stapling.  I read your blog about creating a site definition here ....... http://www.binarywave.com/blogs/eshupps/Lists/Posts/Post.aspx?ID=75

I am looking for more info on feature stapling.  I was going to use a blank custom site definition with feature stapling on my next project to minimize problems upgrading to SPv14 when it is released....your thoughts on this approach?
System Account on 6/12/2009 1:20 PM

RE: Excellent Post

Eric Shupps on 6/12/2009 1:30 PM

In God we trust for everthing else there is metrics...(i do not know who said it)

even though i belong to the SPD camp, i still believe Site definitions have their use.. i am not going to debate that. i am more visual prgrammer (not VS defnitenly not VS, i did Magic/eDevloper), have been doing that over 10 year, so like SPD.

But i really want to know is how is Site defintion faster in terms of performance. When everthing is stored in the Content DB , well almost everthing, then how fast is fast or in terms of performance. In an enterprise, at what level can we yeah Site Defnintion is a better choice to be done than customisations in SPD. I did do one dashbaord with DVWP with around 10 DVWP on a page and it took around 18-20 seconds to load. Two of the DVWP were external data connections.  So does anyone have metrics to show that yes Site Definitions have an edge over Site templates. It would be nice, cause i do get these questions a lot.

And looks like its going to make to the Top 10 flame wars... Go Go Site Template.
System Account on 8/6/2009 6:41 AM

Re: Site Definitions – the Good, the Bad, and the Ugly

[url=http://www.wowne.com] WOW Gold [/url] is a kind of virtual currency, exists only in the virtual world in wow game. However,you should use cash to charge Some of wow gold than to gain the better fitted Equipment. [url=http://www.wowne.com] cheap WOW Gold [/url] can be purchased in a variety of  common props in the game ,or to buy special props in some games with special props ,it can also be special screenings For the scoring in the game so to increase the game fun.
System Account on 5/22/2010 2:02 AM
1 - 10Next

Add Comment

Items on this list require content approval. Your submission will not appear in public views until approved by someone with proper rights. More information on content approval.


Body *

Comment Date *

Select a date from the calendar.
Enter the current date to prevent automated spambot comments.

Spam Prevention *

How many letters, not including spaces, does it take to spell "SharePoint Cowboy"?


photo of Eric Shupps
611 S. Main St., Suite 400
Grapevine , TX , 76051 USA


Eric Shupps LinkedIn Eric Shupps Twitter Eric Shupps Facebook Eric Shupps Google+



BinaryWave Eric Shupps eshupps The SharePoint Cowboy SharePoint monitoring SharePoint monitoring tool SharePoint metrics SharePoint administratrion SharePoint monitoring best practices SharePoint management SharePoint management tool SharePoint operations SharePoint operationsmanagement SharePoint administration SharePoint administration tool SharePoint SLA SharePoint service level agreement SharePoint operational intelligence SharePoint performance SharePoint performance monitoring SharePoint analytics SharePoint real-time SharePoint intelligence SharePoint ITIL SharePoint service operations SharePoint uptime SharePoint alerts SharePoint health SharePoint tools SharePoint metrics SharePoint diagnostics SharePoint SmartTrack SmartTrack Operational Intelligence

Copyright © 2013 BinaryWave, Inc. All rights reserved.