BotDetect ASP.NET WebForms CAPTCHA Integration Quickstart

1. Add a Reference to BotDetect and SQLite

The BotDetect.dll assemby is included in the BotDetect installation.

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.

2. Show a Captcha Challenge on the Form

On the ASP.NET form you want to protect against bots, add:
<%@ Register Assembly="BotDetect" Namespace="BotDetect.Web.UI" 
  TagPrefix="BotDetect" %>
  
  […]
  
<BotDetect:WebFormsSimpleCaptcha ID="ExampleCaptcha" runat="server" />
<asp:TextBox ID="CaptchaCodeTextBox" runat="server" />

3. Check User Input During Form Submission

When the form is submitted, the Captcha validation result must be checked:
if (IsPostBack)
{
    // validate the Captcha to check we're not dealing with a bot
    bool isHuman = ExampleCaptcha.Validate(CaptchaCodeTextBox.Text);
    
    CaptchaCodeTextBox.Text = null; // clear previous user input

    if (!isHuman)
    {
      // TODO: Captcha validation failed, show error message  
    }
    else
    {
      // TODO: Captcha validation passed, proceed with protected action  
    }
}

4. Configure Your ASP.NET Application

Update your application configuration (the web.config file):
<system.web>
  <httpHandlers>
    <!-- Register the HttpHandler used for BotDetect Simple API requests 
      requests -->
    <add verb="GET" path="BotDetectCaptcha.ashx"
      type="BotDetect.Web.SimpleCaptchaHandler, BotDetect"/>
  </httpHandlers>
</system.web>
<system.webServer>
  <validation validateIntegratedModeConfiguration="false"/>
  <handlers>
    <!-- Register the HttpHandler used for BotDetect Simple API requests 
      requests (IIS 7.0+) -->
    <remove name="BotDetectCaptchaHandler"/>
    <add name="BotDetectCaptchaHandler" preCondition="integratedMode" 
      verb="GET" path="BotDetectCaptcha.ashx"
      type="BotDetect.Web.SimpleCaptchaHandler, BotDetect"/>
  </handlers>
</system.webServer>

5. 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>

In-Depth ASP.NET WebForms CAPTCHA Instructions and Explanations

Detailed ASP.NET WebForms Captcha Simple API instructions and explanations can be found in the ASP.NET WebForms Captcha Simple API integration how to guide.

Other BotDetect ASP.NET CAPTCHA Quickstarts

ASP.NET Web Pages CAPTCHA Simple API.

ASP.NET MVC CAPTCHA Simple API.