Setting up the Web.Config File
The configuration section for the ASP.NET ULR Rewriter must be declared in the Web.Config file as follows:
<configuration>
<configSections>
<sectionGroup name="system.web.extensions" type="System.Web.Configuration.SystemWebExtensionsSectionGroup, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35">
<sectionGroup name="scripting" type="System.Web.Configuration.ScriptingSectionGroup, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35">
<section name="scriptResourceHandler" type="System.Web.Configuration.ScriptingScriptResourceHandlerSection, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" requirePermission="false" allowDefinition="MachineToApplication"/>
<sectionGroup name="webServices" type="System.Web.Configuration.ScriptingWebServicesSectionGroup, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35">
<section name="jsonSerialization" type="System.Web.Configuration.ScriptingJsonSerializationSection, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" requirePermission="false" allowDefinition="Everywhere"/>
<section name="profileService" type="System.Web.Configuration.ScriptingProfileServiceSection, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" requirePermission="false" allowDefinition="MachineToApplication"/>
<section name="authenticationService" type="System.Web.Configuration.ScriptingAuthenticationServiceSection, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" requirePermission="false" allowDefinition="MachineToApplication"/>
<section name="roleService" type="System.Web.Configuration.ScriptingRoleServiceSection, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" requirePermission="false" allowDefinition="MachineToApplication"/>
</sectionGroup>
</sectionGroup>
</sectionGroup>
<section name="DaisleyHarrison.UrlRewriter" type="DaisleyHarrison.UrlRewriter.UrlRewriterSection, DaisleyHarrison.UrlRewriter, Version=1.1.0.0, Culture=neutral, PublicKeyToken=86842b37db0c0375" requirePermission="false"/>
</configSections>
...
</configuration>
(Updated for version 1.1.0.0 Beta)
Referencing the HttpModule in the Web.Config file
The HttpModule that does the actual URL rewriting must be referenced in two place in the Web.Config file as follows:
(Note that the UrlRewriterModule should be the
first HttpModule in each section).
<configuration>
<configSections>
...
</configSections>
<system.web>
...
<httpModules>
<add name="UrlRewriterModule" type="DaisleyHarrison.UrlRewriter.UrlRewriterModule, DaisleyHarrison.UrlRewriter, Version=1.1.0.0, Culture=neutral, PublicKeyToken=86842b37db0c0375"/>
<add name="ScriptModule" type="System.Web.Handlers.ScriptModule, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
</httpModules>
</system.web>
...
</configuration>
In the
modules section below also note the setting of the
runAllManagedModulesForAllRequests attribute to
true
<configuration>
<configSections>
...
</configSections>
<system.web>
...
</system.web>
...
<system.webServer>
...
<validation validateIntegratedModeConfiguration="false"/>
<modules runAllManagedModulesForAllRequests="true">
<add name="UrlRewriterModule" type="DaisleyHarrison.UrlRewriter.UrlRewriterModule, DaisleyHarrison.UrlRewriter, Version=1.1.0.0, Culture=neutral, PublicKeyToken=86842b37db0c0375"/>
<remove name="ScriptModule"/>
<add name="ScriptModule" preCondition="managedHandler" type="System.Web.Handlers.ScriptModule, System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
</modules>
...
</system.webServer>
...
</configuration>
(Updated for version 1.1.0.0 Beta)
Defining Rules in the Web.Config File
Rules for the URL Rewriter are defined in the
DaisleyHarrison.UrlRewriter section of the configuration file. This section defines a configuration collection of rules.
- A rule is added to the collection using the tag:
<addRule Name="rule-name" .../> - A rule is removed from the collection using the tag:
<removeRule Name="rule-name"/> - All rules are removed from the collection using the tag:
<clearRules/>
Note that the rules collection can be inherited by the setting of rules in any parent application web.config files. This is similar to the way the
appSettings section is inherited.
Example
<configuration>
<configSections>
...
</configSections>
<appSettings/>
<connectionStrings/>
<system.web>
...
</system.web>
<system.codedom>
...
</system.codedom>
<system.webServer>
...
</system.webServer>
<DaisleyHarrison.UrlRewriter ApplicationRelative="True">
<rules>
<clearRules/>
<addRule Name="rule1" Pattern="(.*?)\.xxx(.*)" Replace="$1.aspx$2" Disposition="Rewrite"/>
<addRule Name="rule2" Pattern="(.*?)\.axd(.*)" Disposition="Accept"/>
<addRule Name="rule3" Pattern="/(?'category'.+?)/(?'action'.+?)/.+\.aspx" When="Match" PassNamedGroups="true" Disposition="Continue"/>
<addRule Name="rule4" Pattern="(.*)" When="Match,PhysicalFile" Disposition="Accept"/>
<addRule Name="rule5" Pattern="(.*)" When="Match" Replace="HandlerTest.ashx" Rebase="False" PathInfo="$1"/>
</rules>
</DaisleyHarrison.UrlRewriter>
...
</configuration>
Debugging URL Rewriter Rules
The URL Rewriter had a fairly complete set of trace messages that can be used to help debug a new rule set.
To turn trace messages on, set the
TraceLevel attribute of the DaisleyHarrison.URLRewriter section to either
Info or
Verbose (see the
TraceLevel attribute section below).
Remember that URL processing is cached for each unique URL, so only the first time the rewriter sees a unique URL will it be processed. It is sometimes useful to turn caching off the during debugging of new rules. Turn processing caching off by setting the
Cache attribute of the DaisleyHarrison.URLRewriter section
false (see the
Cache attribute section below). Just remember to re-enable caching before going live.
To see the trace messages in IIS you will need to turn tracing on. Refer to the
ASP.NET Tracing Overview article on MSDN for more information on tracing in IIS.
For example:
<configuration>
<configSections>
...
</configSections>
...
<system.web>
...
<trace enabled="true" requestLimit="40" localOnly="true" pageOutput="true"/>
...
</system.web>
...
<DaisleyHarrison.UrlRewriter TraceLevel="Info" Cache="false">
<rules>
your rules here
</rules>
</DaisleyHarrison.UrlRewriter>
</configuration>
Enabling trace as in the above example will show all trace messages at the bottom of each page.
Note: It is a good idea to set the
localOnly trace attribute to
true, so only browsers running from the local server will see trace messages.
If you are debugging from a remote machine and the site has public access, like when you are using an ISP that offers limited access to the server, it is best to set the
pageOutput attribute to
false and use the Trace Viewer page to view the trace results for a particular URL.
The Trace Viewer page is available by navigating to trace.axd on the root directory of your application.
For example, if the URL for your application is http://localhost/MyApplication, navigate to http://localhost/MyApplication/trace.axd to view the trace information for that application.
Select the
View Details link for the request that you want to investigate.
For more information on using the Trace Viewer please see the
How to: View ASP.NET Trace Information with the Trace Viewer article on MSDN.
DaisleyHarrison.UrlRewriter Section Attributes
The DaisleyHarrison.UrlRewriter section tag defines a number of optional attributes that can be used to control the global functions of the URL Rewriter. These attributes and their functionality are documented below.
ApplicationRelative Attribute
The ApplicationRelative attribute determine if URLs will be processes as absolute or relative to the application path.
<DaisleyHarrison.UrlRewriter ApplicationRelative="{ true | false }" ...>
When the
ApplicationRelativeattribute is set to
true, the URL is first stripped of the application path and turned into a relative URL before rules are applied. After rule processing, the application path is applied to the resulting URL before the URL is passed on to the server for processing. Setting the
ApplicationRelative attribute to
true allows rules to be defined that are independent of the application path.
When the
ApplicationRelativeattribute is set to
false, all URLs are processed as absolute URL (this is how they arrive at the server). Rules must be defined that take into account the application path.
The default is:
ApplicationRelative="false"Cache Attribute
The Cache attribute turns the URL processing cache on or off.
<DaisleyHarrison.UrlRewriter Cache="{ true | false }" ...>
When the
Cacheattribute is set to
true, the result of processing each unique URL against the rules is cached. The next time the URL is presented to the server, the cached result will be used.
When the
Cacheattribute is set to
false, rule processing is not cached. Each time a URL is presented to the server it will be reprocessed.
The default is:
Cache="true"
Note: Setting some of the rule attributes may disable caching. Please refer to rule attributes below for more information.
Engine Attribute
The engine attribute allow the URL rewriter engine to be turned off or on.
<DaisleyHarrison.UrlRewriter Engine="{ on | off }" ...>
When the
Engineattribute is set to
on, the engine is turned on and all URLs will be processed.
When the
Engineattribute is set to
off, turned off and URL are not processed by the engine.
The default is:
Engine="on"
DefaultDisposition Attribute
The DefaultDisposition attribute specifies how URL that do not match any rewriter rules will be handled.
<DaisleyHarrison.UrlRewriter DefaultDisposition="{ Accept | NotFound }" ...>
When the
DefaultDispositionattribute is set to
Accept, URLs that do not match any rules will be "accepted" and passed on to the server for processing "as is".
When the
DefaultDispositionattribute is set to
NotFound, URLs that do not match any rules will be rejected with an HTTP 404 Not Found error.
The default is:
DefaultDisposition="Accept"TraceLevel Attribute
The TraceLevel attribute specifies the level of trace messages that the URL rewriter will generate. Changing the trace level to Info or Verbose is particularly useful for debugging a new set of processing rules.
<DaisleyHarrison.UrlRewriter TraceLevel="{ Off | Error | Warning | Info | Verbose }" ...>
When the
TraceLevelattribute is set to
Off, no trace messages will be generated by the rewriter engine.
When the
TraceLevelattribute is set to
Error, only error messages will be generated to the IIS trace context.
When the
TraceLevelattribute is set to
Warning, error and warning messages will be generated to the IIS trace context.
When the
TraceLevelattribute is set to
Info, error, warning, and information messages will be generated to the IIS trace context.
When the
TraceLevelattribute is set to
Verbose, all rewriter trace messages will be generated to the IIS trace context.
The default is:
TraceLevel="Error"Note: To see trace messages generated by the URL rewriter engine you will need to configure your .NET application with the trace tag (see the
Debugging URL Writer Rules seciton above).
Rule Attributes
The URL rewriter engine rule are defined in the
DaisleyHarrison.URLRewriterDaisleyHarrison.URLRewriter section of the web.config file.
Rules are added to the section using the
<addRule Name="rule-name" rule-attributes.../> tag.
Rule attributes are defined in the following sections:
Host Attribute
The
Host attribute, if specified requires that the request contains a matching host header for the rule to apply.
The
Host attribute defines a
.NET regular expression which used to match the host header of a request.
<addRule Host=" regular-expression " ...>
Where
regular-expression is any valid
.NET regular expression.
This is an optional attribute. If not specified the rule will match any host header.
(Updated for version 1.1.0.0 Beta)
Name Attribute
The name attribute is a required attribute that gives a unique name to each rule.
<addRule Name=" rule-name " ...>
Where
rule-name is any unique name for a rule.
There is no default for this attribute. This is a required attribute.
Note: All rules are named so they can be removed in a nested application using the
<removeRule Name="rule-name"/> tag.
Verb Attribute
The Verb attribute defines which HTTP verbs a rule will be applied to. If no verbs are specified the rule will apply to all HTTP verbs.
<addRule Verb=" http-verb-list " ...>
Where
http-verb-list is comma delimited list of HTTP verbs.
This is an optional attribute. If not specified the rule will be applied to all HTTP verbs.
Pattern Attribute
The Pattern attribute defines a
.NET regular expression which used to match a URL. The Pattern attribute is used in conjunction with the When attribute to determine which rules will be applied to a URL.
<addRule Pattern=" regular-expression " ...>
Where
regular-expression is any valid
.NET regular expression.
This is an optional attribute. The default setting is
Pattern=".*", which matches any URL.
(Updated for version 1.1.0.0 Beta)
When Attribute
The When attribute defines what test will be used to determine if a rule will be applied to a particular URL.
<addRule When=" conditions " ...>
Where
conditions a comma delimited list of conditions, all of which must evaluate to true, for the rule to apply the HTTP request.
The default value is
When="
Match" (i.e. If the When attribute is not specified the URL must match the Pattern for the rule to apply).
The following sections define the valid when conditions that can be used:
Match condition
The
Match condition means that the
regular expression specified in the
Pattern attribute must match the URL in order for the rule to be applied.
Note if the When attribute is not specified this is the default condition.
NoMatch condition
The
NoMatch condition means that the
regular expression specified in the
Pattern attribute must
NOT match the URL in order for the rule to be applied.
PhysicalFile condition
The
PhysicalFile condition means that the URL must resolve to a physical file on the server in order for the rule to be applied.
NonPysicalFile condition
The
PhysicalFile condition means that the URL must
NOT resolve to a physical file on the server in order for the rule to be applied.
Local condition
The
Local condition means that the HTTP request must originate from the local machine in order for the rule to be applied.
NOTE: Using this condition will disable the caching of rule processing for this and all rules following the rule in which this condition is specified.
NonLocal condition
The
NonLocal condition means that the HTTP request must
NOT originate from the local machine in order for the rule to be applied. i.e. A normal remote HTTP request to the server.
NOTE: Using this condition will disable the caching of rule processing for this and all rules following the rule in which this condition is specified.
Secure condition
The
Secure condition means that the HTTP request must be secure (Using the https:// URI scheme) in order for the rule to be applied.
NOTE: Using this condition will disable the caching of rule processing for this and all rules following the rule in which this condition is specified.
NonSecure condition
The
NonSecure condition means that the HTTP request must be a non-secure (Using the http:// URI scheme) in order for the rule to be applied. i.e. The usually non-secure URL used by client browsers.
NOTE: Using this condition will disable the caching of rule processing for this and all rules following the rule in which this condition is specified.
Authenticated condition
The
Authenticated condition means that the HTTP request must be from an authenticated user in order for the rule to be applied.
NOTE: Using this condition will disable the caching of rule processing for this and all rules following the rule in which this condition is specified.
NonAuthenticated condition
The
NonAuthenticated condition means that the HTTP request must be from an anonymous user in order for the rule to be applied.
NOTE: Using this condition will disable the caching of rule processing for this and all rules following the rule in which this condition is specified.
Replace Attribute
The Replace attribute defines a
.NET regular expression which used to rewrite a URL.
<addRule Replace=" regular-expression " ...>
Where
regular-expression is any valid
.NET regular expression replace expression.
This is an optional attribute. If not specified the rule will not change the URL.
Note: If the attribute When="NoMatch" then only the tagged expression zero "
$0" is available for use in the replace expression.
If the attribute When="Match" (The default value), then any tagged expression is available for use in the replace expression.
Disposition Attribute
The
Disposition attribute defines a what action will be taken when a rule applies to the HTTP request.
<addRule Disposition=" action " ...>
Where
action is any valid rule disposition.
This is an optional attribute. The default disposition action is
Rewrite.
Please refer to the sections below for a description of all rule disposition actions.
Rewrite action
The
Rewrite action means that any HTTP requests that match this rule will be rewritten using the expressions in Replace and PathInfo attributes. No more rules will be processed.
This is the default disposition used when the
Disposition attribute is not specified.
Continue action
The
Continue action means that any HTTP requests that match this rule be modified by the rule and the rule processing will continue with the next rule in order.
Accept action
The
Accept action means that any HTTP requests that match this rule accepted "as it" and passed to the server for processing. No more rules will be processed.
Redirect action
The
Redirect action means that any HTTP requests that match this rule will be redirected, by returned an HTTP redirect response to the client browser. No more rules will be processed.
NotFound action
The
NotFound action means that any HTTP requests that match this rule will be rejected with an HTTP 404 Not Found error. No more rules will be processed.
Execute action
The
Execute action means that replaced URL will be executed on the server via the
Server.Execute method. No more rules will be processed.
PathInfo Attribute
The
PathInfo attribute defines a
.NET regular expression which used to rewrite the pathinfo portion of the URL.
<addRule PathInfo=" regular-expression " ...>
Where
regular-expression is any valid
.NET regular expression replace expression.
This is an optional attribute. If not specified the pathinfo portion of the rewritten URL will be blank.
Note: If the attribute When="NoMatch" then only the tagged expression zero "
$0" is available for use in the replace expression.
If the attribute When="Match" (The default value), then any tagged expression is available for use in the replace expression.
PassNamedGroups Attribute
The
PassNamedGroups attribute indicates that, when set to
true, all named groups in the Pattern attribute will be passed to the rewritten HTTP Request as name=value pairs in the query string.
<addRule PassNamedGroups="{ true | false }" ...>
When
PassNamedGroups="
true" all named groups in the Pattern attribute will be passed to the rewritten HTTP Request as name=value pairs in the query string.
This is an optional attribute. The default value is
false.
Note: Named groups are only available if the attribute When="Match" (The default value).
Rebase Attribute
The
Rebase attribute indicates that, when set to
true, the rewritten URL will be the new base URL for the HTTP Request (The client browser will see the new rewritten URL).
<addRule Rebase="{ true | false }" ...>
When
Rebase="
true" the rewritten URL will be the new base URL for the HTTP Request (The client browser will see the new rewritten URL).
When
Rebase="
false" the rewritten URL will be the be processed internally by the server and the client browser will only see the original URL.
This is an optional attribute. The default value is
false.