Modifying out-of-the-box SharePoint Server 2007 files

One of the most common and simple ways to customise SharePoint is to directly modify the files that are installed as part of the product (referred to as ‘SharePoint-owned’ files).

This is common practice; but not necessarily good practice for many reasons, the most obvious being that this type of customisation is officially unsupported.

In most cases that are alternative ways of achieving the desired customisation without modifying SharePoint-owned files, however in some cases, modifying SharePoint-owned files is the only option. This article will outline the key considerations around modifying SharePoint-owned files.

(Throughout this article \12\ refers to the ‘12’ hive normally located in the following location on each WFE server: C:\Program Files\Common Files\microsoft shared\Web Server Extensions\12\ )

Why not modify SharePoint-owned files?

Directly modifying a SharePoint-owned file is by far the easiest and simplest way to make a customisation, however this approach is unsupported for several reasons, the main ones being:

• Modifying these files may ‘break’ SharePoint in some way if you change the wrong part of the file
• A hot fix or service pack may over-write your customised file without notice, which will effectively un-do your customisation

The detail around the support policy are outlined here: https://msdn.microsoft.com/en-us/library/bb803457.aspx

In addition to the support policy, this is generally bad practice because your customisations effectively get lost amongst all of the out-of-the-box files and the customisation becomes very hard to support and maintain. Additionally, customising SharePoint-owned files may cause problems when upgrading to future versions of SharePoint.

Common Modifications and Suggestion Alternatives

This section will outline some of the most common modifications that are made to SharePoint-owned files and possible alternatives which will achieve the same result in a supported way.

Changing anything in 12\Templates\Layouts

The \12\Templates\Layouts folder contains all of the ASPX pages, MASTER pages etc that represent much of the SharePoint user interface. Many customers need to modify these pages to either disable some out-of-the-box functionality or add additional logic.

Rather than directly modify files in the ‘layouts’ folder, it is possible to create a duplication of the entire folder for each web application you have. You can then re-configure the site in IIS to point to the new folder and make your customisations there instead. This way, the original ‘layouts’ folder remains un-touched, but you still have the desired customisations. The added benefit of this approach is that you can apply customisations on a web application basis.

For the purposes of explanation we’ll base this overview on the ‘layouts’ directory however this approach also applies to the following product-owned directories \12\template\controltemplates, \12\isapi and C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\wpresources

To implement this, follow these steps (assuming we are working with a web application called ‘Portal’):

These steps will need to be repeated on each WFE server.

1. Navigate to \12\TEMPLATES

2. Make a duplicate of the ‘Layouts’ folder and rename the folder to ‘Layouts_Portal’

3. Open IIS Manager

4. Navigate to the IIS site which represents the ’Portal’ web application, right-click the ‘_layouts’ virtual directory and open the properties page (advanced settings on IIS7). This is shown in this screen shot (site called ‘MySite’ rather than 'portal’ but you’ll get the idea!)

5. Set the physical path to the folder you created in step 2 (should \12\template\Layouts_Portal)

6. Perform an IISRESET

You can now safely modify the files in the ‘Layouts_Portal’ portal folder and those changes will only affect the ‘Portal’ web application.

WebTemp.xml

\12\TEMPLATE\1033\XML\WebTemp.xml is an XML file which controls which site definitions are presented to users in the Create Site interface. If your solution contains a custom site definition, it needs to be registered here in order to show-up in the user interface.

If you directly modify WebTemp.xml to include your custom Site Definition, this will work but is bad practice.

Fortunately, the site registration mechanism was developed in such a way that any XML file who’s filename starts with ‘WebTemp’ and is located in \12\TEMPLATE\1033\XML is used to register site definitions. This means that you can create a custom WebTemp file (normally called WebTempCustom.xml) in the same location as WebTemp.xml and providing that your IDs are unique and the values are correct, your site will appear in the Create Site interface.

This means you can register you custom Site Definition without modifying the SharePoint-owned WebTemp.xml file.

SPThemes.xml

\12\TEMPLATE\LAYOUTS\1033\SPThemes.xml is an XML file that controls which themes are available for use across the entire farm. Adding a custom theme is a perfectly common and acceptable way to ‘re-skin’ a SharePoint site.

Unfortunately, this is an area where you have to modify SharePoint-owned files if you what to register your custom theme. Unlike WebTemp.xml, it is not possible to add a custom version of SPTheme.xml with your theme’s registration in it. Only the SharePoint-owned SPTheme.xml is used to register themes.

Site Definitions

Many customisations require simple tweaks to SharePoint-owned site definitions such as ‘team site’ or ‘meeting workspace’. As with previous examples, it is simplest and easiest to directly modify the site definition, however this is unsupported.

An alternative approach is to use a technique called ‘feature stapling’ or ‘site association features’ to add the additional functionality. The feature stapling technique allows you to specific additional features that are activated after a site is created from a specified site definition. This allows you to add to the SharePoint-owned site definition without actually changing any of the SharePoint-owned files.

There are plenty of great article which talk about feature stapling. Here are two particularly good ones:

https://msdn.microsoft.com/en-us/library/aa544294.aspx 

https://blogs.msdn.com/cjohnson/archive/2006/11/01/feature-stapling-in-wss-v3.aspx

If you do have to modify SharePoint-owned files

If you have to modify a SharePoint-owned file and feel there is no alternative, there are several best practices that should be observed:

1. Understand files that are updated with hotfixes and service packs

It is best practice to ensure you understand the files that are updated by a hotfix or service pack. This is especially true if you have modified or duplicated product-owned files which could be updated as a result of a product update. Normally, whenever a service pack is issued, a list of fixes and files that are update is also published.

This is the list that was published for Service Pack 2: https://support.microsoft.com/default.aspx/kb/970358/

This is the list that was published for the WSS infrastructure updates: https://support.microsoft.com/default.aspx/kb/951695

2. Make Duplicates

If you do have to modify any SharePoint-owned files, ensure you have a duplicate of the original file before you make any changes. This way if your customisation is ever removed, you can restore the original file easily.

It is best practice to monitor changes when hot fixes and/or service packs are applied. If your customised files do get overwritten as part of a product update, then make sure the duplicate is up to the same patch number before you re-apply your customisations. This way you are applying your customisations to the latest version of the file.

Do not include the duplicates in your solution package (see Understanding Solution Retraction).

3. Understand Solution Retraction

When adding files via solutions it is important to understand that when a solution is retracted, it will actually remove any files that are contained within the solution package. If these files are modified versions of SharePoint-owned files, the files will be deleted which may actually break SharePoint until another version of that file is replaced.

The best practices in this area are as follows:

• Do not include backup copies of the original product-owned files in your solution package. These should be manually created and stored. Normally these files are stored on the live servers; however this is not mandatory, so long as copies are kept somewhere.
• It is fine to deploy custom versions of files via a solution, but ensure that a manual step is added to the retraction process to replace the deleted file, usually with a copy of the original backup.

This article was published by

Martin Kearn Senior Consultant Microsoft Consulting Services UK Martin.Kearn@Microsoft.com Click here for my bio page

Comments

• Anonymous
  June 21, 2009
  The comment has been removed

• Anonymous
  June 22, 2009
  Top News Stories Can Your SharePoint Backup Harm Your Business? (Information Management) The native SharePoint

• Anonymous
  June 23, 2009
  It seems every week more and more great content appears! These could almost become daily Coffee break posts! WSP Carsten Keutmann: Beginning SharePoint Development (Bonus part #3 WSPBuilder overview)

• Anonymous
  June 27, 2009
  Martin, I have often considered using the technique described in the "Changing anything in 12TemplatesLayouts" section of your post here as a means of achieving greater issolation between web applications, but have hestiated because of concern of the supportability (both in terms of application of service packs, and also v-next upgrade scenario) - any thoughts or comments around that? specifically with regard to service packs - by using this technique the customer now has the extra responsibliity of diff-merging fixes from the "real" layouts directory into their copied one.  and will this configuration be supported by the upgrade to 2010 process?  I'm sure that's anyones guess at this point.

• Anonymous
  July 06, 2009
  The comment has been removed