Best Practices for Ensuring Application Reusability and Upgrade in Windows SharePoint Services

Keith Bankston
Les W. Smith
Microsoft Corporation

April 2005

Applies to:
    Microsoft Windows SharePoint Services

Summary: Revisit key Microsoft Windows SharePoint Services Software Development Kit (SDK) information to know best practices for writing code that will be optimally reusable when software updates, upgrades, or security updates are applied to a deployment. (6 printed pages)

Introduction
SDK Guidelines and Programming Tasks
Site Definitions and Customized Pages
Implementing the Windows SharePoint Services Object Model
Conclusion
Additional Resources

This article revisits guidelines contained in the Microsoft Windows SharePoint Services Software Development Kit (SDK), and helps you consider the kinds of code customization you should perform on front-end Web servers to make those customizations more reusable and safer when software updates, upgrades, or security updates are applied to a deployment of Windows SharePoint Services. By following SDK guidelines, and by planning ahead for the kinds of customizations you need to make, you can help protect your code and enhance the prospects of its reuse. Use custom site definitions to lay out the logic of future sites, lists, or pages, and use Web Parts or Microsoft .NET Framework controls and Microsoft .NET Web applications to implement types and members of the Windows SharePoint Services assembly.

The Windows SharePoint Services SDK provides guidelines for customizing the schema files that define sites and lists. In the SDK, this information is provided in Programming Tasks under Customizing Templates for Microsoft Windows SharePoint Services, and in the following conceptual topics: Introduction to Templates and Definitions and Guidelines for Templates and Definitions. If you adhere to the guidelines and plan ahead, you can work from custom site definitions instead of customizing individual pages, and as a result you can achieve easier future deployment and reuse.

The Windows SharePoint Services SDK topic Creating a Site Definition from an Existing Site Definition provides the central guideline for many programming tasks: Create a custom site definition from a copy of one of the native site definitions installed with Windows SharePoint Services. In this task, you learn how to copy an existing site definition directory and create a custom webtemp*.xml file.

Always work from a custom site definition, rather than from an originally installed site definition, to make changes. If you work from files within a copied, uniquely named site definition directory, your customizations will not be overwritten when software updates, upgrades, or security updates are applied to the deployment, and your custom code will remain reusable. However, if you make changes to a default site definition, your changes will be absent from the new site definition installed through software updates, upgrades, or security updates.

As long as you work from a custom site definition as described in Creating a Site Definition from an Existing Site Definition, files that you modify in many template programming tasks documented in the SDK are safe from being overwritten. Updates or upgrades do not affect the contents of custom site definition directories, for example, the ONET.XML file that defines a site, or the SCHEMA.XML and ASPX files used to view and work with each type of list.

The following table lists programming tasks documented in the SDK that remain safe during upgrade if you perform them within a custom site definition, and shows which files are modified.

Table 1. Programming tasks in which modified files remain safe

You can find the files listed in the preceding table in the following locations:

• **WEBTEMP*.XML   **Local_Drive:\Program Files\Common Files\Microsoft Shared\web server extensions\60\TEMPLATE\Locale_ID\XML
• **ONET.XML   **Local_Drive:\Program Files\Common Files\Microsoft Shared\web server extensions\60\TEMPLATE\Locale_ID\Custom_Site_Definition\XML
• **default.aspx   **Local_Drive:\Program Files\Common Files\Microsoft Shared\web server extensions\60\TEMPLATE\Locale_ID\Custom_Site_Definition
• **SCHEMA.XML   **Local_Drive:\Program Files\Common Files\Microsoft Shared\web server extensions\60\TEMPLATE\Locale_ID\Custom_Site_Definition\LISTS\List_Definition

In addition to the preceding tasks that involve safe changes to files within a custom site definition, the task Extending Help also involves safe changes because you copy the Locale ID directory in the Local_Drive:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\60\ISAPI\HELP\Locale_ID directory, modify the WSTOC.HTM file of the copied directory, and create a CUSTOM_HELP.XML file within this directory.

Of course, to perform certain programming tasks described in the SDK, you need to modify original files in the setup directory. Originally installed files are overwritten during an upgrade, so that customizations you make to these files will be lost. However, if you always save copies of original files that you have customized, you can transfer your code into files after the update or upgrade is complete. Depending on the specific changes implemented in an update, you may not be able to simply replace the originally installed files; you might have to merge your changes into the updated product files. It is therefore good practice to keep detailed notes as to what specific changes you make to these files, so that, if they are replaced during an update, you can more easily merge changes.

The following table shows programming tasks documented in the SDK that specifically require customization of originally installed files, and that will not be safe from overwriting because they are not located within a custom site definition directory.

Table 2. Tasks that put originally installed files at risk

**Note   **The files listed in the table are global to a Windows SharePoint Services deployment and are located outside any custom site definition directory.

Updates apply only to sites created through default site definitions. While sites based on a default definition are carried forward in an update to reflect the new features, sites created through custom site definitions remain as they were before the update. The Windows SharePoint Services SDK warns against modifying any of the following Collaborative Application Markup Language (CAML) files, whose contents apply to an entire deployment on a front-end Web server:

• STDVIEW.XML
• BASE.XML
• FLDTYPES.XML

Do not modify these files because doing so can break every site on a front-end Web server or prevent the object model from functioning properly.

Windows SharePoint Services uses definitions to instantiate sites and lists. A site definition (for example, the native STS or MPS definition) consists of XML, ASPX, and other types of files stored within the file system in the Local_Drive:\Program Files\Common Files\Microsoft Shared\web server extensions\60\TEMPLATE directory.

A site definition contains a list definition for each type of list (for example, announcements, tasks, document libraries, and so on), and each list type has its own folder that usually includes the following files:

• A SCHEMA.XML file that defines the contents of list and item views
• An AllItems.aspx file that provides the page for viewing the list
• NewForm.aspx, EditForm.aspx, and DisplayForm.aspx files that provide pages for working with individual list items

Each list that you create instantiates one of the list types, whose supporting files reside in one of the subfolders of \TEMPLATE\Locale_ID\Site_Definition\LISTS in the setup directory.

Before you customize an individual page on a SharePoint site through a Web site editing tool such as Microsoft Office FrontPage 2003, the page draws its definition from the setup directory in the file system. The view of a list, for example, is defined through Collaborative Application Markup Language (CAML) in SCHEMA.XML, which is cached on the front-end Web server to improve performance and scalability. When you customize the page, however, Windows SharePoint Services stores the page contents in the content database. For more information on site definitions and customized pages, see Introduction to Templates and Definitions.

To preserve customizations and enjoy the benefits of new functionality provided through an update, moving the contents of individually customized pages between major versions of Windows SharePoint Services may require merging changes with new uncustomized files that are installed.

If you create custom site definitions as described in the Windows SharePoint Services SDK, you improve the likelihood that your customizations remain reusable and safe. Web Parts and custom controls or applications created in Microsoft Visual Studio .NET also remain safer from overwriting and are reusable, providing a means to implement types and members of the Windows SharePoint Services assembly. The namespaces of this assembly offer access to most aspects of a SharePoint site, and Web Parts or other controls that derive from System.Web.UI.Control provide the best contexts for making use of these namespaces.

Web Parts are inherently modular and do not need to be embedded in a Web Part Page. Like Web server controls, they offer a means to centralize code for reuse and implementation throughout a deployment. In the previous version of Windows SharePoint Services, SharePoint Team Services from Microsoft, you could embed custom CAML list views directly within a page on a SharePoint site (for examples, see Custom CAML Views in SharePoint Team Services), but doing so made the custom code more vulnerable when you updated or upgraded your deployment. In addition, the custom code was less reusable because such a view would be embedded in the page. If you needed to customize a view that you implemented across various locations in a deployment, you had to modify the view at each location. With Web Parts and Web server controls, the logic does not need to be contained within the page, but can be located elsewhere in a location that is more safe. Because the logic for controls can be centralized, it is much easier to apply code changes throughout a deployment.

In summary, it is best to create controls and applications that make use of objects in the Windows SharePoint Services assembly to accomplish programming tasks.

Note   Modifying the database schema or using code to call stored procedures in Windows SharePoint Services is not supported and such changes will not be safe during an update or upgrade.

This article recommends two strategies for ensuring the reusability of the code you write for a deployment:

• Plan ahead for the kinds of customization that you need to make, and create custom site definitions that contain your code. In other words, use definitions to instantiate sites whose pages already contain the customizations you need, rather than customize individual pages in sites that already exist.
• Centralize your customizations by making use of Web Parts and Web server controls that implement the Windows SharePoint Services object model.

Adding a Custom View Style to Windows SharePoint Services
Best Practices for Developing Web Parts for SharePoint Products and Technologies
Checklist for Testing SharePoint Web Parts
Customizing List Item Forms in Windows SharePoint Services
Customizing SharePoint Sites and Portals: Part 1
Customizing SharePoint Sites and Portals: Using Templates and Site Definitions, Part 2
Customizing SharePoint Sites and Portals: Style Sheet Class Reference Tables, Part 3
Modifying the User Interface for Web Parts and Web Parts Pages
Use Windows SharePoint Services As a Platform for Building Collaborative Applications