Did you know: Changing existing Site Definitions is unsupported
Deployment, Inconvenient SharePoint, SharePointDuring the last SharePoint Black Belts meeting we talked about deploying of all kinds of things in SharePoint. One of the topics was deploying and updating custom Site Definitions. Did you know that changing existing Site Definitions is unsupported?
Personally I’m using custom Site Definitions quite a lot. Every Web Content Management (WCM) solution I’m working on, is based on a custom Site Definition. It’s either for convenience or a must-have (like a customer who wants to be able to create a Topic site even if it’s 100% the same as a Blank Publishing Site). If I ever got a request from a customer to change something about the custom Site Definition, my answer would be: “Yes, I can change it. The changes will apply to all sites you will create from now on. The existing sites can be changed either manually or I can create a change script for you.”. It seems my answer is wrong…
During the last SharePoint Black Belts meeting we talked about deployments in SharePoint: how would you provision different things initially into SharePoint and what would you do if you ever had to update them. One of the things we have discussed were Site Definitions. At some point we peeked into the Guidelines for Using Custom Site Definitions, Configurations, and Templates section of the Windows SharePoint Services (WSS) SDK just to verify our opinion. It turned out we were all wrong about the update process:
Changing a site definition after it has already been deployed can break existing sites and is not supported.
What we found confusing though was, that the same SDK section confirms further on that changing existing sites by changing the Site Definition is unsupported. Existing sites should be changed using the object model while the changes to the Site Definition will be applied to all newly created sites:
Modifying site definition files to customize existing sites or lists is not supported. A good guideline is to use site definitions to modify sites that will be created, but to use the object model to modify sites after they are created.
So I’m confused right now: can we or can we not make changes to Site Definitions?
Another question that arises is: what other gems are there in the WSS/MOSS SDK? Wouldn’t it be easier for us if there was a separate section included which would clarify different unsupported scenario’s so we can be of better help to both community and the customers?
Update
Some of the supported and unsupported scenarios are covered in the KB article: Supported and unsupported scenarios for working with custom site definitions and custom area definitions in Windows SharePoint Services, in SharePoint Portal Server 2003, and in Office SharePoint Server 2007.
March 26th, 2009 at 4:05 pm
Great post mate, followedup with what I hope is some helpful history over on my blog here: http://community.zevenseas.com/Blogs/Daniel/archive/2009/03/26/site-definitions-–-the-controversy-returns.aspx
March 26th, 2009 at 7:23 pm
I don\'t see the confusinon here. Changing a site definition after the first site has been created off that definition is not supported. One option is to use feature stapling which which will apply to all sites created from that time. Yet another argument for working with a simple site definition and put all the important stuff in features.
You can change the sites, though, just not their definition. One reason why you cannot change a site definition afterwards is that the site definition is not \'locked\' when a new site is created. For example you may have list templates in the site definition, and changes to these may affect existing lists, even after the list is created.
By the way, you captcha, is it testing wheter I\'m a computer or color blind?
.b
March 26th, 2009 at 9:36 pm
@Bjørn Furuknap: what's confusing is the second statement. You should use API to modify existing sites and Site Definitions to make changes for all sites which will be created.
March 26th, 2009 at 9:41 pm
I agree it can be confusing, but, as I\'ve always read it, the only \'change\' you can make, and retain supportability, is to add features using stapling. After you hit \'create\' the first time on a new site definition you cannot change the definition.
If you see how definitions are used, and how their source file continue to affect instances, I think it makes sense that this would be the intent of the rule.
March 27th, 2009 at 1:32 pm
I've always known and lived by the "Thou shalt not change a deployed site definition" rule. Of course, that doesn't mean others don't do it all of the time. In the grand scheme of things, it is more like exceeding the speed limit than running a red light. But it is still something that can, under the right (wrong?) circumstances, come back to haunt you.
March 27th, 2009 at 5:56 pm
The guidance is correct but incomplete. It should inform readers that changing certain Site Definition elements, such as WEBTEMP.XML or the SiteTemplate folder structure (and certain files) can cause issues with existing sites, but that other customizations, such as modifying ONET.XML and master page/publishing features, are fully supported. There are, in fact, very few scenarios where modifying a site definition post-deployment will cause issues *IF* the site definition was deployed properly (i.e. using feature stapling) as the primary components of the definition are only "active" during provisioning.
March 28th, 2009 at 3:15 pm
Thanks for clarification, Eric. I think that it would be a good idea to post your explanation to the on-line WSS SDK topic @ http://msdn.microsoft.com/en-us/library/ms416071.aspx. I think that it would help a lot of developers out there doubting whether to use custom Site Definitions and how to manage their life cycle.
March 28th, 2009 at 3:56 pm
Again, the point isn't what changes can be made relatively safely, but rather what is "supported" by Microsoft. Until (or unless) they change the official documentation, you need to be aware that you are on your own with regard to such changes. If that is acceptable in your environment, great!
I come back to the speed limit metaphor. On a straight highway, with no traffic, and miles of visibility, speeding isn't likely to get you into much trouble. On a twisty mountain road during a snowstorm, I recommend a much more conservative approach. :)