Do you Really Need to Create Custom Site Definitions?

Posted on October 23, 2008 by Joel Oleson

<Update> After a lengthy conversation with all our favorite SharePoint MVPs from Andrew Connell, Robert Bogue, Todd Baginski… I need to soften some of the language here, but emphasizing in clarity what I’m concerned about in the spirit of this post. As well a number of IT pros backed up my enthusiasm to discourage the use of custom site definitions.

First, the spirit of this message. My original intention was to ensure that people realize just what people were signing up for when they created custom site definitions. As soon as you have sites that don’t use the out of the box definitions, the Upgrade process becomes much more complex and hard, it also pretty much signs you up for having developers there to help you upgrade those sites with custom site definitions.

The other concern which the devs above shared with me as well is, there are a number of developers who don’t think through the implications of a site definition. It doesn’t mean you’re lazy if you use them. Many of our best devs use them on WCM sites or in special LOB integration sites. Here’s a snippet from our conversation where we are all on the same page… the real goal of this post. Summarized by Robert Bogue.

1) Do site definitions when you need to. (Mostly I think we agree this is when you need a unique ID/name — but there are other cases as well)

2) If you build a site definition is should be very minimal — everything should be built around features. The features can be hidden.

"I think calling out bad practices (heavy site definitions) is absolutely appropriate. However, I think that saying they’re all bad is taking it too far." – Robert Bogue

"For me, you post is too strong. My post that you reference is more how I feel about it… simply tell people you don’t HAVE to create site def. There are reasons when you have to create each one. In fact, while I hate site def’s, EVERY WCM project I do starts with a custom site def. Mind you it’s slimmed WAY down as I only need something with a name (for the user to pick) and ID (to attach Features to), but it is a site def none the less. " — Andrew Connell

"In my opinion it all boils down to the last sentence AC said. “as I only need something with a name (for the user to pick) and ID (to attach Features to), but it is a site def none the less."

If SharePoint had another mechanism for us to provide this functionality then we could probably forego custom site defs altogether. I follow the same approach AC outlines on his blog, come to think of it, the article on my blog you linked to just provides the instructions to implement AC’s approach." — Todd Baginski

So I’m softening the language, but you’ve gotten the gist, and I think my post achieved the goal of helping us narrow down why they are some times needed.

— Joel Oleson

</Update>

I thought we were past mucking around with the site definitions except to make tiny little changes that could easily be backed out.

If you don’t need to modify them don’t do it. Consider them product code! If you need to build something, do it in a feature, staple the feature and deploy it in a solution. Site Templates as tough to work with as they are, are better than custom site definitions. Even the use of site templates is controversial in the community due to the customizations that it causes in the database. From an upgrade perspective, it’s Much Much easier to upgrade a site based on a site template than it is a site based on a custom site definition. Now a site template based on a custom site definition is just as bad if not worse.

Ok so it’s easier to modify an existing site definition. WRONG Answer! You just broke the out of the box product and you will have a hard time getting support. Maybe the dev support people will help you, but poor customer. Poor support. Poor everyone who has to pay to try to undo what’s taken place.

Don’t modify the out of the box site definitions unless you are following some MSDN article… Even then, make sure there is no other way and you know what you are doing so you can back it out. Always back it up. You may even consider backing it up to disk so you’ve got it for later.

I had to listen to customers crying about what consultants came in and did to their environments in the name of "Good SharePoint Development." If you can, leave the site def alone, and package up your code so it can be added and later removed or replaced at least.

I need someone to give me a list of reasons WHY you need to mess around with the site definitions. I’ve had a couple of devs take me up on it, but I still think it’s WAY better if you just leave it alone and pretend like you can’t. It will keep you honest and it will make upgrade and support TONS easier.

You’ve recently seen me in favor of client side code running server side elsewhere. That’s great. See if you can take things to a higher level and go with a zero server footprint deployment. Or go with Off the shelf code where you get support for upgrade from an outside company with assurance.

I’m not totally against custom code, but I do want to see it thought through.

I’m sure nearly all SharePoint Dev classes have info on creating custom site definitions. You may even have something in the certification test on them.

Any SharePoint developer can create a custom site definition, but the challenge is to see if they can fulfill those same requirements without using a custom site definition (The albatross around an admins neck).

Worried about users turning off the features? Make an STSADM extension for provisioning your special site that activates the hidden feature. Or consider feature stapling. Get creative and think outside the V2 Box. If you’re building custom site definitions on a regular basis you haven’t learned how to do things in the new world.

Let’s continue to talk through the trade offs of site templates, feature stapling, and site definitions. I think this is an important discussion. In the future I’d love to see it to not be common at all when even hard things need to happen.

Ok, so developers don’t think much about upgrade, but let’s start preaching… Can we do this without custom Site Defs without a note from the teacher that agrees to says it’s a Requirement. On the hierarchy of Scary Customizations. The Custom Site Def is nearly the worst. The only ones worse are customizing the out of the box site definitions and messing with the database and adding your own triggers and "fixing" the inefficient SharePoint stored procedures.

Todd Posts "How to Create a Custom Site Definition" , but agrees we need to minimize what we do with them (see above). Good job Todd, my friend, you show up as #1 using keywords… custom site definition)

I do think we need to see more about "How to NOT Create a Custom Site Definition" or

You don’t need to use Site Definitions (This is AC’s Love and the discussion) please point your devs to this one. I continue to plan to point customers and developers to that one.

If you’re a lost developer or even one that’s looking to go through a ten step program, I recommend the Hippocratic Oath of SharePoint – First Do No Harm (Thanks Woody). There’s also SharePoint Dev guidance at by the Patterns & Practices Group. AC talks about it. I’m anxious to see them provide guidance on when site definitions are necessary (yes as an IT pro, I want to see them used when features and solutions don’t do the job).

I thought AC would agree with me and he does, in fact he’s given us the formula …. You don’t need to use Site Definitions. Check out the discussion that he’s got going…

This post discusses both Microsoft support, but it’s about the long term view. If you do have questions about Microsoft Supportability for Site Definitions KB 898631.

Don’t do site definitions because they are easier or quicker, do them because it’s the right solution, but please convince me that you understand the upgrade implications and tell me AC’s solution above doesn’t help you.

</UPDATE>

Ok. Back to your normally scheduled lives… The result of this conversation will make us all better off as painful as it will be for both of us.