In a recent discussion over email, Alexander Kirillov, Sean Livingston and myself had a great discussion about SharePoint 2010 Site Definition Upgrade Strategies and trying to understand the nuts and bolts. I was impressed with the dialogue and wanted to share what I could.  Note: I’m sharing this with Sean’s permission.

It’s great to see this unbiased discussion.  I had good debate with Eric Shupps back in the day when I posted “Just say No to site definitions” I later softened the post with Do you really need to use custom site definitions? without really hanging the content on use of Site Definitions with SharePoint 2007.   That debate sparked other debates.  I concluded the debate trying to capture the bulk of that really great discussion that helped developers understand the complexity of how it can make the job of the administrator difficult and challenging in a post titled Custom site definition battle common ground and many of us were totally freaked us about about what could happen at upgrade time.  Sean Livingston has done a good job making upgrade not as painful as it once was and this discussion reveals some of that.  Minimizing the use of site definitions and minimizing complexity of those you do decide to use has been a best practice we’ve all come to adopt.

I do think this discussion captures a good overview of what we’ll face with Site Definition upgrade in SharePoint 2010.

The Players:

Sean Livingston is the SharePoint Foundation PM at Microsoft who owns the upgrade feature for the SharePoint product team from the engineering/PM focus.  Actually he’s the go to guy for upgrade across the entire SharePoint stack, but happens to work in the WSS team.  He’s definitely the brains behind the Do No Harm mantra and gives us the features that give us the flexibility of upgrading the binaries with minimally affecting the visuals (with few exceptions).  Sean and I worked together at MS IT for a while, so we’ve had some history… as well I helped him popularize his famous sunflower doc on planning supportability of SharePoint customizations back when I was in the SharePoint product team and he was in MS IT.  He’s a great guy.  If you have access to the SPC09 content, I highly recommend his 2 sessions on SharePoint 2010 Upgrade.

Alexander Kirillov is the Quest Migration Manager PM.  He owns the features for the recently announced Tech Preview of the Quest Migration Manager for SharePoint 2010 tool that supports upgrading from SharePoint 2003 to SharePoint 2010 as well as SharePoint 2007 to SharePoint 2010 as well as can be used to refactor sites, databases, etc… within 2010 to 2010 once you’ve migrated or upgraded.  A couple of the key features are the ability to do a post upgrade migration sync and a pre-migration assessment providing an assessment on duration of the process helping you better plan your upgrade/migration.

Alex asks Joel:

I’m not very clear on how custom v3 site definition are supposed to be upgraded to v4? So I figure you might educate me here.

As far as I understand it still involves an upgrade definition file. Is it basically the same process as with v2 -> v3 upgrades?

Are not v3 site definitions compatible with SharePoint 2010? Compared to v2, site definitions in v3 are very lightweight, essentially only referencing features.

My understanding is v4 is pretty much the same in this respect. So why the need for the mapping?

Excuse my ignorance please, I haven’t done too much research on upgrading customizations and documentation is scarce.

Joel responds and loops in Sean:

Don't think you need the mapping for most custom site defs v3 to v4, but Sean may have more detail

Sean:

That is correct, most custom site definitions from v3 should continue to work unmodified while in v3 UI mode of Visual Upgrade. However depending on what is in that site definition, a person may still want to do more featurization or other definition refactoring, which is where the upgrade definition file comes in handy. As always, test the existing definition against an upgraded server in both UI modes, and consider the fact that if it is delivered by solution package that it will end up in the WSE/14/Templates vs. WSE/12/Templates directory (which shouldn’t likely be an issue as we now do 14 fall back to 12, fall back to 60 directory lookup logic for ghosted files, but is worth reviewing anyways).

That help?

Site Definition and Upgrade Drill Down

Alex and Sean:

Thanks Sean, that does help! A couple more questions if you don’t mind.

Alex 1. Q) Do I need upgrade definition files for sites based on custom site defs to be upgraded? Will the upgrade process skip sites if no corresponding UDF is found?

Sean 1 A. No. No, it will still upgrade them, but it will not have any special actions to perform related to the site definition specifically, so it will be mainly regular object upgrade and feature upgrade.

2) When the existing custom site def is transferred to SharePoint 2010 (wsp/msi/xcopy), will new sites based on it be v3 or v4 UI? Can the UI mode be switched for them?

2. Depends on the master page you have. If it was a 2007 site def, even installed on 2010, it will not be fully 2010 UI compliant unless the masterpage is adjusted. (emphasis added by Joel)

3) Is site def upgrade required for v4 UI?

3. No, in fact a v3 site definition installed on a 2010 farm will actually attempt to configure as v4 UI by default, you have to make targeted changes to the site definition onet.xml for it to remain in v3 UI for net new site creation, and you need to set properties on the web that inherits from this if you don’t want the default values for when you switch to v4 UI. To allow correct switching to V4 UI, you will need to make these changes.

4) When using UDF to upgrade custom site defs, how does it works? Do I build/deploy a new v4 site def  and then UDF is used to map sites to this new site def?

4. No, UDF can only keep a site in the same site definition. It does allow re-featurization of sites based on it though.

5) Is upgrade the only time to refactor custom site defs? Can this be postponed until later somehow?

5. Nope, UDF can be used any time, but it will have to rev the sitedef version number upwards each time. Yes, it can be postponed if it is not necessary to make the site work in 2010.

Post Upgrade Site Definition Details

Alex:

Great stuff, thanks Sean!

So my last question is a pure curiosity. When I have a v3 site definition and an associated UDF for it, the definition stays pretty much intact on disk, but the sites instantiated off it get new features and files from the upgrade definition?

Sean Responds:

New sites are created using the site definition alone, not the UDF. When you build a UDF that makes changes to such things as files in a UDF, you also need to ensure those changes are in the new version site definition as well or it will cause issues. Think of the DF as a helper file only used during upgrade to specify how to get to the new version site definition from the old one.

If you just copy a site definition from the old version without modification, then existing sites will work and no UDF is needed, however any new sites based on that template may have issues as they will be automatically V4 UI even though they may not actually have the right UI components to work well in v4 UI. To prevent this you would make at least a minor modification to the site definition to specify the UI version (in the Project Tag of the Onet.XML, add UIVersion="3").

To be fully v4 compliant as well as v3 compliant you would want to ensure you supply a new v4 master page as well as ensuring that the existing pages will work correctly with that v4 UI masterpage, and you would want the Project::UIVersion="4" and add the right v4 masterpage reference to the Configuration::MasterUrl properties in Onet.XML. Lastly if you add the v4 masterpage, you want to ensure that a UDF puts that masterpage into the site (or staples in a new feature that will put the masterpage there). I recommend looking at the onet.xml and UDF for sts to see what we did to enable existing sites based on that definition to keep working while allowing new sites to have the appropriate items. (Emphasis added by me.)

Alex and I also discussed the Fabulous 40

Alex explained:

Fab 40 will upgrade just fine as long as the server-side solution packages have been deployed on the 2010 farm – just watched Sean’s SPC09 session J

They all seem to work in both UI modes too.

So I guess I have answers to most of my questions about custom site definition. The biggest question for me was if a UDF was required for a custom site to upgrade. And apparently the answer is no. UDF is also not a prerequisite for a switch to v4 UI.

Joel:

I saw some tweets during MVP summit week from the UA team at MS asking for people to provide feedback on the FAB 40 templates.  I know they are used a lot, so definitely give your feedback to MS on what they should do.  Appears the plan for what to do in 2010 is coming together based on feedback.

Conclusion and References

Hope you enjoyed the discussion as much as I did.  If you’re looking for more on SharePoint 2010 Upgrade refer to the SharePoint 2010 Upgrade Insight Series with links to all my posts on SharePoint 2010 Upgrade as well as links to the upgrade resource centers at Microsoft and outside.