BotDetect ASP CAPTCHA Migration Guide

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

Table of Contents

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

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

Running the updated setup package on your server will do this automatically, but you should stop IIS first for it to release all handles to the old DLL version. Alternatively, you can also manually remove the old version and deploy the new one.

You should also update all copies of script and content files from the Captcha library to the new versions: CaptchaClass.asp, CaptchaHandler.asp, CaptchaConfig.asp, Utils.asp, Layout.css, and Scripts.js have all been updated to implement the needed improvements and bugfixes.

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 CAPTCHA from v3.0.13 to v3.0.14

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

Running the updated setup package on your server will do this automatically, but you should stop IIS first for it to release all handles to the old DLL version. Alternatively, you can also manually remove the old version and deploy the new one.

You should also update all copies of script and content files from the Captcha library to the new versions: CaptchaClass.asp, CaptchaHandler.asp, CaptchaConfig.asp, Utils.asp, Layout.css, and Scripts.js have all been updated to implement the needed improvements and bugfixes.

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

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

Running the updated setup package on your server will do this automatically, but you should stop IIS first for it to release all handles to the old DLL version. Alternatively, you can also manually remove the old version and deploy the new one.

You should also update all copies of script and content files from the Captcha library to the new versions: CaptchaClass.asp, CaptchaConfig.asp and Scripts.js have been updated to implement the needed improvements and bugfixes.

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

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

Running the updated setup package on your server will do this automatically, but you should stop IIS first for it to release all handles to the old DLL version. Alternatively, you can also manually remove the old version and deploy the new one.

You should also update all copies of script and content files from the Captcha library to the new versions: CaptchaClass.asp, CaptchaConfig.asp, Layout.css, and Scripts.js have all been updated to implement the needed improvements and bugfixes.

Old Captcha randomization calls using the LBD_RandomFromRange and LBD_RandomFromValues helper functions should mostly be replaced with the new specialized Captcha randomization functions such as LBD_RandomSoundStyle(), LBD_RandomImageStyleFrom(imageStyleNames) etc. since they're more convenient to use, and the new emergency Captcha image or sound styles disabling depends on it.

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

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

Running the updated setup package on your server will do this automatically, but you should stop IIS first for it to release all handles to the old DLL version. Alternatively, you can also manually remove the old version and deploy the new one.

You should also update all copies of script and content files from the Captcha library to the new versions: CaptchaClass.asp, CaptchaConfig.asp, Utils.asp, Layout.css, and Scripts.js have all been updated to implement the needed improvements and bugfixes.

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 CAPTCHA from v3.0.9 to v3.0.10

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

Running the updated setup package on your server will do this automatically, but you should stop IIS first for it to release all handles to the old DLL version.

You should also update all copies of script and content files from the Captcha library to the new versions: CaptchaClass.asp, CaptchaHandler.asp, Layout.css, and Scripts.js have all been updated to implement the needed improvements and bugfixes.

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 CAPTCHA from v3.0.8 to v3.0.9

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

Running the updated setup package on your server will do this automatically, but you should stop IIS first for it to release all handles to the old DLL version.

You should also update the Scripts.js Captcha library file deployed with your application, which has been changed to implement a minor IE 8 bugfix.

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 CAPTCHA from v3.0.7 to v3.0.8

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

Running the updated setup package on your server will do this automatically, but you should stop IIS first for it to release all handles to the old DLL version.

You should also update the CaptchaClass.asp, CaptchaHandler.asp and Utils.asp Captcha library files deployed with your application, which have been changed to implement the GbPlugin workaround and the minor bugfixes.

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

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

Running the updated setup package on your server will do this automatically, but you should stop IIS first for it to release all handles to the old DLL version.

You should also update the CaptchaClass.asp Captcha library file deployed with your application, which has been changed to implement automatic default icon resizing.

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

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

Running the updated setup package on your server will do this automatically, but you should stop IIS first for it to release all handles to the old DLL version.

You should also update the CaptchaClass.asp Captcha library file deployed with your application, which has been changed to implement tabindex setting.

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

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

Running the updated setup package on your server will do this automatically, but you should stop IIS first for it to release all handles to the old DLL version.

You should also update the CaptchaClass.asp Scripts.js Captcha library files deployed with your application, which have been changed to implement the OnHelpLinkClick custom client-side event.

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 CAPTCHA from v3.0.3 to v3.0.4

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

Running the updated setup package on your server will do this automatically, but you should stop IIS first for it to release all handles to the old DLL version.

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

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

Running the updated setup package on your server will do this automatically, but you should stop IIS first for it to release all handles to the old DLL version.

You should also update the CaptchaClass.asp, Utils.asp, Layout.css and Scripts.js Captcha library files deployed with your application, which contain various 3.0.3 improvements.

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 CAPTCHA from v3.0.1 to v3.0.2

To take advantage of the v3.0.2 changes, you have to deploy the updated BotDetect DLL to your server.

Running the updated setup package on your server will do this automatically, but you should stop IIS first for it to release all handles to the old DLL version.

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

To take advantage of the v3.0.1 changes, you have to deploy the updated BotDetect DLL to your server.

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.

Running the updated setup package on your server will perform both of these changes automatically, but you have to stop IIS first for it to release handles to the old DLL version.

You should also update the BotDetect\Scripts.js file in your applications to the newest version.

Upgrading BotDetect ASP Classic Captcha from v2.0.9 to v3.0.0

Version 3.0.0 is a major new release of BotDetect ASP Classic 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 COM Component

  • The main BotDetect Captcha component file is now called BotDetect.COM.dll instead of LanapBotDetect.dll
  • The Captcha component code is based on .NET instead of unmanaged C++ code, so .NET framework 2.0 or newer is required to use the component
  • The Captcha component ProgId is now BotDetect.Captcha.3 instead of Lanap.BotDetect

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 deployed to your server alongside the DLL, and their location specified in the BotDetect/CaptchaConfig.asp file in your application. If you are running the BotDetect setup package on your server, the sound packages will be deployed automatically.

Sound package files separate from the main DLL 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 DLL 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 your server and give the IIS worker process read access to the folder.

BotDetect CAPTCHA v3.0.0 ASP Captcha Library

Instead of copying the old LanapBotDetectHandler.asp file to your application and writing Html markup referencing it, BotDetect 3 is used by creating a new instance of the Captcha class defined in the BotDetect Captcha ASP library.

You copy the BotDetect ASP files to your application, and adding Captcha protection to your forms is much simpler than before.

Old BotDetect 2 Captcha inclusion syntax:
<label for="CaptchaCode">Retype the characters from the picture:
</label>

<div id="CaptchaDiv">
  <div id="CaptchaImage">
    <img src="LanapBotDetectHandler.asp?Command=CreateImage" 
      alt="CAPTCHA image" id="CaptchaImage" />
  </div>
  <div id="CaptchaIcons">
    <a href="LanapBotDetectHandler.asp?Command=CreateSound" 
      onclick="LBD_LoadSound('soundPlaceholder', 
        'LanapBotDetectHandler.asp?Command=CreateSound'); 
        return false;">
      <img src="speaker.gif" alt="Play sound" style="border:0;" />
    </a>
  <a href="#" onclick='LBD_ReloadImage("CaptchaImage"); return false;' 
    title="Change the code">
    <img src="reload.gif" alt="Change the code" />
  </a>  
  <div id="soundPlaceholder" style="visibility:hidden; border:0; 
    width:0; height:0;"></div>
</div>

<input name="CaptchaCode" id="CaptchaCode" type="text" />
New BotDetect 3 Captcha inclusion syntax:
<!-- #include file ="BotDetect.asp" -->
</head>

...

<label for="CaptchaCode">Retype the characters from the picture:
</label>

<% ' Adding BotDetect CAPTCHA to the page 
  Dim SampleCaptcha : Set SampleCaptcha = (New Captcha)("SampleCaptcha")
  SampleCaptcha.UserInputID = "CaptchaCode"
  Response.Write SampleCaptcha.Html
%>

<input name="CaptchaCode" id="CaptchaCode" type="text" />

BotDetect CAPTCHA v3.0.0 ASP Captcha Validation

The new BotDetect 3 Captcha ASP library also encapsulates Captcha validation, making the necessary code much simpler to use in your form processing logic.

Old BotDetect 2 Captcha validation syntax:
Dim result, codeKey, inputCode
result = False
codeKey = "LanapBotDetectCode"
inputCode = Request("CaptchaCode")

If (Session(codeKey)<>"") Then
  code = Session(codeKey)
  result = (0 = StrComp(inputCode, code, 1))
  'each Captcha code can only be validated once
  Session(codeKey) = ""
End If
New BotDetect 3 Captcha validation syntax:
Dim isHuman : isHuman = SampleCaptcha.Validate()

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 Captcha Customization & Randomization

BotDetect 2 Captcha settings were set in Captcha image querystring parameters or LanapBotDetectHandler.asp code. BotDetect 3 Captcha settings can be set in the BotDetect\CaptchaConfig.asp file (if they apply to all Captcha instances in the application) or as Captcha object properties (if they are instance-specific).

To make the code more readable, various enumerated members (for example, image styles) can now be referred to by name instead of numeric values. Also, Captcha property randomization is simpler to use.

Old BotDetect 2 syntax:
<img src="LanapBotDetectHandler.asp?Command=CreateImage&
  TextStyle=28&ImageWidth=300&imageHeight=40&CodeLength=7&
  CodeType=1&Format=PNG" alt="CAPTCHA image" id="CaptchaImage" />
New BotDetect 3 config file syntax:
LBD_Configuration_CodeLength = 5

Dim codeStyleNames(2)
codeStyleNames(0) = "AlphaNumeric"
codeStyleNames(1) = "Alpha"
codeStyleNames(2) = "Numeric"
LBD_Configuration_CodeStyle = _ 
  LBD_CodeStyles(LBD_RandomFromValues(codeStyleNames))
New BotDtect 3 object properties syntax:
Dim Captcha1 : Set Captcha1 = (New Captcha)("Captcha1")
Captcha1.UserInputID = "CaptchaCode1"
Captcha1.ImageStyleName = "Bullets2"
Captcha1.CodeStyleName = "Numeric

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.UserInputID = "CaptchaCode";
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. If you are interested, you can see how it works in the ASP 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
  }
);