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.Captcha class
BotDetect.Web.CaptchaHandler class
BotDetect.Web.CustomSessionIdManager class
BotDetect.Web.CaptchaTroubleshootingModule class
BotDetect.Web.CaptchaPersistence class
BotDetect.Web.CaptchaUrls class
BotDetect.Web.CaptchaHttpCommand enumeration
BotDetect.Web.SessionTroubleshooting class
BotDetect.Web.HtmlHelper class

BotDetect.Web.Captcha

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

BotDetect.Web.Captcha Class Reference
	Captcha string captchaId	The basic Captcha constructor takes only the Captcha identifier (e.g. "RegistrationCaptcha") as a parameter
	bool Validate	Validate the Captcha from a server-side call, using values automatically read from the current request
	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
	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
	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 Web.Captcha object instance is not available
	bool AjaxValidate	Validate the Captcha from an Ajax call, using values automatically read from the current request
	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
	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
	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 Web.Captcha object instance is not available
	static BotDetect.Web.Captcha Load string captchaId	Loads the Web.Captcha instance stored with the given captchaId
	static void Load BotDetect.Web.Captcha webCaptcha	Updates the Web.Captcha instance according to state persisted for its captchaId value
	static void Save BotDetect.Web.Captcha webCaptcha	Saves necessary state from the given Web.Captcha instance
	static void SaveCaptchaCodes BotDetect.Web.Captcha webCaptcha	Saves only updated code information from the given Web.Captcha instance
	static void RegisterInitialized WebCaptchaHandler EventHandler <BotDetect. InitializedWebCaptcha EventArgs> handler	Propagate InitializedWebCaptcha event handlers registered from different control variants and instances to the global event delegate
	static event EventHandler<InitializedWebCaptchaEventArgs> InitializedWebCaptcha	Custom event handler delegate for InitializedWebCaptcha events, which occurs before captcha is load.
	static event EventHandler<GeneratingCaptchaCodeEventArgs> GeneratingCaptchaCode	Custom event handler delegate for GeneratingCaptchaCode events, which occur before each Captcha code is generated.
	static event EventHandler<GeneratedCaptchaCodeEventArgs> GeneratedCaptchaCode	Custom event handler delegate for GeneratedCaptchaCode events, which occur after each Captcha code has been generated.
	static event EventHandler<GeneratingCaptchaImageEventArgs> GeneratingCaptchaImage	Custom event handler delegate for GeneratingCaptchaImage events, which occur before each Captcha image is generated.
	static event EventHandler<GeneratedCaptchaImageEventArgs> GeneratedCaptchaImage	Custom event handler delegate for GeneratedCaptchaImage events, which occur after each Captcha image has been generated.
	static event EventHandler<GeneratingCaptchaSoundEventArgs> GeneratingCaptchaSound	Custom event handler delegate for GeneratingCaptchaSound events, which occur before each Captcha sound is generated.
	static event EventHandler<GeneratedCaptchaSoundEventArgs> GeneratedCaptchaSound	Custom event handler delegate for GeneratedCaptchaSound events, which occur after each Captcha sound has been generated.
	static event EventHandler<ValidatingUserInputEventArgs> ValidatingUserInput	Custom event handler delegate for ValidatingUserInput events, which occur before each user input is generated.
	static event EventHandler<ValidatedUserInputEventArgs> ValidatedUserInput	Custom event handler delegate for ValidatedUserInput events, which occur after each user input has been generated.
	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
	int CodeLength	Length (number of characters) of the Captcha code rendered; the default value is 5
	BotDetect.CodeStyle CodeStyle	Code style, i.e. the algorithm used to generate Captcha codes; the default value is Alphanumeric
	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.)
	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.)
	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.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
	System.Drawing.Size ImageSize	Size of the Captcha image rendered; the default size is (250, 50)
	BotDetect.ImageFormat ImageFormat	Image format in which the Captcha image will be rendered; the default format is JPEG
	System.Drawing.Color CustomDarkColor	Optional custom dark color point, modifies the color palette used for Captcha image drawing
	System.Drawing.Color CustomLightColor	Optional custom light color point, modifies the color palette used for Captcha image drawing
	bool SoundEnabled	Is Captcha sound enabled
	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.SoundFormat SoundFormat	Audio format in which the Captcha sound will be generated; the default format is WawPcm16bit8kHzMono
	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`.
	string Locale	Locale string, affects the character set used for Captcha code generation and the pronunciation language used for Captcha sound generation
	string ImageTooltip	The Captcha image tooltip can be set for the entire application using web.config settings; this instance property allows overriding those values dynamically.
	string SoundTooltip	Tooltip of the Captcha sound icon
	string ReloadTooltip	Tooltip of the Captcha reload icon
	string HelpLinkText	Text or tooltip of the Captcha help link, depending on help link mode
	string HelpLinkUrl	Url of the localized Captcha help page the help link points to
	bool ReloadEnabled	Is Captcha reloading (changing the Captcha code because the current one is too hard to read) enabled
	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
	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
	string SoundIconUrl	Url of the optional custom Captcha sound icon that will be used instead of the default one
	string ReloadIconUrl	Url of the optional custom Captcha reload icon that will be used instead of the default one
	int IconsDivWidth	Calculated width of the Captcha icons <div>, can be user-set to create custom icon layouts
	bool HelpLinkEnabled	Will Captcha markup include a link to a Captcha help page providing Captcha instructions and explanations for form users
	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.
	string AdditionalCssClasses	User-defined CSS classes that will be added to the BotDetect CAPTCHA container
	string AdditionalInlineCss	User-defined CSS style declarations that will be added as inline style of the BotDetect CAPTCHA container
	bool AddCssIncludeToBody	Should the BotDetect layout stylesheet be included in generated Captcha container markup. This produces invalid markup (since CSS includes are only valid in <head> and not in <body> elements -however, it is occasionally necessary (e.g. in ASP.NET WebForms applications where styles are supposed to be included automatically, but we have no guarantee head inclusion will succeed)
	bool AddScriptInclude	Should the BotDetect JavaScript client-side script code be included by the generated Captcha container markup
	bool AutoUppercaseInput	Should user Captcha code input be automatically uppercased on the fly
	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
	bool AutoClearInput	Should the Captcha user input textbox automatically be cleared on all reload icon clicks and auto-reloads of expired Captcha codes
	bool AutoReloadExpiredCaptchas	Should Captcha challenges automatically be reloaded when the Captcha code expires (controlled by the CodeTimeout property)
	int AutoReloadTimeout	Time period in seconds after which automatic reloading of expired Captcha challenges will cease
	int SoundStartDelay	Starting delay (in milliseconds) of Captcha audio JavaScript playback. The default value is 0 (no delay)
	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)
	readonly string CurrentInstanceId	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
	readonlybool CaptchaSoundAvailable	Are Captcha sounds for the current Locale available
	readonly bool SoundPackageMissing	Is the BotDetect pronunciation sound package for the current Locale missing
	readonly bool RenderIcons	Should the icons be rendered (true if at least one of the icons will be rendered)
	readonly int TotalWidth	Calculated width of the Captcha container <div>, based on Captcha image width and should the icons be rendered or not
	readonly int TotalHeight	Calculated height of the Captcha container <div>, based on Captcha image height
	readonly string ScriptIncludeMarkup	BotDetect script include fragment, including script tags
	readonly string InitScriptMarkup	BotDetect client-side initialization function
	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
	static readonly bool IsCaptchaRequest	Detects is the current Http request a Captcha request (handled by the BotDetect HttpHandler) or not
	readonly string CaptchaImageUrl	Url of Captcha image generated for the current control instance
	readonly string CaptchaSoundUrl	Url of Captcha sound generated for the current control instance
	readonly string ImageClientId	Client-side ID of the <img> element used for Captcha images
	readonly string AudioPlaceholderClientId	Client-side ID of the empty placeholder <div> used for Captcha sound playback
	readonly string ValidatingInstanceKey	Name of the hidden field used to pass InstanceId between postbacks
	readonly string ValidatingInstanceId	InstanceId of the previous CaptchaControl instance that is being submitted, set only if IsSubmit is true
	readonly bool IsSumbit	Detect is the current CaptchaControl instance created after a postback which includes Captcha code input for the previous instance
	readonly bool IsSessionProblemDetected	Did the SessionTroubleshooting helper detect any problems with the current control instance and Session persistence
	readonly string Html	Creates the Html markup that serves as a container for Captcha challenges (images and sounds)

[back to the top of the page]

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
	void ProcessRequest System.Web.HttpContext context	IHttpHandler override, detects and executes a CaptchaHttpCommand appropriate to the current requests
	readonly bool IsReusable	IHttpHandler override, CaptchaHandler instances can be reused to handle multiple requests, since they don't store anything in instance fields

[back to the top of the page]

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
	void Init System.Web.HttpApplication context	IHttpModule override, registers a custom handler for the HttpApplicationError event
	static void LogCurrentContextError	Searches HttpContext.Current. ApplicationInstance.Server. GetLastError() for BotDetect errors and logs them to the configured BotDetect logging provider

[back to the top of the page]

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.

Implements

System.Web.SessionState.ISessionIDManager

Inherits

System.Web.SessionState.SessionIDManager

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

[back to the top of the page]

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
	static bool IsValid string captchaId	Checks does persisted info exist for the supplied captchaId
	static void LoadCodeLength BotDetect.CaptchaBase captchaBase string captchaId	Load the code length
	static void SaveCodeLength string captchaId int? value	Save the code length
	static void LoadCodeStyle BotDetect.CaptchaBase captchaBase string captchaId	Load the code style
	static void SaveCodeStyle string captchaId BotDetect.CodeStyle value	Save the code style
	static void LoadCodeTimeout BotDetect.CaptchaBase captchaBase string captchaId	Load the code timeout
	static void SaveCodeTimeout string captchaId int value	Save the code timeout
	static void LoadDisallowedCodeSubstrings BotDetect.CaptchaBase captchaBase string captchaId	Load disallowed code substrings
	static void SaveDisallowedCodeSubstrings string captchaId BotDetect.DisallowedCodeSubstrings value	Save disallowed code substrings
	static void LoadImageStyle BotDetect.CaptchaBase captchaBase string captchaId	Load the image style
	static void SaveImageStyle string captchaId BotDetect.ImageStyle? value	Save the image style
	static void LoadImageFormat BotDetect.CaptchaBase captchaBase string captchaId	Load the image format
	static void SaveImageFormat string captchaId BotDetect.ImageFormat value	Save the image format
	static void LoadImageSize BotDetect.CaptchaBase captchaBase string captchaId	Load the image size
	static void SaveImageSize string captchaId BotDetect.ImageSize value	Save the image size
	static void LoadCustomLightColor BotDetect.CaptchaBase captchaBase string captchaId	Load the custom light color
	static void SaveCustomLightColor string captchaId BotDetect.Drawing.Color value	Save the custom light color
	static void LoadCustomDarkColor BotDetect.CaptchaBase captchaBase string captchaId	Load the custom dark color
	static void SaveCustomDarkColor string captchaId BotDetect.Drawing.Color value	Save the custom dark color
	static void LoadSoundEnabled BotDetect.CaptchaBase captchaBase string captchaId	Load the sound enabled
	static void SaveSoundEnabled string captchaId bool value	Save the sound enabled
	static void LoadSoundStyle BotDetect.CaptchaBase captchaBase string captchaId	Load the sound style
	static void SaveSoundStyle string captchaId BotDetect.SoundStyle? value	Save the sound style
	static void LoadSoundFormat BotDetect.CaptchaBase captchaBase string captchaId	Load the sound format
	static void SaveSoundFormat string captchaId BotDetect.SoundFormat value	Save the sound format
	static void LoadSoundRegenerationMode BotDetect.CaptchaBase captchaBase string captchaId	Load the sound regeneration mode
	static void SaveSoundRegenerationMode string captchaId BotDetect.SoundRegenerationMode value	Save the sound regeneration mode
	static void LoadHelpLinkEnabled BotDetect.CaptchaBase captchaBase string captchaId	Load the help link enabled
	static void SaveHelpLinkEnabled string captchaId bool value	Save the help link enabled
	static void LoadHelpLinkMode BotDetect.CaptchaBase captchaBase string captchaId	Load the help link mode
	static void SaveHelpLinkMode string captchaId BotDetect.HelpLinkMode value	Save the help link mode
	static void LoadCodeCollection BotDetect.CaptchaBase captchaBase string captchaId	Load the code collection
	static void SaveCodeCollection string captchaId BotDetect.CodeCollection value	Save the code collection
	static void LoadImageTooltip BotDetect.Web.Captcha webCaptcha string captchaId	Load the image tooltip
	static void SaveImageTooltip string captchaId System.String value	Save the image tooltip
	static void LoadReloadTooltip BotDetect.Web.Captcha webCaptcha string captchaId	Load the reload image tooltip
	static void SaveReloadTooltip string captchaId System.String value	Save the reload image tooltip
	static void LoadLocale BotDetect.CaptchaBase captchaBase string captchaId	Load the locale
	static void SaveLocale string captchaId string value	Save the locale

[back to the top of the page]

BotDetect.Web.CaptchaUrls

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

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

[back to the top of the page]

BotDetect.Web.CaptchaHttpCommand

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

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

[back to the top of the page]

BotDetect.Web.SessionTroubleshooting

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

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

[back to the top of the page]

BotDetect.Web.HtmlHelper

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

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