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

The BotDetect.Web namespace contains BotDetect ASP.NET Captcha classes encapsulating Captcha web-related functionality, and used within the System.Web context.

BotDetect.Web.CaptchaControl

This class builds upon the general Captcha functionality in CaptchaBase, and abstracts functionality common to different possible kinds of Captcha controls. For example, the Captcha control used in Web Forms applications and the MvcCaptcha control used in ASP.NET MVC applications both delegate common functionality to a contained CaptchaControl instance.

BotDetect.Web.CaptchaControl Class Reference
BotDetect.Web.CaptchaControl public method CaptchaControl
  • string captchaId
The basic CaptchaControl constructor takes only the Captcha identifier (e.g. "RegistrationCaptcha") as a parameter
BotDetect.Web.CaptchaControl public method bool Validate
  • string userInput
Validate the Captcha from a server-side call, using the specified user input and the instanceId automatically propagated using a hidden field
BotDetect.Web.CaptchaControl public method bool AjaxValidate
  • string userInput
Validate the Captcha from an Ajax call, using the specified user input and the instanceId automatically propagated using a hidden field
BotDetect.Web.CaptchaControl public method bool Validate
  • string userInput
  • string instanceId
Validate the Captcha from a server-side call, using the specified user input and instanceId. Used when automatic hidden field propagation doesn't work
BotDetect.Web.CaptchaControl public method bool AjaxValidate
  • string userInput
  • string instanceId
Validate the Captcha from an Ajax call, using the specified user input and instanceId. Used when automatic hidden field propagation doesn't work
BotDetect.Web.CaptchaControl public property string UserInputClientID User input textbox client-side identifier (the ASP.NET ClientID property), used for all client-side user input processing, e.g. automatic user input lowercasing and focusing
BotDetect.Web.CaptchaControl public property string Locale Locale string, affects the character set used for Captcha code generation and the pronunciation language used for Captcha sound generation
BotDetect.Web.CaptchaControl public property int CodeLength Length (number of characters) of the Captcha code rendered; the default value is 5
BotDetect.Web.CaptchaControl public property BotDetect.CodeStyle CodeStyle Code style, i.e. the algorithm used to generate Captcha codes; the default value is Alphanumeric
BotDetect.Web.CaptchaControl public property string CustomCharacterSetName Optional name of the user-defined character set used for Captcha code generation. A collection of custom character sets can be defined in the <botDetect> section of the web.config file
BotDetect.Web.CaptchaControl public property BotDetect.ImageStyle ImageStyle Image style, i.e. the algorithm used to render Captcha codes in images; if no image style is set, it is randomized by default
BotDetect.Web.CaptchaControl public property System.Drawing.Size ImageSize Size of the Captcha image rendered; the default size is (250, 50)
BotDetect.Web.CaptchaControl public property BotDetect.ImageFormat ImageFormat Image format in which the Captcha image will be rendered; the default format is JPEG
BotDetect.Web.CaptchaControl public property System.Drawing.Color CustomDarkColor Optional custom dark color point, modifies the color palette used for Captcha image drawing
BotDetect.Web.CaptchaControl public property System.Drawing.Color CustomLightColor Optional custom light color point, modifies the color palette used for Captcha image drawing
BotDetect.Web.CaptchaControl public property BotDetect.SoundStyle SoundStyle Sound style, i.e. the algorithm used to pronounce Captcha codes in sounds; if no sound style is set, it is randomized by default
BotDetect.Web.CaptchaControl public property BotDetect.SoundFormat SoundFormat Audio format in which the Captcha sound will be generated; the default format is WawPcm16bit8kHzMono
BotDetect.Web.CaptchaControl public property BotDetect.SoundRegenerationMode SoundRegenerationMode

Sound regeneration mode determining how will multiple consecutive requests for audio Captcha with the same Captcha code be handled by BotDetect; the default mode is Limited.

BotDetect.Web.CaptchaControl public property string CaptchaImageTooltip The Captcha image tooltip can be set for the entire application using web.config settings; this instance property allows overriding those values dynamically.
BotDetect.Web.CaptchaControl public property string ReloadIconTooltip The Captcha reload icon tooltip can be set for the entire application using web.config settings; this instance property allows overriding those values dynamically.
BotDetect.Web.CaptchaControl public property string SoundIconTooltip The Captcha sound icon tooltip can be set for the entire application using web.config settings; this instance property allows overriding those values dynamically.
BotDetect.Web.CaptchaControl public property bool UseHorizontalIcons By default, tells is the selected Captcha image height so low that we should switch to horizontal icon rendering; can be user-specified to always (or never) switch to the horizontal icon layout
BotDetect.Web.CaptchaControl public property bool UseSmallIcons By default, tells is the selected Captcha image height so low that we should switch to smaller icons; can be user-specified to always (or never) use small icons
BotDetect.Web.CaptchaControl public property int IconsDivWidth Calculated width of the Captcha icons <div>, can be user-set to create custom icon layouts
BotDetect.Web.CaptchaControl public property short TabIndex

Starting tabindex for the Captcha control Html output.

The keyboard-selectable Captcha markup elements are: the Captcha reload icon, the Captcha sound icon, and (only in the Free version of BotDetect) the BotDetect website link.

Depending on your settings (is Captcha reloading enabled, are Captcha sounds enabled) and the version of BotDetect you are using (free or paid), the next available tabindex on the page can be from 0 to 3 greater than this value.
BotDetect.Web.CaptchaControl public property readonly string AudioPlaceholderClientId Client-side ID of the empty placeholder <div> used for Captcha sound playback
BotDetect.Web.CaptchaControl public property readonly bool AutoClearInput Is automatic user input clearing on Reload and Sound icon clicks enabled (read from the configuration)
BotDetect.Web.CaptchaControl public property readonly bool AutoFocusInput Is automatic user input focusing on Reload and Sound icon clicks enabled (read from the configuration)
BotDetect.Web.CaptchaControl public property readonly bool AutoUppercaseInput Is automatic user input uppercasing enabled (read from the configuration)
BotDetect.Web.CaptchaControl public property readonly bool AutoReloadExpiredCaptchas Is automatic reloading of Captcha images after the Captcha code expires enabled (read from the configuration)
BotDetect.Web.CaptchaControl public property readonly int AutoReloadTimeout After how many seconds does the automatic reloading stop, to keep the control from generating endless sessions (read from the configuration)
BotDetect.Web.CaptchaControl public property readonly string CaptchaId Unique identifier of the CaptchaControl within the application (for example, if you placed one CaptchaControl on the Registration page and another on the Contact Us, they would have distinct CaptchaId values)
BotDetect.Web.CaptchaControl public property readonly string CaptchaImageUrl Url of Captcha image generated for the current control instance
BotDetect.Web.CaptchaControl public property readonly bool CaptchaSoundAvailable Are Captcha sounds for the current Locale available
BotDetect.Web.CaptchaControl public property readonly bool CaptchaSoundEnabled Are Captcha sounds enabled (read from configuration)
BotDetect.Web.CaptchaControl public property readonly string CaptchaSoundUrl Url of Captcha sound generated for the current control instance
BotDetect.Web.CaptchaControl public property readonly string CurrentInstanceId Globally unique identifier of the current CaptchaControl object instance, used to ensure each page load keeps separate Captcha codes, for example when opening the same form in multiple browser tabs
BotDetect.Web.CaptchaControl public property readonly string DefaultSoundIconUrl Url of the default Captcha Sound icon, depends on the current Captcha image height (a smaller icon is used for Captcha images less than 40 pixels high)
BotDetect.Web.CaptchaControl public property readonly string ImageClientId Client-side ID of the <img> element used for Captcha images
BotDetect.Web.CaptchaControl public property readonly bool IsSessionProblemDetected Did the SessionTroubleshooting helper detect any problems with the current control instance and Session persistence
BotDetect.Web.CaptchaControl public property readonly bool IsSumbit Detect is the current CaptchaControl instance created after a postback which includes Captcha code input for the previous instance
BotDetect.Web.CaptchaControl public property readonly bool ReloadIconEnabled Is Captcha image reloading enabled (read from configuration)
BotDetect.Web.CaptchaControl public property readonly string ReloadIconTooltip Link title and image alt text used for the Captcha Reload icon (read from configuration)
BotDetect.Web.CaptchaControl public property readonly string ReloadIconUrl Url of the currently configured Reload icon
BotDetect.Web.CaptchaControl public property readonly bool RenderIcons Should the icons be rendered (true if at least one of the icons will be rendered)
BotDetect.Web.CaptchaControl public property readonly string SoundIconTooltip Link title and image alt text used for the Captcha Sound icon (read from configuration)
BotDetect.Web.CaptchaControl public property readonly string SoundIconUrl Url of the currently configured Sound icon
BotDetect.Web.CaptchaControl public property readonly bool SoundPackageMissing Is the BotDetect pronunciation sound package for the current Locale missing
BotDetect.Web.CaptchaControl public property readonly int TotalHeight Calculated height of the Captcha container <div>, based on Captcha image height
BotDetect.Web.CaptchaControl public property readonly int TotalWidth Calculated width of the Captcha container <div>, based on Captcha image width and should the icons be rendered or not
BotDetect.Web.CaptchaControl public property readonly string ValidatingInstanceId InstanceId of the previous CaptchaControl instance that is being submitted, set only if IsSubmit is true
BotDetect.Web.CaptchaControl public property readonly string ValidatingInstanceKey Name of the hidden field used to pass InstanceId between postbacks
BotDetect.Web.CaptchaControl public method static bool Validate
  • string captchaId
  • string userInput
  • string instanceId
Validate the Captcha from a server-side call, specifying all validation parameters. Used in cases when a CaptchaControl instance is not available
BotDetect.Web.CaptchaControl public method static bool AjaxValidate
  • string captchaId
  • string userInput
  • string instanceId
Validate the Captcha from an Ajax call, specifying all validation parameters. Used in cases when a CaptchaControl instance is not available
BotDetect.Web.CaptchaControl public method static void RegisterInitialized CaptchaControlHandler
  • string captchaId
  • EventHandler <BotDetect. InitializedCaptchaControl EventArgs> handler
Propagate InitializedCaptchaControl event handlers registered from different control variants and instances to the global event delegate
BotDetect.Web.CaptchaControl public property static System.Collections. Generic.List<string> BannedSequences Optional global list of character sequences which will be filtered out of the randomly generated Captcha codes, used for example for swear-word filtering
BotDetect.Web.CaptchaControl public property static readonly bool IsCaptchaRequest Detects is the current Http request a Captcha request (handled by the BotDetect HttpHandler) or not

BotDetect.Web.CaptchaHandler

HttpHandler used for all BotDetect Captcha requests, generating Captcha images and sounds and loading various Captcha resources (icons, scripts, stylesheets...).

Implements

System.Web.IHttpHandler, System.Web.SessionState.IRequiresSessionState

BotDetect.Web.CaptchaHandler Class Reference
>BotDetect.Web.CaptchaHandler public method void ProcessRequest
  • System.Web.HttpContext context
IHttpHandler override, detects and executes a CaptchaHttpCommand appropriate to the current requests
>BotDetect.Web.CaptchaHandler public property readonly bool IsReusable IHttpHandler override, CaptchaHandler instances can be reused to handle multiple requests, since they don't store anything in instance fields

BotDetect.Web.CaptchaTroubleshootingModule

HttpModule used to detect BotDetect Captcha errors on the server and write them to the configured BotDetect logging provider.

Implements

System.Web.IHttpModule

BotDetect.Web.CaptchaTroubleshootingModule Class Reference
BotDetect.Web.CaptchaTroubleshootingModule public method void Init
  • System.Web.HttpApplication context
IHttpModule override, registers a custom handler for the HttpApplicationError event
BotDetect.Web.CaptchaTroubleshootingModule public method static void LogCurrentContextError Searches HttpContext.Current. ApplicationInstance.Server. GetLastError() for BotDetect errors and logs them to the configured BotDetect logging provider

BotDetect.Web.CustomSessionIdManager

A custom SessionIDManager used to workaround Captcha sound issues in clients which don't propagate ASP.NET Session cookies properly (an optional but recommended improvement, as explained in the BotDetect FAQ). Adds the SessionID (encrypted, to prevent Session hijacking) to Captcha sound request querystrings.

Implementss

System.Web.SessionState.ISessionIDManager

Inherits

System.Web.SessionState.SessionIDManager

BotDetect.Web.CustomSessionIdManager Class Reference
BotDetect.Web.CustomSessionIdManager public property readonly static string EncryptedSessionId The current SessionID, encrypted and ready to be added to Captcha request querystrings

BotDetect.Web.CaptchaPersistence

This class encapsulates BotDetect Captcha persistence operations, saving and loading Captcha instance data from the configured persistence provider.

BotDetect.Web.CaptchaPersistence Class Reference
BotDetect.Web.CaptchaPersistence public method static bool IsValid
  • string captchaId
Checks does persisted info exist for the supplied captchaId
BotDetect.Web.CaptchaPersistence public method static BotDetect.Web.CaptchaControl Load
  • string captchaId
Loads the CaptchaControl instance stored with the given captchaId
BotDetect.Web.CaptchaPersistence public method static void Load
  • BotDetect.CaptchaBase captcha
  • string captchaId
Updates the CaptchaBase instance according to state persisted for the given captchaId value
BotDetect.Web.CaptchaPersistence public method static void Load
  • BotDetect.Web.CaptchaControl control
  • string captchaId
Updates the CaptchaControl instance according to state persisted for the given captchaId value
BotDetect.Web.CaptchaPersistence public method static void Save
  • BotDetect.Web.CaptchaControl captcha
Saves necessary state from the given CaptchaControl instance

BotDetect.Web.CaptchaUrls

Encapsulates Captcha Url generation according to current state and configured BotDetect options.

BotDetect.Web.CaptchaUrls Class Reference
BotDetect.Web.CaptchaUrls public method static string CaptchaImageUrl
  • string captchaId
  • string instanceId
Generates the Captcha image Url with the given parameter values
BotDetect.Web.CaptchaUrls public method static string CaptchaSoundUrl
  • string captchaId
  • string instanceId
Generates the Captcha sound Url with the given parameter values
BotDetect.Web.CaptchaUrls public property readonly static string CaptchaHandlerPath Gets the currently configured BotDetect Captcha HttpHandler path
BotDetect.Web.CaptchaUrls public property readonly static string ClientScriptIncludeUrl Gets the BotDetect client-side include Url
BotDetect.Web.CaptchaUrls public property readonly static string LayoutStyleSheetUrl Gets the BotDetect layout stylesheet Url
BotDetect.Web.CaptchaUrls public property readonly static string ReloadIconUrl Gets the BotDetect reload icon Url
BotDetect.Web.CaptchaUrls public property readonly static string SmallReloadIconUrl Gets the BotDetect small reload icon Url (used when the Captcha image height is < 40px;)
BotDetect.Web.CaptchaUrls public property readonly static string SoundIconUrl Gets the BotDetect sound icon Url
BotDetect.Web.CaptchaUrls public property readonly static string SmallSoundIconUrl Gets the BotDetect small sound icon Url (used when the Captcha image height is < 40px;)
BotDetect.Web.CaptchaUrls public property readonly static string DisabledSoundIconUrl Gets the BotDetect disabled sound icon Url (used when the BotDetect pronunciation sound package for the current locale can not be found and the "warn about missing sound packages" setting is active)

BotDetect.Web.CaptchaHttpCommand

Enumerates all BotDetect Captcha Http commands, i.e. meaningful BotDetect Http request types.

BotDetect.Web.CaptchaHttpCommand Enumeration Members
BotDetect.Web.CaptchaHttpCommand enumeration member Unknown An unknown command i.e. error case
BotDetect.Web.CaptchaHttpCommand enumeration member GetImage The client requests the Captcha image
BotDetect.Web.CaptchaHttpCommand enumeration member GetSound The client requests the Captcha sound
BotDetect.Web.CaptchaHttpCommand enumeration member GetValidationResult The client requests the Captcha validation result (used for Ajax Captcha validation)
BotDetect.Web.CaptchaHttpCommand enumeration member GetSoundIcon The client requests the default Captcha sound icon
BotDetect.Web.CaptchaHttpCommand enumeration member GetSmallSoundIcon The client requests the small Captcha sound icon (used for Captcha images < 40px high)
BotDetect.Web.CaptchaHttpCommand enumeration member GetDisabledSoundIcon The client requests the disabled Captcha sound icon (used when the current locale pronunciation sound package is not available, and "warn about missing sound packages" is set to true)
BotDetect.Web.CaptchaHttpCommand enumeration member GetReloadIcon The client requests the default Captcha reload icon
BotDetect.Web.CaptchaHttpCommand enumeration member GetSmallReloadIcon The client requests the small Captcha reload icon (used for Captcha images < 40px high)
BotDetect.Web.CaptchaHttpCommand enumeration member GetLayoutStyleSheet The client requests the BotDetect layout stylesheet
BotDetect.Web.CaptchaHttpCommand enumeration member GetClientScriptInclude The client requests the BotDetect client-side include
BotDetect.Web.CaptchaHttpCommand enumeration member GetSessionTroubleshooting Report The client requests the BotDetect Session status (generated by the SessionTroubleshooting helper)

BotDetect.Web.SessionTroubleshooting

Runs a series of Session state checks and reports the findings in several formats.

BotDetect.Web.SessionTroubleshooting Class Reference
BotDetect.Web.SessionTroubleshooting public method static BotDetect.Status IsSessionProblemDetected Are any possible Session problems detected for the current request
BotDetect.Web.SessionTroubleshooting public method static BotDetect.Status IsSessionProblemDetected
  • BotDetect.Web.CaptchaControl captchaControl
Are any possible Session problems detected from the given CaptchaControl instance
BotDetect.Web.SessionTroubleshooting public method static BotDetect.Status IsNewSessionOnSubmit
  • BotDetect.Web.CaptchaControl captchaControl
Detects has a new Session been started on postback
BotDetect.Web.SessionTroubleshooting public method static BotDetect.Status DoesCaptchaPersistenceExist
  • BotDetect.Web.CaptchaControl captchaControl
Detects does the Session state for the current request contain a BotDetect CaptchaPersistence set
BotDetect.Web.SessionTroubleshooting public method static BotDetect.Status IsCaptchaPersistenceEmpty
  • BotDetect.Web.CaptchaControl captchaControl
Detects does the Session state for the current request contain any BotDetect Captcha stored values
BotDetect.Web.SessionTroubleshooting public method static string HtmlReport Reports Session state problems found with the current request, formatted for Html output
BotDetect.Web.SessionTroubleshooting public method static string HtmlReport
  • BotDetect.Web.CaptchaControl captchaControl
Reports Session state problems found with the given CaptchaControl instance, formatted for Html output
BotDetect.Web.SessionTroubleshooting public method static string HttpHeaderReport Reports Session state problems found with the current request, formatted for Http header output
BotDetect.Web.SessionTroubleshooting public method static string HttpHeaderReport
  • BotDetect.Web.CaptchaControl captchaControl
Reports Session state problems found with the given CaptchaControl instance, formatted for Http header output
BotDetect.Web.SessionTroubleshooting public method static string PlainTextReport Reports Session state problems found with the current request, formatted for plain text output
BotDetect.Web.SessionTroubleshooting public method static string PlainTextReport
  • BotDetect.Web.CaptchaControl captchaControl
Reports Session state problems found with the given CaptchaControl instance, formatted for plain text output
BotDetect.Web.SessionTroubleshooting public property static bool Enabled Is Session troubleshooting currently enabled
BotDetect.Web.SessionTroubleshooting public property static BotDetect.Status IsSessionHttpModuleRunning Detects is the ASP.NET Session state HttpModule running in the current application instance
BotDetect.Web.SessionTroubleshooting public property static BotDetect.Status IsCustomSessionIdManager Included Detects is the BotDetect custom SessionIDManager included in the current Session instance
BotDetect.Web.SessionTroubleshooting public property static BotDetect.Status IsNewSession Detects is a new Session started with the current request
BotDetect.Web.SessionTroubleshooting public property static BotDetect.Status IsResumedSession Detects is a previous Session resumed with the current request
BotDetect.Web.SessionTroubleshooting public property static bool IsSessionStateEmpty Detects is the Session state for the current request empty

BotDetect.Web.HtmlHelper

This helper class is used for markup generation in various Captcha control variants.

BotDetect.Web.HtmlHelper Class Reference
BotDetect.Web.HtmlHelper public method static string HiddenField
  • string name
  • string value
Creates hidden field markup with the given values
BotDetect.Web.HtmlHelper public method static string ScriptFragment
  • string script
Creates JavaScript fragment markup containing the given script
BotDetect.Web.HtmlHelper public method static string ScriptInclude
  • string scriptUrl
Creates JavaScript include markup pointing to the given Url
BotDetect.Web.HtmlHelper public method static string StylesheetInclude
  • string stylesheetUrl
Creates Css include markup pointing to the given Url

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.