iFinity Friendly Url Provider Module Install Instructions

How to install the iFinity DNN Friendly Url Provider

This version is for DotNetNuke Installations of 4.6 and higher, including DNN 5.0 and higheer. Do NOT install this version on earlier version than 4.6 - it is only compatible with 4.6+ versions.

Another, older, version is available for version 4.0 through 4.5 - however, active support for the 4.5 version has been stopped.

Note : DNN 5.0 requires a minimum version of 5.0.0 of the Friendly Url Provider.

Step by Step Instructions

Step 1: Download the code from the Codeplex Friendly Url Provider page.
Step 2: Copy the iFinity.FriendlyUrlProvider.dll in to the /bin directory.
Step 3: Backup your existing web.config
Step 4: Replace this entry in the <httpModules> section:
<add name="UrlRewrite" type="DotNetNuke.HttpModules.UrlRewriteModule, DotNetNuke.HttpModules.UrlRewrite"/>
with this entry:
<add name="UrlRewrite" type="iFinity.DNN.Modules.FriendlyUrl.UrlRewriteModule, iFinity.FriendlyUrlProvider"/>

and this one in the <modules> section:
<add name="UrlRewrite" type="DotNetNuke.HttpModules.UrlRewriteModule, DotNetNuke.HttpModules.UrlRewrite" preCondition="managedHandler"/>
with this entry:
<add name="UrlRewrite" type="iFinity.DNN.Modules.FriendlyUrl.UrlRewriteModule, iFinity.FriendlyUrlProvider" preCondition="managedHandler"/>

Step 5:   Add this entry to the  existing "friendlyUrl" provider section:
<add name="iFinity.FriendlyUrl" type="iFinity.DNN.Modules.FriendlyUrl.DNNFriendlyUrlProvider, iFinity.FriendlyUrlProvider" includePageName="true" regexMatch="^\+a-zA-Z0-9 _-" urlFormat="HumanFriendly" redirectUnfriendly="true" doNotRedirect="SearchResults;" checkForDupUrls="true" forceLowerCase="false" redirectWrongCase="false" replaceSpaceWith="_" logCacheMessages="false"/>

Url Configuration Options

The above set of options will change an 'old' DNN friendly Url like this:
to this:

This set of options is a good starting point for most websites.

Step 6: Change the entry for <friendlyUrl defaultProvider="DNNFriendlyUrl"> to <friendlyUrl defaultProvider="iFinity.FriendlyUrl">

Step 7: Try it out! Note that you may have to restart your application to get the Friendly Url provider working properly.  Also note you must have your 'Friendly Urls' option in the Host Settings page switched On.

Changing Options to use Different Features

The FriendlyUrlProvider is packed with features to tune the way your website works. This is useful to tailor the Url behaviour to particular modules or requirements with your website. You do not need to change anything if your website is working OK, but if you'd like to tweak it, try any of the following changes. Either modify the existing attribute in the 'FriendlyUrl' config entry, or add the attribute in.

Complete list of web.config options
  • urlFormat (HumanFriendly,omitted) - ''humanFriendly'' when using Url values without the standard tabid/nn path. If omitted, will use standard DNN-style friendly Urls
  • doNotRewritePage - regex string for excluding incoming requests. If the incoming request matches the regex, no rewriting will be attempted. This is used to handle exceptions, such as direct calls to pages/controls in the DesktopModules path.
  • checkForDupURls (true/false) - true means an exception will be logged if duplicate urls are found while building the tab dictionary. Duplicate url''s are urls where the combination of portalAlias/tabpath from two different portals match. Preference is always given to the ''first'' portal / tab path combo, so the second and suqsequent combos will never resolve properly. redirectUnfriendly (true/false) - whether to issue 301 redirect status codes if an incoming url does not match the friendly url for that page. Also redirects requests to the site root (mydomain.com/) to the home page of the site (mydomain.com/home.aspx - assuming 'home.aspx' is the home page name)
  • doNotRedirect - semicolon delimited list of tab paths where a 301 redirect should never be issued. Use when a particular page should use ?key=val type parameters, or unwanted results are occuring. This is only used when redirectUnfriendly = true doNotRedirectRegex - a regex expression which, when evaluated against the incoming url, will not redirect if the result is a match. In the example, the /logoff.aspx page will never 301 redirect. This is only used when redirectUnfriendly = true
  • pageExtensionUsage (never, pageonly or always) - three options on whether to use page extensions (ie .aspx) for the pages.
    • never = don''t use page extensions
    • pageonly = only use page extensions when the page path does not include parameter key/value pairs (ie mysite/mypage.aspx but not mysite/mypage/mykey/myvalue),
    • always = .aspx is appended to all urls.
Default : alwaysUse. If using pageonly or never, the iis setup must have wildcard mapping to the aspnet_isapi.dll
  • ignoreFileTypeRegex (Regex string) - when mapping wildcard requests to aspnet_isapi.dll, the asp.net url rewriting function will be called for all types of iis resources on the page. This means unnecessary file handling for jpeg, gif, css,axd and other file types. By entering a regex string, any match found will bypass the url rewriting code and be passed back to iis.
  • pageExtension - allows the use of a page extension other than .aspx if required. (ie .page, .content - whatever)
  • forceLowerCase (true, false or omitted) - if set to true, all generated Url's will be set to lower case.
  • redirectWrongCase (true, false or omitted) - if set to true, all requests sent to the page with the incorrect case will be 301 redirected to the correct case of the Url.
  • replaceSpaceWith (any valid character, omitted) - if a valid character is supplied, any spaces in the page name will be replaced with this character for generated Urls.   If omitted, the standard DNN behaviour (spaces removed from page name) is used.  When 'replaceSpaceWith' is used, any requests for the non-spaces version of that request (ie for mypage instead of my_page) will be 301 redirected, unless there is another page called the same name (ie a valid mypage exists as well as my page)
  • useBaseFriendlyUrls (list of ; delimited tab paths, with a single / for separating path levels) - if a page path is included in this list, it will not have a 'humanFriendly' url generated for it.  This list is an exclusion list, and any page that is listed will have the 'standard' DNN friendly Url generated.  This option is normally used when a particular module on a page uses proprietary query string handling, and is inoperable against the Friendly Url Provider.  You can exclude this page and maintain standard operations, while using human friendly Urls for the rest of the site. Note: to get the page paths, look at the dnn_Tabs.TabPath table.
  • triggerDictionaryRebuildRegex(Regex String) - when supplied, any Rewritten Url that matches this regex will result in the Page index for the DNN installation being rebuilt. The Page index is cached between requests for performance, but any new page or page change that is performed on the site will need the page index to be rebuilt. It is not required for most installations, and if a new value is added, it should also include the following regex (for page add/edit, portal add/edit) - the recommended value is triggerDictionaryRebuildRegex="&amp;ctl=tab|/ctl/tab|/Admin/Tabs/"
  • allowDebugCode (true, false, or omitted) - allows debug response headers to be output when a request param or query string param of _fpdebug=true is added to the request.  This is used for debugging in html trace programs like Microsoft Fiddler.
  • redirectDefaultPath (true, false or omitted) - redirects the /default.aspx url to the site root.  Can only be used when running with no page extensions, otherwise puts the site root requests into a terminal loop due to IIS.
  • forwardExternalUrls (Redirect301, Redirect302, NoRedirect) - each value determins what to do when a page is requested in a url, and that page has an external Url specified.  The redirect values forward the visitor to the external page.
  • deletedTabHandling  (301RedirectToHome, Output404) - specifies what to do when a page which is deleted (but not removed from the recycle bin) is requested.
  • rebaseClientPath (true, false, omitted (true)) - the value passed to the context.Rewrite(url, rebaseClientPath) call that the underlying asp.net rewriting uses.usePortalAlias="0,www.domain.com;1,www.anothername.com"  - a delimited list of portalid/ portal alias pairs.  This list specifies which of the portal aliases a particular portal shoudl use.  Any request to an alias for that portal which isn't the specified one will result in a 301 redirect to the specified alias.  Use to push non-www to www requests, and to migrate domain names for sites.
  • sslClientRedirect (true, false, omitted (true)) - if true, uses a javascript redirect to send a visitor to the http version of a https request, if the site settings say to do so.  If false, uses a server-based 301 redirect.  Use true to avoid a browser warning.
  • cachePersistRestart (true, false) - if true, the page index cache will be preserved throughout an app restart.  If false, it will be rebuilt on app restart.
  • logCacheMessages (true, false, omitted (true)) - if true, a message will be inserted into the site log every time the page index is rebuilt.  Recommended to use 'false' unless debugging.cacheTime="1000" - any positive integer, specifying the number of minutes the page index is requested to be cached for.  Note that if the web server has insufficient resources to maintain this cache, the page index will be flushed earlier.
  • doNotRedirectSecureRegex - regex match pattern.  When a match is found, the standard SSL redirect code will be ignored, and the request will be completed on the http:// scheme.  This is often used for allowing search engines to index a page without having the page forward to https://.
  • useSiteUrlsRegex - regex match pattern.  When a match is found with the requested Url, it uses the rules in the siteurls.config file directly, instead of trying to find a matching DNN page

Troubleshooting Problems

The most useful tool you can use for determining errors is Microsoft Fiddler. This is a free Http traffic monitoring tool, and will show all the web traffic going from your computer. You can download it at www.fiddlertool.com

Install your Fiddler tool and work out how to monitor traffic from your browser to your website. Fiddler generally only works with IE, and it won't work if you try and request http://localhost requests. Instead, set up your website at http://machinename where machinename is the name of your web server / development PC. Note that you need to enter the machinename/websitename into the portal alias tables in your DNN install.

With Fiddler you can detect 404,500,301 and 302 status return codes for different requests. You do this by switching the tracing on (F12) and then requesting the page/site with a problem. You will be able to see the results in fiddler, and by dragging/dropping the request with the error on to the 'Request' tab, you can re-submit that request without having to reload your entire web page.

Once you have worked out how to trace requests and responses, you can add this value to the end of a request : ?fpdebug=true OR you can add a Http request parameter of fpdebug:true. If you do this (and provided the 'allowDebug' setting is omitted or false) you will get a set of debug information in the response headers. You can see the response headers by clicking in Fiddler on the 'Inspectors' tab, then on the 'Headers' tab in the lower right 'Response Headers' section.

Here's an example of a debug response header:
X-FriendlyUrlProvider-Debug: http://computername/dnn500/newpage.aspx, http://computername/dnn500/New_Page.aspx, Default.aspx?TabId=79, Redirect301,

This string shows a number of comma-delimited elements.
Here's what they mean, in order:
  • X-FriendlyUrlProvider-Debug : response header name
  • http://computername/dnn500/newpage.aspx : originally requested Url
  • http://computername/dnn500/New_Page.aspx : redirect destination, if supplied (will be blank if the request didn't result in a redirect)
  • Default.aspx?Tabid=79 : rewrite path.  This is what the Url is rewritten to, so that the rest of the DNN framework see this as the Url and can request querystring parameters.
  • Redirect301 : resulting action.  This is an internal action value which the system uses to determine the logic path of the request.  Other values are 'Continue' (means request handled ok, and should continue); Redirect302 : do a 302 redirect to the redirect path; Output404 : the request did not match a physical file on the server, and didn't match an expected DNN tab name, so output a 404 error.
  • : the current version of the Friendy Url Provider that handled the request

If you cannot figure out the problem, go onto the Friendly Url Provider support forum at http://www.ifinity.com.au/Products/Support_Forums, or log the issue here in the Codeplex discussion.

You'll get the problem solved much quicker if you can supply the fiddler trace or status of a particular request. Also useful is any events from the DNN Event log, and the copy of your iFinity.FriendlyUrl provider web.config entry. 
In the response headers, if there is a redirect, you'll also see a value like this:
X-Redirect-Reason: Spaces Replaced Requested
The X-Redirect-Reason header shows the reason a redirect was done. This may provide further insight into why a redirect occured.

Last edited Apr 25, 2012 at 7:38 AM by brucerchapman, version 3


No comments yet.