BotDetect ASP.NET CAPTCHA Migration Guide (BotDetect v2.0; deprecated)

documentation > asp.net captcha > botdetect 2.0

This page contains instructions for updating your BotDetect ASP.NET CAPTCHA installation to newer versions.

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

Version 2.0.15 of the BotDetect ASP.NET CAPTCHA contains several bugfixes, which only require updating the Lanap.BotDetect.dll and Lanap.BotDetect.Troubleshooting.dll assemblies in your projects to the new version. For a detailed list of changes included in this release, please consult the v2.0.15 release notes.

[back to top]

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

Version 2.0.14 of the BotDetect ASP.NET CAPTCHA contains several changes which require additional checks besides updating the Lanap.BotDetect.dll assembly to the new version. For a detailed list of changes included in this release, please consult the v2.0.14 release notes.

CAPTCHA Reload Improvements

When you upgrade the Lanap.BotDetect.dll assembly in your projects to the new version, the Reload Captcha button will automatically start using the new, language-independent animation. If you also want to improve the usability of your forms by clearing the user Captcha code input on Reload button clicks, you need to add the following code to your page's Page_PreRender handler:

[C#]

// clear user input on Reload button clicks
string scriptTemplate = @"
  function LBD_ClearUserInput() {{
    var LBD_textBox = document.getElementById('{0}');
    if(LBD_textBox) {{
      LBD_textBox.value = '';
    }}
  }}
  LBD_RegisterHandler('PreReloadCaptchaImage', LBD_ClearUserInput);
";
string script = String.Format(scriptTemplate, CodeTextBox.ClientID);
if (!Page.ClientScript.IsStartupScriptRegistered(
    "CaptchaReloadClearInput"))
{
  Page.ClientScript.RegisterStartupScript(this.GetType(), 
    "CaptchaReloadClearInput", script, true);
}

[VB.NET]

' clear user input on Reload button clicks
Dim scriptTemplate As String
scriptTemplate = "function LBD_ClearUserInput() {{" & _
  "  var LBD_textBox = document.getElementById('{0}');" & _
  "  if(LBD_textBox) {{" & _
  "    LBD_textBox.value = '';" & _
  "  }}" & _
  "}}" & _
  "LBD_RegisterHandler('PreReloadCaptchaImage', LBD_ClearUserInput);"

Dim script As String
script = String.Format(scriptTemplate, CodeTextBox.ClientID)
If (Not Page.ClientScript.IsStartupScriptRegistered( _
    "CaptchaReloadClearInput")) Then
  Page.ClientScript.RegisterStartupScript(Me.GetType(), _ 
    "CaptchaReloadClearInput", script, True)
End If

You also have to replace 'CodeTextBox' in the above code with the ID of the TextBox control you use on your page.

CAPTCHA Error Logging

The BotDetect Troubleshooting utility has been updated to also handle logging Captcha validation attempts in v2.0.14. To adjust for this change, the custom HttpModule has been renamed from Lanap.BotDetect.Troubleshooting.ErrorTrackingModule to Lanap.BotDetect.Troubleshooting.LoggingModule.

When upgrading, besides deploying the new version of the Lanap.BotDetect.Troubleshooting.dll assembly (v1.0.14), you will also have to update your web.config files, replacing (<system.web>):

<add type="Lanap.BotDetect.Troubleshooting.ErrorTrackingModule, 
  Lanap.BotDetect.Troubleshooting" name="ErrorTrackingModule" />

with:

<add type="Lanap.BotDetect.Troubleshooting.LoggingModule, 
  Lanap.BotDetect.Troubleshooting" name="LoggingModule" />

and (<system.webServer>):

<remove name="ErrorTrackingModule"/>
<add name="ErrorTrackingModule" preCondition="integratedMode" 
  type="Lanap.BotDetect.Troubleshooting.ErrorTrackingModule, 
    Lanap.BotDetect.Troubleshooting"/>

with:

<remove name="LoggingModule"/>
<add name="LoggingModule" preCondition="integratedMode" 
  type="Lanap.BotDetect.Troubleshooting.LoggingModule, 
    Lanap.BotDetect.Troubleshooting"/>

If you want to learn how to use the new functionality for logging all Captcha validation attempts, please consult the logging BotDetect ASP.NET CAPTCHA validation attempts how to guide.

ASP.NET MVC CAPTCHA Implementations

To make it simpler to add Captcha validation to ASP.NET MVC applications, v2.0.14 BotDetect ASP.NET MVC Captcha code samples use a custom ActionFilterAttribute.

To upgrade your ASP.NET MVC application to use BotDetect Captcha v2.0.14:

Deploy new versions of the BotDetectLayout.css and BotDetectScript.js files from the Content sample subfolder
Add the CaptchaValidationAttribute source file (.cs or .vb) from the Attributes sample subfolder to your application

Mark the Captcha-protected action in your Controller with this attribute, passing the Id of the user input control as the first parameter, while the second is the CaptchaId value of the Captcha control used. For example, in the sample projects we changed:

[C#]

[AcceptVerbs(HttpVerbs.Post)]
public ActionResult Register(string userName, string email, 
  string password, string confirmPassword, string captchaCode)
{

[VB.NET]

<AcceptVerbs(HttpVerbs.Post)> _
Function Register(ByVal userName As String, ByVal email As String, _
  ByVal password As String, ByVal confirmPassword As String, _ 
  ByVal captchaCode As String) As ActionResult

to:

[C#]

[AcceptVerbs(HttpVerbs.Post)]
[CaptchaValidation("captchaCode", "RegistrationCaptcha")]
public ActionResult Register(string userName, string email, 
  string password, string confirmPassword, string captchaCode)
{

[VB.NET]
		
<AcceptVerbs(HttpVerbs.Post)> _
<CaptchaValidation("captchaCode", "RegistrationCaptcha")> _
Function Register(ByVal userName As String, ByVal email As String, _
  ByVal password As String, ByVal confirmPassword As String, _
  ByVal captchaCode As String) As ActionResult

Update the Captcha validation method in your Controller to use the new, RouteData based approach. For example, in the sample projects we changed:

[C#]

/// Captcha validation
Lanap.BotDetect.MvcCaptcha captchaInstance = 
  new Lanap.BotDetect.MvcCaptcha("RegistrationCaptcha");
	
string captchaInstanceId = 
  Request.Form[captchaInstance.CaptchaIdKey];

// the Captcha is only validated if it was included on the page
if (!(String.IsNullOrEmpty(captchaInstanceId)))
{
  if (!(captchaInstance.Validate(captchaCode, captchaInstanceId)))
  {
    ModelState.AddModelError("captchaCode", 
      "The CAPTCHA code was incorrect!");
  }
}

[VB.NET]

'Captcha validation
Dim captchaInstance As Lanap.BotDetect.MvcCaptcha
Dim captchaInstanceId As String

captchaInstance = New _ 
  Lanap.BotDetect.MvcCaptcha("RegistrationCaptcha")

captchaInstanceId = Request.Form(captchaInstance.CaptchaIdKey)

' the Captcha is only validated if it was included on the page
If (Not (String.IsNullOrEmpty(captchaInstanceId))) Then
  If (Not (captchaInstance.Validate(captchaCode, captchaInstanceId))) Then
    ModelState.AddModelError("captchaCode", _ 
      "The CAPTCHA code was incorrect!")
  End If
End If

to:

[C#]

/// Captcha validation
if (!(bool)this.RouteData.Values["captchaValid"])
{
  ModelState.AddModelError("captchaCode", 
    "The CAPTCHA code was incorrect!");
}

[VB.NET]

'Captcha validation
If (Not (CType(Me.RouteData.Values("captchaValid"), Boolean))) Then
  ModelState.AddModelError("captchaCode", _
    "The CAPTCHA code was incorrect!")
End If

If you want to improve the Reload Captcha button to automatically clear the user input, you can add the script declaration to your View. For example, in the sample projects we used:

<%= Html.Captcha(registrationCaptcha) %gt;
<p>
  <label for="captchaCode">Type the characters you see in the 
    picture:</label>
  <%= Html.TextBox("captchaCode") %>
  <%= Html.ValidationMessage("captchaCode")%>
</p>
<script type="text/javascript">
  function LBD_ClearUserInput() {
    var LBD_textBox = document.getElementById('captchaCode');
    if(LBD_textBox) {
      LBD_textBox.value = '';
    }
  }
  LBD_RegisterHandler('PreReloadCaptchaImage', LBD_ClearUserInput);
</script>
<%

[back to top]

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

Version 2.0.13 of the BotDetect ASP.NET CAPTCHA contains several bug-fixes, some of which require additional checks besides updating the Lanap.BotDetect.dll assembly to the new version. For a detailed list of changes included in this release, please consult the v2.0.13 release notes.

CAPTCHA Randomization

Several issues were found with the PreDrawCaptchaImage event handler used for Captcha image randomization. In all your pages registering handlers for this event, please update the code from:

[C#]

void SampleCaptcha_PreDrawCaptchaImage(object sender, EventArgs e)
{
  captcha.CodeLength = RandomizationHelper.GetRandomCodeLength(4, 6);
  // other randomizations...
}

[VB.NET]

Protected Sub SampleCaptcha_PreDrawCaptchaImage(ByVal sender As 
  System.Object, ByVal e As System.EventArgs)
  
  captcha.CodeLength = RandomizationHelper.GetRandomCodeLength(4, 6)
  ' other randomizations...
End Sub

to:

[C#]

void SampleCaptcha_PreDrawCaptchaImage(object sender, EventArgs e)
{

  ICaptcha captcha = sender as ICaptcha;
  if (captcha.CaptchaId != SampleCaptcha.CaptchaId)
  {
    return;
  }

  captcha.CodeLength = RandomizationHelper.GetRandomCodeLength(4, 6);
  // other randomizations...
}

[VB.NET]

Protected Sub SampleCaptcha_PreDrawCaptchaImage(ByVal sender As 
  System.Object, ByVal e As System.EventArgs)
	
  Dim captcha As ICaptcha = sender
  If (captcha.CaptchaId <> SampleCaptcha.CaptchaId) Then
    Return
  End If

  captcha.CodeLength = RandomizationHelper.GetRandomCodeLength(4, 6)
  ' other randomizations...
End Sub

Also replace SampleCaptcha in the above code snippet with the ID of the Captcha control used on each page.

Captcha Control Layout

To fix layout bugs occurring when multiple Captcha controls are placed within the same page, all BotDetect CSS declarations have been updated to use CSS classes instead of CSS ids. If you had BotDetect CSS declarations overriding the default ones (for example, to show the reload button to the right of the speaker button instead of below it), please update them accordingly.

[back to top]

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

Version 2.0.12 of the BotDetect ASP.NET CAPTCHA contains several bugfixes, which only require updating the Lanap.BotDetect.dll assembly to the new version. For a detailed list of changes included in this release, please consult the v2.0.12 release notes.

[back to top]

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

Version 2.0.11 of the BotDetect ASP.NET CAPTCHA introduces several changes that require your attention when upgrading from older versions. For a detailed list of changes included in this release, please consult the v2.0.11 release notes.

CAPTCHA Randomization

The code used to randomize the CAPTCHA image algorithm, Captcha code length etc. has been updated. Instead of randomizing the CAPTCHA properties in Page methods (Page_Load, Page_PreRender, etc.), the randomization code should be placed in a new Captcha_PreDrawCaptchaImage event handler. You can see the code changes in the updated CAPTCHA Randomization sample project coming with the BotDetect installation.

This is necessary since the Page handlers are only called when the whole page life-cycle is executed on the server, and not on every CAPTCHA image HttpHandler execution. This means the CAPTCHA randomization placed in Page methods is bypassed when the whole .aspx page is not loaded. For example, this happens when clicking the Reload CAPTCHA button, or when a bot accesses the CAPTCHA image Url directly, without loading the page. Updating the CAPTCHA randomization code will ensure the CAPTCHA properties are randomized for every CAPTCHA image generated.

CAPTCHA HttpHandler Path

This release of BotDetect includes the ability to change the full CAPTCHA HttpHandler request path. It is recommended to change this path to a unique value for each of your applications, since that can improve the CAPTCHA security.

For example, if a bot tries scanning many websites for the default LanapCaptcha.aspx path, it becomes slightly more difficult to automatically recognize your site as using BotDetect CAPTCHA protection.

To change the BotDetect CAPTCHA HttpHandler path to CustomCaptchaHandler.ashx (for example):

Add the following lines to the <appSettings> section of the web.config file:

<appSettings>
  <add key="LBD_RequestPath" value="CustomCaptchaHandler.ashx" />
</appSettings>

Update the HttpHandler registration in the <system.web> section of the web.config file:

<httpHandlers>
  <add verb="*" path="CustomCaptchaHandler.ashx" 
    type="Lanap.BotDetect.CaptchaHandler, Lanap.BotDetect"/>
</httpHandlers>

SharePoint Users

Since the LBD_RequestExtension setting has been replaced by the LBD_RequestPath setting in the 2.0.11 release, you should update your web.config settings accordingly, replacing

<appSettings>
  <add key="LBD_RequestPath" value=".ashx" />
</appSettings>
<web.config>
  <httpHandlers>
    <add verb="*" path="LanapCaptcha.ashx" 
      type="Lanap.BotDetect.CaptchaHandler, Lanap.BotDetect" />
  </httpHandlers>

with

<appSettings>
  <add key="LBD_RequestPath" value="LanapCaptcha.ashx" />
</appSettings>
<web.config>
  <httpHandlers>
    <add verb="*" path="LanapCaptcha.ashx" 
      type="Lanap.BotDetect.CaptchaHandler, Lanap.BotDetect" />
  </httpHandlers>

[back to top]

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

Version 2.0.10 of the BotDetect ASP.NET CAPTCHA introduces several changes that require your attention when upgrading from older versions. For a detailed list of changes included in this release, please consult the v2.0.10 release notes.

Captcha control layout

Since the Lanap.BotDetect.Captcha control output has been rewritten to produce semantic, table-less HTML, and most layout declarations have been moved to a separate CSS stylesheet, it is possible the Captcha control will fit differently inside your page layout (might be a few pixels off, etc). This is easily fixed by adjusting the CSS style declarations of your page.

Reload CAPTCHA Button

Also, since the CAPTCHA code changing button has been added to the control and is enabled by default, you should, for example:

Review how the control fits inside your page layout horizontally, if you don't have audio CAPTCHA enabled. The reload icon is rendered to the right of the CAPTCHA image.
If you have audio CAPTCHA enabled and are using a CAPTCHA image height of less than 50 pixels, please review how does the reload icon fit inside your page layout vertically. If you need to show the reload icon to the right of the speaker icon (instead of below it), follow the horizontal icon layout instructions.

ASP.NET Ajax users

Since UpdatePanel compatibility is now added to the built-in Captcha control, the AjaxCaptcha workaround described in the UpdatePanel FAQ entry is no longer required. While this workaround will continue to work, it is now considered deprecated and it's recommended to stop using it. To do so, simply revert the changes used for the workaround.

Also, if you disabled the audio CAPTCHA inside an UpdatePanel because of Firefox compatibility issues, you can now enable it - this problem was caused by a bug in the QuickTime v7.1.6 plug-in for Firefox, and is fixed in later versions of the player.

SharePoint users

Previous versions of BotDetect required minor source code modifications to change the CAPTCHA handler request extension, since SharePoint doesn't allow .aspx requests to map to a non-SharePoint HttpHandler. This can now be achieved with the official build of BotDetect, by specifying the preferred extension to use in the web.config file - for example:

<appSettings>
  <add key="LBD_RequestPath" value=".ashx" />
</appSettings>
<web.config>
  <httpHandlers>
    <add verb="*" path="LanapCaptcha.ashx" 
      type="Lanap.BotDetect.CaptchaHandler, Lanap.BotDetect" />
  </httpHandlers>

will change the CAPTCHA sound and image request requests to use an .ashx extension. When using different extensions, don't forget to make sure they are mapped to the ASP.NET Runtime in the IIS properties for the website.

Also note that we have published instructions for creating a SharePoint Web Part with BotDetect CAPTCHA along with this update.

[back to top]