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 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.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 MvcCaptcha control used in ASP.NET MVC applications both delegate common functionality to a contained CaptchaControl instance.

BotDetect.Web.CaptchaControl Class Reference
	CaptchaControl string captchaId	The basic CaptchaControl constructor takes only the Captcha identifier (e.g. "RegistrationCaptcha") as a parameter
	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 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 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
	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
	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
	string Locale	Locale string, affects the character set used for Captcha code generation and the pronunciation language used for Captcha sound generation
	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 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.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
	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 CaptchaImageTooltip	The Captcha image tooltip can be set for the entire application using web.config settings; this instance property allows overriding those values dynamically.
	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.
	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.
	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
	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
	int IconsDivWidth	Calculated width of the Captcha icons <div>, can be user-set to create custom icon layouts
	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.
	readonly string AudioPlaceholderClientId	Client-side ID of the empty placeholder <div> used for Captcha sound playback
	readonly bool AutoClearInput	Is automatic user input clearing on Reload and Sound icon clicks enabled (read from the configuration)
	readonly bool AutoFocusInput	Is automatic user input focusing on Reload and Sound icon clicks enabled (read from the configuration)
	readonly bool AutoUppercaseInput	Is automatic user input uppercasing enabled (read from the configuration)
	readonly bool AutoReloadExpiredCaptchas	Is automatic reloading of Captcha images after the Captcha code expires enabled (read from the configuration)
	readonly int AutoReloadTimeout	After how many seconds does the automatic reloading stop, to keep the control from generating endless sessions (read from the configuration)
	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)
	readonly string CaptchaImageUrl	Url of Captcha image generated for the current control instance
	readonly bool CaptchaSoundAvailable	Are Captcha sounds for the current Locale available
	readonly bool CaptchaSoundEnabled	Are Captcha sounds enabled (read from configuration)
	readonly string CaptchaSoundUrl	Url of Captcha sound generated for the current control instance
	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
	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)
	readonly string ImageClientId	Client-side ID of the <img> element used for Captcha images
	readonly bool IsSessionProblemDetected	Did the SessionTroubleshooting helper detect any problems with the current control instance and Session persistence
	readonly bool IsSumbit	Detect is the current CaptchaControl instance created after a postback which includes Captcha code input for the previous instance
	readonly bool ReloadIconEnabled	Is Captcha image reloading enabled (read from configuration)
	readonly string ReloadIconTooltip	Link title and image alt text used for the Captcha Reload icon (read from configuration)
	readonly string ReloadIconUrl	Url of the currently configured Reload icon
	readonly bool RenderIcons	Should the icons be rendered (true if at least one of the icons will be rendered)
	readonly string SoundIconTooltip	Link title and image alt text used for the Captcha Sound icon (read from configuration)
	readonly string SoundIconUrl	Url of the currently configured Sound icon
	readonly bool SoundPackageMissing	Is the BotDetect pronunciation sound package for the current Locale missing
	readonly int TotalHeight	Calculated height of the Captcha container <div>, based on Captcha image height
	readonly int TotalWidth	Calculated width of the Captcha container <div>, based on Captcha image width and should the icons be rendered or not
	readonly string ValidatingInstanceId	InstanceId of the previous CaptchaControl instance that is being submitted, set only if IsSubmit is true
	readonly string ValidatingInstanceKey	Name of the hidden field used to pass InstanceId between postbacks
	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
	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
	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
	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
	static readonly bool IsCaptchaRequest	Detects is the current Http request a Captcha request (handled by the BotDetect HttpHandler) or not

[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 BotDetect.Web.CaptchaControl Load string captchaId	Loads the CaptchaControl instance stored with the given captchaId
	static void Load BotDetect.CaptchaBase captcha string captchaId	Updates the CaptchaBase instance according to state persisted for the given captchaId value
	static void Load BotDetect.Web.CaptchaControl control string captchaId	Updates the CaptchaControl instance according to state persisted for the given captchaId value
	static void Save BotDetect.Web.CaptchaControl captcha	Saves necessary state from the given CaptchaControl instance

[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
	readonly static string CaptchaHandlerPath	Gets the currently configured BotDetect Captcha HttpHandler path
	readonly static string ClientScriptIncludeUrl	Gets the BotDetect client-side include Url
	readonly static string LayoutStyleSheetUrl	Gets the BotDetect layout stylesheet Url
	readonly static string ReloadIconUrl	Gets the BotDetect reload icon Url
	readonly static string SmallReloadIconUrl	Gets the BotDetect small reload icon Url (used when the Captcha image height is < 40px;)
	readonly static string SoundIconUrl	Gets the BotDetect sound icon Url
	readonly static string SmallSoundIconUrl	Gets the BotDetect small sound icon Url (used when the Captcha image height is < 40px;)
	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)

[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)
	GetReloadIcon	The client requests the default Captcha reload icon
	GetSmallReloadIcon	The client requests the small Captcha reload icon (used for Captcha images < 40px high)
	GetLayoutStyleSheet	The client requests the BotDetect layout stylesheet
	GetClientScriptInclude	The client requests the BotDetect client-side include
	GetSessionTroubleshooting Report	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.CaptchaControl captchaControl	Are any possible Session problems detected from the given CaptchaControl instance
	static BotDetect.Status IsNewSessionOnSubmit BotDetect.Web.CaptchaControl captchaControl	Detects has a new Session been started on postback
	static BotDetect.Status DoesCaptchaPersistenceExist BotDetect.Web.CaptchaControl captchaControl	Detects does the Session state for the current request contain a BotDetect CaptchaPersistence set
	static BotDetect.Status IsCaptchaPersistenceEmpty BotDetect.Web.CaptchaControl captchaControl	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.CaptchaControl captchaControl	Reports Session state problems found with the given CaptchaControl 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.CaptchaControl captchaControl	Reports Session state problems found with the given CaptchaControl 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.CaptchaControl captchaControl	Reports Session state problems found with the given CaptchaControl 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