This documentation is archived and is not being maintained.

XmlSiteMapProvider.BuildSiteMap Method

Loads the site map information from an XML file and builds it in memory.

Namespace: System.Web
Assembly: System.Web (in system.web.dll)

public override SiteMapNode BuildSiteMap ()
public SiteMapNode BuildSiteMap ()
public override function BuildSiteMap () : SiteMapNode
Not applicable.

Return Value

Returns the root SiteMapNode of the site map navigation structure.

Exception typeCondition


The XmlSiteMapProvider was not initialized properly.

- or -

A siteMapFile is parsed for a <siteMapNode> that is not unique.

- or -

The file specified by the siteMapFile does not have the file name extension .sitemap.

- or -

The file specified by the siteMapFile does not exist.

- or -

A provider configured in the provider of a <siteMapNode> returns a null root node.


The siteMapFile is specified but the path lies outside the current directory structure for the application.


There is an error loading the configuration file.

- or -

The top element of the configuration file is not named <siteMap>.

- or -

More than one top node exists in the configuration file.

- or -

A child of the <siteMap> has a name other than <siteMapNode>.

- or -

An unexpected attribute is parsed for the <siteMapNode>.

- or -

Sub-elements are nested beneath a <siteMapNode> where the provider is set.

- or -

The roles of the <siteMapNode> contain characters that are not valid.

- or -

A url is parsed for a <siteMapNode> that is not unique.

- or -

A SiteMapNode was encountered with a duplicate value for Key.

- or -

The ResourceKey or Title was specified on a SiteMapNode or a custom attribute defined for the node contained an explicit resource expression.

- or -

An explicit resource expression was applied either to the Title or Description or to a custom attribute of a SiteMapNode but the explicit information was not valid.

- or -

An error occurred while parsing the Url of a SiteMapNode.


A named provider cannot be found in the current site map providers collection.


A <siteMapNode> referencing a site map file contains an empty string for the siteMapFile.


A siteMapFile of a <siteMapNode> uses a physical path.

- or -

An error occurred while attempting to parse the virtual path to the file specified in the siteMapFile.

The BuildSiteMap method is called to load and build the site map from persistent storage.

For the default behavior when security trimming is enabled, see "Remarks" in IsAccessibleToUser.

After the XmlSiteMapProvider object parses and loads site map data, all loaded SiteMapNode objects and SiteMapNodeCollection collections are made read-only. When the XmlSiteMapProvider parses the Url property from a site map file, it converts application-relative URLs, as well as relative URLs, to application-absolute virtual paths.

The XmlSiteMapProvider subscribes to file change notifications for the .sitemap file. If any change is made to the .sitemap file, the XmlSiteMapProvider is reloaded, and the site map structure is rebuilt.

The following code example demonstrates how to create a new instance of the XmlSiteMapProvider class and initialize it to build a site map from XML data.

<%@ Page Language="c#" %>
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 <SCRIPT runat="server">
 private void Page_Load(object sender, System.EventArgs e)
     // Create an instance of the XmlSiteMapProvider class.
     XmlSiteMapProvider testXmlProvider = new XmlSiteMapProvider();
     NameValueCollection providerAttributes = new NameValueCollection(1);
     // Initialize the provider with a provider name and file name.
     testXmlProvider.Initialize("testProvider", providerAttributes);

     // The BuildSiteMap method is implicitly called when the 
     // RootNode propety is accessed.

     // Prints "/myvirtualdirectory/WebForm1.aspx"
     Response.Write(testXmlProvider.RootNode.Url + "<BR>");
     // Prints "/myvirtualdirectory/WebForm2.aspx"
     Response.Write(testXmlProvider.CurrentNode.Url + "<BR>");

The preceding code example uses an XML file that is located in the virtual root of the ASP.NET application. The file has the following format:

     <siteMapNode title="RootNode" description="The root page." url="WebForm1.aspx">
         <siteMapNode title="CurrentNode" description="Some sub page." url="WebForm2.aspx"/>

Windows 98, Windows Server 2000 SP4, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.

.NET Framework

Supported in: 3.0, 2.0