BotDetect CAPTCHA ASP.NET Integration & Deployment FAQ

This page answers frequently asked questions about BotDetect ASP.NET Captcha integration in various kinds of ASP.NET projects and deployment to common server configurations.

Table of Contents

Why does BotDetect Captcha require registering a HttpHandler in my ASP.NET project web.config?

We do not save generated image and sound files to the hard drive or reuse them in any way, but create them on-the-fly for security reasons.

An ASP.NET HttpHandler allows us to generate Captcha images and sounds which are unique and re-generated each time they are requested.

Also, dynamically generating binary files according to incoming Http requests is usually done with HttpHandlers.

I am trying to implement BotDetect Captcha and I see the example page references BotDetectCaptcha.ashx, but there is no such file in the downloaded zip. Can you help?

BotDetectCaptcha.ashx is not a physical file, but an ASP.NET HttpHandler.

If you followed the ASP.NET Captcha integration procedure and are having trouble displaying Captcha images, please refer to the Captcha HttpHandler troubleshooting steps.

I'm trying to add BotDetect Captcha to my ASP.NET form, but the Captcha image is missing. What can I do?

Here is a short BotDetect Captcha troubleshooting checklist that can help you:

If this doesn't help, you're going to need to debug the issue a bit to determine why exactly is the image missing.

  • You will need the exact Captcha image Url, which you can get by right-clicking the missing image element in IE and selecting Properties -> Address (URL). Alternatively, you can view the page source and search for BDC_CaptchaImage, then copy the src value of the <img> element. Image Url example:

  • Open a new browser tab, and paste the exact Captcha image Url into the address bar. When you try to access the image directly this way, you should get a more detailed error, and the details should point to the underlying cause.
  • If you get a 404 Not Found error, this means something is preventing correct handling of BotDetectCaptcha.ashx requests. For example, Url Routing could be modifying the request, in which case you should exclude BotDetectCaptcha.ashx paths from routing.
  • If you get a 500 Internal Server Error, you will need the full stack trace. If you only get a generic ASP.NET error page, you might have to temporarily set the <customErrors mode="Off" in web.config to see the stack trace.
  • If the stack trace is not helpful, contact our Support Department and we'll take a look at it for you.

Is BotDetect ASP.NET Captcha compatible with IIS 7? Everything works on IIS 6.0, but when I deploy my project to IIS 7, the Captcha image is missing.

Yes, BotDetect ASP.NET CAPTCHA works with IIS 7. If you are running ASP.NET in integrated mode, you need to add the following declaration to your project's web.config file:

  <validation validateIntegratedModeConfiguration="false" />
    <remove name="BotDetectCaptchaHandler"/>
    <add name="BotDetectCaptchaHandler" 
      verb="GET" path="BotDetectCaptcha.ashx"
      type="BotDetect.Web.CaptchaHandler, BotDetect"/>

I'm trying to add BotDetect Captcha protection to my Login.aspx page, presented to the user before he is authenticated. However, the Captcha image fails to display for non-authenticated users. I am using Forms Authentication, so I cannot use your example web.config file as is.

You need to disable authorization checks for BotDetect Captcha requests. Adding the following declaration to the <configuration> section of your web.config will solve the problem:

<location path="BotDetectCaptcha.ashx">
      <allow users="*"/>

I'm trying to integrate BotDetect Captcha in my project, but the HttpHandler registration doesn't seem to work with Url Rewriting. Is there a way around this?

The simplest workaround for the issue is to avoid rewriting BotDetect paths (BotDetectCaptcha.ashx) altogether. I'm assuming you are rewriting paths so pages have more user-friendly names – but Captcha images and sounds won't have user-friendly paths anyway.

Depending on the rewriting module you use, there should be a way to specify a list of exceptions (paths that will not be rewritten).

For example, if you're using IIS 7 Url Rewriting, you will just have to exclude BotDetectCaptcha.ashx paths from the URL Rewriting rules, as described under "Prevent Rewriting of Requests for ASP.NET Web Resources" at URL Rewriting for ASP.NET Web Forms:

<!--  The following condition prevents rule from rewriting 
  requests to BotDetectCaptcha.ashx -->
<add input="{URL}" negate="true" pattern="BotDetectCaptcha\.ashx$" />

Can I change the handler path used for BotDetect Captcha requests?

Yes, the BotDetect HttpHandler path can be customized in the <botDetect> configuration section. if you don't have that section already registered, you'll have to add it first:

  <!-- Register the BotDetect configuration section -->
  <section name="botDetect" requirePermission="false" 
    type="BotDetect.Configuration.BotDetectConfigurationSection, BotDetect"/>

  <!-- ... other config sections ... -->


Then you can then use the captchaUrls element to specify your custom path:

  <captchaUrls requestPath="TodoCaptchaCustomPath.ashx"/>

  <!-- ... other BotDetect settings ... -->


Of course, you will then have to change the paths used for HttpHandler registration to match this setting.

You can customize both the filename and extension used for Captcha requests. Please keep in mind that if you use an extension which is not processed by the ASP.NET runtime by default, you will also have to update your IIS configuration, mapping the custom extension to the ASP.NET runtime in your application.

Does BotDetect Captcha work with ASP.NET MVC? Can BotDetect Captcha protection be added to Razor Views?

Yes, BotDetect Captcha is compatible with ASP.NET MVC, and includes required classes in the BotDetect.Web.Mvc.dll assembly. Both "regular" .aspx Views and Razor Views are supported. Please check the BotDetect ASP.NET MVC integration how to guide for instructions, and the BotDetect Captcha ASP.NET MVC integration code examples for example code.

I'm trying to add BotDetect to my ASP.NET MVC application, but I'm getting "Could not load file or assembly 'System.Web.Mvc, Version=, Culture=neutral, PublicKeyToken=31bf3856ad364e35' or one of its dependencies. The located assembly's manifest definition does not match the assembly reference." errors when I try to run it. Your component seems to be referencing an older version of ASP.NET MVC, which is not installed on my system.

The BotDetect ASP.NET MVC compatibility code contained in the BotDetect.Web.Mvc.dll assembly is identical for all versions of ASP.NET MVC. Referencing the older version of ASP.NET MVC assemblies allows the BotDetect assembly to work in the broadest set of applications without requiring recompilation of identical code for different ASP.NET MVC version numbers.

In case you need to deploy it to an environment which only has a newer version of ASP.NET MVC installed, you can simply resolve this error by adding a binding redirect to your application's main web.config file:

    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
        <assemblyIdentity name="System.Web.Mvc" 
          publicKeyToken="31bf3856ad364e35" />
        <bindingRedirect oldVersion="" 
          newVersion="" />

Your ASP.NET MVC integration instructions start by adding a CaptchaCode field to a Model class, which conflicts with our requirements. Can we add BotDetect Captcha protection to a Controller action without adding any fields to the Model declarations?

Yes, BotDetect Captcha protection can easily be added to ASP.NET MVC projects even without adding Model fields. A Model field is added in the integration instructions and code examples for the sake of simplicity, but is by no means necessary.

To add BotDetect Captcha to a Controller action without a Model field, make the following adjustments to the example code:


Instead of adding Captcha protection referencing the Model field:

<div class="editor-label">
    @Html.LabelFor(m => m.CaptchaCode)
<div class="editor-field">
    @Html.TextBoxFor(m => m.CaptchaCode)
    @Html.ValidationMessageFor(m => m.CaptchaCode)

create the required elements explicitly instead:

<div class="editor-label">
    @Html.Label("Retype the code from the picture")
<div class="editor-field">


Instead of relying on Model validation to automatically set the Model state based on the Captcha validation result:

[CaptchaValidation("CaptchaCode", "RegistrationCaptcha", "Incorrect code!")]
public ActionResult Register(RegisterModel model)
    if (ModelState.IsValid)

use an additional action parameter and make the validation logic explicit:

[CaptchaValidation("CaptchaCode", "RegistrationCaptcha", "Incorrect code!")]
public ActionResult Register(RegisterModel model, bool captchaValid)
    if (ModelState.IsValid && captchaValid)

How do I use localized Captcha validation error messages from ASP.NET MVC application resources? If I use [CaptchaValidation("Captcha", "RegistrationCaptcha", Resources.Error.CaptchaMismatch)], I get "An attribute argument must be a constant expression, typeof expression or array creation expression of an attribute parameter type" errors.

A possible workaround would be to create a sub-class of the CaptchaValidationAttribute in your application, which sets the error message to the localized value. For example:

[AttributeUsage(AttributeTargets.Method, AllowMultiple = false,Inherited = false)]
  public class LocalizedCaptchaValidationAttribute :
      public LocalizedCaptchaValidationAttribute(string inputfield, string captchaId)
          : base(inputfield, captchaId, Resources.Error.CaptchaMismatch)

and then, instead of:

[CaptchaValidation("Captcha", "RegistrationCaptcha", Resources.Error.CaptchaMismatch)]


[LocalizedCaptchaValidation("CaptchaCode", "RegistrationCaptcha")]

I've chosen the "Deploy to IIS" option during BotDetect installation, but the examples weren't deployed to IIS. Why?

Please check is IIS scripting enabled on the machine where you ran the setup package. You can do this in Control Panel, looking at the Programs and Features -> Turn Windows features on or off -> Internet Information Services -> Web Management Tools -> IIS Management Scripts and Tools option. It must be enabled before the BotDetect installation can deploy packaged examples to local IIS.

Are there any additional steps I need to do when upgrading the component to a newer version? When I update the BotDetect.dll assembly in my project to the new release, I get a "The located assembly's manifest definition does not match the assembly reference" runtime error.

  • If you are using BotDetect Captcha in an ASP.NET Web Application project or an ASP.NET MVC Web Application project (as opposed to an ASP.NET Web Site), you will have to recompile your project with the new version of the BotDetect.dll assembly, and deploy the updated build.
  • If you are using the BotDetect Captcha logging utility to track BotDetect errors or Captcha validation attempts, you will also have to update the BotDetect.Troubleshooting.dll assembly to the newest version.
  • If you reference the BotDetect.dll assembly with the full version number and PublicKeyToken (in your web.config file or an @Register directive for example), you will have to update these values to match the new release.

My host no longer permits Full Trust security levels. Does BotDetect Captcha run in ASP.NET Medium Trust?

Yes, BotDetect runs in both ASP.NET Medium Trust and ASP.NET Minimal Trust.

The only possible complication is if you want to load BotDetect pronunciation sound packages from a central location, to avoid copying .bdsp files to every ASP.NET application on the server. Since lower trust levels restrict application FileIOPermissions, trying to read sound packages from another location could produce security exceptions.

To resolve this in Medium Trust, you can modify the Medium Trust configuration to also be able to access the shared BotDetect sounds folder. You can see an example of such a modification in the web_mediumtrust.config file located in the Config folder included in the BotDetect installation.

In Minimal Trust (or if you don't have permission to edit the Medium Trust configuration), you can just reference BotDetect assemblies from the GAC. Assemblies loaded from GAC can have Full Trust permissions even when the ASP.NET application is running a lower trust level.