Overriding the SiteUrls.config File

When you upgrade a site and have made changes to the siteurls.config file or a similar configuration file, you often need to merge your changes with the updated copy. To do this, you can create a SiteUrls_override.config file that sits in the same directory as your SiteUrls.config, and merge it with the SiteUrls.config file.

The SiteUrls_override.config file allows you to change the data that is read in for URL rewriting which comes from the SiteUrls.config file.

The following example shows a SiteUrls_override.config 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

You must use an xpath to indicate what node needs to be changed, removed, or added. In the example above the xpath attribute locates a specific node in the SiteUrls.config file. Community Server applies this xpath to the XmlDocument using SelectSingleNode.  For more information on xpath you should read the xpath tutorial at w3 schools.

Override Merge Mode Options

You can find the merge options in the Merger.cs class file in the Components project.  You can find this source code in the 2008 SDK download. These options will not work for comments. You can use the following options in your override file in the mode setting to specify how you are overriding a place in the file:

• remove - Deletes 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. 

<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 the optional where attribute to specify whether 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 - Changes the value of an attribute on the xpath node. The following example shows an override that does this for the attribute named value.

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

• new - Creates a new attribute on a node. You must provide both a name and a value, as shown in the following example:

<Override xpath = "/SiteUrls/locations/location[@name='weblogs']"

mode = "change" name = "type"

value = "CommunityServer.Blogs.Components.SingleBlogLocation,

CommunityServer.Blogs" />