XmlSiteMapProvider.BuildSiteMap Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Loads the site map information from an XML file and builds it in memory.
public:
override System::Web::SiteMapNode ^ BuildSiteMap();public override System.Web.SiteMapNode BuildSiteMap ();override this.BuildSiteMap : unit -> System.Web.SiteMapNodePublic Overrides Function BuildSiteMap () As SiteMapNodeReturns
Returns the root SiteMapNode of the site map navigation structure.
Exceptions
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.
Examples
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 property 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>
Remarks
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.
