How To Add BotDetect CAPTCHA Protection to ASP.NET Web Forms

First Time Here?

Check the BotDetect Developer Crash Course for key integration steps.

BotDetect ASP.NET Captcha protection can be added to your ASP.NET Web Forms applications using the default BotDetect:Captcha custom Web Control. Displaying the Captcha challenge can be as simple as:

<BotDetect:Captcha ID="SampleCaptcha" runat="server" />

and checking user input when the form is submitted:

bool isHuman = SampleCaptcha.Validate(userInput);

You can also see how BotDetect Captcha protection has been added to various kinds of ASP.NET forms and projects by running the BotDetect Captcha ASP.NET integration sample projects coming with the BotDetect installation.

You can reuse the sample projects source code (both C# and VB.NET are available) that fits your application requirements.

CAPTCHA Integration Steps

When adding BotDetect Captcha protection to an ASP.NET Web Forms application:

First, Reference the BotDetect.dll assembly.
Then, you can add Captcha protection to selected ASP.NET forms in the application.
- Add the Captcha control to the page
- Add Captcha validation logic to page code-behind
Finally, configure your ASP.NET application to use BotDetect Captcha.

Reference the BotDetect.dll Assembly

You can find the BotDetect.dll assembly for the .NET framework version your application is running in the BotDetect installation folder.

.NET Version	Default Assembly Location
.NET 2.0	C:\Program Files\Lanapsoft\BotDetect 3 CAPTCHA Component\Asp.Net\v2.0\BotDetect.dll
.NET 3.5	C:\Program Files\Lanapsoft\BotDetect 3 CAPTCHA Component\Asp.Net\v3.5\BotDetect.dll
.NET 4.0	C:\Program Files\Lanapsoft\BotDetect 3 CAPTCHA Component\Asp.Net\v4.0\BotDetect.dll

If you are using Visual Studio, you can just add a reference to the appropriate assembly to your application by using the Add reference dialog and browsing to the above location on your development machine.

[back to top]

Add CAPTCHA Protection to Selected ASP.NET Forms

When the required assembly has been referenced, you can add Captcha protection to forms in the application.

Add the Captcha Control to the Page

On the ASP.NET form you want to protect with BotDetect Captcha, add the following ASP.NET controls and Html elements:

A BotDetect:Captcha control which will display the Captcha
An asp:TextBox for the Captcha code user input
A label for the textbox, displaying Captcha instructions
An asp:Label which will display Captcha validation errors

The resulting fragment in your .aspx file could look like:

<p><label for="CaptchaCodeTextBox">Retype the characters from the 
    picture:</label></p>
<BotDetect:Captcha ID="SampleCaptcha" runat="server" />
<asp:TextBox ID="CaptchaCodeTextBox" runat="server" />
<asp:Label ID="CaptchaIncorrectLabel" runat="server"/>

[back to top]

Add CAPTCHA Validation Logic to Page Code-Behind

When the form is submitted, the Captcha validation result must be checked and the protected action (user registration, comment posting, email sending, ...) only performed if the Captcha test was passed. For example:

protected void Page_PreRender(object sender, EventArgs e)
{
    // initial page setup
    if (!IsPostBack)
    {
        // initialize the Captcha validation error label
        CaptchaIncorrectLabel.Text = "Incorrect!";
        CaptchaIncorrectLabel.Visible = false;
    }

    // setup client-side input processing
    SampleCaptcha.UserInputClientID = CaptchaCodeTextBox.ClientID;

    if (IsPostBack)
    {
        // validate the Captcha to check we're not dealing with a bot
        string userInput = CaptchaCodeTextBox.Text;
        bool isHuman = SampleCaptcha.Validate(userInput);
        CaptchaCodeTextBox.Text = null; // clear previous user input

        if (isHuman)
        {
            CaptchaIncorrectLabel.Visible = false;
        }
        else
        {
            CaptchaIncorrectLabel.Visible = true;
        }
    }
}

[back to top]

Configure Your ASP.NET Application to Use BotDetect CAPTCHA

There are several changes that need to be made to your application configuration (the web.config file) to allow it to use BotDetect Captcha protection.

Register the BotDetect CAPTCHA HttpHandler

BotDetect uses a special HttpHandler for Captcha requests (Captcha images, sounds, resources...), which needs to be registered in your application.

HttpHandler Registration

Locate the <system.web> -> <httpHandlers> section of the web.config file.

Add the following BotDetect handler registration to this section:

<!-- Register the HttpHandler used for BotDetect Captcha requests -->
<add verb="GET" path="BotDetectCaptcha.ashx" 
    type="BotDetect.Web.CaptchaHandler, BotDetect"/>

IIS 7 HttpHandler Registration

Locate the <system.webServer> -> <handlers> section of the web.config file.

Add the following BotDetect handler registration to this section:

<!-- Register the HttpHandler used for BotDetect Captcha requests
  (IIS 7.0+) -->
<remove name="BotDetectCaptchaHandler"/>
<add name="BotDetectCaptchaHandler" preCondition="integratedMode"
    verb="GET" path="BotDetectCaptcha.ashx"
    type="BotDetect.Web.CaptchaHandler, BotDetect"/>

[back to top]

Configure ASP.NET Session State

BotDetect requires ASP.NET Session state to function properly, which should be configured for your application. Also, to ensure Captcha sounds work properly in all browsers, a custom SessionIDManager (implementing an optional but recommended improvement, as explained in the BotDetect FAQ) should be registered.

In the <system.web> section of the web.config file, locate the <sessionState> element if it exists, or add it if it doesn't.

Add the following attribute to the declaration:

sessionIDManagerType="BotDetect.Web.CustomSessionIdManager, BotDetect"

The most common resulting declaration would be:

<sessionState mode="InProc" cookieless="AutoDetect" timeout="20" 
    sessionIDManagerType="BotDetect.Web.CustomSessionIdManager, BotDetect"/>

If you want to use a different Session State mode or options, you can change any settings except the sessionIDManagerType – which should point to the BotDetect class as specified above, if you want Captcha sounds to work reliably.

[back to top]

(Optionally) Register BotDetect CAPTCHA Namespaces & Control Tag Prefix

The following two configuration steps are not mandatory, but will make using BotDetect in your application easier.

BotDetect Namespaces

Locate the <system.web> -> <pages> -> <namespaces> section

Add the following lines to its bottom (just before the closing </namespaces> tag):

<add namespace="BotDetect" />
<add namespace="BotDetect.Web" />
<add namespace="BotDetect.Web.UI" />

This will ensure that you can use BotDetect namespace members in all pages in the application. If you prefer, you can also add the namespaces only on the pages using BotDetect.

BotDetect Control Tag Prefix

Locate the <system.web> -> <pages> -> <controls> section

Add the following line to its bottom (just before the closing </controls> tag):

<!-- Register the BotDetect tag prefix for easier use in all pages -->
<add assembly="BotDetect" namespace="BotDetect.Web.UI" 
    tagPrefix="BotDetect"/>

This will ensure that you don't have to add the

<%@ Register Assembly="BotDetect" Namespace="BotDetect.Web.UI" 
    TagPrefix="BotDetect" %>

directive to the top of every page you want to use BotDetect Captcha protection on. If you prefer, you can also just use the directive on selected pages instead.

Other BotDetect CAPTCHA Options

BotDetect ASP.NET Captcha allows detailed customization of many Captcha properties, and you can read more about them in the BotDetect Captcha configuration How To.

[back to top]

Print