BotDetect ASP.NET MVC 4 CAPTCHA Integration Quickstart

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  
    }

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

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)
#64;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

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.

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

Current BotDetect Versions

Popular Content

BotDetect Captcha Image Samples

BotDetect Audio Captcha Sound Samples