|Important||This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here. ArchiveDisclaimer|
ASP.NET Site Maps
To use ASP.NET site navigation, you must describe the structure of the site so that the site navigation API and the site navigation controls can expose the site structure properly. By default, the site navigation system uses an XML file that contains the site hierarchy. However, you can also configure the site navigation system to use alternative data sources. For more information, see ASP.NET Site Navigation Providers.
The simplest way to create a site map is to create an XML file named Web.sitemap that organizes the pages in the site hierarchically. This site map is automatically picked up by the default site-map provider for ASP.NET.
The Web.sitemap file must be located in the application root directory, though it can reference other site-map providers, or other site-map files in other directories as long as those files are in the same application. For more information, see How to: Configure Multiple Site Maps and Site-Map Providers.
Implementing a custom site-map provider that stores site-map data in a file with a file name extension other than .sitemap is a potential security risk. By default, ASP.NET is configured to protect files with known file name extensions — such as .sitemap — from being downloaded by a client. To help protect your data, place any custom site-map data files that have a file name extension other than .sitemap in the App_Data folder. For more information, see Securing ASP.NET Site Navigation.
The following code example shows how the site map might look for a simple site that goes three levels deep. The url attribute can start with the "~/" shortcut which indicates the application root. For more information, see ASP.NET Web Site Paths.
<siteMap> <siteMapNode title="Home" description="Home" url="~/default.aspx"> <siteMapNode title="Products" description="Our products" url="~/Products.aspx"> <siteMapNode title="Hardware" description="Hardware choices" url="~/Hardware.aspx" /> <siteMapNode title="Software" description="Software choices" url="~/Software.aspx" /> </siteMapNode> <siteMapNode title="Services" description="Services we offer" url="~/Services.aspx"> <siteMapNode title="Training" description="Training classes" url="~/Training.aspx" /> <siteMapNode title="Consulting" description="Consulting services" url="~/Consulting.aspx" /> <siteMapNode title="Support" description="Supports plans" url="~/Support.aspx" /> </siteMapNode> </siteMapNode> </siteMap>
In the Web.sitemap file, add a siteMapNode element for each page in your Web site. Then you can create the hierarchy by nesting siteMapNode elements. In the preceding example, the pages for Hardware and Software are child elements of the Products siteMapNode element. The title attribute defines the text that is usually used as link text, and the description attribute acts both as documentation and as a tool tip in the SiteMapPath control.
In a site map, you can reference URLs that are outside of your Web application. Access to a URL outside of the application cannot be tested by ASP.NET. Therefore if you enable security trimming, the site-map node will not be visible unless you set the roles attribute to "*", which enables all clients to view the site-map node without first testing access to the URL. For more information, see ASP.NET Site-Map Security Trimming.
A valid site-map file contains only one siteMapNode element that is located immediately under the siteMap element. But the first-level siteMapNode element can contain any number of child siteMapNode elements. Additionally, a valid sitemap file must not have duplicate URLs, though the url attributes can be empty. Providers other than the default site-map provider for ASP.NET might not have this restriction.
You can use more than one site-map file or provider to describe the navigation structure of an entire Web site. For example, your root Web.sitemap file can link to a child site-map file by referencing the child site-map file in a siteMapNode element using the following code.
For more information, see How to: Configure Multiple Site Maps and Site-Map Providers.
You can localize the following properties in a site map.
To localize the Url property, or to define different navigational structures based on a user's locale, you need to define different site-map files for each locale and programmatically switch to the appropriate Provider at run time. For more information, see How to: Programmatically Modify Site-Map Nodes in Memory. For more information about localizing site maps, see How to: Localize Site-Map Data.