BotDetect ASP.NET MVC 3 CAPTCHA Integration Quickstart

1. Add a Reference to BotDetect and SQLite

Both the BotDetect.dll and BotDetect.Web.Mvc.dll assemblies should be referenced. They are 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

In View code: import the BotDetect namespace, include BotDetect styles in page <head>, create a MvcSimpleCaptcha object and pass it to the SimpleCaptcha HtmlHelper:
@using BotDetect.Web.Mvc;


@{ MvcSimpleCaptcha exampleCaptcha = new MvcSimpleCaptcha("ExampleCaptcha"); }

3. Check User Input During Form Submission

Mark the protected Controller action with the SimpleCaptchaValidation attribute to include SimpleCaptcha validation in ModelState.IsValid checks:
using BotDetect.Web.Mvc;

[SimpleCaptchaValidation("CaptchaCode", "ExampleCaptcha", "Incorrect CAPTCHA code!")]
public ActionResult ExampleAction(ExampleModel model)
    if (!ModelState.IsValid)
      // TODO: SimpleCaptcha validation failed, show error message      
      // TODO: SimpleCaptcha validation passed, proceed with protected action


4. Configure Your ASP.NET Application

Exclude BotDetect paths from ASP.NET MVC Routing:
public static void RegisterRoutes(RouteCollection routes)

    // BotDetect requests must not be routed
      new { botdetect = @"(.*)BotDetectCaptcha\.ashx" });
Update your application configuration (the web.config file):
    <!-- Register the HttpHandler used for BotDetect Simple API 
      requests -->
    <add verb="GET" path="BotDetectCaptcha.ashx"
      type="BotDetect.Web.SimpleCaptchaHandler, BotDetect"/>

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

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=""



In-Depth ASP.NET MVC CAPTCHA Instructions and Explanations

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

Other BotDetect ASP.NET CAPTCHA Quickstarts


ASP.NET Web Pages Basic CAPTCHA.

Current BotDetect Versions