Using HTMLCaptcha - VB.NET

This tutorial shows how to implement HTMLCaptcha with an ASP.NET application written in VB. It is based on a sample Visual Studio solution 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.

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.vb.

A string property in the WebForm1 class is defined, called CaptchaOutput. It returns the value of the private string m_captchaOutput.

Private m_captchaOutput As String
Public ReadOnly Property CaptchaOutput()
    Get
        Return m_captchaOutput
    End Get
End Property

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 Page.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.

            hc = New HtmlCaptcha.Captcha
            
            hc.Init("C:\\Program Files\\HTMLCaptcha\\")

            hc.MaxSelectEntries = 10

            hc.ModifyPixels = True

            ' Start the random output (don't use)
            m_captchaOutput = hc.OutputCaptcha()

            m_captchaOutput = hc.OutputCaptcha() + "<br/>"
            m_captchaOutput += hc.OutputCaptcha() + "<br/>"
            m_captchaOutput += hc.OutputCaptcha() + "<br/>"
            m_captchaOutput += hc.OutputCaptcha() + "<br/>"
            m_captchaOutput += hc.OutputCaptcha() + "<br/>"
            m_captchaOutput += hc.OutputCaptcha()

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


            Dim guid = System.Guid.NewGuid().ToString()
            Cache(guid) = hc.SelectedDescriptor

            Session("correctAnswer") = guid

After instantiating the HtmlCaptcha object, you must give it a path to the HTML image data. This is done using the hc.Init() method. The image cache is created with the included tool (or you can use the default cache that comes with HTMLCaptcha. See the tutorial on creating image data for more information.)

After initializing the image cache, call the method OutputCaptcha() to return a randomly selected CAPTCHA image. It returns a text string of pure HTML code. It is best to call it once without assigning it. This improves the performance of the random output.

We will output a list of images, and ask the user to indentify the last one in the list. Simply call OutputCaptcha(), and each time a random image will be returned. Here we assign the output to the CaptchaOutput property via m_captchaOutput.

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. Note that when you call DesriptorList() the correct descriptor will match the image from the previous call to OutputCaptcha().

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.

Dim guid = System.Guid.NewGuid().ToString()
Cache(guid) = hc.SelectedDescriptor

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.

Dim guid = Session("correctAnswer")

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 InStr(DropDownList1.SelectedValue, Cache(guid)) <> 0 Then
    Label2.Text = "It look like you are <b>human</b>!"
Else
    Label2.Text = "Bad guess. Are you a <b>robot</b>?"
End If

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.