Creating a Custom Control

In this tutorial, you will learn how to create an AJAX Control Toolkit custom control/extender. To learn how to install the AJAX Control Toolkit, see the Step-by-Step Installation Guide page.

Create a new project

Make sure that .NET Framework version is 4.0 or higher.

Add assembly references

Add the AJAX Control Toolkit reference by installing the AjaxControlToolkit NuGet Package. Make sure you have the System.System.Web.Extensions reference added.

Add a class that inherits ExtenderControlBase or ScriptControlBase

The difference between these base classes is that ExtenderControlBase requires a target control to extend its behavior, while ScriptControlBase is a self-contained control that operates independently.

Add the TargetControlType attribute (extenders only)

If your custom class is derived from the ExtenderControlBase class, you need to add the TargetControlType attribute with the type of the control which the extender will be attached to. For example, if the extender targets the asp:TextBox, the attribute should be used as follows:

[TargetControlType(typeof(TextBox))]

Add JavaScript files with client behavior

JavaScript files come into two variants: a debug and release version. A debug version ends with .js, while a release version ends with .min.js To make a minified version of a JavaScript file, use the Web Essentials (Visual Studio 2013 or earlier) or Bundler & Minifier extension (Visual Studio 2015).

Set these files Build Action to Embedded Resource.

Add CSS files with custom styles (optional)

СSS files come into two variants: a debug and release version. A debug version ends with .css, while a release version ends with .min.css To make a minified version of a CSS file, use the Web Essentials (Visual Studio 2013 or earlier) or Bundler & Minifier extension (Visual Studio 2015).

Set these files Build Action to Embedded Resource.

Add the ClientScriptResource attribute

The ClientScriptResource attribute is used to determine what files are needed to load during control/extender initialization. This attribute is applied to a class.

The attribute constructor requires two parameters:

componentType uniquely identifies your script and can be set to an arbitrary string.

resourcePath is used to reference javascript files embedded into your custom assembly.

For example, if the default namespace in your project is CustomAjaxControl and javascript is named MyCustomExtenderBehavior.js, then the attribute will look like this:

[ClientScriptResource("MyCustomExtenderBehavior", "CustomAjaxControl.MyCustomExtenderBehavior")]

Take a note that CustomAjaxControl.MyCustomExtenderBehavior is written without any .js or .min.js suffix. This is because AJAX Control Toolkit internals will add an appropriate suffix automatically.

Add the ClientCssResource attribute (optional)

ClientCssResource is used to indicate that the control/extender has custom CSS styles.

The attribute constructor requires one parameter:

resourcePath is used to reference CSS files embedded into your custom assembly.

For example, if the default namespace in your project is CustomAjaxControl and javascript is named MyCustomExtenderStyle.css, then the attribute will look like this:

[ClientCssResource("CustomAjaxControl.MyCustomExtenderStyle")]

Take a note that CustomAjaxControl.MyCustomExtenderStyle is written without any .css or .min.css suffix. This is because AJAX Control Toolkit internals will add an appropriate suffix automatically.

Add the WebResource attribute

The WebResource attribute is used to resolve web links for resources embedded into an assembly. This attribute is applied to an assembly scope.

The attribute constructor requires two parameters:

webResource is the name of Web resource embedded into an assembly. contentType is the type of a resource, such as "image/gif" or "text/javascript".

For example, if you have embedded resources into an assembly named CustomAjaxControl.MyCustomExtenderBehavior.js and CustomAjaxControl.MyCustomExtenderBehavior.min.js, then the attributes will look like this:

[assembly: WebResource("CustomAjaxControl.MyCustomExtenderBehavior.js", "text/javascript")]
[assembly: WebResource("CustomAjaxControl.MyCustomExtenderBehavior.min.js", "text/javascript")]

Each embedded CSS style file requires a separate WebResource attribute with contentType="text/css":

[assembly: WebResource("CustomAjaxControl.MyCustomExtenderStyle.css", "text/css")]
[assembly: WebResource("CustomAjaxControl.MyCustomExtenderStyle.min.css", "text/css")]

Add the RequiredScript attribute (optional)

The RequiredScript attribute is used when your custom control/extender needs scripts defined in another extender to operate.

The attribute constructor requires one parameter:

extenderType is the type of another control/extender which scripts will be loaded.

For example, if you need a Common.js file, add the following attribute to the class:

[RequiredScript(typeof(CommonToolkitScripts))]

Register a custom tag prefix

A custom class is not defined in the AjaxControlToolkit assembly, so a custom control/extender cannot use the ajaxToolkit: tag prefix by default.

For example, if an assembly name and default namespace of your project is CustomAjaxControl then tag prefix registration will look like this:

<%@ Register Assembly="CustomAjaxControl" Namespace="CustomAjaxControl" TagPrefix="myTag" %>

As a result markup for the custom extender will look like this:

<asp:TextBox ID="textBox1" runat="server" />
<myTag:MyCustomExtender runat="server" TargetControlID="textBox1" />