BotDetect ASP.NET WebForms CAPTCHA Integration Quickstart

1. Add a Reference to BotDetect

Run the following command in the Package Manager Console:

PM> Install-Package Captcha

After the command execution, the references to the BotDetect.dll, BotDetect.Web.MVC.dll, and System.Data.SQLite.dll assemblies will be added to your project.

If your project does not use the MVC, the BotDetect.Web.MVC.dll assembly reference can be safely removed from it.

If your project is not going to be using the Simple API, the System.Data.SQLite.dll assembly reference can be safely removed from it.

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:WebFormsCaptcha ID="ExampleCaptcha" runat="server" 
	UserInputID="CaptchaCodeTextBox" />
<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
      MvcCaptcha.ResetCaptcha("ExampleCaptcha");  
    }
}

4. Configure Your ASP.NET Application

Update your application configuration (the web.config file):
<system.web>
  <httpHandlers>
    <!-- Register the HttpHandler used for BotDetect Captcha 
      requests -->
    <add verb="GET" path="BotDetectCaptcha.ashx"
      type="BotDetect.Web.CaptchaHandler, BotDetect"/>
  </httpHandlers>
  <!-- Register a custom SessionIDManager for BotDetect Captcha 
    requests -->
  <sessionState mode="InProc" cookieless="AutoDetect" timeout="20" 
    sessionIDManagerType="BotDetect.Web.CustomSessionIdManager, BotDetect"/> 
</system.web>
<system.webServer>
  <validation validateIntegratedModeConfiguration="false"/>
  <handlers>
    <!-- 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"/>
  </handlers>
</system.webServer>

In-Depth ASP.NET WebForms CAPTCHA Instructions and Explanations

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

Other BotDetect ASP.NET CAPTCHA Quickstarts

ASP.NET Web Pages CAPTCHA.

ASP.NET MVC CAPTCHA.