VirtualUrl.NET Documentation

Table of Contents

• Adding VirtualUrl.NET in your Web Application
• Removing VirtualUrl.NET for a Virtual Web Application
• Configuration File
• Managing Redirection Rules
  • Static Rules
  • Dynamic Rules
  • Response Filters
  • Querystring Parameter Lookup
• Advanced Settings
• Enabling Extension-less pages
• .NET v2.0 Common Issues
• Related Links

Adding VirtualUrl.NET in your Web Application

VirtualUrl.NET is a HTTP Module native from Microsoft .NET technology. Like every .NET HTTP Module, to add it to your web application, simply copy the assembly Visionalyse.Web.VirtualUrl.dll to your /bin directory and insert the following code in the <httpModules> section of your Web.config:

<add type="Visionalyse.Web.VirtualUrl.Engine, Visionalyse.Web.VirtualUrl" name="VirtualUrl.NET" />

For example:

 1 <?xml version="1.0" encoding="utf-8"?>
 2 <configuration>
 3   <system.web> 
 4   
 5     <httpModules>
 6       <add type="Visionalyse.Web.VirtualUrl.Engine, Visionalyse.Web.VirtualUrl" name="VirtualUrl.NET"/>
 7     </httpModules> 
 8     
 9   </system.web> 
10 </configuration>

Removing VirtualUrl.NET on a child Web Application

By design, when you add a .NET HTTP module in your web application, the web applications located below this application receive the same HTTP Module configuration. If you want to use VirtualUrl.NET for a web application and do not want child web applications to use the URL rewriting process, you can remove it by adding the following code in the Web.config of child application:

 1 <?xml version="1.0" encoding="utf-8"?>
 2 <configuration>
 3   <system.web> 
 4   
 5     <httpModules>
 6       <remove name="VirtualUrl.NET"/>
 7     </httpModules> 
 8     
 9   </system.web> 
10 </configuration>

Notes:

• The value of the attribute "name" must match the value of the HTTP module attribute "name" of your parent web application.
• For cases where VirtualUrl.NET is not registered in the GAC, the assembly .dll file must be copied in the child web application or the.NET framework will throw a "Assembly Not Found" exception.

Configuration File

1 <?xml version="1.0" encoding="utf-8"?>
2 <configuration>
3   <appSettings> 
4   
5     <add key="Visionalyse.Web.VirtualUrl.ConfigurationFilePath" value="{Enter Virtual Path Location of File}"/>
6 
7   </appSettings>
8 </configuration>

Structure of configuration file

 1 <?xml version="1.0" encoding="utf-8" ?> 
 2 <sitemap>
 3 
 4 <website>
 5 
 6     <!-- static redirection rules -->
 7     <page title="" urlmask="" url="" mask="" enable="" /> 
 8 
 9 </website>
10 
11 <extension>
12 
13     <!-- dynamic redirection rules -->
14     <case match="" url="" mask="" enable="" >
15 
16       <!-- response filters for version 2.0 and above -->
17       <responseFilter match="" url="" >
18 
19         <parameter name="" lookupSource="" />
20 
21       </responseFilter>
22 
23     </case>
24 
25 </extension>
26 
27 <!-- for version 1.1.6 and above -->
28 <settings>   
29   
30     <redirection permanent="" />
31 
32     <!-- response filter settings for version 2.0 and above -->
33     <responseFilters mode="" encodeEmailAddress="" >
34         <add tag="" attribute="" />
35     </responseFilters>
36 
37 </settings>

Managing Redirection Rules

To allow VirtualUrl.NET to rewrite the requested URL, you must first create some rules.
There are two types of rules which are called Static and Dynamic.

Static Rules

The Static Rules are plain redirection cases which are matched against the exact URL. They can be used in cases when the actual URL does not vary by querystring parameters or when you wish to use the sitemap.config to draw your website's sitemap. (see example 5: Storing Static Rules Hierarchically)

Static rules must placed inside <website> element of the configuration file and can be nested, one inside an other.

<page title="" urlmask="" url="" mask="" enable="" />

Dynamic Rules

The Dynamic Rules allow you to create redirection by matching an URL against a regular expression pattern. This is useful when you have a data-driven ASP.NET website and use a single page to display content based on querystring parameters. Instead of entering a rule for each case, by simply using regular expressions you can create a dynamic rule. (see example 2: Multiple querystring parameters replacement)

Dynamic Rules must be placed inside <extension> element of the configuration file.

<case match="" url="" mask="" enable="" />

Response Filters

Response filters have been introduced in version 2.0 of VirtualUrl.NET - Upgrade Now

The response filters allow you to modify the URLs of the page output in the run-time. This feature is suitable for existing .NET websites to simply recreate the hyperlinks by only touching the sitemap.config.
Before the HTTP response data is sent to the client, the links on the page matching the regular expression pattern (attribute match) are replaced with new links (attribute url). (see example 7: Using Response Filters)

For best performance, we recommend to replace your links in design-time and avoid using the response filters.

Response Filters must be placed inside each <case> element of the configuration file.

<responseFilter match="" url="" />

Querystring Parameter Lookup

With the new response filter functionality, the querystring parameters can also be replaced in run-time. For instance, this allows you to replace a querystring parameter containing a number with a friendly name page without a querystring. (see Example 8: Working with Querystring parameter Lookup)

Parameters must be placed inside respective <responseFilter> element of the configuration file.

<parameter name="" lookupSource="" />

Example of Lookup Source File containing a single parameter

1 <?xml version="1.0" encoding="utf-8" ?>
2 <lookupSource>
3     <parameter name="id">
4         <set key="1" value="nuts" />
5         <set key="2" value="oranges" />
6     </parameter>
7 </lookupSource>

Example of Lookup Source File containing multiple parameters

 1 <?xml version="1.0" encoding="utf-8" ?>
 2 <lookupSource>
 3     <parameter name="id">
 4         <set key="1" value="nuts" />
 5         <set key="2" value="oranges" />
 6     </parameter>
 7     <parameter name="cat">
 8         <set key="1" value="cereales" />
 9         <set key="2" value="vegetables" />
10         <set key="3" value="fruits" />
11     </parameter>
12 </lookupSource>

Advanced Settings

This section has been introduced in version 1.1.6. The settings allow to control the behaviour of VirtualURL.NET such as redirection status codes and response filters (for version 2.0 and above).

<redirection permanent="" />

<responseFilters mode="" encodeEmailAddress="" >
    <add tag="" attribute="" />
</responseFilters>

Enabling Extension-less pages

If you want to use VirtualUrl.NET without specifying the extension of your new virtual URLs, you can do so by adding a new application mapping to your website IIS settings.

This solution works only if your website is using ASP.NET server pages and not mixing with other dynamic server pages such as ASP and PHP.

Instructions for Windows XP and 2000 operating systems

1. Open IIS and right-click on the website and select 'properties'.

2. Click the 'Configuration' button under Application Settings section

3. Click the 'Add' button to create a new application mapping

4. Set the executable textbox to aspnet_isapi.dll file location.
    i.e. C:\WINDOWS\Microsoft.NET\Framework\v1.1.4322\aspnet_isapi.dll

5. Set the extension textbox to .* to map extension-less URLs and custom extensions to the ASP.NET ISAPI Process.

6. Make sure the checkbox 'Check that file exists' is not checked.

7. Press 'OK' to confirm and close all the windows.

Notes

By configuring IIS to enable extension-less URLs, your default page will not been picked up automatically. To resolve this issue, add a dynamic rule in your configuration file at the very last position as follow:

 1 <?xml version="1.0" encoding="utf-8" ?> 
 2 <sitemap>
 3 <extension>
 4 
 5     <!-- add your rules here -->
 6     
 7     <!-- rule for default page (change default.aspx to your default page) -->
 8     <case match="~/?$" url="~/default.aspx" />
 9   
10 </extension>
11 </sitemap>

.NET v2.0 Common Issues

To avoid getting the error "Cannot use a leading .. to exit above the top directory" when the page is rendered, users must have the forms cookieless property in their web.config set to UseCookies. By default this property is set to UseDeviceProfile and for browsers with no cookie support, the above error message can be thrown depending on a specific directory level between the virtual URL and the real URL.

Example of web.config settings

 1 <?xml version="1.0" encoding="utf-8" ?>
 2 <configuration>
 3 <system.web>
 4 
 5   <authentication>
 6     <forms cookieless="UseCookies" />
 7   </authentication>
 8 
 9 </system.web>
10 </configuration>

For more information about the forms Cookieless property, please visit this link http://msdn2.microsoft.com/library/1d3t3c61(en-US,VS.80).aspx

Alternatively, the error "Cannot use a leading .. to exit above the top directory" can be generated by other web controls such as SiteMapPath and hyperlink that resolve file paths.

We recommend to use absolute paths in your URLs, this will fix such problems.

Related Links

• Guide to Regular Expressions
• HTTP Modules in ASP.NET
• HTTP/1.1 Status Codes