Arcaptcha library for .NET

Arcaptcha for .NET is one of the most popular and well-documented Arcaptcha libraries used by thousands of .NET developers in their ASP.NET web applications. .

Highlights

The following are the highlights of the library:

• Renders Arcaptcha widget and verifies Arcaptcha response with minimal amount of code
• Provides Arcaptcha web control (ASP.NET Web Forms for .NET Framework 4.5 and above
• Provides HTML helper to quickly render Arcaptcha widget (ASP.NET MVC 5 / ASP.NET Core 3.1 and above)
• One of the most well-documented Arcaptcha libraries in the open source community

How to Use Arcaptcha for .NET: Step-by-Step

Creating a Arcaptcha API Key

Before you can use Arcaptcha in your web application, you must first create a Arcaptcha API key (a pair of site and secret keys). Creating Arcaptcha API key is very straight-forward. Steps are explained here

1. After Signing Up please copy Site Key and Secret Key which you would need to specify in your application's web.config file.

Installation

The best and the recommended way to install the latest version of Arcaptcha for .NET is through Nuget. From the Nuget's Package Manager Console in your Visual Studio .NET IDE, simply execute the following command:

DotNet Framework

PM> Install-Package Arcaptcha.Net

DotNet Core Framework

PM> Install-Package Arcaptcha.NetCore

Set Configuration

ASP.NET Web Forms / ASP.NET MVC 5

In the appSettings section of your web.config file, add the following keys:

<appSettings>
<add key="ArcaptchaSiteKey" value="Your site key" />
<add key="ArcaptchaSecretKey" value="Your secret key" />
<add key="ArcaptchaVerificationUrl" value="Arcaptcha Verification URL (https://api.arcaptcha.ir/arcaptcha/api/verify)" />
<add key="ArcaptchaWidgetScriptUrl" value="Arcaptcha widget script url (https://widget.arcaptcha.ir/1/api.js)" />
</appSettings>

ASP.NET Core

In appsettings.json, add the following JSON properties:

"Arcaptcha":{ 
    "SiteKey": "Your site key",
    "SecretKey": "Your secret key",
    "VerificationUrl": "Arcaptcha Verification URL (https://api.arcaptcha.ir/arcaptcha/api/verify)",
    "WidgetScriptUrl": "Arcaptcha widget script url (https://widget.arcaptcha.ir/1/api.js)"
} 

In the ConfigureServices method of the Startup class, add the following line of code:

using Arcaptcha.NetCore.Configuration;
...
ArcaptchaConfigurationManager.SetConfiguration(Configuration);

Render Arcaptcha Widget

You can either use the Arcaptcha.Net.UI.Controls.ArcaptchaWidget web control (ASP.NET Web Forms) or call the ArcaptchaWidget method of HTML helper (ASP.NET MVC 5 / ASP.NET Core) to render Arcaptcha widget:

ASP.NET Web Forms

<%@ Register Assembly="Arcaptcha.Net" Namespace="Arcaptcha.Net.UI.Controls" TagPrefix="cc1" %>
...
<cc1:ArcaptchaWidget ID="Arcaptcha1" runat="server" />

ASP.NET MVC 5

@using Arcaptcha.Net.Mvc;

ASP.NET Core

@using Arcaptcha.NetCore.Mvc;

Both Asp .Net and ASP.NET Core

...
@Html.ArcaptchaWidget()

The above code by default renders both the API script as well as the widget. There are times when you want to render the API script and the widget separately such as the need to render multiple widgets on a page. The following is an example of how to achieve this:

ASP.NET Web Forms

<%@ Register Assembly="Arcaptcha.Net" Namespace="Arcaptcha.Net.UI.Controls" TagPrefix="cc1" %>
...
<cc1:ArcaptchaApiScript ID="ArcaptchaApiScript1" runat="server" />
<cc1:ArcaptchaWidget ID="ArcaptchaWidget1" RenderApiScript="false" runat="server" />
<cc1:ArcaptchaWidget ID="ArcaptchaWidget2" RenderApiScript="false" runat="server" />

ASP.NET MVC 5

@using Arcaptcha.Net.Mvc;

ASP.NET Core

@using Arcaptcha.NetCore.Mvc;

Both Asp .Net and ASP.NET Core

...
@Html.ArcaptchaApiScript()
@Html.ArcaptchaWidget(rednderApiScript:false)
@Html.ArcaptchaWidget(rednderApiScript:false)

Verify Arcaptcha Response

When your end-user submits the form that contains the Arcaptcha widget, you can easily verify Arcaptcha response with few lines of code:

ASP.NET Web Form

if (String.IsNullOrEmpty(Arcaptcha1.Response))
{
    lblMessage.Text = "Captcha cannot be empty.";
}
else
{
    var result = Arcaptcha1.Verify();
    if (result.Success)
    {
        Response.Redirect("Welcome.aspx");
    }
    else
    {
        lblMessage.Text = "Error(s): Challenge is not solved properly";
    }
}

ASP.NET MVC 5

using Arcaptcha.Net.Mvc;

ASP.NET Core

using Arcaptcha.NetCore.Mvc;

Both Asp .Net and ASP.NET Core

...
if (this.VerifyArcaptchaResponse().Success)
{
ModelState.AddModelError("", "Incorrect captcha answer.");
}
//Or Method Two
ArcaptchaVerificationHelper ArcaptchaHelper = this.GetArcaptchaVerificationHelper();
if (String.IsNullOrEmpty(ArcaptchaHelper.Response))
{
ModelState.AddModelError("", "Captcha answer cannot be empty.");
return View(model);
}
ArcaptchaVerificationResult ArcaptchaResult = ArcaptchaHelper.VerifyArcaptchaResponse();
if (ArcaptchaResult.Success)
{
ModelState.AddModelError("", "Incorrect captcha answer.");
}

Attributes

The attributes are used to control the behavior and appearance of the Arcaptcha widget. They are specified in one of the three ways:

• As API parameters (ASP.NET MVC and ASP.NET Core helper methods)
• As properties of a web control (ASP.NET Web Control)
• Configuration (web.config / appsettings.json)

Assigning a value through method or property takes precedence over configuration. Of course, you don't need to set any attribute anywhere unless its requried. The following is the entire list of the attributes:

Attribute	Description	Type	Values	Default Value	Configuration Key	Required
Site Key	Site key for Arcaptcha. It is required for rendering the widget.	String	The site key associated with the site you register in Google Arcaptcha Admin Console.	No default value. Must be provided.	SiteKey	Yes
Secret Key	Secret key for the Arcaptcha. It is required for verifying Arcaptcha response.	String	The secret key associated with the site you register in Google Arcaptcha Admin Console.	No default value. Must be provided.	SecretKey	Yes
Verification URL	Arcaptcha URL to be called in back-end and check wether challenge is solved properly or not	String	-	No default value. Must be provided.	VerificationUrl	Yes
Widget Script URL	Arcaptcha URL from which front-end scripts are downloaded	String	-	No default value. Must be provided.	ArcaptchaLanguage	Yes

Tooling

The current version of the repo is created using Microsoft Visual Studio 2019 Community Edition with .NET Framework 4.5 and .NET Core 3.1 as compilation targets.

Issues

If you find a bug in the library or you have an idea about a new feature, please try to search in the existing list of issues. If the bug or idea is not listed and addressed there, please open a new issue.