BotDetect CAPTCHA Migration Guides
This page contains instructions for updating your BotDetect ASP.NET Captcha installation to newer versions, starting with BotDetect v3.0.0.
Table of Contents
..............................................................
Current Release
Upgrading from v4.4.1 to v4.4.2
To take advantage of the v4.4.2 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 4.4.2.
..............................................................
Old Releases
Upgrading from v4.4.0 to v4.4.1
To take advantage of the v4.4.1 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 4.4.1.
BotDetect CAPTCHA v4.4.1 Simple API HttpHandler Mapping Url
If you were using Simple API in your application, you need to change the generic handler mapping url of
BotDetect.Web.SimpleCaptchaHandler as demonstrated bellow:
Old BotDetect 4.4.0 syntax:
<system.web>
<httpHandlers>
<!-- register the HttpHandler that serves BotDetect Simple API requests -->
<add verb="GET" path="BotDetectCaptcha.ashx"
type="BotDetect.Web.SimpleCaptchaHandler, BotDetect"/>
</httpHandlers>
</system.web>
<system.webServer>
<validation validateIntegratedModeConfiguration="false"/>
<handlers>
<!-- register the HttpHandler that serves BotDetect Simple API requests (IIS 7+) -->
<remove name="BotDetectCaptchaHandler"/>
<add name="BotDetectCaptchaHandler" preCondition="integratedMode"
verb="GET" path="BotDetectCaptcha.ashx"
type="BotDetect.Web.SimpleCaptchaHandler, BotDetect"/>
</handlers>
</system.webServer>
New BotDetect 4.4.1 syntax:
<system.web>
<httpHandlers>
<!-- register the HttpHandler that serves BotDetect Simple API requests -->
<add verb="GET" path="simple-captcha-endpoint.ashx"
type="BotDetect.Web.SimpleCaptchaHandler, BotDetect"/>
</httpHandlers>
</system.web>
<system.webServer>
<validation validateIntegratedModeConfiguration="false"/>
<handlers>
<!-- register the HttpHandler that serves BotDetect Simple API requests (IIS 7+) -->
<remove name="BotDetectCaptchaHandler"/>
<add name="BotDetectCaptchaHandler" preCondition="integratedMode"
verb="GET" path="simple-captcha-endpoint.ashx"
type="BotDetect.Web.SimpleCaptchaHandler, BotDetect"/>
</handlers>
</system.webServer>
[back to the top of the page]
Upgrading from v4.3.3 to v4.4.0
To take advantage of the v4.4.0 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 4.4.0.
[back to the top of the page]
Upgrading from v4.3.2 to v4.3.3
To take advantage of the v4.3.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 4.3.3.
[back to the top of the page]
Upgrading from v4.3.1 to v4.3.2
To take advantage of the v4.3.2 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 4.3.2.
[back to the top of the page]
Upgrading from v4.3.0 to v4.3.1
To take advantage of the v4.3.1 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 4.3.1.
[back to the top of the page]
Upgrading from v4.2.0 to v4.3.0
To take advantage of the v4.3.0 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 4.3.0.
The function prototype GetInputElement of BotDetect ClientSide Object has renamed to GetUserInputElement.
[back to the top of the page]
Upgrading from v4.1.0 to v4.2.0
To take advantage of the v4.2.0 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 4.2.0.
[back to the top of the page]
Upgrading from v4.0.0 to v4.1.0
To take advantage of the v4.1.0 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 4.1.0.
[back to the top of the page]
Upgrading BotDetect ASP.NET CAPTCHA from v3.* to v4.*
To take advantage of the v4.0.0 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 4.0.0.
Please follow this migration guide carefully, and you'll be running the latest version of BotDetect Captcha in no time.
[back to the top of the page]
BotDetect CAPTCHA v4.0.0 Assemblies
Captcha control namespace organization & class names has been changed:
- BD3 Web.CaptchaControl has been changed to BD4 Web.Captcha
- BD3 Web.UI.Captcha has been changed to BD4 Web.UI.WebFormsCaptcha
(i.e. <BotDetect:Captcha ID="ExampleCaptcha" runat="server" /> becomes <BotDetect:WebFormsCaptcha ID="ExampleCaptcha" runat="server" />)
- BD3 Web.UI.Mvc.MvcCaptcha has been changed to BD4 Web.Mvc.MvcCaptcha
(i.e. @using BotDetect.Web.UI.Mvc; becomes @using BotDetect.Web.Mvc;)
[back to v4.0.0 migration guide contents]
BotDetect CAPTCHA v4.0.0 Configuration
BotDetect CAPTCHA Configuration Section control in web.config has been flattened. On the other hand, all BD4 application configuration settings are attributes of the <botDetect> configuration element. We replaced the BD3 unnecessary and fragile (hard to change and maintain) hierarchy of sub-elements (removing the need to pre-emptively design the correct hierarchy that can support any future settings added)
i.e.
<botDetect>
<captchaImage>
<helpLink enabled="true" mode="image" />
</captchaImage>
</botDetect>
becomes
<botDetect helpLinkEnabled="true" helpLinkMode="image" />
You can use our migration helper tool to convert BotDetect v3 into BotDetect v4 CAPTCHA Config Format.
Additionally, if you were using CustomCharset or BannedSequences settings, please note that they have merged into the "disallowed code substrings" setting (i.e. you need to use DisallowedCodeSubstrings setting instead).
[back to v4.0.0 migration guide contents]
If you were using BotDetect client-side instance function Validate(), please note that it has been renamed to StartAjaxValidation() (i.e. input.Captcha.Validate() became input.Captcha.StartAjaxValidation()). Now this function no longer sets the ValidationResult instance property (Ajax validation result is now available through AjaxValidationPassed or AjaxValidationFailed callbacks). You should take a look into the Captcha client-side workflow settings code example for more details.
Additionally, we replaced client-side UserInputClientID (envisioned for WebForms use) with universal UserInputID (which also allows simpler Captcha validation calls) and WebForms-only server-side UserInputControlID (automatically expanded into client-side variation and used internally by BotDetect)
i.e.:
<BotDetect:Captcha ID="ExampleCaptcha" runat="server" UserInputClientID="CaptchaCodeTextBox" /> becomes <BotDetect:WebFormsCaptcha ID="ExampleCaptcha" runat="server" UserInputControlID="CaptchaCodeTextBox" />exampleCaptcha.UserInputClientID = "CaptchaCode"; becomes exampleCaptcha.UserInputID = "CaptchaCode";
[back to v4.0.0 migration guide contents]
Upgrading BotDetect ASP.NET CAPTCHA from v3.0.17 to v3.0.18
To take advantage of the v3.0.18 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.18.0.
[back to the top of the page]
Upgrading BotDetect ASP.NET CAPTCHA from v3.0.16 to v3.0.17
To take advantage of the v3.0.17 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.17.0.
[back to the top of the page]
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.
[back to the top of the page]
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.
[back to the top of the page]
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.
[back to the top of the page]
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.
[back to the top of the page]
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.
[back to the top of the page]
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.
[back to the top of the page]
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).
[back to the top of the page]
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 the top of the page]
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 the top of the page]
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 the top of the page]
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 examples included in v3.0.6 BotDetect installations.
[back to the top of the page]
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 the top of the 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.
[back to the top of the page]
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 the top of the page]
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 the top of the page]
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 the top of the page]
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 code example 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 CodeStyleCodeType.AlphaNumeric has been renamed to CodeStyle.AlphanumericTextStyle 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.FingerprintsTextStyle.Spiderweb has been renamed to ImageStyle.SpiderWebTextStyle.SunRays has been renamed to ImageStyle.SunraysTextStyle.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.InitializedCaptchaControlCaptcha.GeneratingCaptchaCodeCaptcha.GeneratedCaptchaCodeCaptcha.GeneratingCaptchaImageCaptcha.GeneratedCaptchaImageCaptcha.GeneratingCaptchaSoundCaptcha.GeneratedCaptchaSoundCaptcha.ValidatingUserInputCaptcha.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 example 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:
ExampleCaptcha.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.PostInitBotDetect.PreReloadImageBotDetect.PostReloadImageBotDetect.PrePlaySoundBotDetect.PreAjaxValidateBotDetect.AjaxValidationFailedBotDetect.AjaxValidationPassedBotDetect.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 example 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 example), 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 code example 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 example 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 the top of the page]
This page contains instructions for updating your BotDetect Java Captcha copy to newer versions, starting with BotDetect v3.0.Alpha2.
Table of Contents
..............................................................
Current Release
Upgrading BotDetect Java CAPTCHA from v4.0.Beta3.6 to v4.0.Beta3.7
To take advantage of the v4.0.Beta3.7
changes, you have to copy updated BotDetect library jar files to your application's (or server's) classpath.
..............................................................
Old Releases
Upgrading BotDetect Java CAPTCHA from v4.0.Beta3.5 to v4.0.Beta3.6
To take advantage of the v4.0.Beta3.6
changes, you have to copy updated BotDetect library jar files to your application's (or server's) classpath.
Please follow this migration guide carefully, and you'll be running the latest version of BotDetect Captcha in no time.
BotDetect CAPTCHA v4.0.Beta3.6 Simple API SimpleCaptchaServlet Mapping Url
If you were using Simple API in your application, you need to change the servlet mapping url of SimpleCaptchaServlet as demonstrated bellow:
In web.xml configuration file:
Old BotDetect 4.0.Beta3.5 syntax:
<servlet>
<servlet-name>BotDetect Captcha</servlet-name>
<servlet-class>com.captcha.botdetect.web.servlet.SimpleCaptchaServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>BotDetect Captcha</servlet-name>
<url-pattern>/botdetectcaptcha</url-pattern>
</servlet-mapping>
New BotDetect 4.0.Beta3.6 syntax:
<servlet>
<servlet-name>BotDetect Captcha</servlet-name>
<servlet-class>com.captcha.botdetect.web.servlet.SimpleCaptchaServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>BotDetect Captcha</servlet-name>
<url-pattern>/simple-captcha-endpoint</url-pattern>
</servlet-mapping>
In @SpringBootApplication class:
Old BotDetect 4.0.Beta3.5 syntax:
@SpringBootApplication
public class SpringBootWebApplication {
[...]
@Bean
ServletRegistrationBean captchaServletRegistration () {
ServletRegistrationBean srb = new ServletRegistrationBean();
srb.setServlet(new SimpleCaptchaServlet());
srb.addUrlMappings("/botdetectcaptcha");
return srb;
}
}
New BotDetect 4.0.Beta3.6 syntax:
@SpringBootApplication
public class SpringBootWebApplication {
[...]
@Bean
ServletRegistrationBean captchaServletRegistration () {
ServletRegistrationBean srb = new ServletRegistrationBean();
srb.setServlet(new SimpleCaptchaServlet());
srb.addUrlMappings("/simple-captcha-endpoint");
return srb;
}
}
In struts.xml configuration file:
Old BotDetect 4.0.Beta3.5 syntax:
<constant name="struts.action.excludePattern" value="/botdetectcaptcha"/>
New BotDetect 4.0.Beta3.6 syntax:
<constant name="struts.action.excludePattern" value="/simple-captcha-endpoint"/>
..............................................................
Old Releases
Upgrading BotDetect Java CAPTCHA from v4.0.Beta3.4 to v4.0.Beta3.5
To take advantage of the v4.0.Beta3.5 changes, you have to copy updated BotDetect library jar files to your application's (or server's) classpath.
Upgrading BotDetect Java CAPTCHA from v4.0.Beta3.3 to v4.0.Beta3.4
To take advantage of the v4.0.Beta3.4 changes, you have to copy updated BotDetect library jar files to your application's (or server's) classpath.
Upgrading BotDetect Java CAPTCHA from v4.0.Beta3.2 to v4.0.Beta3.3
To take advantage of the v4.0.Beta3.3 changes, you have to copy updated BotDetect library jar files to your application's (or server's) classpath.
Please follow this migration guide carefully, and you'll be running the latest version of BotDetect Captcha in no time.
BotDetect CAPTCHA v4.0.Beta3.3 Simple API Default Persistence Provider
We have reverted back to unembedded HSQLDB use because the embedded use is breaking application builds for developers who have another HSQLDB version already embedded in their project. Therefore, you need to add hsqldb.jar library in your application classpath again, which is default persistence provider.
Upgrading BotDetect Java CAPTCHA from v4.0.Beta3.1 to v4.0.Beta3.2
To take advantage of the v4.0.Beta3.2 changes, you have to copy updated BotDetect library jar files to your application's (or server's) classpath.
Please follow this migration guide carefully, and you'll be running the latest version of BotDetect Captcha in no time.
BotDetect CAPTCHA v4.0.Beta3.2 Simple API Captcha Packages
If you were using simple-botdetect-jsp20.jar, simple-botdetect-jsf20.jar, or simple-botdetect-jsf12.jar in your application, you need to remove them and use botdetect-jsp20.jar, botdetect-jsf20.jar, or botdetect-jsf12.jar instead.
BotDetect CAPTCHA v4.0.Beta3.2 Simple API Captcha Tag Namespace
If you were using Simple API Captcha tag in your JSP pages, Standard JSF(.jsp) view, or Facelets(.xhtml) view, you need to change the namespace of Captcha tag as show bellow:
In JSP pages:
Old BotDetect 4.0.Beta3.1 syntax:
<%@taglib prefix="botDetect" uri="https://captcha.com/java/jsp"%>
New BotDetect 4.0.Beta3.2 syntax:
<%@taglib prefix="botDetect" uri="https://captcha.com/java/jsp/simple-api"%>
In Standard JSF(.jsp) view:
Old BotDetect 4.0.Beta3.1 syntax:
<%@taglib prefix="botDetect" uri="https://captcha.com/java/jsf"%>
New BotDetect 4.0.Beta3.2 syntax:
<%@taglib prefix="botDetect" uri="https://captcha.com/java/jsf/simple-api"%>
In Facelets (.xhtml) view:
Old BotDetect 4.0.Beta3.1 syntax:
xmlns:botDetect="https://captcha.com/java/jsf"
New BotDetect 4.0.Beta3.2 syntax:
xmlns:botDetect="https://captcha.com/java/jsf/simple-api"
BotDetect CAPTCHA v4.0.Beta3.2 Simple API Captcha Tag Attribute
If you were using Simple API Captcha tag in your JSP pages, Standard JSF(.jsp) view, or Facelets(.xhtml) view, you need to change the styleName attribute to id attribute as show bellow:
Old BotDetect 4.0.Beta3.1 syntax:
<botDetect:simpleCaptcha styleName="exampleCaptcha"
<botDetect:simpleJsfCaptcha styleName="exampleCaptcha"
New BotDetect 4.0.Beta3.2 syntax:
<botDetect:simpleCaptcha id="exampleCaptcha"
<botDetect:simpleJsfCaptcha id="exampleCaptcha"
BotDetect CAPTCHA v4.0.Beta3.2 Simple API Validating Captcha Id Key
If you were using SimpleCaptcha class getValidatingInstanceKey method in your application, you need to change it by using new api as show bellow:
Old BotDetect 4.0.Beta3.1 syntax:
exampleCaptcha.getValidatingInstanceKey();
New BotDetect 4.0.Beta3.2 syntax:
exampleCaptcha.getValidatingCaptchaIdKey();
[back to v4.0.Beta3.2 migration guide contents]
Upgrading BotDetect Java CAPTCHA from v4.0.Beta3 to v4.0.Beta3.1
To take advantage of the v4.0.Beta3.1 changes, you have to copy updated BotDetect library jar files to your application's (or server's) classpath.
Upgrading BotDetect Java CAPTCHA from v4.0.Beta2 to v4.0.Beta3
To take advantage of the v4.0.Beta3 changes, you have to copy updated BotDetect library jar files to your application's (or server's) classpath.
Upgrading BotDetect Java CAPTCHA from v4.0.Beta1 to v4.0.Beta2
To take advantage of the v4.0.Beta2 changes, you have to copy updated BotDetect library jar files to your application's (or server's) classpath.
Please follow this migration guide carefully, and you'll be running the latest version of BotDetect Captcha in no time.
BotDetect CAPTCHA v4.0.Beta2 Init Script Include
If you were using BotDetect Captcha Init Script option in your application, you need to change it by using new api as show bellow:
Captcha object instance property:
Old BotDetect 4.0.Beta1 syntax:
exampleCaptcha.setAddInitScript(false);
New BotDetect 4.0.Beta2 syntax:
exampleCaptcha.setAddInitScriptInclude(false);
JSP / JSF Captcha tags:
Old BotDetect 4.0.Beta1 syntax:
<botDetect:captcha id="exampleCaptcha" addInitScript="false"
<botDetect:jsfCaptcha id="exampleCaptcha" addInitScript="false"
New BotDetect 4.0.Beta2 syntax:
<botDetect:captcha id="exampleCaptcha" addInitScriptInclude="false"
<botDetect:jsfCaptcha id="exampleCaptcha" addInitScriptInclude="false"
In web.xml file:
Old BotDetect 4.0.Beta1 syntax:
<context-param>
<param-name>BDC_addInitScript</param-name>
<param-value>false</param-value>
</context-param>
New BotDetect 4.0.Beta2 syntax:
<context-param>
<param-name>BDC_addInitScriptInclude</param-name>
<param-value>false</param-value>
</context-param>
[back to v4.0.Beta2 migration guide contents]
Upgrading BotDetect Java CAPTCHA from v4.0.Alpha5 to v4.0.Beta1
To take advantage of the v4.0.Beta1 changes, you have to copy updated BotDetect library jar files to your application's (or server's) classpath.
Please follow this migration guide carefully, and you'll be running the latest version of BotDetect Captcha in no time.
BotDetect CAPTCHA v4.0.Beta1 Html Markup
If you were using BotDetect Captcha Html markup method getHtml(ServletContext) in your application, you need to change it to getHtml(), which now has no parameter anymore, for example:
Old BotDetect 4.0.Alpha5 syntax:
String captchaHtml = captcha.getHtml(pageContext.getServletContext());
New BotDetect 4.0.Beta1 syntax:
String captchaHtml = captcha.getHtml();
[back to v4.0.Beta1 migration guide contents]
BotDetect CAPTCHA v4.0.Beta1 Captcha Tag Namespace
If you were using Captcha tag in your JSP pages, Standard JSF(.jsp) view, or Facelets(.xhtml) view, you need to change the namespace of Captcha tag as show bellow:
In JSP pages:
Old BotDetect 4.0.Alpha5 syntax:
<%@taglib prefix="botDetect" uri="botDetect"%>
New BotDetect 4.0.Beta1 syntax:
<%@taglib prefix="botDetect" uri="https://captcha.com/java/jsp"%>
In Standard JSF(.jsp) view:
Old BotDetect 4.0.Alpha5 syntax:
<%@taglib prefix="botDetect" uri="botDetect"%>
New BotDetect 4.0.Beta1 syntax:
<%@taglib prefix="botDetect" uri="https://captcha.com/java/jsf"%>
In Facelets (.xhtml) view:
Old BotDetect 4.0.Alpha5 syntax:
xmlns:botDetect="botDetectFacelets"
New BotDetect 4.0.Beta1 syntax:
xmlns:botDetect="https://captcha.com/java/jsf"
[back to the top of the page]
Upgrading BotDetect Java CAPTCHA from v4.0.Alpha4 to v4.0.Alpha5
To take advantage of the v4.0.Alpha5 changes, you have to copy updated BotDetect library jar files to your application's (or server's) classpath.
Please follow this migration guide carefully, and you'll be running the latest version of BotDetect Captcha in no time.
[back to the top of the page]
BotDetect CAPTCHA v4.0.Alpha5 Dependency
BotDetect Java code is now separated to multiple jars in order to support different versions of Servlet, JavaServer Pages, and JavaServer Faces. Follow the BotDetect CAPTCHA v4.0.Alpha5 guides to integrate BotDetect Java CAPTCHA with your web application:
[back to v4.0.Alpha5 migration guide]
BotDetect CAPTCHA v4.0.Alpha5 Package Name
Changed package name of BotDetect Captcha to start with com.captcha.botdetect. instead of with botdetect. as previous versions did. Some BotDetect classes are also moved to other packages. Therefore in your application, you'll need to change BotDetect package-related import directives. For example:
Old BotDetect 4.0.Alpha4 API:
import botdetect.ImageStyle;
import botdetect.web.jsf.JsfCaptcha;
...
New BotDetect 4.0.Alpha5 API:
import com.captcha.botdetect.ImageStyle;
import com.captcha.botdetect.web.jsf.JsfCaptcha;
...
[back to v4.0.Alpha5 migration guide]
BotDetect CAPTCHA v4.0.Alpha5 Enumeration Members
The BotDetect enumeration naming convention is now changed to UPPERCASE_UPPERCASE:
Old BotDetect 4.0.Alpha4 syntax:
exampleCaptcha.setImageStyle(ImageStyle.Bubbles);
exampleCaptcha.setSoundStyle(SoundStyle.HiveMind);
New BotDetect 4.0.Alpha5 syntax:
exampleCaptcha.setImageStyle(ImageStyle.BUBBLES);
exampleCaptcha.setSoundStyle(SoundStyle.HIVE_MIND);
[back to v4.0.Alpha5 migration guide]
BotDetect CAPTCHA v4.0.Alpha5 ServletCaptcha Registration
ServletCaptcha class is moved to botdetect-servlet25 package and its package name has been changed accordingly. You need to update your web.xml:
Old BotDetect 4.0.Alpha4 syntax in web.xml:
<servlet>
<servlet-name>BotDetect Captcha</servlet-name>
<servlet-class>botdetect.web.http.CaptchaServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>BotDetect Captcha</servlet-name>
<url-pattern>/botdetectcaptcha</url-pattern>
</servlet-mapping>
New BotDetect 4.0.Alpha5 syntax in web.xml:
<servlet>
<servlet-name>BotDetect Captcha</servlet-name>
<servlet-class>com.captcha.botdetect.web.servlet.CaptchaServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>BotDetect Captcha</servlet-name>
<url-pattern>/botdetectcaptcha</url-pattern>
</servlet-mapping>
[back to v4.0.Alpha5 migration guide]
BotDetect CAPTCHA v4.0.Alpha5 Captcha Class
Captcha class is moved to botdetect-servlet25 package and there are some related changes in API:
Replaced validate(HttpServletRequest context, String userInput) method with validate(String userInput), which now accepts submitted user input value as an only argument.
Replaced renderCaptchaMarkup(ServletContext context, Writer out) method with getHtml(ServletContext context) method, which now accepts ServletContext object as an only argument and doesn't print Captcha Html markup anymore (but returns it). Therefore you should print returned Captcha Html markup yourself.
Replaced setUserInputClientId() method with setUserInputID() method, which also allows simpler Captcha validation calls.
Replaced setIncludeStyle() method with setAddCssInclude() method.
Replaced setIncludeClientScript() method with setAddScriptInclude() method.
Replaced setIncludeInitScript() method with setAddInitScript() method.
Replaced setIncludeRemoteScript() method with setRemoteScriptEnabled() method.
Replaced setCaptchaImageTooltip() method with setImageTooltip() method.
Replaced setSoundIconTooltip() method with setSoundTooltip() method.
Replaced setReloadIconTooltip() method with setReloadTooltip() method.
[back to v4.0.Alpha5 migration guide]
BotDetect CAPTCHA v4.0.Alpha5 JsfCaptcha Class
JsfCaptcha class is moved to botdetect-jsf20 package and there are some related changes in API:
Changed setCodeStyle(CodeStyle style) method to setCodeStyle(String style) method, which now receives java.lang.String as an argument.
Changed setImageStyle(ImageStyle style) method to setImageStyle(String style) method, which now receives java.lang.String as an argument.
Changed setImageFormat(ImageFormat style) method to setImageFormat(String style) method, which now receives java.lang.String as an argument.
Changed setSoundFormat(SoundFormat style) method to setSoundFormat(String style) method, which now receives java.lang.String as an argument.
Merged setImageStyles() method into setImageStyle() method.
Merged setSoundStyles() method into setSoundStyle() method.
Replaced setUserInputClientId() method with setUserInputID() method.
Replaced setOmitStylesheet() method with setAddCssInclude() method.
Replaced setOmitClientScript() method with setAddScriptInclude() method.
[back to v4.0.Alpha5 migration guide]
BotDetect CAPTCHA v4.0.Alpha5 JSP / Standard JSF Captcha Tag
- Replaced
userInputClientId attribute with userInputID attribute:
Old BotDetect 4.0.Alpha4 syntax:
<botDetect:jsfCaptcha id="exampleCaptcha" userInputClientId="captchaCode"
<botDetect:captcha id="exampleCaptcha" userInputClientId="captchaCode"
New BotDetect 4.0.Alpha5 syntax:
<botDetect:jsfCaptcha id="exampleCaptcha" userInputID="captchaCode"
<botDetect:captcha id="exampleCaptcha" userInputID="captchaCode"
- Replaced
imageStyles attribute with imageStyle attribute:
Old BotDetect 4.0.Alpha4 syntax:
<botDetect:jsfCaptcha id="exampleCaptcha" imageStyles="CHESS3D,IN_BANDAGES"
<botDetect:captcha id="exampleCaptcha" imageStyles="CHESS3D,IN_BANDAGES"
New BotDetect 4.0.Alpha5 syntax:
<botDetect:jsfCaptcha id="exampleCaptcha" imageStyle="CHESS3D,IN_BANDAGES"
<botDetect:captcha id="exampleCaptcha" imageStyle="CHESS3D,IN_BANDAGES"
- Replaced
omitStylesheet attribute with addCssInclude attribute:
Old BotDetect 4.0.Alpha4 syntax:
<botDetect:jsfCaptcha id="exampleCaptcha" omitStylesheet="true"
<botDetect:captcha id="exampleCaptcha" omitStylesheet="true"
New BotDetect 4.0.Alpha5 syntax:
<botDetect:jsfCaptcha id="exampleCaptcha" addCssInclude="false"
<botDetect:captcha id="exampleCaptcha" addCssInclude="false"
- Replaced
omitClientScript attribute with addScriptInclude attribute:
Old BotDetect 4.0.Alpha4 syntax:
<botDetect:jsfCaptcha id="exampleCaptcha" omitClientScript="true"
<botDetect:captcha id="exampleCaptcha" omitClientScript="true"
New BotDetect 4.0.Alpha5 syntax:
<botDetect:jsfCaptcha id="exampleCaptcha" addScriptInclude="false"
<botDetect:captcha id="exampleCaptcha" addScriptInclude="false"
[back to v4.0.Alpha5 migration guide]
BotDetect CAPTCHA v4.0.Alpha5 Application web.xml Configuration
BotDetect Captcha params names prefix have been changed from 'LBD_' to 'BDC_'. For example:
Old BotDetect 4.0.Alpha4 syntax:
<context-param>
<param-name>LBD_codeLength</param-name>
<param-value>4</param-value>
</context-param>
New BotDetect 4.0.Alpha5 syntax:
<context-param>
<param-name>BDC_codeLength</param-name>
<param-value>4</param-value>
</context-param>
Besides that, the following captcha param names are changed:
- Merged
imageStyles param name into imageStyle param name:
Old BotDetect 4.0.Alpha4 syntax:
<context-param>
<param-name>LBD_imageStyles</param-name>
<param-value>LEGO,CHIPPED</param-value>
</context-param>
New BotDetect 4.0.Alpha5 syntax:
<context-param>
<param-name>BDC_imageStyle</param-name>
<param-value>LEGO,CHIPPED</param-value>
</context-param>
- Merged
soundStyles param name into soundStyle param name:
Old BotDetect 4.0.Alpha4 syntax:
<context-param>
<param-name>LBD_soundStyles</param-name>
<param-value>DISPATCH,SYNTH</param-value>
</context-param>
New BotDetect 4.0.Alpha5 syntax:
<context-param>
<param-name>BDC_soundStyle</param-name>
<param-value>DISPATCH,SYNTH</param-value>
</context-param>
- Replaced
omitStylesheet param name with addCssInclude param name:
Old BotDetect 4.0.Alpha4 syntax:
<context-param>
<param-name>LBD_omitStylesheet</param-name>
<param-value>true</param-value>
</context-param>
New BotDetect 4.0.Alpha5 syntax:
<context-param>
<param-name>BDC_addCssInclude</param-name>
<param-value>false</param-value>
</context-param>
- Replaced
omitClientScript param name with addScriptInclude param name:
Old BotDetect 4.0.Alpha4 syntax:
<context-param>
<param-name>LBD_omitClientScript</param-name>
<param-value>true</param-value>
</context-param>
New BotDetect 4.0.Alpha5 syntax:
<context-param>
<param-name>BDC_addScriptInclude</param-name>
<param-value>false</param-value>
</context-param>
- Replaced
bannedSequences param name with disallowedCodeSubstrings param name:
Old BotDetect 4.0.Alpha4 syntax:
<context-param>
<param-name>LBD_bannedSequences</param-name>
<param-value>x,y,z,aa,bb,cc,abc,bca,cab</param-value>
</context-param>
New BotDetect 4.0.Alpha5 syntax:
<context-param>
<param-name>BDC_disallowedCodeSubstrings</param-name>
<param-value>x,y,z,aa,bb,cc,abc,bca,cab</param-value>
</context-param>
- Replaced
captchaRemoteScript param name with remoteScriptEnabled param name:
Old BotDetect 4.0.Alpha4 syntax:
<context-param>
<param-name>LBD_captchaRemoteScript</param-name>
<param-value>false</param-value>
</context-param>
New BotDetect 4.0.Alpha5 syntax:
<context-param>
<param-name>BDC_remoteScriptEnabled</param-name>
<param-value>false</param-value>
</context-param>
[back to v4.0.Alpha5 migration guide contents]
BotDetect CAPTCHA v4.0.Alpha5 Client-side Processing
If you were using BotDetect client-side instance function Validate(), it is renamed to StartAjaxValidation() in v4.0.Alpha5 (i.e. input.Captcha.Validate() became input.Captcha.StartAjaxValidation()). The function no longer sets the ValidationResult instance property. Ajax validation result is now available through AjaxValidationPassed or AjaxValidationFailed callbacks. Take a look into the Captcha client-side workflow settings code example for more details.
[back to the top of the page]
Upgrading BotDetect Java CAPTCHA from v3.0.Alpha3 to v4.0.Alpha4
To take advantage of the v3.0.Alpha4 changes, you have to put updated BotDetect library .jar file to your application's or server's classpath replacing old botdetect.jar file.
[back to the top of the page]
Upgrading BotDetect Java CAPTCHA from v3.0.Alpha2 to v3.0.Alpha3
To take advantage of the v3.0.Alpha3 changes, you have to put updated BotDetect library .jar file to your application's or server's classpath replacing old botdetect.jar file.
[back to the top of the page]
Upgrading BotDetect Java CAPTCHA from v3.0.Alpha1 to v3.0.Alpha2
To take advantage of the v3.0.Alpha2 changes, you have to put updated BotDetect .jar file to your application's or server's classpath replacing old botdetect.jar file.
[back to the top of the page]
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 the top of the page]
This page contains instructions for updating your BotDetect PHP Captcha copy to newer versions, starting with BotDetect 3 Alpha2.
Table of Contents
..............................................................
Current Release
Upgrading BotDetect PHP CAPTCHA from v4.2.4 to v4.2.5
To take advantage of the v4.2.5 changes, you have to update all Captcha library files included in the BotDetect download package – overwrite the old lib folder contents with the updated one.
If you had custom include paths defined in the old lib/botdetect.php, lib/simple-botdetect.php files, you should merge your changes from it into the updated botdetect.php, simple-botdetect.php files.
If you had custom Captcha settings in the default library configuration file (lib/botdetect/CaptchaConfigDefaults.php or lib/config/botdetect.xml), you should merge them into the updated CaptchaConfigDefaults.php, botdetect.xml files.
[back to the top of the page]
..............................................................
Old Releases
Upgrading BotDetect PHP CAPTCHA from v4.2.3 to v4.2.4
To take advantage of the v4.2.4 changes, you have to update all Captcha library files included in the BotDetect download package – overwrite the old lib folder contents with the updated one.
If you had custom include paths defined in the old lib/botdetect.php, lib/simple-botdetect.php files, you should merge your changes from it into the updated botdetect.php, simple-botdetect.php files.
If you had custom Captcha settings in the default library configuration file (lib/botdetect/CaptchaConfigDefaults.php or lib/config/botdetect.xml), you should merge them into the updated CaptchaConfigDefaults.php, botdetect.xml files.
[back to the top of the page]
Upgrading BotDetect PHP CAPTCHA from v4.2.2 to v4.2.3
To take advantage of the v4.2.3 changes, you have to update all Captcha library files included in the BotDetect download package – overwrite the old lib folder contents with the updated one.
If you had custom include paths defined in the old lib/botdetect.php, lib/simple-botdetect.php files, you should merge your changes from it into the updated botdetect.php, simple-botdetect.php files.
If you had custom Captcha settings in the default library configuration file (lib/botdetect/CaptchaConfigDefaults.php or lib/config/botdetect.xml), you should merge them into the updated CaptchaConfigDefaults.php, botdetect.xml files.
[back to the top of the page]
Upgrading BotDetect PHP CAPTCHA from v4.2.1 to v4.2.2
To take advantage of the v4.2.2 changes, you have to update all Captcha library files included in the BotDetect download package – overwrite the old lib folder contents with the updated one.
If you had custom include paths defined in the old lib/botdetect.php, lib/simple-botdetect.php files, you should merge your changes from it into the updated botdetect.php, simple-botdetect.php files.
If you had custom Captcha settings in the default library configuration file (lib/botdetect/CaptchaConfigDefaults.php or lib/config/botdetect.xml), you should merge them into the updated CaptchaConfigDefaults.php, botdetect.xml files.
[back to the top of the page]
Upgrading BotDetect PHP CAPTCHA from v4.2.0 to v4.2.1
To take advantage of the v4.2.1 changes, you have to update all Captcha library files included in the BotDetect download package – overwrite the old lib folder contents with the updated one.
If you had custom include paths defined in the old lib/botdetect.php, lib/simple-botdetect.php files, you should merge your changes from it into the updated botdetect.php, simple-botdetect.php files.
If you had custom Captcha settings in the default library configuration file (lib/botdetect/CaptchaConfigDefaults.php or lib/config/botdetect.xml), you should merge them into the updated CaptchaConfigDefaults.php, botdetect.xml files.
If you used AddInitScript setting, you should rename AddInitScript into AddInitScriptInclude.
[back to the top of the page]
Upgrading BotDetect PHP CAPTCHA from v4.1.0 to v4.2.0
To take advantage of the v4.2.0 changes, you have to update all Captcha library files included in the BotDetect download package – overwrite the old lib folder contents with the updated one.
If you had custom include paths defined in the old lib/botdetect.php file, you should merge your changes from it into the updated botdetect.php file.
If you had custom Captcha settings in the default library configuration file (lib/botdetect/CaptchaConfigDefaults.php), you should merge them into the updated CaptchaConfigDefaults.php file.
[back to the top of the page]
Upgrading BotDetect PHP CAPTCHA from v4.0.0 to v4.1.0
To take advantage of the v4.1.0 changes, you have to update all Captcha library files included in the BotDetect download package – overwrite the old lib folder contents with the updated one.
If you had custom include paths defined in the old lib/botdetect.php file, you should merge your changes from it into the updated botdetect.php file.
If you had custom Captcha settings in the default library configuration file (lib/botdetect/CaptchaConfigDefaults.php), you should merge them into the updated CaptchaConfigDefaults.php file.
[back to the top of the page]
Upgrading BotDetect PHP CAPTCHA from v3.* to v4.*
To take advantage of the v4.0.0 changes, you have to update all Captcha library files included in the BotDetect download package – overwrite the old lib folder contents with the updated one.
If you had custom include paths defined in the old lib/botdetect.php file, you should merge your changes from it into the updated botdetect.php file.
If you had custom Captcha settings in the default library configuration file (lib/botdetect/CaptchaConfig.php), you should merge them into the new CaptchaConfigDefaults.php file.
In BotDetect v4, a $BotDetect object is created for each Captcha instance. $BotDetect object contains actual instance Captcha settings, and there is no need to call
CaptchaConfiguration::GetSettings(); to get them anymore. Therefore, if your current BD3 integration code overrides global Captcha settings in a
local configuration file (CaptchaConfig.php),
when migrating to BD4 you should just use $BotDetect object instead (e.g. $BotDetect->CodeStyle = CodeStyle::Alphanumeric;).
If you were using BotDetect classes having LBD_ prefix, you need to change them to BDC_ (e.g. LBD_CaptchaBase became BDC_CaptchaBase).
If you were using CustomCharset or BannedSequences settings, please note that they have merged into the "disallowed code substrings" setting (i.e. you need to use DisallowedCodeSubstrings setting instead).
If you were using BotDetect client-side instance function Validate(), please note that it has been renamed to StartAjaxValidation() (i.e. input.Captcha.Validate() became input.Captcha.StartAjaxValidation()). Now this function no longer sets the ValidationResult instance property (Ajax validation result is now available through AjaxValidationPassed or AjaxValidationFailed callbacks). You should take a look into the Captcha client-side workflow settings code example for more details.
When deploying the updated Captcha library, clearing Session data generated by the old version is also recommended. Due to changes in some persisted fields, loading Session data with old values could cause errors.
[back to the top of the page]
Upgrading BotDetect PHP CAPTCHA from v3.0.2 to v3.0.3
To take advantage of the v3.0.3 changes, you have to update all Captcha library files included in the BotDetect download package – overwrite the old lib folder contents with the updated one.
If you had custom include paths defined in the old lib/botdetect.php file, you should merge your changes from it into the updated botdetect.php file.
If you had custom Captcha settings in the default library configuration file (lib/botdetect/CaptchaConfig.php), you should merge them into the updated CaptchaConfig.php file.
[back to the top of the page]
Upgrading BotDetect PHP CAPTCHA from v3.0.1 to v3.0.2
To take advantage of the v3.0.2 changes, you have to update all Captcha library files included in the BotDetect download package – overwrite the old lib folder contents with the updated one.
If you had custom include paths defined in the old lib/botdetect.php file, you should merge your changes from it into the updated botdetect.php file.
If you had custom Captcha settings in the default library configuration file (lib/botdetect/CaptchaConfig.php), you should merge them into the updated CaptchaConfig.php file.
[back to the top of the page]
Upgrading BotDetect PHP CAPTCHA from v3.0.0 to v3.0.1
To take advantage of the v3.0.1 changes, you have to update all Captcha library files included in the BotDetect download package – overwrite the old lib folder contents with the updated one.
If you had custom include paths defined in the old lib/botdetect.php file, you should merge your changes from it into the updated botdetect.php file.
If you had custom Captcha settings in the default library configuration file (lib/botdetect/CaptchaConfig.php), you should merge them into the updated CaptchaConfig.php file.
[back to the top of the page]
Upgrading BotDetect PHP CAPTCHA from v3.0.Beta3 to v3.0.0
To take advantage of the v3.0.0 changes, you have to update all Captcha library files included in the BotDetect download package – overwrite the old lib folder contents with the updated one.
If you had custom include paths defined in the old lib/botdetect.php file, you should merge your changes from it into the updated botdetect.php file.
If you had custom Captcha settings in the default library configuration file (lib/botdetect/CaptchaConfig.php), you should merge them into the updated CaptchaConfig.php file.
[back to the top of the page]
Upgrading BotDetect PHP CAPTCHA from v3.0.Beta2 to v3.0.Beta3
To take advantage of the v3.0.Beta3 changes, you have to update all Captcha library files included in the BotDetect download package – overwrite the old lib folder contents with the updated one.
If you had custom include paths defined in the old lib/botdetect.php file, you should merge your changes from it into the updated botdetect.php file.
If you had custom Captcha settings in the default library configuration file (lib/botdetect/CaptchaConfig.php), you should merge them into the updated CaptchaConfig.php file.
[back to the top of the page]
Upgrading BotDetect PHP CAPTCHA from v3.0.Beta1 to v3.0.Beta2
To take advantage of the v3.0.Beta2 changes, you have to update all Captcha library files included in the BotDetect download package – overwrite the old lib folder contents with the updated one.
If you had custom include paths defined in the old lib/botdetect.php file, you should merge your changes from it into the updated botdetect.php file.
If you had custom Captcha settings in the default library configuration file (lib/botdetect/CaptchaConfig.php), you should merge them into the updated CaptchaConfig.php file.
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.
[back to the top of the page]
Upgrading BotDetect PHP CAPTCHA from v3.0.Alpha4 to v3.0.Beta1
To take advantage of the v3.0.Beta1 changes, you have to update all Captcha library files included in the BotDetect download package. Since the library folder names have been changed, you should first backup the Alpha CaptchaLibrary folder, then delete it from your website source and copy downloaded files from the Beta lib folder.
If your PHP forms are running on Linux or another case-sensitive file-system, you should replace all require("BotDetect.php") calls with require("botdetect.php"). And if you had custom include paths defined in the old BotDetect.php file, you should merge your changes from it into the updated botdetect.php file.
[back to the top of the page]
If you had custom Captcha settings in the default library configuration file (CaptchaLibrary/BotDetect/CaptchaConfig.php), you should merge them with the configuration file at the new location (lib/botdetect/CaptchaConfig.php).
If you were using BotDetect classes other than Captcha, CodeStyle, ImageStyle, SoundStyle, SoundFormat, ImageFormat, HelpLinkMode, CaptchaUrls, CaptchaConfiguration, and CaptchaRandomization, please note that they have renamed with the LBD_ prefix (e.g. CaptchaBase became LBD_CaptchaBase) to avoid name clashes with 3rd party and user code.
Due to these internal class name changes, clearing Session data generated by the Alpha version of BotDetect is also recommended before deploying the updated Captcha library. Due to changes in some persisted fields, loading Session data with old values could cause errors for visitors whose Sessions remain active during the upgrade.
[back to the top of the page]
Upgrading BotDetect PHP CAPTCHA from v3.0.Alpha3 to v3.0.Alpha4
To take advantage of the v3.0.Alpha4 changes, you have to update all Captcha library files included in the BotDetect download package. Simply copy the contents of the updated CaptchaLibrary folder over the old one, and check that your pages using Captcha protection work properly.
If you were using the available Captcha persistence medium configuration options to keep Captcha data outside PHP Sessions, please note that the configuration API has changed to only receive peristence function names instead of having them defined in the base configuration file. Changing this should be straightforward, and will allow you to keep your custom persistence functions declared anywhere in your code.
[back to the top of the page]
Upgrading BotDetect PHP CAPTCHA from v3.0.Alpha2 to v3.0.Alpha3
To take advantage of the v3.0.Alpha3 changes, you have to update all Captcha library files included in the BotDetect download package. Simply copy the contents of the updated CaptchaLibrary folder over the old one, and check that your pages using Captcha protection work properly.
When deploying the updated Captcha library, clearing Session data generated by the old version is also recommended. Due to changes in some persisted fields, loading Session data with old values could cause errors.
[back to the top of the page]
Upgrading BotDetect PHP CAPTCHA from v3.0.Alpha1 to v3.0.Alpha2
To take advantage of the v3.0.Alpha2 changes, you have to update all Captcha library files included in the BotDetect download package.
Due to requirements of more advanced PHP Captcha integration scenarios (including the Captcha library in multiple websites, various PHP framework compatibility etc.), including the BotDetect.php file doesn't automatically add the Captcha layout stylesheet anymore. When upgrading your forms to use v3.0.Alpha2, please add the BotDetect stylesheet using the CaptchaUrls::LayoutStylesheetUrl() function call.
Please note that the BotDetect/CaptchaConfig.php file format has been changed, so any changes you made in the v3.0.Alpha1 Captcha configuration will not be automatically upgraded. However, the format changes are minor and replicating your old changes in the new format is completely straightforward.
When deploying the updated Captcha library, clearing Session data generated by the old version is also recommended. Due to changes in some persisted fields, loading Session data with old values could cause errors.
[back to the top of the page]
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 from v4.0.0 to v4.1.0
To take advantage of the v4.1.0 changes, you have to update all Captcha library files included in the BotDetect download package – overwrite the old BotDetect.asp file and BotDetect folder contents with the updated one.
Alternatively, you can also manually remove the old version and deploy the new one.
[back to the top of the page]
BotDetect CAPTCHA v4.1.0 ImageStyle And SoundStyle Properties
You can assign an array to ImageStyle and SoundStyle properties
i.e.:
BotDetect.ImageStyle = BDC_ImageStyles("SunAndWarmAir") Dim imageStyleNames(3)
imageStyleNames(0) = "Chipped"
imageStyleNames(1) = "Fingerprints"
imageStyleNames(2) = "Graffiti"
imageStyleNames(3) = "Bullets"
BotDetect.ImageStyle = BDC_RandomImageStyleFrom(imageStyleNames)
BotDetect.SoundStyle = BDC_SoundStyles("Radio") Dim soundStyleNames(2)
soundStyleNames(0) = "Dispatch"
soundStyleNames(1) = "RedAlert"
soundStyleNames(2) = "Synth"
BotDetect.SoundStyle = BDC_RandomSoundStyleFrom(soundStyleNames)
Upgrading BotDetect ASP CAPTCHA from v3.* to v4.*
To take advantage of the v4.0.0 changes, you have to update all Captcha library files included in the BotDetect download package – overwrite the old BotDetect.asp file and BotDetect folder contents with the updated one.
Alternatively, you can also manually remove the old version and deploy the new one.
If you had custom include paths defined in the old BotDetect/CaptchaClass.asp file, you should merge your changes from it into the updated BotDetect/CaptchaIncludes.asp file.
If you were using BotDetect classes having LBD_ prefix, you need to change them to BDC_ (e.g. LBD_RandomImageStyle becames BDC_RandomImageStyle)
If you had custom Captcha settings in the default library configuration file (BotDetect/CaptchaConfig.asp), you should merge them into the new CaptchaConfig.asp file. CaptchaConfig.asp user override now support CaptchaId-based conditional settings:
- instead of the BD3 universal LBD_CaptchaConfig object, now modifying a BotDetect object separately created for each CaptchaId, available as BDC_CurrentCaptchaId at runtime
If you were using CustomCharset or BannedSequences settings, please note that they have merged into the "disallowed code substrings" setting (i.e. you need to use DisallowedCodeSubstrings setting instead).
If you were using BotDetect client-side instance function Validate(), please note that it has been renamed to StartAjaxValidation() (i.e. input.Captcha.Validate() became input.Captcha.StartAjaxValidation()). Now this function no longer sets the ValidationResult instance property (Ajax validation result is now available through AjaxValidationPassed or AjaxValidationFailed callbacks). You should take a look into the Captcha client-side workflow settings code example for more details.
Additionally, the BotDetect.asp include no longer always adds the BotDetect stylesheet automatically; instead, you can include the BotDetect stylesheet anywhere they would usually add stylesheets to page <head> (but after including the BotDetect Captcha library)
When deploying the updated Captcha library, clearing Session data generated by the old version is also recommended. Due to changes in some persisted fields, loading Session data with old values could cause errors.
[back to the top of the page]
Upgrading BotDetect ASP CAPTCHA from v3.0.17 to v3.0.18
To take advantage of the v3.0.18 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 and Scripts.js have been updated to implement the needed improvements and bugfixes.
[back to the top of the page]
Upgrading BotDetect ASP CAPTCHA from v3.0.16 to v3.0.17
To take advantage of the v3.0.17 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 and Scripts.js have been updated to implement the needed improvements and bugfixes.
[back to the top of the page]
Upgrading BotDetect ASP CAPTCHA from v3.0.15 to v3.0.16
To take advantage of the v3.0.16 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 and Scripts.js have been updated to implement the needed improvements and bugfixes.
[back to the top of the page]
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.
[back to the top of the page]
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.
[back to the top of the page]
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.
[back to the top of the page]
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.
[back to the top of the page]
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.
[back to the top of the page]
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).
[back to the top of the page]
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.
[back to the top of the page]
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.
[back to the top of the page]
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.
[back to the top of the page]
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.
[back to the top of the page]
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.
[back to the top of the 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.
[back to the top of the page]
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.
[back to the top of the page]
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.
[back to the top of the page]
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.
[back to the top of the page]
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
[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 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.
[back to v3.0.0 migration guide contents]
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" />
[back to v3.0.0 migration guide contents]
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()
[back to v3.0.0 migration guide contents]
BotDetect CAPTCHA v3.0.0 Interface Naming
CodeType has been renamed to CodeStyleCodeType.AlphaNumeric has been renamed to CodeStyle.AlphanumericTextStyle 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.FingerprintsTextStyle.Spiderweb has been renamed to ImageStyle.SpiderWebTextStyle.SunRays has been renamed to ImageStyle.SunraysTextStyle.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 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
[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.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.PostInitBotDetect.PreReloadImageBotDetect.PostReloadImageBotDetect.PrePlaySoundBotDetect.PreAjaxValidateBotDetect.AjaxValidationFailedBotDetect.AjaxValidationPassedBotDetect.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 example 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 example), you would add your handler to the
BotDetect.PostReloadImage client-side event by using:
BotDetect.RegisterCustomHandler('PostReloadImage',
function() {
// your code goes here
}
);
[back to the top of the page]
