Site Map Providers

Introduction to the Provider Model
Membership Providers
Role Providers
Site Map Providers
Session State Providers
Profile Providers
Web Event Providers
Web Parts Personalization Providers
Custom Provider-Based Services
Hands-on Custom Providers: The Contoso Times

Site map providers provide the interface between ASP.NET's data-driven site-navigation features and site map data sources. The two most common reasons for writing a custom site map provider are:

• You wish to store site maps in a data source that is not supported by the site map providers included with the .NET Framework, such as a Microsoft SQL Server database.
• You wish to store site map data in an XML file whose schema differs from that of the one used by System.Web.XmlSiteMapProvider.

The fundamental job of a site map provider is to read site map data from a data source and build an upside-down tree of SiteMapNode objects (Figure 4-1), and to provide methods for retrieving nodes from the site map. Each SiteMapNode in the tree represents one node in the site map. SiteMapNode properties such as Title, Url, ParentNode, and ChildNodes define the characteristics of each node and allow the tree to be navigated up, down, and sideways. A single site map can be managed by one or several providers. Site map providers can form a tree of their own, linked together by their ParentProvider properties, with each provider in the tree claiming responsibility for a subset of the site map. A SiteMapNode's Provider property identifies the provider that "owns" that node.

Figure 1. Site map structure

ASP.NET assumes that each site map node's URL is unique with respect to other URLs in the site map. However, site maps do support nodes without URLs. Every SiteMapNode has a Key property that the provider initializes with a value that uniquely identifies the node. ASP.NET's XmlSiteMapProvider class sets SiteMapNode.Key equal to the node's URL if SiteMapNode.Url is neither null nor empty, or to a randomly generated GUID otherwise. Site map providers include methods for finding nodes by URL or by key.

Developers writing custom site map providers typically begin by deriving from System.Web.StaticSiteMapProvider, which derives from System.Web.SiteMapProvider. However, developers also have the option of deriving from SiteMapProvider directly. SiteMapProvider defines the basic contract between ASP.NET and site map providers. StaticSiteMapProvider goes much further, providing default implementations of most of SiteMapProvider's abstract methods and overriding key virtuals to provide functional, even optimized, implementations.

Deriving from StaticSiteMapProvider is appropriate for custom providers that read node data once (or infrequently) and then cache the information for the lifetime of the provider. Deriving from SiteMapProvider is appropriate for custom providers that query a database or other underlying data source in every method call.

The SiteMapProvider Class

System.Web.SiteMapProvider is prototyped as follows:

public abstract class SiteMapProvider : ProviderBase
{
    // Public events
    public event SiteMapResolveEventHandler SiteMapResolve;

    // Public properties
    public virtual SiteMapNode CurrentNode { get; }
    public bool EnableLocalization { get; set; }
    public virtual SiteMapProvider ParentProvider { get; set; }
    public string ResourceKey { get; set; }
    public virtual SiteMapProvider RootProvider { get; }
    public virtual SiteMapNode RootNode { get; }
    public bool SecurityTrimmingEnabled { get; }

    // Non-virtual methods
    protected SiteMapNode ResolveSiteMapNode(HttpContext context) {}
    protected static SiteMapNode GetRootNodeCoreFromProvider
        (SiteMapProvider provider) {}

    // Virtual methods
    public override void Initialize(string name,
        NameValueCollection attributes) {}
    protected virtual void AddNode(SiteMapNode node) {}
    protected internal virtual void AddNode(SiteMapNode node,
        SiteMapNode parentNode) {}
    protected internal virtual void RemoveNode(SiteMapNode node) {}
    public virtual SiteMapNode FindSiteMapNode(HttpContext context) {}
    public virtual SiteMapNode FindSiteMapNodeFromKey(string key) {}
    public virtual SiteMapNode GetCurrentNodeAndHintAncestorNodes
        (int upLevel) {}
    public virtual SiteMapNode GetCurrentNodeAndHintNeighborhoodNodes
        (int upLevel, int downLevel) {}
    public virtual SiteMapNode
        GetParentNodeRelativeToCurrentNodeAndHintDownFromParent
        (int walkupLevels, int relativeDepthFromWalkup) {}
    public virtual SiteMapNode
        GetParentNodeRelativeToNodeAndHintDownFromParent
        (SiteMapNode node, int walkupLevels,
        int relativeDepthFromWalkup) {}
    public virtual void HintAncestorNodes(SiteMapNode node,
        int upLevel) {}
    public virtual void HintNeighborhoodNodes(SiteMapNode node,
        int upLevel, int downLevel) {}
    public virtual bool IsAccessibleToUser(HttpContext context,
        SiteMapNode node) {}

    // Abstract methods
    public abstract GetChildNodes(SiteMapNode node);
    public abstract SiteMapNode FindSiteMapNode(string rawUrl);
    public abstract SiteMapNode GetParentNode(SiteMapNode node);
    protected internal abstract SiteMapNode GetRootNodeCore();
}

The following table describes SiteMapProvider's methods and properties and provides helpful notes regarding their implementation:

Security Trimming

The SiteMapProvider class contains built-in support for security trimming, which restricts the visibility of site map nodes based on users' role memberships. SiteMapProvider implements a Boolean read-only property named SecurityTrimmingEnabled, which indicates whether security trimming is enabled. Furthermore, SiteMapProvider.Initialize initializes this property from the provider's securityTrimmingEnabled configuration attribute. Internally, SiteMapProvider methods that retrieve nodes from the site map call the provider's virtual IsAccessibleToUser method to determine whether nodes can be retrieved. All a custom provider has to do to support security trimming is initialize each SiteMapNode's Roles property with an array of role names identifying users that are permitted to access that node, or "*" if everyone (including unauthenticated users and users who enjoy no role memberships) is permitted.

Security trimming doesn't necessarily prevent SiteMapProvider.IsAccessibleToUser from returning true if the user doesn't belong to one of the roles specified in a node's Roles property. Here's a synopsis of how IsAccessibleToUser uses SiteMapNode.Roles to authorize access to a node-that is, to determine whether to return true or false:

1. If the current user is in a role specified in the node's Roles property, or if Roles is "*", the node is returned.
2. If the current user is not in a role specified in the node's Roles property, then a URL authorization check is performed to determine whether the user has access to the node's URL. If the answer is yes, the node is returned.
3. If Windows authentication is being used on the site, and if (1) and (2) failed, then a file authorization (ACL) check is performed against the node's URL using the current user's security token. If the ACL check succeeds, the node is returned.

Nodes lower in the hierarchy implicitly inherit the Roles properties of their parents, but only to a point. Refer to the sidebar below for a more detailed explanation.

Content Localization

The combination of SiteMapProvider's EnableLocalization and ResourceKey properties and SiteMapNode's ResourceKey property enables site map providers to support content localization. If localization is enabled (as indicated by the provider's EnableLocalization property), a provider may use the ResourceKey properties to load text for SiteMapNode's Title and Description properties, and even for custom properties, from resources (for example, compiled RESX files).

Resource keys can be implicit or explicit. Here's an example of an XmlSiteMapProvider-compatible site map that uses implicit resource keys to load node titles and descriptions:

<siteMap enableLocalization="true">
  <siteMapNode description="Home" url="~/Default.aspx">
    <siteMapNode title="Autos" description="Autos"
      url="~/Autos.aspx" resourceKey="Autos" />
    <siteMapNode title="Games" description="Games"
      url="~/Games.aspx" resourceKey="Games" />
    <siteMapNode title="Health" description="Health"
      url="~/Health.aspx" resourceKey="Health" />
    <siteMapNode title="News" description="News"
      url="~/News.aspx" resourceKey="News" />
  </siteMapNode>
</siteMap>

In this example, the "Autos" site map node's Title and Description properties are taken from resources named Autos.Title and Autos.Description (and default to "Autos" and "Autos" if those resources don't exist or localization isn't enabled). SiteMapNode formulates the resource names by combining resourceKey values and property names; it also handles the chore of loading the resources.

The root name of the file containing the resources is specified using the provider's ResourceKey property. For example, suppose ResourceKey="SiteMapResources", and that localization resources are defined in RESX files deployed in the application's App_GlobalResources directory for automatic compilation. SiteMapNode will therefore extract resources from SiteMapResources.culture.resx, where culture is the culture expressed in Thread.CurrentThread.CurrentUICulture. Resources for the fr culture would come from SiteMapResources.fr.resx, resources for en-us would come from SiteMapResources.en-us.resx, and so on. Requests lacking a culture specifier would default to SiteMapResources.resx.

A site map provider that supports localization via implicit resource keys should do the following:

• Initialize its ResourceKey property with a root resource file name. This value could come from a custom configuration attribute, or it could be based on something else entirely. ASP.NET's XmlSiteMapProvider, for example, sets the provider's ResourceKey property equal to the site map file name specified with the siteMapFile configuration attribute (which defaults to Web.sitemap).
• Pass resource key values specified for site map nodes—for example, the resourceKey attribute values in <siteMapNode> elements—to SiteMapNode's constructor as the implicitResourceKey parameter.
• Set its own EnableLocalization property to true.

Although SiteMapProvider implements the EnableLocalization property, neither SiteMapProvider nor StaticSiteMapProvider initializes that property from a configuration attribute. If you want to support enableLocalization in your provider's configuration, you should do as XmlSiteMapProvider does and initialize the provider's EnableLocalization property from the enableLocalization attribute of the <siteMap> element in the site map file. It's important to set the provider's EnableLocalization property to true if you wish to localize site map nodes, because the SiteMapNode class checks that property before deciding whether to load content from resources.

The StaticSiteMapProvider Class

Whereas SiteMapProvider defines the basic contract between ASP.NET and site map providers, StaticSiteMapProvider aids developers in implementing that contract. StaticSiteMapProvider is the base class for ASP.NET's XmlSiteMapProvider. It can also be used as the base class for custom site map providers. Provider classes that derive from StaticSiteMapProvider require considerably less code than providers derived from SiteMapProvider.

The word "Static" in StaticSiteMapProvider refers to the fact that the site map data source is static. Nonetheless, while the data source may be static, the site map itself does not have to be. Developers can add, remove, and change site map nodes on the fly by responding to a site map provider's SiteMapResolve events.

System.Web.StaticSiteMapProvider is prototyped as follows:

public abstract class StaticSiteMapProvider : SiteMapProvider
{
    public abstract SiteMapNode BuildSiteMap();
    protected virtual void Clear() {}
    protected internal override void AddNode(SiteMapNode node,
        SiteMapNode parentNode) {}
    protected internal override void RemoveNode(SiteMapNode node) {}
    public override SiteMapNode FindSiteMapNode(string rawUrl) {}
    public override SiteMapNode FindSiteMapNodeFromKey(string key) {}
    public override SiteMapNodeCollection
        GetChildNodes(SiteMapNode node) {}
    public override SiteMapNode GetParentNode(SiteMapNode node) {}
}

The following table describes StaticSiteMapProvider's methods and provides helpful notes regarding their implementation:

StaticSiteMapProvider provides default implementations of most of SiteMapProvider's abstract methods (the notable exception being GetRootNodeCore), and internally it uses a set of Hashtables to make lookups performed by FindSiteMapNode, GetParentNode, and GetChildNodes fast and efficient. It also defines an abstract method of its own, BuildSiteMap, which signals the provider to read the data source and build the site map. BuildSiteMap can be (and in practice, is) called many times throughout the provider's lifetime, so it's crucial to build in an internal check to make sure the site map is loaded just once. (Subsequent calls to BuildSiteMap can simply return a reference to the existing root node.) In addition, BuildSiteMap should generally not call other site map provider methods or properties, because many of the default implementations of those methods and properties call BuildSiteMap. For example, the simple act of reading RootNode in BuildSiteMap causes a recursive condition that terminates in a stack overflow.

SqlSiteMapProvider

SqlSiteMapProvider is a StaticSiteMapProvider-derivative that demonstrates the key ingredients that go into a custom site map provider. Unlike XmlSiteMapProvider, which reads site map data from an XML file, SqlSiteMapProvider reads site maps from a SQL Server database. It doesn't support localization, but it does support other significant features found in XmlSiteMapProvider, including security trimming and site maps of unlimited depth. SqlSiteMapProvider's source code appears below.

SqlSiteMapProvider

using System;
using System.Web;
using System.Data.SqlClient;
using System.Collections.Specialized;
using System.Configuration;
using System.Web.Configuration;
using System.Collections.Generic;
using System.Runtime.CompilerServices;
using System.Configuration.Provider;
using System.Security.Permissions;
using System.Data.Common;

[SqlClientPermission (SecurityAction.Demand, Unrestricted=true)]
public class SqlSiteMapProvider : StaticSiteMapProvider
{
    private const string _errmsg1 = "Missing node ID";
    private const string _errmsg2 = "Duplicate node ID";
    private const string _errmsg3 = "Missing parent ID";
    private const string _errmsg4 = "Invalid parent ID";
    private const string _errmsg5 =
        "Empty or missing connectionStringName";
    private const string _errmsg6 = "Missing connection string";
    private const string _errmsg7 = "Empty connection string";

    private string _connect;
    private int _indexID, _indexTitle, _indexUrl,
        _indexDesc, _indexRoles, _indexParent;
    private Dictionary<int, SiteMapNode> _nodes =
        new Dictionary<int, SiteMapNode>(16);
    private SiteMapNode _root;

    public override void Initialize (string name,
        NameValueCollection config)
    {
        // Verify that config isn't null
        if (config == null)
            throw new ArgumentNullException("config");

        // Assign the provider a default name if it doesn't have one
        if (String.IsNullOrEmpty(name))
            name = "SqlSiteMapProvider";

        // Add a default "description" attribute to config if the
        // attribute doesn't exist or is empty
        if (string.IsNullOrEmpty(config["description"]))
        {
            config.Remove("description");
            config.Add("description", "SQL site map provider");
        }

        // Call the base class's Initialize method
        base.Initialize(name, config);

        // Initialize _connect
        string connect = config["connectionStringName"];

        if (String.IsNullOrEmpty (connect))
            throw new ProviderException (_errmsg5);

        config.Remove ("connectionStringName");

        if (WebConfigurationManager.ConnectionStrings[connect] == null)
            throw new ProviderException (_errmsg6);

        _connect = WebConfigurationManager.ConnectionStrings
            [connect].ConnectionString;

        if (String.IsNullOrEmpty (_connect))
            throw new ProviderException (_errmsg7);
        
        // In beta 2, SiteMapProvider processes the
        // securityTrimmingEnabled attribute but fails to remove it.
        // Remove it now so we can check for unrecognized
        // configuration attributes.

        if (config["securityTrimmingEnabled"] != null)
            config.Remove("securityTrimmingEnabled");
        
        // Throw an exception if unrecognized attributes remain
        if (config.Count > 0)
        {
            string attr = config.GetKey(0);
            if (!String.IsNullOrEmpty(attr))
                throw new ProviderException
                    ("Unrecognized attribute: " + attr);
        }
    }

   public override SiteMapNode BuildSiteMap()
   {
        lock (this)
        {
            // Return immediately if this method has been called before
            if (_root != null)
                return _root;

            // Query the database for site map nodes
            SqlConnection connection = new SqlConnection(_connect);
            
            try
            {
                connection.Open();
                SqlCommand command =
                    new SqlCommand("proc_GetSiteMap", connection);
                command.CommandType = CommandType.StoredProcedure;            
                SqlDataReader reader = command.ExecuteReader();
                _indexID = reader.GetOrdinal("ID");
                _indexUrl = reader.GetOrdinal("Url");
                _indexTitle = reader.GetOrdinal("Title");
                _indexDesc = reader.GetOrdinal("Description");
                _indexRoles = reader.GetOrdinal("Roles");
                _indexParent = reader.GetOrdinal("Parent");

                if (reader.Read())
                {
                    // Create the root SiteMapNode and add it to
                    // the site map
                    _root = CreateSiteMapNodeFromDataReader(reader);
                    AddNode(_root, null);

                    // Build a tree of SiteMapNodes underneath
                    // the root node
                    while (reader.Read())
                    {
                        // Create another site map node and
                        // add it to the site map
                        SiteMapNode node =
                            CreateSiteMapNodeFromDataReader(reader);
                        AddNode(node,
                            GetParentNodeFromDataReader (reader));
                    }
                }
            }
            finally
            {
                connection.Close();
            }

            // Return the root SiteMapNode
            return _root;
        }
    }

    protected override SiteMapNode GetRootNodeCore ()
    {
        BuildSiteMap ();
        return _root;
    }

    // Helper methods
    private SiteMapNode
        CreateSiteMapNodeFromDataReader (DbDataReader reader)
    {
        // Make sure the node ID is present
        if (reader.IsDBNull (_indexID))
            throw new ProviderException (_errmsg1);

        // Get the node ID from the DataReader
        int id = reader.GetInt32 (_indexID);

        // Make sure the node ID is unique
        if (_nodes.ContainsKey(id))
            throw new ProviderException(_errmsg2);

        // Get title, URL, description, and roles from the DataReader
        string title = reader.IsDBNull (_indexTitle) ?
            null : reader.GetString (_indexTitle).Trim ();
        string url = reader.IsDBNull (_indexUrl) ?
            null : reader.GetString (_indexUrl).Trim ();
        string description = reader.IsDBNull (_indexDesc) ?
            null : reader.GetString (_indexDesc).Trim ();
        string roles = reader.IsDBNull(_indexRoles) ?
            null : reader.GetString(_indexRoles).Trim();

        // If roles were specified, turn the list into a string array
        string[] rolelist = null;
        if (!String.IsNullOrEmpty(roles))
            rolelist = roles.Split(new char[] { ',', ';' }, 512);

        // Create a SiteMapNode
        SiteMapNode node = new SiteMapNode(this, id.ToString(), url,
            title, description, rolelist, null, null, null);

        // Record the node in the _nodes dictionary
        _nodes.Add(id, node);
       
        // Return the node        
        return node;        
    }

    private SiteMapNode
        GetParentNodeFromDataReader(DbDataReader reader)
    {
        // Make sure the parent ID is present
        if (reader.IsDBNull (_indexParent))
            throw new ProviderException (_errmsg3);

        // Get the parent ID from the DataReader
        int pid = reader.GetInt32(_indexParent);

        // Make sure the parent ID is valid
        if (!_nodes.ContainsKey(pid))
            throw new ProviderException(_errmsg4);

        // Return the parent SiteMapNode
        return _nodes[pid];
    }
}

The heart of SqlSiteMapProvider is its BuildSiteMap method, which queries the database for site map node data and constructs SiteMapNodes from the query results. The query is performed by calling the stored procedure named proc_GetSiteMap, which is defined as follows:

CREATE PROCEDURE proc_GetSiteMap AS SELECT [ID], [Title],
[Description], [Url], [Roles], [Parent] FROM [SiteMap] ORDER BY [ID]

The helper method CreateSiteMapNodeFromDataReader does the node construction, checking for errors such as missing or non-unique node IDs as well. CreateSiteMapNodeFromDataReader also records each SiteMapNode that it creates in an internal dictionary used by the other helper method, GetParentNodeFromDataReader, to retrieve a reference to a node's parent before adding the node to the site map with AddNode.

SqlSiteMapProvider inherits support for the securityTrimmingEnabled configuration attribute from SiteMapProvider. It also supports one configuration attribute of its own: connectionStringName. The provider's Initialize method reads connectionStringName and BuildSiteMap uses it to read a database connection string from the <connectionStrings> configuration section. This is the connection string used to connect to the SQL Server database containing the site map. The Web.config file below makes SqlSiteMapProvider the default provider and provides it with a connection string.

Web.config file making SqlSiteMapProvider the default site map provider and enabling security trimming

<configuration>
  <connectionStrings>
    <add name="SiteMapConnectionString" connectionString="..." />
  </connectionStrings>
  <system.web>
    <siteMap enabled="true" defaultProvider="AspNetSqlSiteMapProvider">
      <providers>
        <add name="AspNetSqlSiteMapProvider"
          type="SqlSiteMapProvider, CustomProviders"
          description="SQL Server site map provider"
          securityTrimmingEnabled="true"
          connectionStringName="SiteMapConnectionString"
        />
      </providers>
    </siteMap>
  </system.web>
</configuration>

The SQL script below creates a SqlSiteMapProvider-compatible SiteMap table. The Title, Description, Url, and Roles columns correspond to the SiteMapNode properties of the same names. The ID and Parent columns serve to uniquely identify nodes in the site map and form parent-child relationships between them. Every node must have a unique ID in the ID column, and every node except the root node must contain an ID in the Parent column identifying the node's parent. The one constraint to be aware of is that a child node's ID must be greater than its parent's ID. In other words, a node with an ID of 100 can be the child of a node with an ID of 99, but it can't be the child of a node with an ID of 101. That's a consequence of the manner in which SqlSiteMapProvider builds the site map in memory as it reads nodes from the database.

SQL script for creating a SqlSiteMapProvider-compatible SiteMap table

CREATE TABLE [dbo].[SiteMap] (
    [ID]          [int] NOT NULL,
    [Title]       [varchar] (32),
    [Description] [varchar] (512),
    [Url]         [varchar] (512),
    [Roles]       [varchar] (512),
    [Parent]      [int]
) ON [PRIMARY]
GO

ALTER TABLE [dbo].[SiteMap] ADD 
    CONSTRAINT [PK_SiteMap] PRIMARY KEY CLUSTERED 
    (
        [ID]
    )  ON [PRIMARY] 
GO

Figure 2 shows a view in SQL Server Enterprise Manager of a SiteMap table. Observe that each node has a unique ID and a unique URL. (Tthe latter is a requirement of site maps managed by site map providers that derive from StaticSiteMapProvider.) All nodes but the root node also have a parent ID that refers to another node in the table, and the parent's ID is always less than the child's ID. Finally, because the "Entertainment" node has a Roles value of "Members,Administrators," a navigational control such as a TreeView or Menu will only render that node and its children if the user viewing the page has been authenticated and is a member of the Members or Administrators group. That's assuming, of course, that security trimming is enabled. If security trimming is not enabled, all nodes are visible to all users. SqlSiteMapProvider contains no special code to make security trimming work; that logic is inherited from SiteMapProvider and StaticSiteMapProvider.

Figure 2. Sample SiteMap table (Click on the graphic for a larger image)

Click here to continue on to part 4, Session State Providers

© Microsoft Corporation. All rights reserved.