One of the key features of the Url Master module was the ability to extend it for your own custom purposes – whether that was to create a friendly URL scheme for a specific module, or to complete a task of a specific set of redirects. When DNN 7.1 initially shipped, the Advanced URLs were born, and with it came an adaptation of the old Url Master custom URL provider functionality. These were now called ‘Extension URL Providers’. The idea is exactly the same – provide an extension point to the DNN Platform where a developer would like to take control over the entire URL for their purposes. The implementation is largely the same but differs in a few small places.
Because of this difference, some people who built custom URL providers for their Url Master install need to have the equivalent provider created for the built-in DNN functionality – indeed, this is a impediment if you want to switch from Url Master to DNN Advanced URLs but you rely on a Custom URL Provider for this purpose. I encourage everyone to do this – there are a lot of benefits in moving from Url Master to using Advanced URLs.
This blog post gives a top-level run down on how to convert a Url Master – spec custom URL provider to a DNN Extension URL Provider – without introducing any bugs or having to rewrite it.
Converting the Code
The first thing I recommend is to copy your entire source code project from it’s current location to a new location. You want to make sure you have a backup of your existing code. You can branch in source control, start an entirely new project – whatever you want to do, just start working on a fresh project copy.
For this example, I am going to step through the conversion of the ‘iFinity Url Redirect Provider’ to it’s DNN equivalent – the ‘DNN Url Redirect Provider’.
To step along in time, have your to-be-converted code open and ready to edit in your code editor (remember, do this to a saved copy!). I recommend getting a working build going before you change anything – this will help to make sure you’re only chasing one issue at a time trying to get it compiling properly.
Conversion Process in Steps
The primary difference is that the URL Provider main class is going to inherit from a completely different parent. This means changing all the references in your project.
1. Remove the Url Master reference from the code, and make sure the DotNetNUke.dll reference is 7.1 or later.
- In the Project References, delete the reference to the Url Master assembly [red arrow]
- Double check to make sure you have your DotNetNuke Assembly reference pointing to a 7.1 (or later) version – this will need to be done by checking the version at the file location or using the object browser in Visual Studio.
- Make sure you set the build properties for the project to target .NET 4.0 or later.
Once this is done, you will have a broken build, because you will have references in your code pointing at the wrong location.
2. Remove all the URL Master references and using statements, and replace with DotNetNuke.Entities.Urls
- Any reference to ‘ModuleFriendlyUrlProvider’ is now ‘ExtensionUrlProvider’
- Any reference to WebControl, IProviderSettings becomes PortalModuleBase, IExtensionUrlProviderSettingsControl
Changing these values points the references to the old types to the new types which are in the DotNetNuke.Entities.Urls namespace.
When this is complete there should be no more references to iFInity.DNN.Modules.UrlMaster* in the code.
3. Re-do Overloads of the old ModuleFriendlyUrlProvider
- FriendlyName is no longer supported – this should be removed.
-IsLicensed is no longer supported – this should be removed. If you have a licensing solution for your code, you will need to incorporate that in another way. The ‘IsLicensed’ worked with the URL Master licensing scheme to highlight unlicensed providers.
-SettingsControlSrc is no longer supported – the location of the ‘Settings’ UserControl is now specified in the Extension Manifest file.
You will need to build a new Constructor method for the Provider – the new design does not contain the attributes for the provider upon instantiation. In fact there is usually no point in overloading the constructor, but you will have to put initialization code into a routine and make sure it is called by *all* of the overloads to ensure that all custom attributes you might require within the code are loaded correctly.
In this example, there were three attributes being read in during reading of the constructor. These now have to be moved to an initialization routine that gets called within the normal operation of the provider itself – as a developer, you cannot trust that member-level variables have been instantiated for you as they are when tied to a constructor method.
4. Re-do overloads of the old IProviderSettings
The IProviderSettings interface allowed a custom settings control to retrieve/store key/value pairs specific to the provider. This interface no longer exists and has no direct equivalent.
- LoadSettings(provider) and UpdateSettings(provider) becomes LoadSettngs() and SaveSettings(). Will need to take care of reading/writing to the provider from the .Provider property.
New Load/ Save Settings use the ExtensionUrlProviderInfo class, which uses a lighter-weight object to hold the actual settings (portalId, portal settings, etc). Any code using the old IProviderSettings format will likely use the actual provider object to pass values back and forth for saving / reading, so will need to be updated.
5. Update the Manifest File
In Url Master specific providers, it was necessary for the developer to craft a set of web.config XML merge statements to create the correct definition for a provider to be loaded. This is no longer the case with the DNN implementation. The loading of the providers is handled by the configuration of the provider, which in turn is controlled by being a first-class member of the manifest component types. Thus, a provider will not need to manipulate the web.config file directly, but will have to include a specific ‘Component’ type for the install process.
- Each Extension URL provider must have a min DNN version of 7.1 in the dependencies section, to prevent installation on earlier DNN builds.
- Each Extension URL Provider requires a component declaration of type ‘UrlProvider’. The values for this component definition are:
- name : the friendly name as shown to Administrators
- type : the fully-qualified type of the class in the provider which inherits from the ExtensionUrlProvider type.
- settingsControlSrc : relative path location of the User Control used to load the settings page. This is loaded in a popup directly from the provider definition in the Admin->Site Settings page.
- redirectAllUrls : if true, the provider ‘redirect’ method overload will be called for every request for the portal.
- replaceAllUrls : if true, the provider ‘change friendly url’ method overload will be called for each NavigateURL() call in DNN for the portal.
- rewriteAllUrls : if true, the provider ‘rewrite’ method will be called for each request for the portal
- desktopModules : the installed DesktopModule the provider should be associated with, for when the redirect, rewrite and replace calls should only occur on pages associated with the module. In this example, the URL Redirect provider is a generic provider with no associated DNN module, hence it has an empty ‘desktopModule’ link.
Note that with the redirect/replace/rewrite URLs – it is normally the association with a DesktopModule record that determines which requests / navigateURL() method calls are also run through the specific provider. In this example, this is not the case.
6. Compile, install and test
Your Extension URL Provider should now compile OK. At this point, you should package it up into an install package, and install it on a test site and put it through it’s paces. If you are replacing a Url Master custom provider, you should be able to directly test to make sure that all of the existing URLs work as before. Note that you will have to convert the URL Master installation to use DNN Advanced URLs first – the provider will not be loaded by DNN unless it is using the ‘Advanced’ mode of URLs.
If you have converted a custom URL provider, be sure to let people know via the comments. You may even want to upload a useful provider up into the DNN Url Providers Codeplex site so others can benefit from your hard work. If that’s the case, just get in contact with me and I can make it happen.