How To Add BotDetect CAPTCHA Protection to ASP.NET Web Pages Applications

BotDetect ASP.NET Captcha Simple API protection can be added to your ASP.NET Web Pages applications using the SimpleCaptcha class, implemented in the BotDetect.dll assembly. Displaying the Captcha challenge can be as simple as:
SimpleCaptcha exampleCaptcha = new SimpleCaptcha("ExampleCaptcha");
and checking user input when the form is submitted:
bool isHuman = exampleCaptcha.Validate();

First Time Here?

Check the BotDetect ASP.NET Web Pages Captcha Simple API Quickstart for key integration steps.

You can reuse the example 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 Pages application:

  1. Display a Captcha challenge on the Asp.Net Web Pages page
  2. Check is the visitor a human on ASP.NET Web Pages page
  3. Further Captcha customization and options

I. Display a Captcha challenge on the Asp.Net Web Pages page

Before protecting a form action in your ASP.NET Web Pages application with BotDetect Captcha, you should decide how to call the Captcha instance and the related textbox you will use. In this guide, we will use ExampleCaptcha and CaptchaCode. If you plan to protect multiple pages within the same ASP.NET Web Pages application, you should take care to give each Captcha instance a different name (e.g. LoginCaptcha, RegisterCaptcha, CommentCaptcha etc.).

You will also need to register a HttpHandler that will handle Captcha requests.

Reference the BotDetect.dll Assembly

ASP.NET Web Pages applications should reference the base BotDetect.dll assembly which is contained in a single assembly included in the BotDetect ASP.NET download package.

You can find the BotDetect.dll assembly for the .NET framework version your application is running in the BotDetect installation folder – if you didn't change the installation folder during BotDetect setup, the .NET assembly can be found in the C:\Program Files (x86)\Captcha Inc\BotDetect 4 CAPTCHA Component\Asp.Net\.NET\bin\ folder, etc.

Reference the System.Data.SQLite.dll Assembly

By default, BotDetect ASP.NET CAPTCHA Simple API uses SQLite as the default persistence provider for storing captcha data, so you need to ensure SQLite assembly is referenced in your project. Here is where you can find the SQLite installation guide. Or check any Simple API examples that are installed with BotDetect.

Create and render a BotDetect.Web.SimpleCaptcha instance

SimpleCaptcha objects in ASP.NET Web Pages applications are represented by the SimpleCaptcha class. To use them, your View should first import the BotDetect.Web namespace.

Then, you can add a Captcha challenge to the View by rendering a Html.Label with the Captcha instructions for the user, a Html.Raw with the string to interpret as HTML markup that serves as a container for Captcha challenges from SimpleCaptcha object instance, and a Html.TextBox in which the user is to type the Captcha code:

@using BotDetect.Web;

  […]
@Html.Label("Retype the code from the picture:", "CaptchaCode")
@{
  SimpleCaptcha exampleCaptcha = new SimpleCaptcha("ExampleCaptcha");

}
@Html.Raw(exampleCaptcha.Html)
@Html.TextBox("CaptchaCode")

Configure Captcha options

Configure captcha options in botdetect.xml configuration file. By default, this file is located at the root of your project.

<?xml version="1.0" encoding="UTF-8"?>
<botdetect xmlns="https://captcha.com/schema/net"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="https://captcha.com/schema/net 
     https://captcha.com/schema/net/botdetect-4.4.0.xsd">

  <captchaStyles>
    <captchaStyle>
      <name>ExampleCaptcha</name>
      <userInputID>CaptchaCode</userInputID>
      <codeLength>3-5</codeLength>
    </captchaStyle>
  </captchaStyles>

</botdetect>

Register the BotDetect HttpHandler for CAPTCHA Requests

BotDetect uses a special HttpHandler for Captcha requests (Captcha images, sounds, resources...), which needs to be registered in your application before Captcha images will be displayed. This registration is a two-step process:

1. Base 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.SimpleCaptchaHandler, BotDetect"/>

2. IIS 7.0+ 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.SimpleCaptchaHandler, BotDetect"/>

Once all of these steps have been performed, the Captcha should be displayed when you open your form in a browser:

BotDetect CAPTCHA added to an ASP.NET form

If the Captcha image isn't being rendered properly, please check the BotDetect integration FAQ.

II. Check is the visitor a human on ASP.NET Web Pages page

Once the Captcha challenge is displayed on your form, the code processing form submissions can check if the Captcha was solved successfully and deny access to bots.

This code needs to access the Captcha and textbox control instances added to the form;

Add Captcha Validation logic to Web Pages page

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:

@if ((Request.HttpMethod == "POST"))
  {
    bool isHuman = sampleCaptcha.Validate();
    if (isHuman)
    {
        <span class="correct">Correct!</span>
    }
    else
    {
        <span class="incorrect">Incorrect!</span>
    }
  }

III. Further CAPTCHA Customization and Options

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