Overview

When you are upgrading a site and have made changes to the siteurls.config or a similar configuration file, you will often need to merge your changes with the updated copy.  Since 2007 this is no longer necessary when you use an override file to make your changes.  You can create a SiteUrls_override.config file that sits in the same directory as your SiteUrls.config, which is merged with it to make changes to it.  The SiteUrls_override.config file allows you to completely change the data that is read in for URL rewriting that comes from the SiteUrls.config.

Sample Override File

<?xml version="1.0" encoding="utf-8" ?> 
<Overrides>
    <Override xpath="/SiteUrls/transformers/add[@key='##blogdirectory##']" 
                       mode = "change" name = "value" value = "" />
    <Override xpath = "/SiteUrls/locations/location[@name='weblogs']" 
                       mode = "new" name = "physicalPath" value = "/blogs/" />
    <Override xpath = "/SiteUrls/locations/location[@name='weblogs']" 
                       mode = "change" name = "type" 
                       value = "CommunityServer.Blogs.Components.SingleBlogLocation, 
                                     CommunityServer.Blogs" />
</Overrides>

XPath

In order to indicate what node needs to be changed, removed, or added to you use xpath.  In the previous example file you see that the xpath attribute is used to locate a specific node in the SiteUrls.config file.  This xpath is applied to the XmlDocument using SelectSingleNode.  For more information on xpath you should read the xpath tutorial at w3 schools.

Override Merge Mode Options

The merge options can be found in the Merger.cs class file in the Components project.  This source code can be found in the 2008 SDK download.  You should note that these options will not work for comments.  Below are the options that you can use in your override file in the mode setting to indicate how you are overriding a place in the file.

• remove - Used to delete a node or an attribute of a node.  If you provide a name then it will remove that attribute from the node, otherwise it removes the node itself.  Below are a couple of examples of using this mode:

<Override xpath = "/SiteUrls/locations/location[@name='weblogs']/url[@name='weblogabout']" 
     mode = "remove" />

• update - Replaces the node with the new node you provide.

<Override xpath = "/SiteUrls/locations/location[@name='weblogs']/url[@name='weblogabout']" 
         mode = "update">
    <url name = "weblogabout"  path="##blogdirectory##test.aspx" 
                    pattern="##blogName##/test.aspx" 
                    physicalPath="##blogthemeDir##"  
                    vanity="{2}?App=${{app}}" page="test.aspx" />
</Override>

• add - You can provide an optional attribute, where, to indicate if the new node should be at the start or end of the xpath location.

<Override xpath = "/SiteUrls/locations/location[@name='weblogs']/url[@name='weblogabout']" mode = "add">
        <url name = "NewAbout"  
                  path="##blogdirectory##test.aspx" 
                  pattern="##blogName##/test.aspx" 
                  physicalPath="##blogthemeDir##"  
                  vanity="{2}?App=${{app}}" page="test.aspx" />
</Override>

• change - This is used to change the value of an attribute on the xpath node.  Below is an example of an override that does this for the attribute named value.

<Override xpath="/SiteUrls/transformers/add[@key='##blogdirectory##']" 
                       mode = "change" name = "value" value = "" />

• new - Used to create a new attribute on a node.  You must provide both a name and a value.  Below is an example of this:

<Override xpath = "/SiteUrls/locations/location[@name='weblogs']" 
                       mode = "change" name = "type" 
                       value = "CommunityServer.Blogs.Components.SingleBlogLocation, 
                                     CommunityServer.Blogs" />