BotDetect ASP.NET CAPTCHA Migration Guide

This page contains instructions for updating your BotDetect ASP.NET Captcha installation to newer versions, starting with BotDetect v3.0.0.

Table of Contents

Upgrading BotDetect ASP.NET CAPTCHA from v3.0.15 to v3.0.16

To take advantage of the v3.0.16 changes, you have to copy updated BotDetect assemblies to your server.

If you use BotDetect from the GAC or have registered any BotDetect elements (such as the BotDetect config section) using fully-qualified names, you should also update the assembly version number to 3.0.16.0.

Upgrading BotDetect ASP.NET CAPTCHA from v3.0.14 to v3.0.15

To take advantage of the v3.0.15 changes, you have to copy updated BotDetect assemblies to your server.

If you use BotDetect from the GAC or have registered any BotDetect elements (such as the BotDetect config section) using fully-qualified names, you should also update the assembly version number to 3.0.15.0.

The default Captcha code length has changed from 5 to randomly between 4 and 6 characters. If you use a fixed number of characters other than 5, consider also randomizing the code length for increased Captcha security.

Upgrading BotDetect ASP.NET CAPTCHA from v3.0.13 to v3.0.14

To take advantage of the v3.0.14 changes, you have to copy updated BotDetect assemblies to your server.

If you use BotDetect from the GAC or have registered any BotDetect elements (such as the BotDetect config section) using fully-qualified names, you should also update the assembly version number to 3.0.14.0.

Upgrading BotDetect ASP.NET CAPTCHA from v3.0.12 to v3.0.13

To take advantage of the v3.0.13 changes, you have to copy updated BotDetect assemblies to your server.

If you use BotDetect from the GAC or have registered any BotDetect elements (such as the BotDetect config section) using fully-qualified names, you should also update the assembly version number to 3.0.13.0.

Upgrading BotDetect ASP.NET CAPTCHA from v3.0.11 to v3.0.12

To take advantage of the v3.0.12 changes, you have to copy updated BotDetect assemblies to your server.

If you use BotDetect from the GAC or have registered any BotDetect elements (such as the BotDetect config section) using fully-qualified names, you should also update the assembly version number to 3.0.12.0.

If you're using BotDetect to protect an ASP.NET MVC form, note that you don't have to call the SaveSettings() method on the Captcha object anymore (it will be called automatically). Leaving the call in old code won't break anything, but simplifying it by removing unnecessary calls is recommended.

Upgrading BotDetect ASP.NET CAPTCHA from v3.0.10 to v3.0.11

To take advantage of the v3.0.11 changes, you have to copy updated BotDetect assemblies to your server.

If you use BotDetect from the GAC or have registered any BotDetect elements (such as the BotDetect config section) using fully-qualified names, you should also update the assembly version number to 3.0.11.0.

If you're also upgrading your applications to .NET 4.5, you should use the new .NET 4.5 BotDetect assemblies from the c:\Program Files (x86)\Lanapsoft\BotDetect 3 CAPTCHA Component\Asp.Net\v4.5\ folder.

Please note that automatic user input lowercasing has been replaced with automatic user input uppercasing in this release. If you were using any related configuration settings, you don't have to change them – the new code will automatically interpret them the same as the new ones.

Also note that Captcha help link behavior has been changed as well, with different new defaults and many additional options. You might need to adjust its settings if you want to keep it working as before.

Upgrading BotDetect ASP.NET CAPTCHA from v3.0.9 to v3.0.10

To take advantage of the v3.0.10 changes, you have to copy updated BotDetect assemblies to your server.

If you use BotDetect from the GAC or have registered any BotDetect elements (such as the BotDetect config section) using fully-qualified names, you should also update the assembly version number to 3.0.10.0.

Since the help link has been removed from Captcha images in this release, related configuration / customization options and the OnHelpLinkClick client-side event are no longer available.

If you were using the InputElement property of the client-side BotDetect object, please note that it has been replaced with the GetInputElement() function call to avoid circular references (and the possible memory leaks).

Upgrading BotDetect ASP.NET CAPTCHA from v3.0.8 to v3.0.9

To take advantage of the v3.0.9 changes, you have to copy updated BotDetect assemblies to your server.

If you use BotDetect from the GAC or have registered any BotDetect elements (such as the BotDetect config section) using fully-qualified names, you should also update the assembly version number to 3.0.9.0.

If you want to use the Chalkboard image style or the Dispatch sound style in your application, you should explicitly set them, since they are no longer the default values.

Upgrading BotDetect ASP.NET CAPTCHA from v3.0.7 to v3.0.8

To take advantage of the v3.0.8 changes, you have to copy updated BotDetect assemblies to your server.

If you use BotDetect from the GAC or have registered any BotDetect elements (such as the BotDetect config section) using fully-qualified names, you should also update the assembly version number to 3.0.9.0.

Upgrading BotDetect ASP.NET CAPTCHA from v3.0.6 to v3.0.7

To take advantage of the v3.0.7 changes, you have to copy updated BotDetect assemblies to your server.

If you use BotDetect from the GAC or have registered any BotDetect elements (such as the BotDetect config section) using fully-qualified names, you should also update the assembly version number to 3.0.7.0.

Upgrading BotDetect ASP.NET CAPTCHA from v3.0.5 to v3.0.6

To take advantage of the v3.0.6 changes, you have to copy updated BotDetect assemblies to your server.

If you use BotDetect from the GAC or have registered any BotDetect elements (such as the BotDetect config section) using fully-qualified names, you should also update the assembly version number to 3.0.7.0.

ASP.NET MVC CAPTCHA Implementation

If you are using BotDetect in ASP.NET MVC applications, you should note that the [CaptchaValidation] Attribute has been significantly changed in v3.0.6. While the new implementation should be backwards-compatible, it's recommended to upgrade your application code to take advantage of the improvements made.

Most significantly, instead of checking RouteData and manually adding ModelState errors when Captcha validation fails, the [CaptchaValidation] Attribute can now automatically add the error if configured correctly, significantly simplifying Captcha validation code.

You can see how this simplification affects your application code in the new ASP.NET MVC Captcha How To guide and the new ASP.NET MVC Captcha code samples included in v3.0.6 BotDetect installations.

Upgrading BotDetect ASP.NET CAPTCHA from v3.0.4 to v3.0.5

To take advantage of the v3.0.5 changes, you have to copy updated BotDetect assemblies to your server.

If you use BotDetect from the GAC or have registered any BotDetect elements (such as the BotDetect config section) using fully-qualified names, you should also update the assembly version number to 3.0.5.0.

If you use Polish sounds, you should also update the Pronunciation_Polish_PL.bdsp sound package to the newest version available at the Polish Captcha localization page.

Upgrading BotDetect ASP.NET CAPTCHA from v3.0.3 to v3.0.4

To take advantage of the v3.0.4 changes, you have to copy updated BotDetect assemblies to your server.

If you use BotDetect from the GAC or have registered any BotDetect elements (such as the BotDetect config section) using fully-qualified names, you should also update the assembly version number to 3.0.4.0.

Upgrading BotDetect ASP.NET CAPTCHA from v3.0.2 to v3.0.3

To take advantage of the v3.0.3 changes, you have to copy updated BotDetect assemblies to your server.

If you use BotDetect from the GAC or have registered any BotDetect elements (such as the BotDetect config section) using fully-qualified names, you should also update the assembly version number to 3.0.3.0.

Considering the changes in Captcha drawing styles and default BotDetect Css style declarations, it's recommended to also review your Captcha-protected pages to make sure the changes stll fit.

Upgrading BotDetect ASP.NET CAPTCHA from v3.0.1 to v3.0.2

To take advantage of the v3.0.2 changes, you just have to copy updated BotDetect assemblies to your server.

If you use BotDetect from the GAC or have registered any BotDetect elements (such as the BotDetect config section) using fully-qualified names, you should also update the assembly version number to 3.0.2.0.

Upgrading BotDetect ASP.NET CAPTCHA from v3.0.0 to v3.0.1

To take advantage of the v3.0.1 changes, you just have to copy updated BotDetect assemblies to your server.

If you use BotDetect from the GAC or have registered any BotDetect elements (such as the BotDetect config section) using fully-qualified names, you should update the assembly version number to 3.0.1.0.

If you use Canadian French or Mexican Spanish Captcha sounds, you should also update the Pronunciation_French_CA.bdsp and Pronunciation_Spanish_MX.bdsp sound packages to the newest version.

Upgrading BotDetect ASP.NET CAPTCHA from v2.0.15 to v3.0.0

Version 3.0.0 is a major new release of BotDetect ASP.NET CAPTCHA, with many significant improvements (also: v3.0.0 release notes). To make these improvements possible, we had to make some significant changes in the component, and BotDetect 3 is NOT backwards compatible with older BotDetect releases.

We are aware this makes upgrading non-trivial, and we tried to make it as straightforward as possible. We feel that the improvements made more than justify the small upgrading effort required. Besides, a new major release allowed us to clean up many details accumulated during 4 years of BotDetect v2.0 lifetime, which we couldn't change precisely because we wanted all v2.0 releases to be 100% backward compatible.

So please follow this migration guide carefully, and you'll be running the latest version of BotDetect Captcha in no time.

BotDetect CAPTCHA v3.0.0 Assemblies

  • The main BotDetect Captcha assembly is now called BotDetect.dll instead of Lanap.BotDetect.dll
  • The BotDetect Troubleshooting assembly is now called BotDetect.Troubleshooting.dll instead of Lanap.BotDetect.Troubleshooting.dll
  • The ASP.NET MVC Captcha control is now separated into a new assembly, BotDetect.Web.UI.Mvc.dll (both the MVC Captcha and the base Captcha assembly must be reference by ASP.NET MVC projects)

BotDetect CAPTCHA v3.0.0 Sound Packages

BotDetect 3 Captcha sounds also require pronunciation sound packages for the locales your application supports. The .bdsp (BotDetect Sound Package) files should be copied to the Bin\BotDetectSounds folder in your application.

Sound package files separate from the main assembly allow you to download and deploy only the sound files for the locales you will actually use. Embedding sound files (as BotDetect 2 did) for all the locales we want to support would make the assembly grow to possibly hundreds of megabytes, so it's not a feasible option for BotDetect 3.

Default sound packages (for North America locales) are located in the C:\Program Files (x86)\Lanapsoft\BotDetect 3 CAPTCHA Component\Asp.Net\BotDetectSounds folder. Additional sound packages for other locales can be found at the BotDetect localizations download page.

For default English Captcha sounds, you would copy
C:\Program Files\Lanapsoft\BotDetect 3 CAPTCHA Component\Asp.Net\
  BotDetectSounds\Pronunciation_English_US.bdsp
to
<TODO:ApplicationFolder>\Bin\BotDetectSounds\Pronunciation_English_US.bdsp

BotDetect CAPTCHA v3.0.0 Web.config HttpHandler Registration

Old BotDetect 2 syntax:
<system.web>
  <httpHandlers>
    <add verb="*" path="LanapCaptcha.aspx"
      type="Lanap.BotDetect.CaptchaHandler, Lanap.BotDetect"/>

  ...

<system.webServer>
  <handlers>
    <remove name="LanapCaptchaHandler"/>
    <add name="LanapCaptchaHandler" preCondition="integratedMode"
      verb="*" path="LanapCaptcha.aspx"
      type="Lanap.BotDetect.CaptchaHandler, Lanap.BotDetect"/>
New BotDetect 3 syntax:
<system.web>
  <httpHandlers>
    <!-- Register the HttpHandler used for BotDetect
      Captcha requests -->
    <add verb="GET" path="BotDetectCaptcha.ashx"
      type="BotDetect.Web.CaptchaHandler, BotDetect"/>

  ...

<system.webServer>
  <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"/>

BotDetect CAPTCHA v3.0.0 Web.config Session State Configuration

Old BotDetect 2 syntax:
<sessionState mode="InProc" cookieless="AutoDetect" timeout="20"
  sessionIDManagerType="
    Lanap.BotDetect.Persistence.CustomSessionIDManager,
    Lanap.BotDetect"/>
New BotDetect 3 syntax:
<!-- Register a custom SessionIDManager for
  BotDetect Captcha requests -->
<sessionState mode="InProc" cookieless="UseCookies" timeout="20"
  sessionIDManagerType="BotDetect.Web.CustomSessionIdManager,
    BotDetect"/>

BotDetect CAPTCHA v3.0.0 Web.config TagPrefix Registration

This is a small utility improvement, allowing you to register the BotDetect control TagPrefix globally in your application, so you don't have to add <%@ Register directives at the top of every page using BotDetect.
<!-- Session state is required for BotDetect storage;
  you can also turn if off globally and only enable for
  BotDetect-protected pages if you prefer -->
    <pages enableSessionState="true">
      <controls>
        <!-- Register the BotDetect tag prefix for easier use
          in all pages -->
        <add assembly="BotDetect" namespace="BotDetect.Web.UI"
          tagPrefix="BotDetect"/>

BotDetect CAPTCHA v3.0.0 Web.config Customizations

The old <appSettings> Captcha overrides have been moved to a new BotDetect configuration section (which also contains many new customization options). You can see the available options in the Captcha Customization code sample coming with the BotDetect 3 installation. The configuration section should first be registered:
<configSections>
  <!-- Register the BotDetect configuration section -->
  <section name="botDetect" requirePermission="false"
    type="BotDetect.Configuration.BotDetectConfigurationSection,
      BotDetect"/>
The old settings should then be migrated from <appSettings> to <botDetect>:
  • LBD_RequestPath becomes
    <captchaUrls requestPath="CaptchaCustomPath.ashx"/>
  • LBD_AllowedRepeatedRequests becomes
    <captchaRequestFilter enabled="true" allowedRepeatedRequests="3"/>
  • LBD_SessionIdEncryptionKey becomes
    <captchaEncryption encryptionPassword="SecretEncryptionPassword"/>

BotDetect CAPTCHA v3.0.0 Interface Naming

  • CodeType has been renamed to CodeStyle
  • CodeType.AlphaNumeric has been renamed to CodeStyle.Alphanumeric
  • TextStyle has been renamed to ImageStyle (also note that the Captcha sound algorithm property is called SoundStyle, so all properties are named consistently)
  • TextStyle.FingerPrints has been renamed to ImageStyle.Fingerprints
  • TextStyle.Spiderweb has been renamed to ImageStyle.SpiderWeb
  • TextStyle.SunRays has been renamed to ImageStyle.Sunrays
  • TextStyle.SunRays2 has been renamed to ImageStyle.Sunrays2

You can see all important BotDetect enumerations and their members at the new BotDetect enumerations reference page.

BotDetect CAPTCHA v3.0.0 Events

The BotDetect event system has been rewritten, with a number of new Captcha events being available in BotDetect 3, and exposing more data through the event arguments. The events are:

  • Captcha.InitializedCaptchaControl
  • Captcha.GeneratingCaptchaCode
  • Captcha.GeneratedCaptchaCode
  • Captcha.GeneratingCaptchaImage
  • Captcha.GeneratedCaptchaImage
  • Captcha.GeneratingCaptchaSound
  • Captcha.GeneratedCaptchaSound
  • Captcha.ValidatingUserInput
  • Captcha.ValidatedUserInput

The change that affects code using BotDetect 2 the most is that Captcha property randomization is now done in the Captcha.InitializedCaptchaControl event, instead of the old Captcha.PreDrawCaptchaImage event. You can see this change in the Captcha Randomization code sample coming with the BotDetect 3 installation.

BotDetect CAPTCHA v3.0.0 Randomization

Besides using a different Captcha event to specify the randomized properties (as mentioned above), BotDetect 3 also integrates the old RandomizationHelper functionality into the component itself. So for example, while you would randomize BotDetect 2 by using:
captcha.CodeLength = RandomizationHelper.GetRandomCodeLength(4, 6);
You can do the same in BotDetect 3 even without including RandomizationHelper in your project using the new CaptchaRandomization class from the root BotDetect namespace:
captcha.CodeLength = CaptchaRandomization.GetRandomCodeLength(4, 6);

BotDetect CAPTCHA v3.0.0 Client-side

BotDetect 3 includes a number of client-side improvements related to the user input textbox. To take advantage of this new functionality (automatic user input lowercasing and input field focusing on Captcha reload and sound icon clicks, for example), you should specify your Captcha code user input client ID on each page load:
SampleCaptcha.UserInputClientID = CaptchaCodeTextBox.ClientID;
Also, a new client-side event system has been implemented, allowing you to specify your own client-side handlers for certain BotDetect actions. The events available are:
  • BotDetect.PostInit
  • BotDetect.PreReloadImage
  • BotDetect.PostReloadImage
  • BotDetect.PrePlaySound
  • BotDetect.PreAjaxValidate
  • BotDetect.AjaxValidationFailed
  • BotDetect.AjaxValidationPassed
  • BotDetect.AjaxValidationError

The last four events are related to the new Ajax Captcha validation functionality, which works independently from any Ajax frameworks (ASP.NET Ajax or 3rd party solutions). If you are interested, you can see how it works in the ASP.NET built-in Ajax Captcha validation code sample coming with BotDetect 3 installations.

Keep in mind that some changes that required custom client-side event handling are now included in base component functionality (for example, the above mentioned automatic user input lowercasing). If you have any code using the old client-side events for custom behavior, first review how the functionality fits with the new BotDetect 3 client-side logic.

For example (as also shown in the Captcha Customization code sample), you would add your handler to the BotDetect.PostReloadImage client-side event by using:
BotDetect.RegisterCustomHandler('PostReloadImage',
  function() {
    // your code goes here
  }
);

BotDetect CAPTCHA v3.0.0 Troubleshooting

BotDetect 3 improves the troubleshooting capabilities of the component, especially in providing a detailed trace of Captcha events (that can be filtered by a regular expression matching logged event names) and making custom logging providers much easier to implement.

Log4net is still used as the showcase logging provider, but with a small configuration tweak that makes text file logging possible in Medium Trust environments. You can see all these changes in the Captcha Troubleshooting code sample coming with BotDetect installations.

Old BotDetect 2 syntax:
<configSections>
  <section name="log4net"
    type="log4net.Config.Log4NetConfigurationSectionHandler,
    log4net"/>

  ...
  
<log4net configSource="log4net.config"/>
  
  ...
  
<system.web>
  <httpModules>
    <add type="Lanap.BotDetect.Troubleshooting.LoggingModule,
      Lanap.BotDetect.Troubleshooting" name="LoggingModule" />

  ...

<system.webServer>
  <modules>
    <remove name="LoggingModule"/>
    <add name="LoggingModule" preCondition="integratedMode"
      type="Lanap.BotDetect.Troubleshooting.LoggingModule,
        Lanap.BotDetect.Troubleshooting"/>
New BotDetect 3 syntax:
<configSections>
  <!-- Register the log4net configuration section -->
  <section name="log4net"
    type="log4net.Config.Log4NetConfigurationSectionHandler,
    log4net" requirePermission="false"/>
  <!-- Register the BotDetect configuration section -->
  <section name="botDetect"
    type="BotDetect.Configuration.BotDetectConfigurationSection,
      BotDetect" requirePermission="false"/>

  ...
  
<log4net configSource="log4net.config"/>
<botDetect>
  <!-- Register the log4net BotDetect logging provider -->
  <captchaLogging errorLoggingEnabled="true" traceEnabled="true"
    eventFilter=".*" 
    loggingProvider="BotDetect.Logging.Log4NetLoggingProvider,
      BotDetect.Troubleshooting"/>
</botDetect>  
  ...
  
<system.web>
  <httpModules>
    <!-- Register the HttpModule used for BotDetect
      error logging -->
    <add name="BotDetectTroubleshootingModule"
      type="BotDetect.Web.CaptchaTroubleshootingModule, BotDetect"/>

  ...

<system.webServer>
  <modules>
    <!-- Register the HttpModule used for BotDetect
      error logging (IIS 7.0+) -->
    <remove name="BotDetectTroubleshootingModule"/>
    <add name="BotDetectTroubleshootingModule"
      preCondition="integratedMode"
      type="BotDetect.Web.CaptchaTroubleshootingModule, BotDetect"/>

BotDetect CAPTCHA v3.0.0 ASP.NET MVC Integration

As previously mentioned, all BotDetect elements that were used for ASP.NET MVC compatibility in BotDetect 2 implementations (the CaptchaValidationAttribute, the HtmlHelper, all content files...) have been integrated in a new BotDetect assembly, BotDetect.Web.UI.Mvc.dll. This makes the Captcha component much easier to include into your ASP.NET MVC projects.

There have also been some minor tweaks to the source code fragments used to add Captcha validation to your controllers and views. The best way to see these changes is to review the ASP.NET MVC sample projects (now also including ASP.NET MVC 2.0) coming with the BotDetect installation.

BotDetect CAPTCHA v3.0.0 Source Code Customizations

If you used the BotDetect 2 source code coming with Developer Edition licenses to implement any custom changes in Captcha functionality, you will have to port them to the new source code structure used in BotDetect 3.

Keep in mind that some changes that required source code customization in BotDetect 2 are now possible using the standard control interface. For example, Captcha image color scheme customization is now simply a matter of specifying:
// customize the CAPTCHA image color scheme
SampleCaptcha.CustomDarkColor = System.Drawing.Color.DarkSlateBlue;
SampleCaptcha.CustomLightColor = System.Drawing.Color.LightSkyBlue;
Other changes can be made using the new <botDetect> configuration section, for example customizing the Captcha reload and sound icons is now possible by specifying the custom icon Urls and titles in web.config:
<!-- Custom sound Captcha icon image & titles -->
  <soundIcon filePath="~/CustomSoundIcon.gif">
    <soundIconTooltip>
      <localizedString locale="" value="Custom Universal Tooltip"/>
      <localizedString locale="en" value="Custom English Tooltip"/>
      <localizedString locale="es" value="Custom Spanish Tooltip"/>
      <!-- ...custom titles for other locales you want... -->
    </soundIconTooltip>
  </soundIcon>

If you require any help in reviewing how your changes fit into the new source code structure, or want to hear our suggestions how to go about porting them, simply contact us and we'll do our best to assist you.