Using HTMLCaptcha - C#

This tutorial shows how to implement HTMLCaptcha with an ASP.NET application written in C#. It is based on a sample Visual Studio solution that was installed with HTMLCaptcha. Click here to extract the solution. You might want to reference the code as you go through the tutorial.

First, create a new "ASP.NET Web Application" project.

Then, add a reference to HTMLCaptcha. Do this by right-clicking on References in Solution Explorer for your project, and browsing to the folder where HTMLCaptcha.dll is installed. You can click on the "Library" shortcut that is installed in your Start menu under HTMLCaptcha to be taken to directly to the DLL. Put a

using HtmlCaptcha;

so that you can refer to the Captcha object with out using the full namespace.

The sample consists of a single .aspx document, WebForm1.aspx. A couple simple controls are drawn onto it: a dropdown box, a button, and a couple labels. View the source code of WebForm1.aspx, which is located in the file WebForm1.aspx.cs.

First, a private HtmlCaptcha object is defined.

private Captcha hc;

Also, a string property in the WebForm1 class is defined, called CaptchaOutput. It returns the value of the private string captchaOutput.

private string captchaOutput;
public string CaptchaOutput
{
    get { return captchaOutput; }
}

This property is used to place the HTML CAPTCHA image on the web page, as you will see shortly.

When the page loads, the method Page_Load() fires. It checks the variable IsPostBack to see if this is the first time the page has loaded or if the user has clicked a button or other control. If it is the first time the page loads, the following code executes, which instantiates the HtmlCaptcha object, generates the HTML CAPTCHA, and outputs the descriptor selection.

	// Specify the directory where the HTML CAPTCHA image
	// data is stored. 
	hc = new Captcha();
	hc.Init("C:\\Program Files\\HTMLCaptcha\\");
	
	hc.MaxSelectEntries = 10;

	// Get the random CAPTHCA, save in variable for display
	captchaOutput = hc.OutputCaptcha();
	

	// Bind the drop-down list to ListItemCollection -- descriptors
	DropDownList1.DataSource = hc.DescriptorList();
	DropDownList1.DataBind();
	

	// Generate new GUID
	string guid = System.Guid.NewGuid().ToString();

	// Save the CAPTCHA descriptor in the cache
	Cache[guid] = hc.SelectedDescriptor;
	



	// Assign the GUID to the session state (used for validation)
	Session["correctAnswer"] = guid;

After instantiating the Captcha object, you must pass it the path to your image cache. This is done with hc.Init(). You can have any number of image caches. See the tutorial on creating image data for more information.

hc.MaxSelectEntries = 10 specifies that we want to have 10 choices in the descriptor list. You can set this to any number or omit it entirely, and HtmlCaptcha returns the default number.

After instantiating the object hc, call the method OutputCaptcha() to return a randomly selected CAPTCHA image. It returns a text string of pure HTML code. This is assigned to the CaptchaOutput property via captchaOutput:

captchaOutput = hc.OutputCaptcha();

In the HTML source of WebForm1.aspx, insert the CaptchaOutput property wherever you want it to appear on the page. I have simply inserted it above the <form> element using the following bit of code.

<%= CaptchaOutput %>

You will also need to provide the user with a list of descriptors. At least one of the descriptors will be paired with the output image, and if selected, will validate the humanity of the user. This is done easily by binding the output from the HtmlCaptcha object's DescriptorList() method to your control. DescriptorList() returns a ListItemCollection, so it may be bound to any control that can use this type as its data source. I've used a dropdown list in this example.

DropDownList1.DataSource = hc.DescriptorList();
DropDownList1.DataBind();

Now that the user has been shown the CAPTCHA and given the selection of descriptors, you must save the correct answer for comparison when the user posts his choice. This is done securely by using the Cache and Session objects. The SelectedDescriptor property of HtmlCaptcha contains the correct answer for the output CAPTCHA image. By calling OutputCaptcha(), this value is set. If you save SelectedCaptcha under a unique name to Cache, and save the name in the Session, the answer does not need to be passed through the HTML output of your web application. I use System.Guid to create a unique name.

// Generate new GUID
string guid = System.Guid.NewGuid().ToString();

// Save the CAPTCHA descriptor in the cache
Cache[guid] = hc.SelectedCaptcha;

// Assign the GUID to the session state (used for validation)
Session["correctAnswer"] = guid;

The page is now rendered, and the user may make his choice.

After the choice is made, and the button (Button1) is pressed, a postback is sent, and Button1_Click() handles the event. First, you must retrieve the unique name of the correct descriptor from Cache. This is done by looking at the correctAnswer session value, where the GUID is stored.

string guid = Session["correctAnswer"].ToString();

Now that this has been obtained, it is a simple comparison to see if the user has picked the right descriptor. Just match the selected value in the dropdown box against the value stored in cache. The user has now been validated/invalidated.

if ( DropDownList1.SelectedValue.ToString() == Cache[guid].ToString() )
{
    Label2.Text = "It looks like you are <b>human</b>!";
}
else
{
    Label2.Text = "Bad guess. Are you a <b>robot</b>?";
}

Be sure to clean up Cache and Session!

Cache.Remove(guid);
Session.Remove(guid);

That's it. You have now used HTMLCaptcha to validate the humanity of the user of your web application.