How To Troubleshoot BotDetect ASP.NET CAPTCHA Issues
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:
- There are several BotDetect Captcha troubleshooting files that need to be deployed with your application.
- There are additional BotDetect Captcha troubleshooting configuration changes that have to be made to your application configuration.
- You should review the general BotDetect Captcha troubleshooting guidelines to ensure you're using the troubleshooting approach that fits the problem you are trying to diagnose.
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
Beside the base BotDetect assembly for the .NET version you are running (for example,
C:\Program Files\Captcha Inc\BotDetect 4 CAPTCHA Component\Asp.Net\.NET4.0\BotDetect.dll), you will also need the files from the
Troubleshooting subfolder (
C:\Program Files\Captcha Inc\BotDetect 4 CAPTCHA Component\Asp.Net\.NET4.0\Troubleshooting in the same case).
BotDetect.Troubleshooting.dllcontains 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
log4net.dllis the main log4net assembly, and should be deployed to the
Binsubfolder with other assemblies.
log4net.configis the log4net configuration file, defining loggers and outputs. It should be copied to your application's root folder, along with your
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:
- IIS 6.0 or 7.0:
- IIS 7.5: the
ApplicationPoolIdentityuser account for your application's AppPool
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
BotDetect CAPTCHA Troubleshooting Configuration
BotDetect Troubleshooting is configured through your application's
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.
<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) --> <remove name="BotDetectTroubleshootingModule"/> <add name="BotDetectTroubleshootingModule" preCondition="integratedMode" type="BotDetect.Web.CaptchaTroubleshootingModule, BotDetect"/>
Register the BotDetect and Log4Net Configuration SectionsAdd the
log4netconfiguration section declarations to the
<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"/>
Configure Log4Net Output SettingsLog4Net settings will be loaded from the mentioned
log4net.configfile. To use the provided file copied from the BotDetect installation, you just have to define a
<log4net>element below the closing
<!-- 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.
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
<!-- 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" />
<captchaLogging> element includes the following options:
errorLoggingEnabledattribute specifies should BotDetect errors be logged to the
error.txtfile or not.
traceEnabledattribute specifies should the BotDetect event trace be logged to the
debug.txtfile or not. If you only want to log BotDetect errors, set this value to
eventFilterspecifies 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).
loggingProviderspecifies 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.
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
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.
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.
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.