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