BotDetect ASP.NET CAPTCHA Configuration API Reference (BotDetect v3.0; deprecated)

BotDetect ASP.NET Captcha exposes a configuration facade over the underlying configuration implementation reading BotDetect settings from .NET .config files.

BotDetect.CaptchaConfiguration

Main BotDetect configuration access point.

BotDetect.CaptchaConfiguration Class Reference
BotDetect.CaptchaConfiguration public property readonly static BotDetect.Configuration. ICaptchaCodesConfiguration CaptchaCodes Encapsulates BotDetect Captcha code settings.
BotDetect.CaptchaConfiguration public property readonly static BotDetect.Configuration. ICaptchaImageConfiguration CaptchaImage Encapsulates BotDetect Captcha image settings.
BotDetect.CaptchaConfiguration public property readonly static BotDetect.Configuration. ICaptchaSoundConfiguration CaptchaSound Encapsulates BotDetect Captcha sound settings.
BotDetect.CaptchaConfiguration public property readonly static BotDetect.Configuration. ICaptchaLoggingConfiguration CaptchaLogging Encapsulates BotDetect Captcha logging settings.
BotDetect.CaptchaConfiguration public property readonly static BotDetect.Configuration. ICaptchaReloading Configuration CaptchaReloading Encapsulates BotDetect Captcha reloading settings.
BotDetect.CaptchaConfiguration public property readonly static BotDetect.Configuration. ICaptchaEncryption Configuration CaptchaEncryption Encapsulates BotDetect Captcha encryption settings.
BotDetect.CaptchaConfiguration public property readonly static BotDetect.Configuration. ICaptchaRequestFilter Configuration CaptchaRequestFilter Encapsulates BotDetect Captcha request filtering settings.
BotDetect.CaptchaConfiguration public property readonly static BotDetect.Configuration. ICaptchaHttpHandler TroubleshootingConfiguration CaptchaHttpHandler Troubleshooting Encapsulates BotDetect Captcha HttpHandler state troubleshooting settings.
BotDetect.CaptchaConfiguration public property readonly static BotDetect.Configuration. ICaptchaSession TroubleshootingConfiguration CaptchaSession Troubleshooting Encapsulates BotDetect Captcha Session state troubleshooting settings.
BotDetect.CaptchaConfiguration public property readonly static BotDetect.Configuration. ICaptchaUrlConfiguration CaptchaUrls Encapsulates BotDetect Captcha Url settings.
BotDetect.CaptchaConfiguration public property readonly static BotDetect.Configuration. ICaptchaUserInput Configuration CaptchaUserInput Encapsulates BotDetect Captcha user input settings.

BotDetect.Configuration.ICaptchaCodesConfiguration

Captcha code configuration settings.

BotDetect.Configuration.ICaptchaCodesConfiguration Interface Reference
BotDetect.Configuration.ICaptchaCodesConfiguration public property readonly int Timeout Captcha code timeout in seconds – the Captcha can only be successfully solved within the specified time after generation. This is an optional security improvement that narrows the window of opportunity for attacks based on re-using the Captcha image on another site controlled by the attacker, or similar human-solver-based attacks on Captcha-protected forms.
BotDetect.Configuration.ICaptchaCodesConfiguration public property readonly BotDetect.Configuration. ICharacterSet CollectionConfiguration CharacterSets Encapsulates custom Captcha character set settings
BotDetect.Configuration.ICaptchaCodesConfiguration public property readonly BotDetect.Configuration. ITestModeConfiguration TestMode Encapsulates Captcha Test Mode settings

BotDetect.Configuration.ICharacterSetCollectionConfiguration

Defines custom character sets for Captcha code generation. You can then map the custom character sets defined here to appropriate Captcha control instances by name in calling code.

BotDetect.Configuration.ICharacterSetCollectionConfiguration Interface Reference
BotDetect.Configuration.ICharacterSetCollectionConfiguration public property readonly BotDetect.Configuration. ICharacterSetConfiguration this[string name] Access a single custom character set declaration by name

BotDetect.Configuration.ICharacterSetConfiguration

A single custom character set declaration.

BotDetect.Configuration.ICharacterSetConfiguration Interface Reference
BotDetect.Configuration.ICharacterSetConfiguration public property readonly string Name custom charset name, by which it can be applied to Captcha instances
BotDetect.Configuration.ICharacterSetConfiguration public property readonly System.Collections. Specialized. StringCollection Alphanumeric

Collection of alphanumeric characters.

If you don't want to distinguish between code styles, you can specify the alphanumeric characters only and they will be used for all Captcha codes regardless of the CodeStyle value set

BotDetect.Configuration.ICharacterSetConfiguration public property readonly System.Collections. Specialized. StringCollection Alpha Collection of characters used for "Alpha" CodeStyle codes
BotDetect.Configuration.ICharacterSetConfiguration public property readonly System.Collections. Specialized. StringCollection Numeric Collection of characters used for "Numeric" CodeStyle codes

BotDetect.Configuration.ITestModeConfiguration

Test mode configuration settings.

BotDetect.Configuration.ITestModeConfiguration Interface Reference
BotDetect.Configuration.ITestModeConfiguration public property readonly bool Enabled

Test mode, set to "true" during automated testing of your page to make the Captcha trivially solvable (always use the "TEST" code).

Be careful not to enable this on production websites since it will allow trivial Captcha bypassing for bots but human users will still have to solve it.

BotDetect.Configuration.ICaptchaImageConfiguration

Captcha image configuration settings.

BotDetect.Configuration.ICaptchaImageConfiguration Interface Reference
BotDetect.Configuration.ICaptchaImageConfiguration public property readonly BotDetect.Configuration. ILocalizedString Configuration Tooltip Custom Captcha image alt text, locale-dependent

BotDetect.Configuration.ICaptchaSoundConfiguration

Captcha sound configuration settings.

BotDetect.Configuration.ICaptchaSoundConfiguration Interface Reference
BotDetect.Configuration.ICaptchaSoundConfiguration public property readonly bool Enabled Are Captcha sounds enabled
BotDetect.Configuration.ICaptchaSoundConfiguration public property readonly int StartDelay Starting delay of the Captcha sound playback
BotDetect.Configuration.ICaptchaSoundConfiguration public property readonly SoundRegenerationMode SoundRegenerationMode Determines how will multiple consecutive requests for audio Captcha with the same Captcha code be handled by BotDetect
BotDetect.Configuration.ICaptchaSoundConfiguration public property readonly BotDetect.Configuration. ISoundPackagesConfiguration SoundPackages Encapsulates Captcha sound package settings
BotDetect.Configuration.ICaptchaSoundConfiguration public property readonly BotDetect.Configuration. ICaptchaSoundIcon Configuration SoundIcon Encapsulates Captcha sound icon settings

BotDetect.Configuration.ISoundPackagesConfiguration

BotDetect Captcha sound packages configuration settings.

BotDetect.Configuration.ISoundPackagesConfiguration Interface Reference
BotDetect.Configuration.ISoundPackagesConfiguration public property readonly string FolderPath Custom sound packages folder. You can reuse a single location for all ASP.NET applications using BotDetect Captcha on the same server, and don't have to copy the SoundPackage files to each and every application's Bin folder.
BotDetect.Configuration.ISoundPackagesConfiguration public property readonly bool WarnAboutMissing SoundPackages

Captcha sounds in BotDetect 3.0 require locale-dependent pronunciation SoundPackage (.bdsp) files. If the required SoundPackage in not deployed, the sound icon is not clickable and displays a warning tooltip by default.

If you want to disable this warning and simply not display the sound Captcha icon at all for locales whose pronunciations are not deployed with the application, set this property to "false".

BotDetect.Configuration.ICaptchaSoundIconConfiguration

Captcha sound icon configuration settings.

BotDetect.Configuration.ICaptchaSoundIconConfiguration Interface Reference
BotDetect.Configuration.ICaptchaSoundIconConfiguration public property readonly string FilePath Custom Captcha sound icon image file
BotDetect.Configuration.ICaptchaSoundIconConfiguration public property readonly int IconWidth Custom Captcha sound icon image width (affects icon layout)
BotDetect.Configuration.ICaptchaSoundIconConfiguration public property readonly BotDetect.Configuration. ILocalizedString Configuration Tooltip Custom Captcha sound icon title, locale dependent

BotDetect.Configuration.ICaptchaReloadingConfiguration

Captcha reloading configuration settings.

BotDetect.Configuration.ICaptchaReloadingConfiguration Interface Reference
BotDetect.Configuration.ICaptchaReloadingConfiguration public property readonly bool Enabled Is Captcha reloading enabled
BotDetect.Configuration.ICaptchaReloadingConfiguration public property readonly BotDetect.Configuration. ICaptchaReloadIcon Configuration ReloadIcon Encapsulates Captcha reload icon settings
BotDetect.Configuration.ICaptchaReloadingConfiguration public property readonly BotDetect.Configuration. IAutoReloadExpired CaptchasConfiguration AutoReloadExpiredCaptchas Encapsulates Captcha auto-reloading settings

BotDetect.Configuration.ICaptchaReloadIconConfiguration

Captcha reload icon configuration settings.

BotDetect.Configuration.ICaptchaReloadIconConfiguration Interface Reference
BotDetect.Configuration.ICaptchaReloadIconConfiguration public property readonly string FilePath Custom Captcha reload icon image file
BotDetect.Configuration.ICaptchaReloadIconConfiguration public property readonly int IconWidth Custom Captcha reload icon image width (affects icon layout)
BotDetect.Configuration.ICaptchaReloadIconConfiguration public property readonly BotDetect.Configuration. ILocalizedString Configuration Tooltip Custom Captcha reload icon title, locale-dependent

BotDetect.Configuration.IAutoReloadExpiredCaptchasConfiguration

Captcha reload icon configuration settings. Captcha images are automatically reloaded when the Captcha code expires (as set in the <captchaCodes timeout="value"> element, or the ASP.NET Session timeout), but only within a certain interval from their first generation.

This allows you to have a short Captcha code timeout (e.g. 2 minutes) to narrow the window of opportunity for Captcha reusing on other sites or human-solver-powered bots, and actual visitors can still fill out your form at their own pace and without rushing (since the Captcha image will be reloaded automatically when it is no longer valid).

Since we don't want infinite sessions when the user leaves the form open in a background browser tab over the weekend (for example), we set a reasonable upper limit on the auto-reload period (e.g. 2 hours = 7200 seconds).

BotDetect.Configuration.IAutoReloadExpiredCaptchasConfiguration Interface Reference
BotDetect.Configuration.IAutoReloadExpiredCaptchasConfiguration public property readonly bool Enabled Should auto-reloading be enabled
BotDetect.Configuration.IAutoReloadExpiredCaptchasConfiguration public property readonly int Timeout Max time during which the auto-reloading will work, in seconds

BotDetect.Configuration.ICaptchaUserInputConfiguration

The Captcha user input textbox client ID can be registered for each Captcha control instance in code-behind or the .aspx designer, with several client-side options then becoming available.

BotDetect.Configuration.ICaptchaUserInputConfiguration Interface Reference
BotDetect.Configuration.ICaptchaUserInputConfiguration public property readonly bool AutoUppercase Anything the users type in the input textbox will be uppercased on the fly, since Captcha validation is not and should not be case- sensitive. This is a small usability improvement that helps communicate that fact to the users clearly.
BotDetect.Configuration.ICaptchaUserInputConfiguration public property readonly bool AutoClear The input textbox will be cleared on all Reload icon clicks and auto- reloads, since any previous input in the textbox will be invalidated by Captcha reloading. This is a small usability improvement that helps users avoid having to delete the previous input themselves.
BotDetect.Configuration.ICaptchaUserInputConfiguration public property readonly bool AutoFocus

The input textbox will be assigned focus on all Captcha Sound and Captcha Reload icon clicks, allowing the users to more easily type in the code as they hear it or as the new image loads.

This does not apply to auto-reloading of expired Captchas, since the user might be filling out another field on the form when the auto-reload starts and shouldn't be distracted.

BotDetect.Configuration.ICaptchaLoggingConfiguration

Captcha logging configuration settings.

BotDetect.Configuration.ICaptchaLoggingConfiguration Interface Reference
BotDetect.Configuration.ICaptchaLoggingConfiguration public property readonly bool ErrorLoggingEnabled Should Captcha errors be logged
BotDetect.Configuration.ICaptchaLoggingConfiguration public property readonly bool TraceEnabled Should Captcha traces be logged
BotDetect.Configuration.ICaptchaLoggingConfiguration public property readonly string EventFilter Only events whose eventType matches this regex will be traced
BotDetect.Configuration.ICaptchaLoggingConfiguration public property readonly string LoggingProvider Fully qualified class name of the ILoggingProvider implementation to use

BotDetect.Configuration.ICaptchaUrlConfiguration

Captcha Url configuration settings.

BotDetect.Configuration.ICaptchaUrlConfiguration Interface Reference
BotDetect.Configuration.ICaptchaUrlConfiguration public property readonly string RequestPath

Custom Captcha HttpHandler path, in case the default "BotDetectCaptcha.ashx" doesn't suit your application.

You can customize both the filename and the extension, but you must ensure the IIS mapping for the custom extension is set to be processed by the ASP.NET runtime.

For example, you can use the ".jpg" extension only if you re-map ".jpg" requests to be handled by ASP.NET in your application's virtual folder, instead of the default IIS filesystem mapping for ".jpg" files.

BotDetect.Configuration.ICaptchaEncryptionConfiguration

Captcha encryption configuration settings.

BotDetect.Configuration.ICaptchaEncryptionConfiguration Interface Reference
BotDetect.Configuration.ICaptchaEncryptionConfiguration public property readonly string EncryptionPassword

Custom SessionID encryption key, used to secure the SessionID value that has to be passed in the sound Captcha querystring to avoid sound mismatch problems in some older browsers.

The SessionID is never passed in plaintext querystring to avoid Session hijacking attacks, and you should specify your own unique encryption key to secure it properly.

BotDetect.Configuration.ICaptchaRequestFilterConfiguration

Specialized Captcha Http request filtering configuration settings.

BotDetect.Configuration.ICaptchaRequestFilterConfiguration Interface Reference
BotDetect.Configuration.ICaptchaRequestFilterConfiguration public property readonly bool Enabled Is specialized Captcha Http request filtering enabled
BotDetect.Configuration.ICaptchaRequestFilterConfiguration public property readonly int AllowedRepeatedRequests

Custom Captcha Http request validator, allowing only a certain number of repeated requests with identical querystrings.

Human users in normal browsers will always use unique querystrings to access Captcha images and sounds (the way the Captcha control works guarantees this), while simple bots will often repeat the same request in short time intervals.

This is a simple measure that increases Captcha security by stopping to serve Captcha images and sounds to such obvious bots (Captcha is used for bot detection, and in such a case we can detect that a bot is involved even without wasting resources on generating more Captcha images or sounds).

BotDetect.Configuration. ICaptchaHttpHandlerTroubleshootingConfiguration

Captcha HttpHandler troubleshooting configuration settings.

BotDetect.Configuration.ICaptchaHttpHandlerTroubleshootingConfiguration Interface Reference
BotDetect.Configuration.ICaptchaHttpHandlerTroubleshootingConfiguration public property readonly bool Enabled Is BotDetect HttpHandler troubleshooting enabled

BotDetect.Configuration. ICaptchaSessionTroubleshootingConfiguration

Captcha Session state troubleshooting configuration settings.

BotDetect.Configuration.ICaptchaSessionTroubleshootingConfiguration Interface Reference
BotDetect.Configuration.ICaptchaSessionTroubleshootingConfiguration public property readonly bool Enabled Is BotDetect Session state troubleshooting enabled

BotDetect.Configuration.ICaptchaRemoteScriptConfiguration

Captcha remote script include configuration settings.

BotDetect.Configuration.ICaptchaRemoteScriptConfiguration Interface Reference
BotDetect.Configuration.ICaptchaRemoteScriptConfiguration public property readonly bool Enabled Is the BotDetect Captcha remote script include enabled

BotDetect.Configuration.ILocalizedStringConfiguration

A collection of Captcha locale-dependent strings.

BotDetect.Configuration.ILocalizedStringConfiguration Interface Reference
BotDetect.Configuration.ILocalizedStringConfiguration public property readonly string this[string locale] Access configured string by locale regex. You can specify a universal value (""), a general localization ("ja"), and a specific localization ("ja-Hira-JP") in the configuration, and the value belonging to the longest pattern matching the current locale will be used

Please Note

The information on this page is out of date and applies to a deprecated version of BotDetect™ CAPTCHA (v3.0).

An up-to-date equivalent page for the latest BotDetect Captcha release (v4) is BotDetect v4 Captcha documentation index.

General information about the major improvements in the current BotDetect release can be found at the What's New in BotDetect v4.0 page.