Telerik UI for ASP.NET AJAX

This article explains the entries a Telerik-enabled Web Site or Web Application has. There are several mandatory additions, and a number of optional configuration settings:

Mandatory Additions to the web.config

For the controls from the Telerik UI for ASP.NET AJAX suite to function, the needed HTTP handlers must be registered in the web.config (Example 1).

There are several ways to add them:

  • Using the Configuration and Creation Wizard from the Telerik Visual Studio Extensions can add them automatically.

  • The Smart Tag of each control will let you register the handlers it needs if they are not present. Not all handlers are needed by each control, so the available list may vary.

  • You can simply use the following code snippet and paste it into your web.config:

Example 1: The HTTP handlers needed by the Telerik UI for ASP.NET AJAX suite.

CopyXML
<configuration>
    <system.web>
        <!-- for IIS versions below 7 and Classic Pipeline mode -->
        <httpHandlers>
            <!-- This is the primary handler used to fetch most of the needed resources -->
            <add path="Telerik.Web.UI.WebResource.axd" type="Telerik.Web.UI.WebResource" verb="*" validate="false" />
            <!-- Only needed for RadSpell and RadEditor's spell checking -->
            <add path="Telerik.Web.UI.SpellCheckHandler.axd" type="Telerik.Web.UI.SpellCheckHandler" verb="*" validate="false" />
            <!-- Only needed for controls that have complex dialogs like RadEditor, RadImageEditor -->
            <add path="Telerik.Web.UI.DialogHandler.aspx" type="Telerik.Web.UI.DialogHandler" verb="*" validate="false" />
            <!-- Only needed if RadAsyncUpload, RadProgressArea/RadProgressManager or the obsolete RadUpload are used -->
            <add path="Telerik.RadUploadProgressHandler.ashx" type="Telerik.Web.UI.RadUploadProgressHandler" verb="*" validate="false" />
            <!-- Only needed if the obsolete RadChart is used -->
            <add path="ChartImage.axd" type="Telerik.Web.UI.ChartHttpHandler" verb="*" validate="false" />
        </httpHandlers>
        <httpModules>
            <!-- Only needed if the obsolete RadUpload is used in the site -->
            <!--    <add name="RadUploadModule" type="Telerik.Web.UI.RadUploadHttpModule" /> -->
            <!-- Only needed if RadCompression is used in the site. IIS7+ offers built-in dynamic content compression -->
            <!--    <add name="RadCompression" type="Telerik.Web.UI.RadCompression" />  -->
        </httpModules>
    </system.web>

    <system.webServer>
        <!-- For IIS7+ and Integrated Pipeline mode -->
        <validation validateIntegratedModeConfiguration="false" />
        <modules runAllManagedModulesForAllRequests="true">
            <!-- Only needed if the obsolete RadUpload is used in the site -->
            <!--    <remove name="RadUploadModule" /> -->
            <!--    <add name="RadUploadModule" type="Telerik.Web.UI.RadUploadHttpModule" preCondition="integratedMode" /> -->
            <!-- Only needed if RadCompression is used in the site. IIS7+ offers built-in dynamic content compression -->
            <!--    <remove name="RadCompression" /> -->
            <!--    <add name="RadCompression" type="Telerik.Web.UI.RadCompression" preCondition="integratedMode" /> -->
        </modules>
        <handlers>
            <remove name="Telerik_Web_UI_WebResource_axd" />
            <remove name="Telerik_Web_UI_SpellCheckHandler_axd" />
            <remove name="Telerik_Web_UI_DialogHandler_aspx" />
            <remove name="Telerik_RadUploadProgressHandler_ashx" />
            <remove name="ChartImage_axd" />
            <!-- This is the primary handler used to fetch most of the needed resources -->
            <add name="Telerik_Web_UI_WebResource_axd" path="Telerik.Web.UI.WebResource.axd" type="Telerik.Web.UI.WebResource" verb="*" preCondition="integratedMode" />
            <!-- Only needed for RadSpell and RadEditor's spell checking -->
            <add name="Telerik_Web_UI_SpellCheckHandler_axd" path="Telerik.Web.UI.SpellCheckHandler.axd" type="Telerik.Web.UI.SpellCheckHandler" verb="*" preCondition="integratedMode" />
            <!-- Only needed for controls that have complex dialogs like RadEditor, RadImageEditor -->
            <add name="Telerik_Web_UI_DialogHandler_aspx" path="Telerik.Web.UI.DialogHandler.aspx" type="Telerik.Web.UI.DialogHandler" verb="*" preCondition="integratedMode" />
            <!-- Only needed if RadAsyncUpload, RadProgressArea/RadProgressManager or the obsolete RadUpload are used -->
            <add name="Telerik_RadUploadProgressHandler_ashx" path="Telerik.RadUploadProgressHandler.ashx" type="Telerik.Web.UI.RadUploadProgressHandler" verb="*" preCondition="integratedMode" />
            <!-- Only needed if the obsolete RadChart control is used -->
            <add name="ChartImage_axd" path="ChartImage.axd" type="Telerik.Web.UI.ChartHttpHandler" verb="*" preCondition="integratedMode" />
        </handlers>
    </system.webServer>
</configuration>
Note

In case your project references the Telerik assemblies from the GAC, you will need to register these handlers by using the fully qualified assembly name by adding the assembly information to the type attribute (Example 2).

If you deploy the project on a WebFarm/WebGarden, you need to change the Telerik.Web.UI.WebResource.axd type (Example 3). You can read more about deploying a solution that uses Telerik controls on a WebFarm or WebGarden in the How to integrate RadControls for ASP.NET AJAX in a WebFarm or WebGarden scenario blog post.

Example 2: An HTTP handler registration that uses a fully qualified assembly name.

CopyXML
<add name="Telerik_Web_UI_WebResource_axd" path="Telerik.Web.UI.WebResource.axd" type="Telerik.Web.UI.WebResource, Telerik.Web.UI, Culture=neutral, Version=2014.3.1209.45, PublicKeyToken=121fae78165ba3d4" verb="*" preCondition="integratedMode" />

where you will need to change the Version property to the concrete version you are using and the same assembly is to be used with all handlers.

Example 3: The Telerik.Web.UI.WebResource.axd handler type for WebFarm/WebGarden deployment.

CopyXML
<system.web>
    <httpHandlers>
        <add path="Telerik.Web.UI.WebResource.axd" type="Telerik.Web.UI.WebResourceSession" verb="*" validate="false" />
    </httpHandlers>
</system.web>

<system.webServer>
    <handlers>
        <add name="Telerik_Web_UI_WebResource_axd" path="Telerik.Web.UI.WebResource.axd" type="Telerik.Web.UI.WebResourceSession" verb="*" preCondition="integratedMode" />
    </handlers>
</system.webServer>
Tip

You can register the Telerik controls assembly and tag prefix globally in the web.config, so you can use the controls in all the pages/user controls in the project without adding an explicit Register directive to each of them. This addition is not mandatory, but can be very helpful.

Copyweb.config
<pages>
 <controls>
   <add tagPrefix="telerik" namespace="Telerik.Web.UI" assembly="Telerik.Web.UI" />
 </controls>
</pages>

Control Properties You Can Set From the web.config

There are various control properties that you can set from the web.config for an application-wide effect. This includes scripts CDN, skins CDN, render mode, skin, etc.

Such keys are added under the <appSettings> section in the web.config like shown in Example 4.

Example 4: A site-wide setting added in the web.config.

CopyXML
<configuration>
    <appSettings>
        <add key="Telerik.Skin" value="Black" />
    </appSettings>
</configuration>

You can add any of the keys below in a similar fashion.

Here follows a list with all the available appSettings keys for the Telerik UI for ASP.NET AJAX controls:

  • BindGridInvisibleColumns—when set to true, all columns in a RadGrid which have the Visible property to false will bind their data. You can read more about its use case in the Breaking change: Hidden column cell text is not persisted in ViewState forum thread.

  • CSApiKey—the key provided by http://www.hisoftware.com/. Required for using the Accessibility Compliance Check RadEditor Dialog.

  • KeepOriginalOrderOfScriptDescriptorsDuringAjax—when set to true, the original order of the $create() statements of the controls that participate in the partial page rendering will be preserved in case RadAjaxManager or RadAjaxPanel is used. Otherwise, the order will be reversed. You can read more about this in the Tips and tricks for ajaxifying specific controls help article.

  • Telerik.AsyncUpload.TemporaryFolder—lets you set the temporary folder RadAsyncUpload uses on an application level. You can read more about this feature in the RadAsyncUpload Overview help article.

  • Telerik.EnableEmbeddedBaseStylesheet—lets you disable the embedded base stylesheets for all Telerik controls in the application by setting it to false. The How Skins Work article explains what the base stylesheet is. You can read more about disabling the embedded resources in the Disabling Embedded Resources article.

  • Telerik.EnableEmbeddedScripts—lets you disable the embedded scripts for all Telerik controls in the application by setting it to false. You can read more about disabling the embedded resources in the Disabling Embedded Resources article.

  • Telerik.EnableEmbeddedSkins—lets you disable the embedded skin-specific stylesheets for all Telerik controls in the application by setting it to false. The How Skins Work article explains what the skin-specific stylesheet is. You can read more about disabling the embedded resources in the Disabling Embedded Resources article.

  • Telerik.ScriptManager.EnableEmbeddedjQuery—lets you disable the embedded jQuery that comes with the Telerik controls by setting it to false. You can read more about this feature in the Disabling the Embedded jQuery article.

  • Telerik.ScriptManager.TelerikCdn—lets you enable the scripts CDN support in RadScriptManager globally for the application by setting it to true. You can read more about this feature in the Scripts CDN Overview article.

  • Telerik.ScriptManager.TelerikCdn.BaseSecureUrl—lets you configure the base secure (HTTPS) URL of the scripts CDN for the entire application. You can read more about this feature in the Custom CDN Provider article.

  • Telerik.ScriptManager.TelerikCdn.BaseUrl—lets you configure the base URL of the scripts CDN for the entire application. You can read more about this feature in the Custom CDN Provider article.

  • Telerik.Skin—lets you choose the skin for all Telerik controls in the application by setting it to the desired string value. You can read more about using skins in the Skin Registration article.

  • Telerik.Web.CaptchaImageStorageProviderTypeName—lets you set the RadCaptcha custom caching provider for the entire application. You can read more about using custom providers for RadCaptcha in the Caching Provider article.

  • Telerik.Web.SkinsAssembly—in order to load skins from an external assembly, you need to register its name via this key. You can read more about using external skins assemblies in the How to Load Skins from External Assemblies article and you may also find useful the RadSkinManager control.

  • Telerik.Web.UI.DialogParametersEncryptionKey—lets you set a static key that RadEditor will use when deserializing its dialog parameters. By default, this key is randomly generated each time the application recycles. You can read more about its use in the Cannot Deserialize Dialog Parameters. Invalid character in a Base-64 string troubleshooting article.

  • Telerik.Web.UI.ScriptFolder—a folder in the project that hosts the external scripts combined by RadScriptManager through the Telerik.Web.UI.WebResource.axd handler. You can read more about this feature in the Combining External Scripts article.

  • Telerik.Web.UI.ScriptFolders—a semicolon-separated list of folders in the project that host the external scripts combined by RadScriptManager through the Telerik.Web.UI.WebResource.axd handler. You can read more about this feature in the Combining External Scripts article.

  • Telerik.Web.UI.StyleSheetFolder—a folder in the project that hosts the external stylesheets combined by RadStyleSheetManager and RadSkinManager. This key must be set in order for these controls to work with custom skins. You can read more about the feature in the RadSkinManager and Serving external style sheets articles.

  • Telerik.Web.UI.StyleSheetFolders—a semicolon-separated list of folders in the project that hosts the external stylesheets combined by RadStyleSheetManager and RadSkinManager. This key must be set in order for these controls to work with custom skins. You can read more about the feature in the RadSkinManager and Serving external style sheets articles.

  • UseGridNativeEditorsInMobileMode—lets you disable the native browser editors and use the Telerik editors for a RadGrid in Mobile RenderMode by setting it to false. You can read more about this feature in the Data Editing on Mobile Devices article.

Example 5: A sample that shows how you can set all of the available appSettings keys for the Telerik controls.

CopyXML
<configuration>
    <appSettings>
        <add key="BindGridInvisibleColumns" value="true" />
        <add key="CSApiKey" value="abcdefghjiklmnopqrstuvwxyz1234567890" />
        <add key="KeepOriginalOrderOfScriptDescriptorsDuringAjax" value="true" />
        <add key="Telerik.AsyncUpload.TemporaryFolder" value="~/tempUploads" />
        <add key="Telerik.EnableEmbeddedBaseStylesheet" value="true" />
        <add key="Telerik.EnableEmbeddedScripts" value="true" />
        <add key="Telerik.EnableEmbeddedSkins" value="true" />
        <add key="Telerik.ScriptManager.EnableEmbeddedjQuery" value="true" />
        <add key="Telerik.ScriptManager.TelerikCdn" value="disabled" />
        <add key="Telerik.ScriptManager.TelerikCdn.BaseSecureUrl" value="https://my.favorite.cdn" />
        <add key="Telerik.ScriptManager.TelerikCdn.BaseUrl" value="http://my.favorite.cdn" />
        <add key="Telerik.Skin" value="Default" />
        <add key="Telerik.Web.CaptchaImageStorageProviderTypeName" value="MyCustomCaptchaStorageProvider" />
        <add key="Telerik.Web.SkinsAssembly" value="MyCustomSkinsAssembly" />
        <add key="Telerik.Web.UI.DialogParametersEncryptionKey" value="TheseMustBe46Characters-abcdefghijklmnopqrstu" />
        <add key="Telerik.Web.UI.ScriptFolder" value="~/MyScripts/" />
        <add key="Telerik.Web.UI.ScriptFolders" value="~/MyScripts/; ~/MoreScripts/" />
        <add key="Telerik.Web.UI.StyleSheetFolder" value="~/App_Themes/" />
        <add key="Telerik.Web.UI.StyleSheetFolders" value="~/App_Themes/; ~/MyStyleSheets/" />
        <add key="UseGridNativeEditorsInMobileMode" value="true" />
    </appSettings>
</configuration>