How To Troubleshoot BotDetect ASP.NET CAPTCHA Issues

For troubleshooting purposes, BotDetect ASP.NET Captcha allows detailed logging of Captcha events and errors. The default BotDetect logging provider is based on the open source log4net project.

You can also test all troubleshooting options described here by running the BotDetect ASP.NET Captcha troubleshooting code example included in the BotDetect installation.

When using BotDetect Captcha troubleshooting:

BotDetect CAPTCHA Troubleshooting Files Deployment

To keep things simple, we'll describe how to write all BotDetect logs to text files located in the application folder.

BotDetect CAPTCHA Troubleshooting Required Files

Download the BotDetect ASP.NET CAPTCHA Generator archive. The root folder of the extracted archive is referred as the <BDC-DIR>.

The BotDetect binaries are located in:
<BDC-DIR>/v4.4.2/lgcy-on-lgcy/bin/ folder.

Copy the BotDetect.dll files to the /your-app-backend-folder/bin/ folder -- and then reference it in your project.

The troubleshooting binaries are located in:
<BDC-DIR>/v4.4.2/lgcy-on-lgcy/troubleshooting/ folder.

Copy all files to the /your-app-backend-folder/bin/ folder -- and then reference assemblies in your project.

  • BotDetect.Troubleshooting.dll contains the log4net BotDetect logging provider implementation. It's separate from the main BotDetect assembly so log4net is not a base dependency. It should be deployed in your application's Bin subfolder.
  • log4net.dll is the main log4net assembly, and should be deployed to the Bin subfolder with other assemblies.
  • log4net.config is the log4net configuration file, defining loggers and outputs. It should be copied to your application's root folder, along with your web.config file.
  • log4net license.txt and log4net notice.txt are log4net licensing files, which are included to meet the log4net terms of use. The log4net license can also be can be found on the official log4net site.

[back to the top of the page]

BotDetect CAPTCHA Troubleshooting Output Log Files

We will log BotDetect errors to a text file called error.txt, and trace Captcha events to a text file called debug.txt. Both of these files should be created in the same folder the log4net.config file is in.

You should also make sure the appropriate IIS user account has Modify permissions for the files. Which user account is used depends on the IIS version you are running and your IIS configuration. By default, you will use:

  • IIS 5.0 or 5.1: ASPNET
  • IIS 6.0 or 7.0: NETWORK SERVICE
  • IIS 7.5, 8.0, 8.5, 10: the ApplicationPoolIdentity user account for your application's AppPool
You can set the required permissions from the command line by running: 
cacls error.txt /G "ASPNET":C /E /C
cacls error.txt /G "NETWORK SERVICE":C /E /C
cacls error.txt /G "IIS AppPool\TODO:AppicationPoolName":C /E /C

cacls debug.txt /G "ASPNET":C /E /C
cacls debug.txt /G "NETWORK SERVICE":C /E /C
cacls debug.txt /G "IIS AppPool\TODO:AppicationPoolName":C /E /C

[back to the top of the page]

BotDetect CAPTCHA Troubleshooting Configuration

BotDetect Troubleshooting is configured through your application's web.config file.

Register the BotDetect Error Logging HttpModule

To allow BotDetect errors to be logged, we have to hook up a global application error handler which will recognize BotDetect errors (which is possible since they are all sub-classes of BotDetect.BaseException) and pass them to the configured BotDetect logging provider. This functionality is implemented as a custom BotDetect HttpModule that needs to be included in your application.

Since this module ignores errors which don't inherit from BotDetect.BaseException and re-throws BotDetect errors after logging them, it won't affect the error handling mechanisms you chose for your ASP.NET application.

HttpModule Registration

<system.web>
  <httpModules>
    <!-- Register the HttpModule used for BotDetect error logging -->
    <add name="BotDetectTroubleshootingModule" 
      type="BotDetect.Web.CaptchaTroubleshootingModule, BotDetect"/>

IIS 7 HttpModule Registration

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

[back to the top of the page]

Register the BotDetect and Log4Net Configuration Sections

Add the botDetect and log4net configuration section declarations to the <configSections> element: 
<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"/>

[back to the top of the page]

Configure Log4Net Output Settings

Log4Net settings will be loaded from the mentioned log4net.config file. To use the provided file copied from the BotDetect installation, you just have to define a <log4net> element below the closing </configSections> tag: 
<!-- log4net settings are loaded from a separate config file -->
<log4net configSource="log4net.config"/>

If logging to text files is not suitable for your purposes, you can also write logs to a database, the console, the Windows event log etc. There are many log4net options and settings you can use, and we encourage you to learn more about them in the log4net manual.

[back to the top of the page]

Configure BotDetect Logging Settings

BotDetect logging options are exposed through the <botDetect> configuration section, along with other BotDetect settings. For the most detailed logging available, paste the following just below the <log4net> element:

<!-- BotDetect Captcha settings can be configured in this section -->
<!-- Register the log4net BotDetect logging provider -->
  <botDetect
   loggingProvider="BotDetect.Logging.Log4NetLoggingProvider, BotDetect.Troubleshooting"
   errorLoggingEnabled="true"
   traceLoggingEnabled="true"
   traceLoggingEventFilter=".*"
   helpLinkEnabled="true"
   helpLinkMode="image"
   />

The <captchaLogging> element includes the following options:

  • The errorLoggingEnabled attribute specifies should BotDetect errors be logged to the error.txt file or not.
  • The traceEnabled attribute specifies should the BotDetect event trace be logged to the debug.txt file or not. If you only want to log BotDetect errors, set this value to false.
  • The eventFilter specifies a regular expression used to filter which Captcha events will be traced. If you only want to trace Captcha validation attempts for example, specify eventFilter="UserInput" (which matches both "ValidatingUserInput" and "ValidatedUserInput", but none of the other event names).
  • The loggingProvider specifies which logging provider class will be used to write BotDetect logs. If you don't want to use log4net for example, it's also possible to use custom BotDetect.Logging.ILoggingProvider implementations suited to your purposes.

[back to the top of the page]

BotDetect CAPTCHA Troubleshooting Guidelines

There are several things you should keep in mind when using the BotDetect troubleshooting facilities to diagnose Captcha problems in your applications.

Using BotDetect CAPTCHA Error Logging on Production Servers

BotDetect Captcha error logging can be useful to detect any edge cases or server configuration issues that might be affecting BotDetect on your servers.

The troubleshooting module shipped with BotDetect only handles errors occurring in BotDetect internal code, and should not (in principle) significantly impact your application performance.

However, this may vary depending on your server load and configuration settings; if you find that it's slowing your application down, you can simply turn it off by removing the mentioned <httpModules> element from your web.config file.

Setting errorLoggingEnabled="false" in the captchaLogging element will prevent the error log from being written, but the CaptchaTroubleshootingModule will still be registered at each application initialization, so it's better to also remove the HttpModule registration if you won't use it.

[back to the top of the page]

Using BotDetect CAPTCHA Event Tracing on Production Servers

Captcha event tracing can be useful to track Captcha workflow issues (most commonly related to Captcha validation), and should only be turned on for limited periods of time, during troubleshooting and debugging.

To provide detailed information required to properly diagnose Captcha generation and validation problems, event tracing logs several kilobytes of text per single Captcha generation or validation operation. Captcha event logging should not be left running for longer periods of time on production servers, since it will quickly generate very large log files.

So only set traceEnabled="true" during short testing periods, and use the eventFilter value to only trace events you are interested in. The more focused the generated log file, the easier it is to track state changes related to the problem you are having.

If you're trying to track down a problem that only occurs for some users, it also helps to copy all event entries related to the user in question (by visitor IP and user agent) to a separate file. Comparing this data to your IIS logs can also be helpful in some cases.

[back to the top of the page]

Diagnosing BotDetect CAPTCHA Problems in Your Application

If you are experiencing difficulties with BotDetect Captcha protection, first try to reproduce the problem using one of the example projects shipped with BotDetect installations instead of your application code.

Try changing the example code to be more like the code you are using – does the problem start occurring after a particular change? If the problem occurs only in your application and never when using the examples, there is probably an error in your code that is using BotDetect Captcha protection, and you should review it carefully.

Another important distinction is whether the problem is client-side or server-side related:

  • If the issue occurs for all users and can easily be traced in BotDetect log files, it's probably server-side related.
  • If the issue occurs only for some users, and the BotDetect log files are not helpful, it's probably client-side related.

While server-side issues can be tracked down using BotDetect troubleshooting and comparing your application code to BotDetect example projects, client-side issues are more commonly found by isolating affected clients (for example, only IE 6.0 users), and testing does the same problem occur when using the BotDetect online demo in the same client.

[back to the top of the page]


© Captcha, Inc. 2004-2023. All rights reserved.

BotDetect, BotDetect CAPTCHA, Lanap, Lanap CAPTCHA, Lanap BotDetect, Lanap BotDetect CAPTCHA, Lanapsoft, Lanapsoft CAPTCHA, Lanapsoft BotDetect, Lanapsoft BotDetect CAPTCHA, and Lanap Software are trademarks of Captcha, Inc. All other product, brand, and company names are mentioned for identification purposes only and are trademarks or registered trademarks of their respective owners.

Captcha, Inc. -- formerly: Lanapsoft, Inc. / Lanap, Inc.