Export (0) Print
Expand All

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()

Return Value

Type: System.Web.SiteMapNode
Returns the root SiteMapNode of the site map navigation structure.

ExceptionCondition
InvalidOperationException

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.

ArgumentException

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

ConfigurationErrorsException

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.

ProviderException

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

ArgumentNullException

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

HttpException

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);
     providerAttributes.Add("siteMapFile","test.sitemap");
     // 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:

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

.NET Framework

Supported in: 4.5.2, 4.5.1, 4.5, 4, 3.5, 3.0, 2.0

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Show:
© 2014 Microsoft