BotDetect ASP.NET CAPTCHA Web API Reference



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

BotDetect.Web.SimpleCaptcha

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

BotDetect.Web.SimpleCaptcha Class Reference
BotDetect.Web.SimpleCaptcha public method Captcha
  • string captchaStyleName
The basic Captcha constructor takes only the Captcha identifier (e.g. "RegistrationCaptcha") as a parameter
BotDetect.Web.SimpleCaptcha public method bool Validate Validate the Captcha from a server-side call, using values automatically read from the current request
BotDetect.Web.SimpleCaptcha public method bool Validate
  • string userInput
Validate the Captcha from a server-side call, using the specified user input and the captchaId automatically propagated using a hidden field
BotDetect.Web.SimpleCaptcha public method bool Validate
  • string userInput
  • string captchaId
Validate the Captcha from a server-side call, using the specified user input and captchaId. Used when automatic hidden field propagation doesn't work
BotDetect.Web.SimpleCaptcha public method bool AjaxValidate Validate the Captcha from an Ajax call, using values automatically read from the current request
BotDetect.Web.SimpleCaptcha public method bool AjaxValidate
  • string userInput
Validate the Captcha from an Ajax call, using the specified user input and the captchaId automatically propagated using a hidden field
BotDetect.Web.SimpleCaptcha public method bool AjaxValidate
  • string userInput
  • string captchaId
Validate the Captcha from an Ajax call, using the specified user input and captchaId. Used when automatic hidden field propagation doesn't work
BotDetect.Web.SimpleCaptcha public method static void SaveCode
  • BotDetect.Web.SimpleCaptcha webCaptcha
Saves only updated code information from the given Web.Captcha instance
BotDetect.Web.SimpleCaptcha public method static void RegisterInitialized WebSimpleCaptchaHandler
  • EventHandler <BotDetect. InitializedWebSimpleCaptcha EventArgs> handler
Propagate InitializedWebSimpleCaptcha event handlers registered from different control variants and instances to the global event delegate
BotDetect.Web.SimpleCaptcha event handler static event EventHandler<InitializedWebSimpleCaptchaEventArgs> InitializedWebSimpleCaptcha Custom event handler delegate for Initialized WebSimpleCaptcha events, which occurs before captcha is load.
BotDetect.Web.SimpleCaptcha event handler static event EventHandler<GeneratingSimpleCaptchaCodeEventArgs> GeneratingSimpleCaptchaCode Custom event handler delegate for Generating SimpleCaptchaCode events, which occur before each Captcha code is generated.
BotDetect.Web.SimpleCaptcha event handler static event EventHandler<GeneratedSimpleCaptchaCodeEventArgs> GeneratedSimpleCaptchaCode Custom event handler delegate for Generated SimpleCaptchaCode events, which occur after each Captcha code has been generated.
BotDetect.Web.SimpleCaptcha event handler static event EventHandler<GeneratingSimpleCaptchaImageEventArgs> GeneratingSimpleCaptchaImage Custom event handler delegate for Generating SimpleCaptchaImage events, which occur before each Captcha image is generated.
BotDetect.Web.SimpleCaptcha event handler static event EventHandler<GeneratedSimpleCaptchaImageEventArgs> GeneratedSimpleCaptchaImage Custom event handler delegate for Generated SimpleCaptchaImage events, which occur after each Captcha image has been generated.
BotDetect.Web.SimpleCaptcha event handler static event EventHandler<GeneratingSimpleCaptchaSoundEventArgs> GeneratingSimpleCaptchaSound Custom event handler delegate for Generating SimpleCaptchaSound events, which occur before each Captcha sound is generated.
BotDetect.Web.SimpleCaptcha event handler static event EventHandler<GeneratedSimpleCaptchaSoundEventArgs> GeneratedSimpleCaptchaSound Custom event handler delegate for Generated SimpleCaptchaSound events, which occur after each Captcha sound has been generated.
BotDetect.Web.SimpleCaptcha event handler static event EventHandler<SimpleValidatingUserInputEventArgs> SimpleValidatingUserInput Custom event handler delegate for SimpleValidatingUserInput events, which occur before each user input is generated.
BotDetect.Web.SimpleCaptcha event handler static event EventHandler<SimpleValidatedUserInputEventArgs> SimpleValidatedUserInput Custom event handler delegate for SimpleValidatedUserInput events, which occur after each user input has been generated.
BotDetect.Web.SimpleCaptcha public property string UserInputID Captcha user input textbox identifier used for all server-side and client-side user input processing. The default value is empty (must be set for each Captcha individually). Valid user Captcha user input id setting values are strings corresponding to the Html identifier of the Captcha code input control on the form. Each Captcha instance should have an associated user input control
BotDetect.Web.SimpleCaptcha public property int CodeLength Length (number of characters) of the Captcha code rendered; the default value is 5
BotDetect.Web.SimpleCaptcha public property BotDetect.CodeStyle CodeStyle Code style, i.e. the algorithm used to generate Captcha codes; the default value is Alphanumeric
BotDetect.Web.SimpleCaptcha public property string DisallowedCodeSubstringsCsv Strings that should never occur in randomly generated Captcha codes. Can be both single characters (allows Captcha character set customization) and sequences of two or more characters (useful for swear words filtering, avoiding particular hard-to-read sequences etc.)
BotDetect.Web.SimpleCaptcha public property List<string> DisallowedCodeSubstringsList Strings that should never occur in randomly generated Captcha codes. Can be both single characters (allows Captcha character set customization) and sequences of two or more characters (useful for swear words filtering, avoiding particular hard-to-read sequences etc.)
BotDetect.Web.SimpleCaptcha public property int CodeTimeout The time period after random Captcha code generation during which Captcha challenges based on it can be solved: when it expires, even correct inputs will be considered as invalid submissions
BotDetect.Web.SimpleCaptcha 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.SimpleCaptcha public property System.Drawing.Size ImageSize Size of the Captcha image rendered; the default size is (250, 50)
BotDetect.Web.SimpleCaptcha public property BotDetect.ImageFormat ImageFormat Image format in which the Captcha image will be rendered; the default format is JPEG
BotDetect.Web.SimpleCaptcha public property System.Drawing.Color CustomDarkColor Optional custom dark color point, modifies the color palette used for Captcha image drawing
BotDetect.Web.SimpleCaptcha public property System.Drawing.Color CustomLightColor Optional custom light color point, modifies the color palette used for Captcha image drawing
BotDetect.Web.SimpleCaptcha public property bool SoundEnabled Is Captcha sound enabled
BotDetect.Web.SimpleCaptcha 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.SimpleCaptcha public property BotDetect.SoundFormat SoundFormat Audio format in which the Captcha sound will be generated; the default format is WawPcm16bit8kHzMono
BotDetect.Web.SimpleCaptcha 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.SimpleCaptcha 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.SimpleCaptcha public property string ImageTooltip The Captcha image tooltip can be set for the entire application using botdetect.xml settings.
BotDetect.Web.SimpleCaptcha public property string ImageColorMode The Captcha image color mode can be set for the entire application using botdetect.xml settings.
BotDetect.Web.SimpleCaptcha public property string SoundTooltip Tooltip of the Captcha sound icon
BotDetect.Web.SimpleCaptcha public property string ReloadTooltip Tooltip of the Captcha reload icon
BotDetect.Web.SimpleCaptcha public property string HelpLinkText Text or tooltip of the Captcha help link, depending on help link mode
BotDetect.Web.SimpleCaptcha public property string HelpLinkUrl Url of the localized Captcha help page the help link points to
BotDetect.Web.SimpleCaptcha public property bool ReloadEnabled Is Captcha reloading (changing the Captcha code because the current one is too hard to read) enabled
BotDetect.Web.SimpleCaptcha 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.SimpleCaptcha 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.SimpleCaptcha public property string SoundIconUrl Url of the optional custom Captcha sound icon that will be used instead of the default one
BotDetect.Web.SimpleCaptcha public property string ReloadIconUrl Url of the optional custom Captcha reload icon that will be used instead of the default one
BotDetect.Web.SimpleCaptcha public property int IconsDivWidth Calculated width of the Captcha icons <div>, can be user-set to create custom icon layouts
BotDetect.Web.SimpleCaptcha public property bool HelpLinkEnabled Will Captcha markup include a link to a Captcha help page providing Captcha instructions and explanations for form users
BotDetect.Web.SimpleCaptcha public property short TabIndex

Starting tabindex for the Captcha container Html markup elements.

There are three keyboard-selectable Captcha markup elements: the Captcha help link, the Captcha sound icon and the Captcha reload icon.

Depending on your settings (whether the Captcha help link is enabled, are Captcha sounds enabled, is Captcha reloading enabled), the next available tabindex on the page can be from 0 to 3 greater than this value.
BotDetect.Web.SimpleCaptcha public property string AdditionalCssClasses User-defined CSS classes that will be added to the BotDetect CAPTCHA container
BotDetect.Web.SimpleCaptcha public property string AdditionalInlineCss User-defined CSS style declarations that will be added as inline style of the BotDetect CAPTCHA container
BotDetect.Web.SimpleCaptcha public property bool AddScriptInclude Should the BotDetect JavaScript client-side script code be included by the generated Captcha container markup
BotDetect.Web.SimpleCaptcha public property bool AutoUppercaseInput Should user Captcha code input be automatically uppercased on the fly
BotDetect.Web.SimpleCaptcha public property bool AutoFocusInput Should the Captcha code input textbox automatically 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
BotDetect.Web.SimpleCaptcha public property bool AutoClearInput Should the Captcha user input textbox automatically be cleared on all reload icon clicks and auto-reloads of expired Captcha codes
BotDetect.Web.SimpleCaptcha public property bool AutoReloadExpiredCaptchas Should Captcha challenges automatically be reloaded when the Captcha code expires (controlled by the CodeTimeout property)
BotDetect.Web.SimpleCaptcha public property int AutoReloadTimeout Time period in seconds after which automatic reloading of expired Captcha challenges will cease
BotDetect.Web.SimpleCaptcha public property int SoundStartDelay Starting delay (in milliseconds) of Captcha audio JavaScript playback. The default value is 0 (no delay)
BotDetect.Web.SimpleCaptcha public property readonly string CaptchaId Unique identifier of the Web.Captcha within the application (for example, if you placed one Captcha on the Registration form and another on the Contact Us form, they would have distinct CaptchaId values)
BotDetect.Web.SimpleCaptcha public property readonly string CurrentCaptchaId Globally unique identifier of the current Web.Captcha 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.SimpleCaptcha public property readonlybool CaptchaSoundAvailable Are Captcha sounds for the current Locale available
BotDetect.Web.SimpleCaptcha public property readonly bool SoundPackageMissing Is the BotDetect pronunciation sound package for the current Locale missing
BotDetect.Web.SimpleCaptcha public property readonly bool RenderIcons Should the icons be rendered (true if at least one of the icons will be rendered)
BotDetect.Web.SimpleCaptcha 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.SimpleCaptcha public property readonly int TotalHeight Calculated height of the Captcha container <div>, based on Captcha image height
BotDetect.Web.SimpleCaptcha public property readonly string ScriptIncludeMarkup BotDetect script include fragment, including script tags
BotDetect.Web.SimpleCaptcha public property BotDetect.Web.ICaptchaUrlGenerator UrlGenerator Instead of accessing the CaptchaUrls helper directly, we encapsulate the access through a field, so switching between relative and absolute urls can be done per Web.Captcha instance
BotDetect.Web.SimpleCaptcha public property static readonly bool IsCaptchaRequest Detects is the current Http request a Captcha request (handled by the BotDetect HttpHandler) or not
BotDetect.Web.SimpleCaptcha public property readonly string CaptchaImageUrl Url of Captcha image generated for the current control instance
BotDetect.Web.SimpleCaptcha public property readonly string CaptchaSoundUrl Url of Captcha sound generated for the current control instance
BotDetect.Web.SimpleCaptcha public property readonly string ImageClientId Client-side ID of the <img> element used for Captcha images
BotDetect.Web.SimpleCaptcha public property readonly string AudioPlaceholderClientId Client-side ID of the empty placeholder <div> used for Captcha sound playback
BotDetect.Web.SimpleCaptcha public property readonly string ValidatingCaptchaIdKey Name of the hidden field used to pass CaptchaId between postbacks
BotDetect.Web.SimpleCaptcha public property readonly string ValidatingCaptchaId CaptchaId of the previous CaptchaControl instance that is being submitted, set only if IsSubmit is true
BotDetect.Web.SimpleCaptcha 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.SimpleCaptcha public property readonly string Html Creates the Html markup that serves as a container for Captcha challenges (images and sounds)

BotDetect.Web.SimpleCaptchaHandler

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.SimpleCaptchaHandler Class Reference
>BotDetect.Web.SimpleCaptchaHandler public method void ProcessRequest
  • System.Web.HttpContext context
IHttpHandler override, detects and executes a SimpleCaptchaHttpCommand appropriate to the current requests
>BotDetect.Web.SimpleCaptchaHandler 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.SimpleCaptchaTroubleshootingModule

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.SimpleCaptchaTroubleshootingModule Class Reference
BotDetect.Web.SimpleCaptchaTroubleshootingModule public method void Init
  • System.Web.HttpApplication context
IHttpModule override, registers a custom handler for the HttpApplicationError event
BotDetect.Web.SimpleCaptchaTroubleshootingModule 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.SimpleCaptchaPersistence

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

BotDetect.Web.SimpleCaptchaPersistence Class Reference
BotDetect.Web.SimpleCaptchaPersistence public method static void SaveCode
  • string captchaId
  • BotDetect.Code code
Save the Code

BotDetect.Web.SimpleCaptchaUrls

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

BotDetect.Web.SimpleCaptchaUrls Class Reference
BotDetect.Web.SimpleCaptchaUrls public method static string CaptchaImageUrl
  • string captchaId
  • string captchaId
Generates the Captcha image Url with the given parameter values
BotDetect.Web.SimpleCaptchaUrls public method static string CaptchaSoundUrl
  • string captchaId
  • string captchaId
Generates the Captcha sound Url with the given parameter values
BotDetect.Web.SimpleCaptchaUrls public method static string CaptchaValidationResultUrl
  • string captchaId
  • string captchaId
Generates the Captcha Ajax validation result Url with the given parameter values
BotDetect.Web.SimpleCaptchaUrls public property readonly static string CaptchaHandlerPath Gets the currently configured BotDetect Captcha HttpHandler path
BotDetect.Web.SimpleCaptchaUrls public property readonly static string DefaultSoundIconUrl Gets the BotDetect sound icon Url
BotDetect.Web.SimpleCaptchaUrls public property readonly static string DefaultReloadIconUrl Gets the BotDetect reload icon Url
BotDetect.Web.SimpleCaptchaUrls public method string SmallIconUrl
  • string iconUrl
Gets the BotDetect small icon Url
BotDetect.Web.SimpleCaptchaUrls public method string DisabledIconUrl
  • string iconUrl
Gets the BotDetect disabled icon Url
BotDetect.Web.SimpleCaptchaUrls public property readonly static string ScriptIncludeUrl Gets the BotDetect client-side include Url
BotDetect.Web.SimpleCaptchaUrls public property readonly static string LayoutStyleSheetUrl Gets the BotDetect layout stylesheet Url

BotDetect.Web.SimpleCaptchaHttpCommand

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

BotDetect.Web.SimpleCaptchaHttpCommand Enumeration Members
BotDetect.Web.SimpleCaptchaHttpCommand enumeration member Unknown An unknown command i.e. error case
BotDetect.Web.SimpleCaptchaHttpCommand enumeration member GetImage The client requests the Captcha image
BotDetect.Web.SimpleCaptchaHttpCommand enumeration member GetSound The client requests the Captcha sound
BotDetect.Web.SimpleCaptchaHttpCommand enumeration member GetValidationResult The client requests the Captcha validation result (used for Ajax Captcha validation)
BotDetect.Web.SimpleCaptchaHttpCommand enumeration member GetSoundIcon The client requests the default Captcha sound icon
BotDetect.Web.SimpleCaptchaHttpCommand enumeration member GetSmallSoundIcon The client requests the small Captcha sound icon (used for Captcha images < 40px high)
BotDetect.Web.SimpleCaptchaHttpCommand 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.SimpleCaptchaHttpCommand enumeration member GetSmallDisabledSoundIcon The client requests the small disabled Captcha sound icon
BotDetect.Web.SimpleCaptchaHttpCommand enumeration member GetReloadIcon The client requests the default Captcha reload icon
BotDetect.Web.SimpleCaptchaHttpCommand enumeration member GetSmallReloadIcon The client requests the small Captcha reload icon (used for Captcha images < 40px high)
BotDetect.Web.SimpleCaptchaHttpCommand enumeration member GetDisabledReloadIcon The client requests the disabled Captcha reload icon
BotDetect.Web.SimpleCaptchaHttpCommand enumeration member GetSmallDisabledReloadIcon The client requests the small disabled Captcha reload icon
BotDetect.Web.SimpleCaptchaHttpCommand enumeration member GetLayoutStyleSheet The client requests the BotDetect layout stylesheet
BotDetect.Web.SimpleCaptchaHttpCommand enumeration member GetScriptInclude The client requests the BotDetect client-side include

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