BotDetect ASP.NET MVC 5 CAPTCHA Integration Quickstart

C#
VB.NET

1. Add a Reference to BotDetect

Reference Nuget
Reference .DLL

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 is not going to be using the Simple API, the System.Data.SQLite.dll assembly reference can be safely removed from it.

Download the BotDetect ASP.NET CAPTCHA Generator archive. The root folder of the extracted archive is referred as the <BDC-DIR>.

The BotDetect binaries are located in:
<BDC-DIR>/v4.4.2/lgcy-on-lgcy/bin/ folder.

Copy the BotDetect.dll and BotDetect.Web.MVC.dll files to the /your-app-backend-folder/bin/ folder -- and then reference them in your project.

2. Show a Captcha Challenge on the Form

In View code: import the BotDetect namespace, include BotDetect styles in page <head>, create a MvcCaptcha object and pass it to the Captcha HtmlHelper:

@using BotDetect.Web.Mvc;

  […]

  <link href="@BotDetect.Web.CaptchaUrls.Absolute.LayoutStyleSheetUrl"
    rel="stylesheet" type="text/css" />
</head>

  […]

@{ MvcCaptcha exampleCaptcha = new MvcCaptcha("ExampleCaptcha"); 
exampleCaptcha.UserInputID = "CaptchaCode";}
@Html.Captcha(exampleCaptcha)
@Html.TextBox("CaptchaCode")

3. Check User Input During Form Submission

Using CaptchaValidationActionFilter Attribute
Using Validate method

Mark the protected Controller action with the CaptchaValidationActionFilter attribute to include Captcha validation in ModelState.IsValid checks:

using BotDetect.Web.Mvc;
  
  […]

[HttpPost]
[AllowAnonymous]
[CaptchaValidationActionFilter("CaptchaCode", "ExampleCaptcha", "Incorrect CAPTCHA code!")]
public ActionResult ExampleAction(ExampleModel model)
{
    if (!ModelState.IsValid)
    {  
      // TODO: Captcha validation failed, show error message      
    }  
    else
    {  
      // TODO: Captcha validation passed, proceed with protected action
      MvcCaptcha.ResetCaptcha("ExampleCaptcha");     
    }

Use the built-in Validate method of a MvcCaptcha instance.

In cases when a CaptchaControl instance is not available, use static Validate method of MvcCaptcha class.

using BotDetect.Web.Mvc;
  
  […]

[HttpPost]
[AllowAnonymous]
public ActionResult ExampleAction(ExampleModel model)
{
  // init mvcCaptcha instance with captchaId
    MvcCaptcha mvcCaptcha = new MvcCaptcha("ExampleCaptcha");

    // get user input value
    string userInput = HttpContext.Request.Form["CaptchaCode"];

    // get validatingInstanceId from HttpContext.Request.Form
    string validatingInstanceId = HttpContext.Request.Form[mvcCaptcha.ValidatingInstanceKey];

    // or get validatingInstanceId from above mvcCaptcha instance
    //string validatingInstanceId = mvcCaptcha.WebCaptcha.ValidatingInstanceId;

    // call the built-in Validate method from above MvcCaptcha instance.
    if (mvcCaptcha.Validate(userInput, validatingInstanceId))
    {
        // or you can use static Validate method of MvcCaptcha class 
  (i.e. MvcCaptcha.Validate("ExampleCaptcha", userInput, validatingInstanceId); )
        MvcCaptcha.ResetCaptcha("ExampleCaptcha");
    }
    else
    {
        ModelState.AddModelError("CaptchaCode", "Incorrect!");
    }
    return View(model);
  
}

4. Configure Your ASP.NET Application

Exclude BotDetect paths from ASP.NET MVC Routing:

public static void RegisterRoutes(RouteCollection routes)
{
    routes.IgnoreRoute("{resource}.axd/{*pathInfo}");

    // BotDetect requests must not be routed
    routes.IgnoreRoute("{*botdetect}", 
      new { botdetect = @"(.*)BotDetectCaptcha\.ashx" });

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>