How To Deploy BotDetect ASP.NET CAPTCHA Globally on a Server (BotDetect v3.0; deprecated)

The usual BotDetect ASP.NET Captcha deployment procedure involves copying the BotDetect assembly and pronunciation sound packages to the Bin folder of each ASP.NET application using BotDetect Captcha protection. If you have multiple applications using BotDetect running on the same server, there are two levels of global deployment available:

GAC Deployment

Instead of copying the BotDetect assembly to each application's Bin folder, it can be kept in the Global Assembly Cache. This will also affect how you reference BotDetect from your application configuration.

Step 1: Add the BotDetect Assembly to the GAC

Note that after following the outlined steps, the BotDetect.dll assembly must not be copied to any individual application's Bin folder, otherwise an error about duplicate declarations will be thrown. So if you deployed it to a particular application's Bin folder, please remove it first.

.NET 2.0 and .NET 3.5

  • From the Control Panel, choose Administrative Tools > Microsoft .NET Framework 2.0 Configuration > Manage the Assembly Cache > Add an Assembly to the Assembly Cache
  • Browse to the BotDetect Captcha installation folder: C:\Program Files\Lanapsoft\BotDetect 3 CAPTCHA Component\Asp.Net\v2.0\BotDetect.dll. The .NET 2.0 and 3.5 base BotDetect assemblies are identical, so you can use either one.

Alternatively, if you have the .NET 2.0 SDK on the server, you can also use the command line gacutil utility, for example:

"c:\Program Files\Microsoft Visual Studio 8\Sdk\v2.0\bin\gacutil.exe" 
  /nologo /if BotDetect.dll

.NET 4.0

  • For .NET 4.0, you will have the use the gacutil command line utility from the .NET 4.0 SDK, since there appears to be no GUI-based GAC management available.
  • The assembly you'll use will also be different: C:\Program Files\Lanapsoft\BotDetect 3 CAPTCHA Component\Asp.Net\v4.0\BotDetect.dll.

[back to the top of the page]

Step 2: Load BotDetect Sound Packages From a Global Location

Since BotDetect 3 Captcha sounds also require pronunciation sound package files for the locales you want to support, they also have to be accessible to all ASP.NET applications you will use BotDetect in.

The .NET GAC only manages assemblies, so it can't help us with the .bdsp files. Fortunately, it's quite easy to configure your ASP.NET application to read these files from a central location.

  • Find the sound package folder in the BotDetect installation (C:\Program Files\Lanapsoft\BotDetect 3 CAPTCHA Component\Asp.Net\BotDetectSounds), or copy it to a location you want all applications to access.
  • Make sure this folder can be accessed by the user account the IIS worker process is using. The BotDetect installation should do this automatically, and you can grant all users generic read permissions by running: 
    cacls BotDetectSounds /G "Users":R /E /C /T
    Of course, you can also give read permissions only to those user accounts which will be running the actual ASP.NET applications using BotDetect Captcha.
  • Register the <botDetect> configuration section in your applications' web.config files: 
    <configuration>
  <configSections>
    <!-- Register the BotDetect configuration section -->
    <section name="botDetect" requirePermission="false" 
      type="BotDetect.Configuration.BotDetectConfigurationSection, 
        BotDetect, Version=3.0.16.0, Culture=neutral, 
        PublicKeyToken=74616036388b765f" />
  • Set the sound package folder in BotDetect settings: 
    <botDetect>
  <captchaSound enabled="true">
    <soundPackages folderPath="C:\Program Files\Lanapsoft\
      BotDetect 3 CAPTCHA Component\Asp.Net\BotDetectSounds" />

[back to the top of the page]

Step 3: Update the BotDetect HttpHandler Registration

Since the BotDetect assembly will be loaded from the GAC, all references to BotDetect types (including the Captcha HttpHandler) must use fully-qualified type names.

IIS 6.0

Change the BotDetect Captcha handler registration in your application's web.config file from 
<add verb="*" path="BotDetectCaptcha.ashx" 
  type="BotDetect.Web.CaptchaHandler, BotDetect"/>
to 
<add verb="*" path="BotDetectCaptcha.ashx" 
  type="BotDetect.Web.CaptchaHandler, BotDetect, 
    Version=3.0.16.0, Culture=neutral, PublicKeyToken=74616036388b765f"
/>

IIS 7.x

Change the BotDetect Captcha handler IIS 7.x registration in your application's web.config file from 
<add name="BotDetectCaptchaHandler" preCondition="integratedMode" 
  verb="GET" path="BotDetectCaptcha.ashx" 
  type="BotDetect.Web.CaptchaHandler, BotDetect"/>
to 
<add name="BotDetectCaptchaHandler" preCondition="integratedMode" 
  verb="GET" path="BotDetectCaptcha.ashx" 
  type="BotDetect.Web.CaptchaHandler, BotDetect, 
    Version=3.0.16.0, Culture=neutral, PublicKeyToken=74616036388b765f"
/>

[back to the top of the page]

Step 4: Update the CustomSessionIDManager Registration

Change the BotDetect Captcha CustomSessionIDManager registration in your application's web.config file from 
<sessionState mode="InProc" cookieless="AutoDetect" timeout="20"
  sessionIDManagerType="BotDetect.Web.CustomSessionIdManager, 
    BotDetect" />
to 
<sessionState mode="InProc" cookieless="AutoDetect" timeout="20"
  sessionIDManagerType="BotDetect.Web.CustomSessionIdManager, 
    BotDetect, Version=3.0.16.0, Culture=neutral,
    PublicKeyToken=74616036388b765f" 
/>

When you make these changes, your applications will no longer require copying the BotDetect assembly and sound package files for the Captcha protection to work.

[back to the top of the page]

Global Server Configuration

If you have many ASP.NET applications, adding the required BotDetect Captcha HttpHandler registration and other elements to each application can be a lot of work.

Fortunately, it is also possible to make all necessary changes in the global server configuration, allowing all applications to use BotDetect Captcha with a one-time configuration setup per server (instead of once per application).

The exact steps will depend on the .NET and IIS versions you are running. You can see an example of needed modifications in the web_global.config file located in the Config folder included in the BotDetect installation. To keep things simple, we'll only show the .NET 2.0 + IIS 6.0 configuration steps here, and assume BotDetect version 3.0.0.

Start by deploying BotDetect to the GAC.

Step 1. Locate and Backup the Global ASP.NET Configuration File

Global ASP.NET 2.0 configuration is located at %windir%\Microsoft.NET\Framework\v2.0.50727\CONFIG\web.config on each server.

Before making any changes to this file, please make a backup copy you can revert to if there are any problems – if some default configuration elements get accidentally corrupted, it will affect all ASP.NET websites on the server.

Similar to editing the Windows Registry, there is a very small chance that such a problem will occur, but the potential impact of errors is serious, so it's better to make all reasonable precautions.

[back to the top of the page]

Step 2. Add the Global BotDetect Assembly Reference

  • Locate the <system.web> -> <compilation> -> <assemblies> section of the global web.config file.
  • Look for the <add assembly="*" /> line
  • Add the following BotDetect assembly reference just above that line: 
    <add assembly="BotDetect, Version=3.0.16.0, Culture=neutral, 
  PublicKeyToken=74616036388b765f" />
  • Locate the <system.web> -> <pages> -> <namespaces> section
  • Add the following lines to its bottom (just before the closing </namespaces> tag): 
    <add namespace="BotDetect" />
<add namespace="BotDetect.Web" />
<add namespace="BotDetect.Web.UI" />
This will ensure that you don't have to add a reference to BotDetect in every application, and that you can use BotDetect namespace members in all page code.

[back to the top of the page]

Step 3. Register the Global BotDetect Configuration Section

  • Register the <botDetect> configuration section, just below the root configuration element: 
    <configuration>
<configSections>
<!-- Register the BotDetect configuration section -->
  <section name="botDetect" requirePermission="false" 
    type="BotDetect.Configuration.BotDetectConfigurationSection, 
      BotDetect, Version=3.0.16.0, Culture=neutral, 
      PublicKeyToken=74616036388b765f" />
</configSections>

[back to the top of the page]

Step 4. Specify the Global BotDetect Sound Package Location

You can skip this step if you plan to disable Captcha sounds in all your websites. Otherwise, it is needed to load BotDetect pronunciation sound packages from a central location.

  • Create the <botDetect> section just below the closing </configSections> element: 
    <botDetect>
  <captchaSound enabled="true">
    <soundPackages folderPath="C:\Program Files\Lanapsoft\
      BotDetect 3 CAPTCHA Component\Asp.Net\BotDetectSounds" />
  </captchaSound>
</botDetect>

[back to the top of the page]

Step 5. Register the Global BotDetect Captcha HttpHandler

  • Locate the <system.web> -> <httpHandlers> section of the global web.config file.
  • Look for the <add path="*.ashx" verb="*" type="System.Web.UI.SimpleHandlerFactory" validate="True" /> line registering the base .ashx handler.
  • Add the following BotDetect handler registration just above that line: 
    <add path="BotDetectCaptcha.ashx" verb="GET" 
  type="BotDetect.Web.CaptchaHandler, BotDetect, Version=3.0.16.0,
    Culture=neutral, PublicKeyToken=74616036388b765f" />

After you make this change, you should also remove any BotDetect handler registrations from individual application web.config files to avoid duplicate declarations.

[back to the top of the page]

Step 6. Register the Global BotDetect Custom SessionIDManagerType

You can skip this step if you plan to disable Captcha sounds in all your websites. Otherwise, it is needed to ensure the Captcha sound works properly in all supported browsers (an optional but recommended improvement, as explained in the BotDetect FAQ).

  • In the <system.web> section of the global web.config file, locate the <sessionState> element if it exists, or add it if it doesn't.
  • Add the following attribute to the declaration: 
    sessionIDManagerType="BotDetect.Web.CustomSessionIdManager, 
  BotDetect, Version=3.0.16.0, Culture=neutral, 
  PublicKeyToken=74616036388b765f"
The most common resulting declaration would be: 
<sessionState mode="InProc" cookieless="AutoDetect" timeout="20" 
  sessionIDManagerType="BotDetect.Web.CustomSessionIdManager, 
    BotDetect, Version=3.0.16.0, Culture=neutral, 
    PublicKeyToken=74616036388b765f" />

If you want to use a different Session State mode or options, you can change any settings except the sessionIDManagerType – which must point to the BotDetect class as specified above.

[back to the top of the page]

Step 7. Register the Global BotDetect Captcha Control

  • Locate the <system.web> -> <pages> -> <controls> section
  • Add the following line to its bottom (just before the closing </controls> tag): 
    <add tagPrefix="BotDetect" namespace="BotDetect.Web.UI" 
  assembly="BotDetect, Version=3.0.16.0, Culture=neutral, 
    PublicKeyToken=74616036388b765f" />
This will ensure that you don't have to add the 
<%@ Register Assembly="BotDetect" Namespace="BotDetect.Web.UI" 
  TagPrefix="BotDetect" %>

directive to the top of every page you want to use BotDetect Captcha protection on, and you can simply use the control on all pages by adding a <BotDetect:Captcha> tag in the .aspx file.

If you added the Register directive to any pages before, please remove it since duplicate registrations will clash.

When you finish making these changes, BotDetect Captcha protection will be available in all ASP.NET applications running the configured .NET version on the server.

[back to the top of the page]


Please Note

The information on this page is out of date and applies to a deprecated version of BotDetect™ CAPTCHA (v3.0).

An up-to-date equivalent page for the latest BotDetect Captcha release (v4) is BotDetect v4 Captcha documentation index.

General information about the major improvements in the current BotDetect release can be found at the What's New in BotDetect v4.0 page.

© Captcha, Inc. 2004-2023. All rights reserved.

BotDetect, BotDetect CAPTCHA, Lanap, Lanap CAPTCHA, Lanap BotDetect, Lanap BotDetect CAPTCHA, Lanapsoft, Lanapsoft CAPTCHA, Lanapsoft BotDetect, Lanapsoft BotDetect CAPTCHA, and Lanap Software are trademarks of Captcha, Inc. All other product, brand, and company names are mentioned for identification purposes only and are trademarks or registered trademarks of their respective owners.

Captcha, Inc. -- formerly: Lanapsoft, Inc. / Lanap, Inc.