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.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.

[back to top]

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.

[back to top]

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.

[back to top]

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.

[back to top]

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.

[back to top]

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.

[back to top]

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.

[back to top]

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.

[back to top]

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.

[back to top]

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)

[back to v3.0.0 migration guide contents]

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

[back to v3.0.0 migration guide contents]

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"/>

[back to v3.0.0 migration guide contents]

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"/>

[back to v3.0.0 migration guide contents]

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"/>

[back to v3.0.0 migration guide contents]

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 sample project 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"/>

[back to v3.0.0 migration guide contents]

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.

[back to v3.0.0 migration guide contents]

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 sample project coming with the BotDetect 3 installation.

[back to v3.0.0 migration guide contents]

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

[back to v3.0.0 migration guide contents]

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 Captcha Ajax Validation sample project 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 sample project), you would add your handler to the BotDetect.PostReloadImage client-side event by using: 
BotDetect.RegisterCustomHandler('PostReloadImage',
  function() {
    // your code goes here
  }
);

[back to v3.0.0 migration guide contents]

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 sample project 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"/>

[back to v3.0.0 migration guide contents]

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.

[back to v3.0.0 migration guide contents]

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.

[back to top]

language: English Español Tiếng Việt

© Lanapsoft, Inc. 2004-2012. 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 Lanapsoft, Inc. All other product, brand, and company names are mentioned for identification purposes only and are trademarks or registered trademarks of their respective owners.