Upgrading from v7.x and below

Important note: The ASP.NET AJAX Control Toolkit now requires that your project is using .NET framework v4.0 or higher. Projects targeting .NET framework v3.5 have to be migrated to a more recent .NET version before upgrading.

0 - Remove previous version

Make sure your have removed previous versions before installing ASP.NET AJAX Control Toolkit v16.1:

1. If you have added the toolkit to Toolbox via the “Choose items...” dialog, remove an assembly reference and reset your toolbox.
2. If you have added the toolkit via the NuGet package manager, simply uninstall the package from the solution.

1 - Install

To install the ASP.NET AJAX Control Toolkit go to the Download page and get the new Installer (created by DevExpress).

If you use the fully-qualified name for the ASP.NET AJAX Control Toolkit assembly, then please ensure that all occurrences are updated (this includes references in web.config and @Register directives in the ASPX markup).

2 - Replace ToolkitScriptManager with ScriptManager

The ToolkitScriptManager has been removed in v15.1. Please use the standard ScriptManager control. It should be sufficient to change the tag name in the markup from :ToolkitScriptManager -> asp:ScriptManager. If you find any issues, then please report them here.

Refer to the "ToolkitScriptManager Removed in v15.1, Use ScriptManager" section for details.

3 - Clean up Web.config

Remove the following outdated elements from your project’s web.config file:

// (in system.web/httpHandlers and system.webServer/handlers sections).
<add name="CombineScriptsHandler" verb="*" path="CombineScriptsHandler.axd" type="AjaxControlToolkit.CombineScriptsHandler, AjaxControlToolkit"/>


// (in system.web section)
<section name="sanitizer" requirePermission="false" type="AjaxControlToolkit.Sanitizer.ProviderSanitizerSection, AjaxControlToolkit"/> 

// (in system.web section)
<sanitizer defaultProvider="HtmlAgilityPackSanitizerProvider">
. . .
</sanitizer>

4 - Use Microsoft.Web.Optimization for bundling and minification

The AjaxControlToolkit.CombineScriptsHandler have been removed in v15.1 and resource bundling was delegated to the ASP.NET Web Optimization Framework.

Find the detailed description and instructions on enabling it in the following article: How to use bundling and CDN.

Note: if you use named Control Bundles (defined in the ~/AjaxControlToolkit.config file), then adjust the script bundle virtual path as shown below:

"~/Scripts/AjaxControlToolkit/<ControlBundleName>Bundle".

5 - Html Editor

The following namespaces have been renamed so please update your code accordingly:

Change AjaxControlToolkit.HTMLEditor to AjaxControlToolkit.HtmlEditor.

Change AjaxControlToolkit.HTMLEditor.ToolbarButton to AjaxControlToolkit.HtmlEditor.ToolbarButtons.

To reduce the number of dependencies, we have moved Html Sanitizer out to an external NuGet package: AjaxControlToolkit.HtmlEditor.Sanitizer

For security concerns, we recommend that you always use Html Editor together with Html Sanitizer.

Reporting Issues

If you have any questions regarding upgrading your projects then open a ticket in the Issue Tracker.

ToolkitScriptManager Removed in v15.1, Use ScriptManager

Use ScriptManager

Starting with the v15.1 release the standard ScriptManager is used. We have removed the ToolScriptManager due to various issues it caused.

Details

Previous versions of ASP.NET AJAX Control Toolkit required that ToolkitScriptManager was used on each page with extenders. This control has been introduced back in 2007 to add features missing from the standard ScriptManager: script combining and CDN support.

Since then, ASP.NET has evolved, and ScriptManager can currently handle both tasks on its own with the help of the ASP.NET Web Optimization framework (check ASP.NET 4.5 ScriptManager Improvements in WebForms for details).

Another common issue is that Visual Studio ASP.NET templates contain ScriptManager on the master page by default. So using the ASP.NET AJAX Control Toolkit became complicated and required additional edits of the template to work with the ToolScriptManager.

Our top priority was to ensure that the ASP.NET AJAX Control Toolkit works with modern versions of Visual Studio and .NET. And that it also integrates seamlessly into the standard (modern) web templates.

In the v15.1 release, we have extensively reworked most of the code related to scripts, styles and images, and decided to leverage modern technologies available in the current .NET frameworks.

Script and CSS bundling is delegated to Bundles. This topic is covered in the following article: ”How to use bundling and CDN?”.