The Great Debate: SharePoint Designer vs. Custom Site Definitions

I often get asked about the pros and cons of using SharePoint Designer versus custom site definitions for branding purposes. There seems to be a great deal of confusion surrounding this topic so I’ll offer my two cent’s worth in hopes that it clears the air and helps you, the SharePoint developer or administrator, make a more informed decision on which to use and where.

First, let’s be clear on the difference between the two. SharePoint Designer is an off-the-shelf tool that provides add-on functionality for SharePoint – namely workflows, data view web parts, and UI customization (by this I mean the HTML structure, styles, and overall design of individual layout and master pages). It is targeted mostly at power users but can also be employed by developers to create quick data-driven applets or implement serial workflows quickly with minimal coding. Site definitions, on the other hand, are a set of Features and XML-driven configuration files which provide a framework for deploying SharePoint sites with a certain look, feel, structure, and functionality. For the most part, the two are mutually-exclusive in that a site must already be deployed for it to be customized by SharePoint Designer and site definitions are only applicable during the creation of a new site. The confusion arises from the ability of both methods to implement advanced interface customizations; however, the manner in which they do so is drastically different.

SharePoint Designer

To begin with, SharePoint Designer must be attached to an existing site in order to change anything related to the site’s look and feel (what we commonly refer to as the "chrome"). This makes it an "out-of-band" process (to borrow an old networking term) in that the site is deployed first then edited later. This has the advantage of providing a comfortable GUI environment for the developer as SPD can render a view on-the-fly of how HTML and style changes impact the chrome. It is also able to enforce certain security requirements, such as the need to check out documents before they can be edited, and provide contextual assistance for style references and easy-to-use HTML design tools.

This out-of-band approach may sound easy (and it is) but it comes with some major drawbacks. First, editing a master or layout page in SPD causes the evil "unghosting" monster to rear its ugly head. You’ve probably heard this term before, especially if you worked with Frontpage in the previous version of SharePoint, but you may have also heard its new, more politically correct variant, "customized". Whatever you call it, the results can have a significant impact on the overall performance and maintainability of your SharePoint farm. In order to understand why this issue is so important, you first need to understand how SharePoint renders pages to the requesting web browser. The following diagram illustrates the rendering method for both customized (unghosted) and uncustomized (ghosted) pages.

Figure 1 – The SharePoint Page Rendering Process

As the diagrams demonstrate, the unghosting process can be significantly less performant because page content must always be loaded from the database before it can be rendered. Ghosted pages, on the other hand (so-called because they actually live on the file system of each front end server and only a pointer is held in the content database), are loaded locally from disk. SharePoint already creates a tsunami of network traffic between front-end servers and the database; adding another request to the stack, especially for large blocks of text that are transferred over long-running TCP sessions *during* the ASP.NET Just In Time (JIT) compilation and page-rendering process, can completely overwhelm physical resources if the traffic load is high enough. To make things worse, because the content is dynamically retrieved from the database, it cannot be cached effectively by IIS (it still gets cached and compressed to a certain degree but much less efficiently than static resources on disk). That being said, the situation may not be so desperate as it first appears, as SharePoint employs its own caching mechanisms on top of IIS and a single site collection with a custom master page, no matter how many levels deep it goes, still only uses one dynamic resource for page rendering. But – and this is a biggie – the same cannot be said of any form pages (editform.aspx, dispform.aspx, newform.aspx, etc.) and pages which include data view web parts (DVWP). Yes, MOSS still employs some caching, but each page instance is stored in the database. And, it should be noted, the caching benefits only apply to MOSS farms; if the portal is based on WSS then no caching mechanisms are available within SharePoint.

Second, customizations achieved with SPD are static. That is, they cannot be replicated from site to site. Want to deploy a new site collection for Finance using the same branding you created for Human Resources? Sorry, proceed to the back of the line; you’ll have to start all over from the beginning. Need to have a set of common templates for ad-hoc site creation? Nope, can’t do that either – each site either inherits the parent master page or uses its own that you create from scratch (or copy over from another site). Need to make sure that all Wiki pages (remember, Wiki’s and Blogs are custom templates that you choose when creating the site) deployed in your organization have the same set of functionality? Dream on.

Finally, SPD customizations "break" the connection with the site and its underlying site definition. Once the master or layout page has been customized, any changes to the template it was based on (such as "Team Site" or "Collaboration Portal") from an update or service pack will not be available. The design is effectively frozen at the point in time at which it was created. This makes deploying updates, such as a new set of header images supplied by Marketing, across multiple site collections a nightmare as you must open each customized page in SPD and apply the changes (or copy the page from site gallery to site gallery).

So all of these issues beg the question "Just what is SharePoint Designer good for?". Well, for one thing, it makes creating new master and layout page designs a quick and enjoyable experience. Because it duplicates the ASP.NET JIT model in the design view (meaning it merges the layout and master pages together into a single view), modifying these pages is much easier than doing it all by hand in HTML. It’s quite difficult to envision what impact your changes have in a child page when you can’t see its parent. Secondly, it makes the devilishly difficult task of applying new styles much simpler as you have a context-aware CSS editor at your disposal (this is especially true for MOSS pages as they often employ several interrelated CSS files that override each other). Finally, it’s a great prototyping and RAD tool as new designs can be envisioned and tested very quickly in situ.

Custom Site Definitions

Now that we understand the limitations and advantages of SPD, we still have to ask ourselves: What about those pesky unghosting and replication/maintainability issues? That’s where custom site definitions and the SharePoint Feature framework come in (note that when I use a capital "F" I am referring to an element in the SharePoint Feature framework, not an element of functionality within the overall system, which I differentiate with a lower case "f"). When you create a new site or site collection in SharePoint, it gives you a list of available templates to use, grouped by functionality into a set of four tabs. The first two tabs are for WSS and the second two are for MOSS. SharePoint uses these definitions, which are sets of features and configuration files that provide the underlying structure for site creation and the deployment of associated functionality, to determine what type of site to create and what to put in it once it’s in place (web parts, sub sites, workflows, etc.).

Figure 2 – Site Definition Structure

Thankfully, Microsoft gave us the capability to create our own custom site definitions that mimic the way in which the product itself functions. If you think about it, that’s quite a powerful statement; it’s like buying a shirt and getting the tailor who made it thrown in as a freebie in case you ever want another one. By building our own site definitions, we can control what gets provisioned during site creation and how it looks when the process is done. Even more importantly, the custom code will follow the same rules as the built-in definitions (assuming it’s written properly, of course) and thereby avoid all the pitfalls of SPD’s out-of-band model. Our master pages will be stored on disk, new sites will be able to use a pre-defined template, and a single change to the ghosted source files will immediately replicate across all of the sites that rely upon them. In addition, custom site definitions allow the developer to programmatically restrict what features are available to the user – including the use of other definitions and templates – and provide a more controllable environment with only those features necessary to meet the requirements.

Naturally, there are some drawbacks to this method as well. First and foremost, custom site definitions are complex and difficult to create. They involve numerous XML files and code-only HTML files (sorry, no GUI’s here) and they must follow a strictly defined structure. I’ve known many an ASP.NET developer to sit with their mouth hanging open after the first hour of learning how to do a basic site definition thinking "You’ve got to be kidding me! Is all this stuff really necessary?".

Second, for maximum effectiveness, site definitions should be deployed using the Solution and Feature framework and make extensive use of Feature Stapling (attaching features to a definition in a specified order, not to be confusing with Feature Dependencies, in which one feature calls another feature from within the Feature definition file). As both Features and Solutions require their own learning curve, they invariably introduce further confusion into the process.

Third, due to the stapling function of site definitions, along with some of the various content type associations and layout dependencies required for MOSS, there is no way to avoid getting your hands dirty with at least the superficial aspects of Microsoft’s Collborative Application Markup Language (CAML). CAML isn’t necessarily difficult to learn but it is tempermental, laborious and poorly documented, all of which doesn’t exactly add up to a rich and rewarding developer experience.

Finally, site definitions are only applicable during provisioning; that is, they have no effect after a site has been created. Certain Features of a definition may be applied after provisioning, such as a custom master page, but the entire definition is applied only once when the site is created. This means that sites which are already in place cannot be customized using site definitions. This doesn’t completely prevent their use post-provisioning, as any child sites created after the new definition is in place may use it, but it does effectively limit the scope to new deployments.

Making the Right Choice

Fortunately, choosing between SPD and site definitions isn’t a zero-sum equation. The SharePoint platform is flexible enough to allow the use of both and they can be employed interchangeably in a single environment quite successfully. The decision of which route is best often depends upon the stage of the deployment and the nature of the application. If a portal is to be used primarily as an outward-facing public Internet site it is very unlikely that multiple templates will be required that have different chrome elements; in that situation, provisioning the site using an out-of-the-box template then customizing it with SPD might be a perfectly acceptable solution. Similarly, if an Intranet site has been in place for some time, or has been upgraded from a previous version, there may be no other option but to implement customizations in place.

On the other hand, a new internal deployment that may have multiple branding components or departmental functional requirements may be better served in the long run by employing site definitions via the Features and Solutions framework. In those cases where SharePoint serves as a middle-tier operating environment for line of business applications, site definitions are a better method for stripping out those functional elements which are not absolutely required, rather than repetitively having to deploy a standard template and manually remove those elements which do not serve the core purpose.

One factor which may have a definitive impact on the decision behind which method to use is overall portal performance. All the evidence suggests that site definitions, which make the best use of disk-based caching and compression mechanisms, will perform better under heavy loads, especially when scaled to thousands of concurrent users. While site definitions may require a heavier investment on the front end, they pay off in terms of delivery cost and resource utilization.

Furthermore, the use of custom site definitions improves maintainability and reduces operational overhead by requiring less manual intervention to effect changes. Various update mechanisms are available within SharePoint to push changes out to local file systems on every server in a farm; in turn, the definitions which rely on these files are automatically updated. The same cannot be said for SPD customizations. While it may be argued that a change to the UI within SPD is, in fact, a global change as the customizations are stored in the content database, that argument overlooks the fact that the changes will not cross site collection, web application, or content database boundaries, and may not be propagated within a single site collection if a child site has broken its inheritance on the parent master or layout pages. In the same vein, any system-wide updates, such as those introduced by a service pack or hotfix, will also not be inherited by SPD-customized sites and must be introduced manually (if possible).

Conclusion

In my experience, SPD is most appropriate in small, static deployments where the organization does not possess the requisite development skills (or budget) to implement custom site definitions. It is also the only effective solution for upgraded legacy installations. For larger deployments, and those where performance is a key consideration, the benefits of site definitions make them a much more attractive option. Site definitions may also be the only answer when the specification calls for many customized sites to be provisioned programmatically (such as in hosted and Software-as-a-Service environments).

But these are not the only options. It is quite common to use SPD to prototype new designs, export the resulting master page, and include it as a Feature in a custom site definition. In some cases, portions of the portal which are lightly stressed or "one off" sites designed for a particular purpose, SPD customizations my coexist side-by-side with a more robust definition-based environment.

In the end, it comes down to suitability for purpose, resource availability, and, of course, cost. What may work in a portal that starts out as a small departmental deployment may not work quite so well when the portal grows exponentially into an enterprise information resource. Likewise, the overhead of an enterprise-class solution may be overkill for a portal whose primary purpose is a small user base focused on a particular set of tasks. As with any new system, consider first what the application is supposed to do, then determine which tools are right for the job. This may mean trying both methods before eventually deciding that one or the other is right for a particular environment.

Resources

For more information on branding and customization using SharePoint Designer:

SharePoint Products and Technologies Customization Policy [MSFT]
Heather Solomon’s List of SharePoint Branding Resources [Heather Solomon]
Understanding SharePoint Branding Options [Robert Bogue]

For more information regarding custom site definitions, Features, solution packages and custom master pages:

Site Definitions and Configurations [MSDN]
Creating a Custom WSS Site Definition [Eric Shupps]
Creating a Custom Site Definition in WSS v3 / MOSS [Todd Baginski]

Happy SharePointing!

UPDATE: I’ve posted a complete Visual Studio 2008 solution containing code samples for both WSS and  MOSS custom site definitions (including features and the final solution package).