BotDetect ASP.NET MVC 4 CAPTCHA Integration Quickstart

documentation > asp.net captcha > asp.net mvc

Traditional API
Simple API (Experimental)

C#
VB.NET

ASPX
Razor

1. Add a Reference to BotDetect

Both the BotDetect.dll and BotDetect.Web.Mvc.dll assemblies should be referenced. They are included in the BotDetect installation.

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:

<%@ Import Namespace="BotDetect.Web.Mvc" %>

  […]

  <link href="<%: Url.Content("~/" + BotDetect.Web.CaptchaUrls.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 CaptchaValidation Attribute
Using Validate method

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

using BotDetect.Web.Mvc;
  
  […]

[HttpPost]
[AllowAnonymous]
[CaptchaValidation("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>
  <!-- make sure Session State is enabled -->
  <pages enableSessionState="true">
    <namespaces>
      <add namespace="System.Web.Mvc" />
      <add namespace="System.Web.Mvc.Ajax" />
      <add namespace="System.Web.Mvc.Html" />
      <add namespace="System.Web.Routing" />
    </namespaces>
  </pages>
  <!-- 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>

1. Add a Reference to BotDetect

Both the BotDetect.dll and BotDetect.Web.Mvc.dll assemblies should be referenced. They are included in the BotDetect installation.

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 CaptchaValidation Attribute
Using Validate method

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

using BotDetect.Web.Mvc;
  
  […]

[HttpPost]
[AllowAnonymous]
[CaptchaValidation("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>
  <!-- make sure Session State is enabled -->
  <pages enableSessionState="true">
    <namespaces>
      <add namespace="System.Web.Helpers" />
      <add namespace="System.Web.Mvc" />
      <add namespace="System.Web.Mvc.Ajax" />
      <add namespace="System.Web.Mvc.Html" />
      <add namespace="System.Web.Routing" />
      <add namespace="System.Web.WebPages" />
    </namespaces>
  </pages>
  <!-- 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>

ASPX
Razor

1. Add a Reference to BotDetect

Both the BotDetect.dll and BotDetect.Web.Mvc.dll assemblies should be referenced. They are included in the BotDetect installation.

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:

<%@ Import Namespace="BotDetect.Web.Mvc" %>

  […]

  <link href="<%: Url.Content("~/" + BotDetect.Web.CaptchaUrls.LayoutStyleSheetUrl) %>" 
  rel="stylesheet" type="text/css" />
</head>

  […]
<% Dim exampleCaptcha As MvcCaptcha = New MvcCaptcha("ExampleCaptcha")
exampleCaptcha.UserInputID = "CaptchaCode"%>
<%: Html.Captcha(exampleCaptcha) %>
<%: Html.TextBox("CaptchaCode") %>

3. Check User Input During Form Submission

Using CaptchaValidation Attribute
Using Validate method

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

Imports System.Web.Mvc
  
  […]

<HttpPost()> _
<CaptchaValidation("CaptchaCode", "ExampleCaptcha", "Incorrect CAPTCHA Code!")> _
Public Function Index(ByVal model As ExampleModel) As ActionResult
    If ModelState.IsValid Then
      ' 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.

Imports System.Web.Mvc
  
  […]

<HttpPost()> _
Public Function Index(ByVal model As ExampleModel) As ActionResult
	' init mvcCaptcha instance with captchaId
	Dim mvcCaptcha = New MvcCaptcha("ExampleCaptcha")

	' get user input value
	Dim userInput As String = HttpContext.Request.Form("CaptchaCode")

	' get validatingInstanceId from HttpContext.Request.Form
	Dim validatingInstanceId As String = HttpContext.Request.Form(mvcCaptcha.ValidatingInstanceKey)

	' or get validatingInstanceId from above mvcCaptcha instance
	' Dim validatingInstanceId As String = mvcCaptcha.WebCaptcha.ValidatingInstanceId

	' call the built-in Validate method from above MvcCaptcha instance.
	If (mvcCaptcha.Validate(userInput, validatingInstanceId)) Then

		' 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!")
	End If
	Return View(model)

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>
  <!-- make sure Session State is enabled -->
  <pages enableSessionState="true">
    <namespaces>
      <add namespace="System.Web.Mvc" />
      <add namespace="System.Web.Mvc.Ajax" />
      <add namespace="System.Web.Mvc.Html" />
      <add namespace="System.Web.Routing" />
    </namespaces>
  </pages>
  <!-- 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>

1. Add a Reference to BotDetect

Both the BotDetect.dll and BotDetect.Web.Mvc.dll assemblies should be referenced. They are included in the BotDetect installation.

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:

@Imports BotDetect.Web.Mvc

  […]

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

  […]
@Code Dim exampleCaptcha As MvcCaptcha = New MvcCaptcha("ExampleCaptcha")
exampleCaptcha.UserInputID = "CaptchaCode" End Code
@Html.Captcha(exampleCaptcha)
@Html.TextBox("CaptchaCode")

3. Check User Input During Form Submission

Using CaptchaValidation Attribute
Using Validate method

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

Imports System.Web.Mvc
  
  […]

<HttpPost()> _
<CaptchaValidation("CaptchaCode", "ExampleCaptcha", "Incorrect CAPTCHA Code!")> _
Public Function Index(ByVal model As ExampleModel) As ActionResult
    If ModelState.IsValid Then
      ' 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.

Imports System.Web.Mvc
  
  […]

<HttpPost()> _
Public Function Index(ByVal model As ExampleModel) As ActionResult
	' init mvcCaptcha instance with captchaId
	Dim mvcCaptcha = New MvcCaptcha("ExampleCaptcha")

	' get user input value
	Dim userInput As String = HttpContext.Request.Form("CaptchaCode")

	' get validatingInstanceId from HttpContext.Request.Form
	Dim validatingInstanceId As String = HttpContext.Request.Form(mvcCaptcha.ValidatingInstanceKey)

	' or get validatingInstanceId from above mvcCaptcha instance
	' Dim validatingInstanceId As String = mvcCaptcha.WebCaptcha.ValidatingInstanceId

	' call the built-in Validate method from above MvcCaptcha instance.
	If (mvcCaptcha.Validate(userInput, validatingInstanceId)) Then

		' 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!")
	End If
	Return View(model)

4. Configure Your ASP.NET Application

Exclude BotDetect paths from ASP.NET MVC Routing:

Public Shared Sub RegisterRoutes(ByVal routes As RouteCollection)
    routes.IgnoreRoute("{resource}.axd/{*pathInfo}")

    ' BotDetect requests must not be routed
    routes.IgnoreRoute("{*botdetect}", 
    New With {.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>
  <!-- make sure Session State is enabled -->
  <pages enableSessionState="true">
    <namespaces>
      <add namespace="System.Web.Helpers" />
      <add namespace="System.Web.Mvc" />
      <add namespace="System.Web.Mvc.Ajax" />
      <add namespace="System.Web.Mvc.Html" />
      <add namespace="System.Web.Routing" />
      <add namespace="System.Web.WebPages" />
    </namespaces>
  </pages>
  <!-- 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 MVC CAPTCHA Instructions and Explanations

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

Other BotDetect ASP.NET CAPTCHA Quickstarts

ASP.NET WebForms CAPTCHA.

ASP.NET Web Pages Basic CAPTCHA.

[back to top]

C#
VB.NET

ASPX
Razor

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:

<%@ Import Namespace="BotDetect.Web.Mvc" %>

  
<% MvcSimpleCaptcha exampleCaptcha = new MvcSimpleCaptcha("ExampleCaptcha"); %>
<%: Html.SimpleCaptcha(exampleCaptcha) %>
@Html.TextBox("CaptchaCode")

3. Check User Input During Form Submission

Using SimpleCaptchaValidation Attribute
Using Validate method

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

using BotDetect.Web.Mvc;
  
  […]

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

    }

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

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

using BotDetect.Web.Mvc;
  
  […]

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

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

    // get validatingCaptchaId from HttpContext.Request.Form
    string validatingCaptchaId = HttpContext.Request.Form[mvcCaptcha.ValidatingCaptchaIdKey];

    // or get validatingCaptchaId from above mvcCaptcha instance
    //string validatingCaptchaId = mvcCaptcha.WebCaptcha.ValidatingCaptchaId;

    // call the built-in Validate method from above MvcSimpleCaptcha instance.
    if (mvcCaptcha.Validate(userInput, validatingCaptchaId))
    {
        // or you can use static Validate method of MvcSimpleCaptcha class 
	(i.e. MvcSimpleCaptcha.Validate("ExampleCaptcha", userInput, validatingCaptchaId); )

    }
    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 Simple API 
      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 (IIS 7.0+) -->
    <remove name="BotDetectCaptchaHandler"/>
    <add name="BotDetectCaptchaHandler" preCondition="integratedMode" 
      verb="GET" path="BotDetectCaptcha.ashx"
      type="BotDetect.Web.SimpleCaptchaHandler, BotDetect"/>
  </handlers>
</system.webServer>

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"); }
@Html.SimpleCaptcha(exampleCaptcha)
@Html.TextBox("CaptchaCode")

3. Check User Input During Form Submission

Using SimpleCaptchaValidation Attribute
Using Validate method

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

using BotDetect.Web.Mvc;
  
  […]

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

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

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

using BotDetect.Web.Mvc;
  
  […]

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

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

    // get validatingCaptchaId from HttpContext.Request.Form
    string validatingCaptchaId = HttpContext.Request.Form[mvcCaptcha.ValidatingCaptchaIdKey];

    // or get validatingCaptchaId from above mvcCaptcha instance
    //string validatingCaptchaId = mvcCaptcha.WebCaptcha.ValidatingCaptchaId;

    // call the built-in Validate method from above MvcSimpleCaptcha instance.
    if (mvcCaptcha.Validate(userInput, validatingCaptchaId))
    {
        // or you can use static Validate method of MvcSimpleCaptcha class 
	(i.e. MvcSimpleCaptcha.Validate("ExampleCaptcha", userInput, validatingCaptchaId); )

    }
    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 Simple API 
      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 (IIS 7.0+) -->
    <remove name="BotDetectCaptchaHandler"/>
    <add name="BotDetectCaptchaHandler" preCondition="integratedMode" 
      verb="GET" path="BotDetectCaptcha.ashx"
      type="BotDetect.Web.SimpleCaptchaHandler, BotDetect"/>
  </handlers>
</system.webServer>

ASPX
Razor

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:

<%@ Import Namespace="BotDetect.Web.Mvc" %>

  
<% Dim exampleCaptcha As MvcSimpleCaptcha = New MvcSimpleCaptcha("ExampleCaptcha") %>
<%: Html.SimpleCaptcha(exampleCaptcha) %>
<%: Html.TextBox("CaptchaCode") %>

3. Check User Input During Form Submission

Using SimpleCaptchaValidation Attribute
Using Validate method

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

Imports System.Web.Mvc
  
  […]

<HttpPost()> _
<SimpleCaptchaValidation("CaptchaCode", "ExampleCaptcha", "Incorrect CAPTCHA Code!")> _
Public Function Index(ByVal model As ExampleModel) As ActionResult
    If ModelState.IsValid Then
      ' TODO: SimpleCaptcha validation failed, show error message      

    Else
      ' TODO: SimpleCaptcha validation passed, proceed with protected action

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

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

Imports System.Web.Mvc
  
  […]

<HttpPost()> _
Public Function Index(ByVal model As ExampleModel) As ActionResult
	' init mvcCaptcha instance with captchaStyleName
	Dim mvcCaptcha = New MvcSimpleCaptcha("ExampleCaptcha")

	' get user input value
	Dim userInput As String = HttpContext.Request.Form("CaptchaCode")

	' get validatingCaptchaId from HttpContext.Request.Form
	Dim validatingCaptchaId As String = HttpContext.Request.Form(mvcCaptcha.ValidatingCaptchaIdKey)

	' or get validatingCaptchaId from above mvcCaptcha instance
	' Dim validatingCaptchaId As String = mvcCaptcha.WebCaptcha.ValidatingCaptchaId

	' call the built-in Validate method from above MvcSimpleCaptcha instance.
	If (mvcCaptcha.Validate(userInput, validatingCaptchaId)) Then

		' or you can use static Validate method of MvcSimpleCaptcha class (i.e. MvcSimpleCaptcha.Validate("ExampleCaptcha", userInput, validatingCaptchaId); )


	Else

		ModelState.AddModelError("CaptchaCode", "Incorrect!")
	End If
	Return View(model)

Update your application configuration (the web.config file):

<system.web>
  <httpHandlers>
    <!-- Register the HttpHandler used for BotDetect Simple API 
      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 (IIS 7.0+) -->
    <remove name="BotDetectCaptchaHandler"/>
    <add name="BotDetectCaptchaHandler" preCondition="integratedMode" 
      verb="GET" path="BotDetectCaptcha.ashx"
      type="BotDetect.Web.SimpleCaptchaHandler, BotDetect"/>
  </handlers>
</system.webServer>

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:

@Imports BotDetect.Web.Mvc

  
@Code Dim exampleCaptcha As MvcSimpleCaptcha = New MvcSimpleCaptcha("ExampleCaptcha") End Code
@Html.SimpleCaptcha(exampleCaptcha)
@Html.TextBox("CaptchaCode")

3. Check User Input During Form Submission

Using SimpleCaptchaValidation Attribute
Using Validate method

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

Imports System.Web.Mvc
  
  […]

<HttpPost()> _
<SimpleCaptchaValidation("CaptchaCode", "ExampleCaptcha", "Incorrect CAPTCHA Code!")> _
Public Function Index(ByVal model As ExampleModel) As ActionResult
    If ModelState.IsValid Then
      ' TODO: SimpleCaptcha validation failed, show error message      

    Else
      ' TODO: SimpleCaptcha validation passed, proceed with protected action

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

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

Imports System.Web.Mvc
  
  […]

<HttpPost()> _
Public Function Index(ByVal model As ExampleModel) As ActionResult
	' init mvcCaptcha instance with captchaStyleName
	Dim mvcCaptcha = New MvcSimpleCaptcha("ExampleCaptcha")

	' get user input value
	Dim userInput As String = HttpContext.Request.Form("CaptchaCode")

	' get validatingCaptchaId from HttpContext.Request.Form
	Dim validatingCaptchaId As String = HttpContext.Request.Form(mvcCaptcha.ValidatingCaptchaIdKey)

	' or get validatingCaptchaId from above mvcCaptcha instance
	' Dim validatingCaptchaId As String = mvcCaptcha.WebCaptcha.ValidatingCaptchaId

	' call the built-in Validate method from above MvcSimpleCaptcha instance.
	If (mvcCaptcha.Validate(userInput, validatingCaptchaId)) Then

		' or you can use static Validate method of MvcSimpleCaptcha class (i.e. MvcSimpleCaptcha.Validate("ExampleCaptcha", userInput, validatingCaptchaId); )


	Else

		ModelState.AddModelError("CaptchaCode", "Incorrect!")
	End If
	Return View(model)

4. Configure Your ASP.NET Application

Exclude BotDetect paths from ASP.NET MVC Routing:

Public Shared Sub RegisterRoutes(ByVal routes As RouteCollection)
    routes.IgnoreRoute("{resource}.axd/{*pathInfo}")

    ' BotDetect requests must not be routed
    routes.IgnoreRoute("{*botdetect}", 
    New With {.botdetect = "(.*)BotDetectCaptcha\.ashx"})

Update your application configuration (the web.config file):

<system.web>
  <httpHandlers>
    <!-- Register the HttpHandler used for BotDetect Simple API 
      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 (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 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.

BotDetect ASP.NET MVC 4 CAPTCHA Integration Quickstart

1. Add a Reference to BotDetect

2. Show a Captcha Challenge on the Form

3. Check User Input During Form Submission

4. Configure Your ASP.NET Application

1. Add a Reference to BotDetect

2. Show a Captcha Challenge on the Form

3. Check User Input During Form Submission

4. Configure Your ASP.NET Application

1. Add a Reference to BotDetect

2. Show a Captcha Challenge on the Form

3. Check User Input During Form Submission

1. Add a Reference to BotDetect

2. Show a Captcha Challenge on the Form

3. Check User Input During Form Submission

4. Configure Your ASP.NET Application

In-Depth ASP.NET MVC CAPTCHA Instructions and Explanations

Other BotDetect ASP.NET CAPTCHA Quickstarts

1. Add a Reference to BotDetect and SQLite

2. Show a Captcha Challenge on the Form

3. Check User Input During Form Submission

4. Configure Your ASP.NET Application

1. Add a Reference to BotDetect and SQLite

2. Show a Captcha Challenge on the Form

3. Check User Input During Form Submission

4. Configure Your ASP.NET Application

1. Add a Reference to BotDetect and SQLite

2. Show a Captcha Challenge on the Form

3. Check User Input During Form Submission

1. Add a Reference to BotDetect and SQLite

2. Show a Captcha Challenge on the Form

3. Check User Input During Form Submission

4. Configure Your ASP.NET Application

5. Configure Captcha options

In-Depth ASP.NET MVC CAPTCHA Instructions and Explanations

Other BotDetect ASP.NET CAPTCHA Quickstarts

Current BotDetect Versions

Popular Content

BotDetect Captcha Image Samples

BotDetect Audio Captcha Sound Samples