UrlMappingModule
By Mike Ellison
Bringing MVC Framework-style URL redirections to classic ASP.NET 2.0 WebForms development
Introduction
URL redirection or rewriting, is the process of intercepting an incoming request URL and redirecting it internally such that a potentially different page handles the request. For example, an incoming URL requesting the application resource Reports/Customer/407.aspx may be internally redirected to DisplayCustomer.aspx?ID=407, with a different page (DisplayCustomer.aspx) actually processing the request. To the end user, this internal redirection is transparent, and the requesting URL remains Reports/Customer/407.aspx. The originally requested page (407.aspx) need not even exist in the application.
Typically a URL rewriting engine will use a list of regular expressions to provide rules for mapping an incoming URL to a redirected URL; there are a number of examples available both commercially and in the public domain of such engines. The MVC Framework, recently made available as a community preview, includes a powerful and easy-to-use engine for mapping incoming URLs to controller classes that process a given Web request. By using syntax of square-bracketed [tokens] within URL templates, the MVC Framework simplifies the specification of mapping rules, eliminating the need for more complicated regular expressions. For example, the URL template Reports/[Type]/[ID].aspx can be listed among mapping rules; when an incoming URL matches this pattern, the proper controller is activated and values for the tokens [Type] and [ID] are automatically parsed. This syntax is elegant, simple to apply, and easy to understand.
This article presents a URL redirection engine called UrlMappingModule designed for the ASP.NET 2.0 WebForms environment and inspired by the MVC Framework's [token]-based syntax. The module implements IHttpModule and is attached to the ASP.NET HTTP pipeline through Web.config entries. The module supports a provider model for the supplying of URL redirection rules, with two concrete providers, XmlUrlMappingProvider and SqlUrlMappingProvider, available in the module's assembly. While the developer may implement the included IUrlMappingProvider interface to take full control of regular expression syntax for pattern matching, the two built-in providers support the simplicity of [tokens] in URL template strings. When incoming URLs are matched to a pattern with tokens, token names and values are automatically appended to the redirection URL as querystring arguments and thus are available to the page handling the request through the normal Request.QueryString collection.
Using the UrlMappingModule with the XmlUrlMappingProvider
The XmlUrlMappingProvider supplies the UrlMappingModule with URL templates and redirection mappings from an XML file, typically stored in the web application's App_Data directory. Mappings are defined in the XML file as <urlMapping> nodes with three attributes: name, urlTemplate, and redirection.
- The
name attribute specifies a developer-relevant name and is not used directly by the UrlMappingModule.
- The
urlTemplate attribute is a string specifying an incoming URL or URL pattern to match. The urlTemplate may reflect a static URL, such as Reports.aspx, or may include token names in [squareBrackets] to imply a pattern for dynamic matching, such as Reports/[ReportID].aspx.
- The
redirection attribute is a string specifying the URL to redirect to when the corresponding urlTemplate is matched on an incoming URL.
A fourth attribute, enabled, is optional, and may be set to true or false to enable or disable the particular mapping rule respectively. By default, mapping rules are enabled.
The following shows an example of an XML file with URL mapping rules:
="1.0" ="utf-8"
<urlMappings>
<urlMapping name="default"
urlTemplate="Default.aspx"
redirection="Default.aspx"
enabled="true"
/>
<urlMapping name="msdn"
urlTemplate="msdn.aspx"
redirection="http://www.msdn.com"
/>
<urlMapping name="customerReports"
urlTemplate="Customers/[ID]/[Action].aspx"
redirection="CustReports.aspx"
enabled="true"
/>
</urlMappings>
Note that the urlTemplate attributes all assume an application-relative incoming URL. Also note, each urlTemplate must incorporate an extension that IIS has mapped to the ASP.NET process (in all examples in this article, the extension will be ASPX). The first item, default shows a static redirection to the same application-relative URL. The second, msdn, shows a static redirection to an external Web site. The third, customerReports, shows a dynamic redirection, using [tokens] in the urlTemplate to represent portions of a possible incoming URL. If an incoming URL matches the pattern, the [ID] and [Action] values are parsed and appended as querystring values to the redirection page CustReports.aspx.
For example, an incoming URL of Customers/407/Display.aspx is matched according to this third mapping rule and redirected to the application URL CustReports.aspx?ID=407&Action=Display. Matches are attempted in the order in which <urlMapping> items appear in the file; in the event an incoming URL could match multiple items, the redirection of the first item matched is used.
Assuming the URL mapping file is stored in the APP_DATA directory with the filename urlMappings.xml, the following shows an example of the Web.config settings necessary to make use of the provider with this file. Note that three separate pieces of configuration are required:
- The
<configSections> section tag entry, identifying that the provider-specific XmlUrlMappingProviderConfiguration object should be used for configuration
- The
<urlMappingModule> entry including the urlMappingFile attribute specifying the XML file providing the mapping rules
- The
<httpModules> entry, telling ASP.NET to include the UrlMappingModule in the pipeline
Collapse
<configuration>
<configSections>
<section name="urlMappingModule"
type="UNLV.IAP.UrlMapping.XmlUrlMappingProviderConfiguration,
UrlMappingModule"
/>
</configSections>
<urlMappingModule providerType="UNLV.IAP.UrlMapping.XmlUrlMappingProvider,
UrlMappingModule"
noMatchAction="ThrowException"
noMatchRedirectUrl=""
incomingQueryStringBehavior="PassThrough"
ignoreExtensions=".js .css"
automaticallyUpdateFormAction="true"
urlProcessingEvent="BeginRequest"
urlMappingFile="~/App_Data/urlMappings.xml"
useDependency="true"
/>
<system.web>
<httpModules>
<add name="UrlMappingModule"
type="UNLV.IAP.UrlMapping.UrlMappingModule, UrlMappingModule"
/>
</httpModules>
</system.web>
</configuration>
The name for the custom configuration section is required to be literally urlMappingModule. The attributes for the configuration section include those that affect the behavior of the UrlMappingModule itself (providerType, noMatchAction, noMatchRedirectUrl, incomingQueryStringBehavior, ignoreExtensions, automaticallyUpdateFormAction, and urlProcessingEvent) as well as those specific to the XmlUrlMappingProvider (urlMappingFile and useDependency).
providerType - Specifies the type of the provider used by the UrlMappingModule (in this case, the XmlUrlMappingProvider) noMatchAction - One of four actions the UrlMappingModule may take when it fails to match an incoming URL given the provided set of mapping rules. Possible values are defined by the NoMatchActionEnum enumeration:
PassThrough – (default) Allow an unmatched URL to continue to be processed normally by the ASP.NET engine. ThrowException - Throw a NoMatchFoundException when presented with an unmatched URL. Return404 - Return a 404 (page not found) error code to the browser when presented with an unmatched URL. Redirect - Redirect to the page specified in the configuration's noMatchRedirectUrl attribute when presented with an unmatched URL.
incomingQueryStringBehavior - One of three behaviors to influence how the UrlMappingModule treats querystring arguments on an incoming URL. Possible values are defined by the IncomingQueryStringBehaviorEnum enumeration:
PassThrough – (default) Ignore incoming querystring values when pattern matching a URL, but apply those values to the redirected URL. Ignore – Ignore incoming querystring values when pattern matching a URL, and do not apply those values to the redirected URL. Include - Include the querystring on an incoming URL when pattern matching.
To further illustrate how incoming querystring values are treated, consider the following examples. If PassThrough is specified, an incoming querystring of Default.aspx?cat=1 will be treated as Default.aspx for the sake of pattern matching. If a match is found, "cat=1" will be appended to the redirection URL as part of the redirected querystring.
If Ignore is specified, an incoming querystring of Default.aspx?cat=1 will be treated as Default.aspx for the sake of pattern matching. If a match is found, "cat=1" will not be appended to the redirection URL.
If Include is specified, an incoming querystring of "Default.aspx?cat=1" will be treated literally as Default.aspx?cat=1 for the sake of pattern matching. If that URL is compared to a URL template of Default.aspx, the match is not made - the URL template would need to incorporate potential querystring input. For example, a URL template may capture a specific querystring value using a template such as Default.aspx?cat=[cat]. In this case, the redirected URL will append "cat=xxx" to the querystring.
ignoreExtensions – A list of file extensions, requests for which will be ignored completely by the UrlMappingModule. For example, to allow all requests for JavaScript files and CSS stylesheets to pass by the UrlMappingModule and be processed without redirection as normal by ASP.NET, set this attribute to the string .js .css. Separate multiple items with spaces or commas. automaticallyUpdateFormAction – An optional Boolean instructing the UrlMappingModule to automatically adjust rendered <form action=”…”> tags such that the action for a redirected form matches the incoming URL. See Points of Interest below for more information. The default value is true. urlProcessingEvent – One of three options which determines when in the request cycle the UrlMappingModule processes the incoming URL. Possible values are defined by the UrlProcessingEventEnum enumeration:
BeginRequest – (default) – Process incoming requests in the application’s BeginRequest event. This is the common choice when authentication is not required. AuthenticateRequest – Process incoming requests in the application’s AuthenticateRequest event. This option may be helpful, particularly if the application employs Windows authentication. AuthorizeRequest - Process incoming requests in the application’s AuthorizeRequest event. This option may be helpful, particularly if the application employs Forms authentication.
Scott Mitchell describes issues surrounding the timing of URL rewriting with respect to other HttpModules (such as those that manage application authorization) very well in the article URL Rewriting in ASP.NET[^]. Readers who want a more thorough discussion on URL rewriting in general, and event handling specifically, are encouraged to read his article.
urlMappingFile - The application-relative path to the XML file with <urlMapping> rules defined. useDependency - A Boolean that determines whether the internally-cached mapping items should be updated automatically as changes are made in the urlMappingFile. If set to true, a CacheDependency[^] object is used internally to poll the urlMappingFile for changes. If false, changes made to the urlMappingFile are only incorporated upon the next application startup, or upon an explicit call to the static utility method UrlMappingModule.RefreshUrlMappings().
Using the UrlMappingModule with the SqlUrlMappingProvider
The SqlUrlMappingProvider supplies the UrlMappingModule with redirection rules from an SQL Server database. The database must supply a stored procedure that returns at least three named columns: [Name], [UrlTemplate], and [Redirection], with records sorted as desired for the UrlMappingManager to match incoming URLs. As with the XmlUrlMappingProvider, the UrlTemplate column may include strings with square-bracketed [tokens] to imply patterns for matching.
The following shows an example of an SQL script with commands to create and populate a UrlMappings table, and a stored procedure for supplying the UrlMappingModule with matching rules:
create table UrlMappings
(
[Name] varchar(255) NOT NULL
,[UrlTemplate] varchar(8000) NOT NULL
,[Redirection] varchar(8000) NOT NULL
,[SortOrder] numeric(18,0) NOT NULL
)
insert into UrlMappings
values('default', 'Default.aspx', 'Default.aspx', 1);
insert into UrlMappings
values('msdn', 'msdn.aspx', 'http://www.msdn.com', 2);
insert into UrlMappings
values('customerReports', 'Customers/[ID]/[Action].aspx',
'CustReports.aspx', 3);
create procedure GetUrlMappings
as
begin
select Name,UrlTemplate,Redirection
from UrlMappings
order by SortOrder, Name
end
The developer may include any other columns in the UrlMappings table as desired, but the stored procedure must return at least three columns with the literal names [Name], [UrlTemplate], and [Redirection], or an exception is thrown upon usage. Assuming the table name UrlMappings, the stored procedure name GetUrlMappings, and a connection string name UrlMappingData defined in the <connectionStrings> entry of the Web.config file, the following shows the additional Web.config settings required to configure the UrlMappingModule for use with the SqlUrlMappingProvider:
Collapse
<configuration>
<configSections>
<section name="urlMappingModule"
type="UNLV.IAP.UrlMapping.SqlUrlMappingProviderConfiguration,
UrlMappingModule"
/>
</configSections>
<urlMappingModule
providerType="UNLV.IAP.UrlMapping.SqlUrlMappingProvider, UrlMappingModule"
noMatchAction="ThrowException"
noMatchRedirectUrl=""
incomingQueryStringBehavior="PassThrough"
ignoreExtensions=".js .css"
automaticallyUpdateFormAction="true"
urlProcessingEvent="BeginRequest"
connectionStringName="UrlMappingData"
tableName="UrlMappings"
procName="GetUrlMappings"
useDependency="true"
dependencyName="UrlMappingDep"
/>
<system.web>
<httpModules>
<add name="UrlMappingModule"
type="UNLV.IAP.UrlMapping.UrlMappingModule, UrlMappingModule"
/>
</httpModules>
</system.web>
</configuration>
As already stated, the <urlMappingModule> attributes providerType, noMatchAction, noMatchRedirectUrl, incomingQueryStringBehavior, ignoreExtensions, automaticallyUpdateFormAction,urlProcessingEvent affect the module itself and function as described above, with providerType specifying the SqlUrlMappingProvider type. Additional attributes that affect the behavior of the SqlUrlMappingProvider specifically are as follows:
connectionStringName - Specifies the name of the <connectionString> entry that defines the SQL Server database connection tableName - The name of the SQL Server database table containing URL templates and redirection mappings procName - The name of the SQL Server stored procedure that retrieves a data set of URL redirection rules. The procedure must accept no arguments and return a result set with three named columns: [Name], [UrlTemplate], and [Redirection]. useDependency - Determines whether the table identified by tableName should be periodically polled for changes. If useDependency is set to true, polling should occur and the internally-cached data for URL mappings will be refreshed automatically upon updates. If useDependency is false, changes in the persisted mapping table will be reflected only upon the next application startup, or upon an explicit call to the static utility method UrlMappingModule.RefreshUrlMappings(). dependencyName - Used when useDependency="true" to specify the name of the associated sqlCacheDependency entry in the Web.config file.
Additional configuration is necessary when a dependency is requested (i.e. useDependency="true"); specifically, the database and table must be configured for cache dependencies. For SQL Server 2000 or 2005 databases, the command line tool aspnet_regsql.exe[^] may be run with the following syntax to enable cache dependencies:
aspnet_regsql.exe -S <Server> -U <Username> -P <Password> -ed
-d <DatabaseName> -et -t <TableName>
To run the utility and authenticate with Windows credentials, use the following syntax instead:
aspnet_regsql.exe -S <Server> -E -ed -d <DatabaseName> -et -t <TableName>
An additional Web.config entry defining configuration for the dependency is also required. The following shows an example of such an entry:
<system.web>
<caching>
<sqlCacheDependency enabled="true">
<databases>
<add name="UrlMappingDep" connectionStringName="UrlMappingData"
pollTime="30000"
/>
</databases>
</sqlCacheDependency>
</caching>
</system.web>
The dependency name is referenced in the <urlMappingModule>'s dependencyName attribute, and the pollTime indicates how frequently tableName should be polled for changes (in milliseconds).
In addition to the aspnet_regsql.exe tool, databases may be programmatically prepared to support cache dependencies by using static methods of the SqlCacheDependencyAdmin[^] class found in the System.Web.Caching namespace. The TestSqlUrlMappingModule project in the article download shows an example of such code in the EnableNotifications.aspx page. This code was executed once in the sample project to enable cache dependencies in its accompanying SQL Server 2005 Express database.
If the developer prefers not to have the overhead associated with automatic polling, he or she may set useDependency="false" and explicitly refresh the cached mapping data by calling the static method UrlMappingModule.RefreshUrlMappings().
Developing a Custom Provider: IUrlMappingProvider
Developers who wish to persist mapping rules using something other than an XML file or SQL Server database, or who wish to fully control pattern-matching regular expression syntax may create a custom provider. To create a custom provider, define a class that implements the IUrlMappingProvider interface. If provider-specific configuration attributes are desired, then subclass the UrlMappingProviderConfiguration class as well.
Among the IUrlMappingProvider methods to implement are Initialize(), Dispose(), and GetUrlMappings().
Typically a provider will create an in-memory cache of mapping rules in the form of a UrlMappingItemCollection, usually in its Initialize() method. The module provides the Initialize() method with a configuration object, either UrlMappingProviderConfiguration or a subclassed object specific to the provider. With this configuration, the provider reads mapping rules from its persistence medium and creates its UrlMappingItemCollection. In the Initialize() method, the developer may cast the supplied configuration object to a custom subclass as necessary, using code like the following:
void IUrlMappingProvider.Initialize(UrlMappingProviderConfiguration config)
{
CustomUrlMappingProviderConfiguration myConfig
= (config as CustomUrlMappingProviderConfiguration);
if (myConfig == null)
throw new ProviderException(
"Invalid CustomUrlMappingProvider configuration."
);
}
Individual mapping rules are typed as UrlMappingItem objects. These expose a UrlTarget property as a Regex object and a Redirection property as a string. The provider establishes regular expressions for matching and associated redirection URLs with these properties. Should the developer wish to incorporate the same [token] syntax as supported by the built-in providers, the developer may use the utility method UrlMappingHelper.CreateTemplatedMappingItem() to create its UrlMappingItem collection.
The provider returns its cached UrlMappingItemCollection through its implementation of the GetUrlMappings() method and may release any resources it consumed in Initialize() by implementing Dispose(). For providers to support explicit refreshing of their mapping rules, developers may implement the RefreshUrlMappings() and GetLastRefreshTime() methods. The source code for the built-in providers demonstrates implementations for each of these methods.
The custom provider may be compiled into its own assembly, or it may exist as a stand-alone class file in the APP_CODE directory of a Web application project. In the latter case, the UrlMappingModule uses the BuildManager[^] class to instantiate the provider. This requires a permissions context on the server (specifically, medium level for the Demand security action). If the appropriate permission level is not available, an attempt to use BuildManager will trigger an exception. This may be avoided by compiling the provider into its own assembly and referencing that assembly in the Web application project.
Once created, the declarative configuration for a custom provider is similar to that of the built-in XML and SQL providers. Assuming the provider type is defined as MyNamespace.CustomUrlMappingProvider, with a CustomUrlMappingProviderConfiguration subclass for adding relevant configuration attributes, packaged in an assembly called MyProviderAssembly.dll, the UrlMappingModule may be configured in Web.config like the following:
<configuration>
<configSections>
<section name="urlMappingModule"
type="MyNamespace.CustomUrlMappingProviderConfiguration,
MyProviderAssembly"
/>
</configSections>
<urlMappingModule providerType="MyNamespace.CustomUrlMappingProvider,
MyProviderAssembly"
noMatchAction="..."
noMatchRedirectUrl="..."
incomingQueryStringBehavior="..."
customAttribute1="..."
customAttribute2="..."
customAttribute3="..."
...
/>
<system.web>
<httpModules>
<add name="UrlMappingModule"
type="UNLV.IAP.UrlMapping.UrlMappingModule, UrlMappingModule"
/>
</httpModules>
</system.web>
</configuration>
The article download contains the project TestUrlMappingModule, which demonstrates a custom implementation of IUrlMappingProvider in the APP_CODE directory. As there are no custom configuration options necessary for this sample implementation, the configuration object specified in Web.config is the base class UrlMappingProviderConfiguration.
Points of Interest
One difficulty that all ASP.NET 2.0 URL rewriting engines eventually face lies in the rendered <form action="..."> tag of the page. Without any adjustment, the form’s action attribute reflects the redirected URL rather than the incoming URL. Postbacks then go directly to the redirection URL, which is typically undesirable and potentially unmatchable depending on the module configuration. Even worse, the ViewState context can be corrupted.
A number of individuals have offered several creative ways to handle this problem. Some use a small piece of JavaScript code to rewrite the action attribute client-side. Some use a customized HtmlTextWriter, or custom Page subclasses to deal with the issue. There is certainly no one right answer, as each approach has its benefits and costs.
To keep the deployment of this engine as simple as possible, the UrlMappingModule addresses the form action problem by injecting a small code method in the PreRender event of affected Web forms. This injection occurs in the module's handler for the PostMapRequest event:
protected void OnPostMapRequestHandler(object sender, EventArgs e)
{
HttpApplication app = (sender as HttpApplication);
if (app != null)
{
Page page = (app.Context.Handler as Page);
if (page != null)
{
if (HttpContext.Current.Items[kCONTEXTITEMS_RAWURLKEY] != null)
page.PreRender += new EventHandler(OnPagePreRender);
}
}
}
The injected PreRender code then uses the RewritePath() method of the current HttpContext to re-establish the incoming URL prior to rendering. This allows the action attribute on the <form> tag to be rendered correctly for the incoming URL.
protected void OnPagePreRender(object sender, EventArgs e)
{
if (HttpContext.Current.Items[kCONTEXTITEMS_RAWURLKEY] != null)
{
string rawPath =
HttpContext.Current.Items[kCONTEXTITEMS_RAWURLKEY].ToString();
string qs = "";
if (rawPath.Contains("?"))
{
int index = rawPath.IndexOf("?");
qs = (_qsBehavior == IncomingQueryStringBehaviorEnum.Ignore
? ""
: qs = rawPath.Substring(index + 1)
);
rawPath = rawPath.Remove(index);
}
HttpContext.Current.RewritePath(rawPath, "", qs, false);
}
}
There is an important ramification to this adjustment: querystring variables that are included as a result of parsing a URL template for [tokens] are no longer available in the page's PreRender event. Developers should use an event earlier in the page lifecycle, such as Page.Load, to retrieve these querystring variables. The benefit to this cost is that there is no additional HtmlTextWriter, specialized Page subclass, or special JavaScript component necessary for deployment, and no need to modify individual pages.
While adjusting the <form attribute='...'> tag in some way is important to preserve proper ViewState and postback context, the form adjustment automatically made by the UrlMappingModule may be disabled if desired by including the attribute automaticallyUpdateFormAction="false" in the Web.config <urlMappingModule> configuration section. By default, automaticallyUpdateFormAction is true.
Summary
The UrlMappingModule is an HttpModule that provides a URL redirection capability to an ASP.NET 2.0 WebForms project. Mapping rules are supplied by a provider object that implements IUrlMappingProvider, of which the built-in XmlUrlMappingProvider and SqlUrlMappingProvider are examples. Inspired by the simple [token] syntax allowed for by the MVC Framework's URL mapping engine, built-in UrlMappingProviders internally convert such templates to a regular expression for matching incoming URLs. Token names and values are parsed from matched incoming URLs and appended as querystring values to the redirection URL. To re-associate a WebForm's rendered <form action="..."> tag with the incoming URL rather than the redirected one, the module injects code in the Page.PreRender event, thus avoiding the need for additional components or form-by-form coding. The module is presented in the hope that MVC-style URL redirection adds value for developers working within the 2.0 WebForms Framework.
License
This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)