Kentico CMS 7.0 Developer's Guide

Registering providers via the web.config

Registering providers via the web.config

 Previous topic Next topic Mail us feedback on this topic!  

Registering providers via the web.config

 Previous topic Next topic JavaScript is required for the print function Mail us feedback on this topic!  

You can register custom providers and helpers through your application's web.config file. This is done by mapping provider objects to the appropriate custom classes. Registering providers in the web.config allows you to switch between different providers (custom or default) without having to edit the application code

 

Note: If you do not need your provider customizations to be adjustable through the web.config file, it is more efficient to register custom providers directly through the API in the App_Code folder (as described in Registering providers in App_Code).

 

1. Edit your web.config file and add the following section into the <configSections> element:

 

<?xml version="1.0"?>
<configuration xmlns="http://schemas.microsoft.com/.NetConfiguration/v2.0">
 <configSections>

 
 ...
 

<!-- Extensibility BEGIN -->
 <section name="cms.extensibility" type="CMS.SettingsProvider.CMSExtensibilitySection" />
<!-- Extensibility END -->

 
 </configSections>
...

 

This defines the cms.extensibility web.config section where you can register custom providers and helpers.

 

2. Create the actual <cms.extensibility> section directly under the root level of the web.config.

 

3. Assign your custom classes to providers or helpers via <add> elements with the following attributes:

 

•name - must match the name of the provider/helper class that you wish to customize (without the extension).

•assembly - specifies the assembly where your custom class is located. Set the value to App_Code for classes placed in the App_Code folder (even on web application installations, where the actual name of the folder is Old_App_Code).

•type - specifies the name of your custom provider class (including namespaces).

oIf the class is in the App_Code folder, the system triggers the OnGetCustomClass event when requesting the provider class. The type value is passed on through the ClassName property of the event's ClassEventArgs parameter. When writing the event's handler, use the value to identify and load an instance of the appropriate custom provider class.

 

You need to categorize the <add> elements under <providers> or <helpers> sub-sections based on the type of the customized class.

 

<configuration>

...

 

<!-- Extensibility BEGIN -->
<cms.extensibility>
 <providers>
   <add name="EmailProvider" assembly="App_Code" type="CustomEmailProvider" />
   <add name="SiteInfoProvider" assembly="App_Code" type="CustomSiteInfoProvider" />
   <add name="ForumPostInfoProvider" assembly="CMS.CustomProviders"
  type="CMS.CustomProviders.CustomForumPostInfoProvider" />
   ...
 </providers>
 <helpers>
   <add name="CacheHelper" assembly="App_Code" type="CustomCacheHelper" />
   ...
 </helpers>
</cms.extensibility>
<!-- Extensibility END -->

 

...

</configuration>

 

In the case of custom providers placed in a separate assembly, the registration is now complete.

 

Loading App_Code classes

 

When using the web.config to register custom providers defined in the App_Code folder, you also need to ensure that the system can load the classes.

 

Example:

 

[C#]

 

using System;
 
using CMS.SettingsProvider;
 
[ClassLoader]
public partial class CMSModuleLoader
{
   /// <summary>
   /// Attribute class that ensures the loading of custom classes.
   /// </summary>
  private class ClassLoader : CMSLoaderAttribute
   {
      /// <summary>
      /// Called automatically when the application starts.
      /// </summary>
      public override void Init()
       {
          // Assigns a handler for the OnGetCustomClass event
          // This event is triggered when the system requests a class with App_Code as the assembly name
          ClassHelper.OnGetCustomClass += GetCustomClassEventHandler;
       }
 
      /// <summary>
      /// Gets the custom class object based on the specified class name (i.e. type value).
      /// </summary>
      private static void GetCustomClassEventHandler(object sender, ClassEventArgs e)
       {
          // Checks whether an object is already assigned to the requested class.
          if (e.Object == null)
           {
              switch (e.ClassName)
               {
                  // Loads an instance of the 'CustomEmailProvider' class
                  case "CustomEmailProvider":
                       e.Object = new CustomEmailProvider();
                      break;
 
                   // Loads an instance of the 'CustomSiteInfoProvider' class
                  case "CustomSiteInfoProvider":
                       e.Object = new CustomSiteInfoProvider();
                      break;
 
                   // Loads an instance of the 'CustomCacheHelper' class
                  case "CustomCacheHelper":
                       e.Object = new CustomCacheHelper();
                      break;
               }
           }
       }
   }
}

 

When the system requests an App_Code provider class registered through the cms.extensibility section of the web.config, the OnGetCustomClass event is triggered and the handler method returns an instance of the appropriate class.