HCaptcha.AspNetCore
2.0.2
dotnet add package HCaptcha.AspNetCore --version 2.0.2
NuGet\Install-Package HCaptcha.AspNetCore -Version 2.0.2
<PackageReference Include="HCaptcha.AspNetCore" Version="2.0.2" />
<PackageVersion Include="HCaptcha.AspNetCore" Version="2.0.2" />
<PackageReference Include="HCaptcha.AspNetCore" />
paket add HCaptcha.AspNetCore --version 2.0.2
#r "nuget: HCaptcha.AspNetCore, 2.0.2"
#:package HCaptcha.AspNetCore@2.0.2
#addin nuget:?package=HCaptcha.AspNetCore&version=2.0.2
#tool nuget:?package=HCaptcha.AspNetCore&version=2.0.2
hCaptcha for .NET
<p align="center"> <a href="https://www.nuget.org/packages/HCaptcha/"><img src="https://img.shields.io/nuget/v/HCaptcha?label=HCaptcha&logo=nuget&color=0f766e" alt="HCaptcha on NuGet" /></a> <a href="https://www.nuget.org/packages/HCaptcha.AspNetCore/"><img src="https://img.shields.io/nuget/v/HCaptcha.AspNetCore?label=HCaptcha.AspNetCore&logo=nuget&color=0369a1" alt="HCaptcha.AspNetCore on NuGet" /></a> <a href="https://github.com/BenjaminAbt/hcaptcha/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-f4b400.svg" alt="MIT license" /></a> </p>
<p align="center"> <strong>Server-side hCaptcha verification for .NET 8, 9, 10, and 11.</strong> <br /> A typed HTTP client for .NET and a model binder for ASP.NET Core MVC. </p>
The hCaptcha widget gives the browser a single-use token. Your application sends that token to hCaptcha and checks the response before processing the form. This unofficial client handles verification and makes the result available to your application as an HCaptchaVerifyResponse.
| NuGet package | Use it for |
|---|---|
| HCaptcha | Verify a token directly from a .NET application. |
| HCaptcha.AspNetCore | Register the client with dependency injection and bind the verified response to an MVC action parameter. Includes the core package. |
Table of Contents
Usage with ASP.NET Core
dotnet add package HCaptcha.AspNetCore
Configure the public site key with HCaptcha:SiteKey and supply the server secret through your secret store or the HCaptcha__Secret environment variable. Register the client and the model binder in Program.cs:
using BenjaminAbt.HCaptcha.AspNetCore;
builder.Services.AddHCaptcha(builder.Configuration.GetRequiredSection("HCaptcha"));
builder.Services.AddControllersWithViews(options => options.AddHCaptchaModelBinder());
In a Razor form, render the widget with the public site key:
@inject Microsoft.Extensions.Options.IOptions<BenjaminAbt.HCaptcha.HCaptchaOptions> Captcha
<form method="post">
@Html.AntiForgeryToken()
<div class="h-captcha" data-sitekey="@Captcha.Value.SiteKey"></div>
<button type="submit">Submit</button>
</form>
<script src="@Captcha.Value.JavaScriptUrl" async defer></script>
Check the server result before executing the protected operation:
[HttpPost, ValidateAntiForgeryToken]
public IActionResult Submit(HCaptchaVerifyResponse? captcha)
{
if (!ModelState.IsValid || captcha?.Success != true)
return BadRequest("Please complete a new challenge.");
return Ok();
}
The binder reads one token from the configured form field (default h-captcha-response) and forwards request cancellation. The client posts a URL-encoded form to https://api.hcaptcha.com/siteverify, including the expected site key. By default it includes the client IP when available. Behind a reverse proxy, configure ASP.NET Core forwarded headers for your trusted proxies. Set HCaptcha:VerifyRemoteIp to false to omit the IP. Tokens are single-use. Obtain a fresh token after a failed or timed-out verification. hCaptcha developer guide
Direct verification
Inject IHCaptchaProvider and call await provider.VerifyAsync(token, remoteIp, cancellationToken). Authorize the operation only when the returned response has Success == true. For standalone use, construct HCaptchaProvider with an HttpClient whose base address is the verification API and IOptions<HCaptchaOptions> containing the site key and secret. Direct callers should handle HCaptchaApiException for HTTP status or malformed JSON, HttpRequestException for transport failures and cancellation or timeouts.
Sample and build
The MVC sample targets .NET 11. Its Development configuration uses hCaptcha's public, always-pass test credentials. Supply your own credentials for a deployed application. hCaptcha test keys
dotnet run --project sample/sample.aspnetcore
dotnet build -c Release
dotnet test -c Release --no-build --coverlet --coverlet-include '[BenjaminAbt.HCaptcha*]*' --coverlet-output-format cobertura --coverlet-threshold 90 --coverlet-threshold-type line --coverlet-threshold-stat Minimum
dotnet pack -c Release --no-build -o artifacts
Build with SDK 11.0.100 or a compatible patch. The xUnit tests run on Microsoft.Testing.Platform. Install the ASP.NET Core runtimes for .NET 8, 9, 10, and 11 to run the full suite.
The HCaptcha.UnitTests project measures both shipping libraries with Coverlet. CI requires at least 90% line coverage for each library on each target framework. Pull requests publish the Cobertura reports alongside the TRX test results.
Releases
Pull requests build, test all four frameworks, and check packaging. A successful main build creates a GitHub draft release for its Nerdbank.GitVersioning version and attaches the two NuGet packages and their symbols. Review and publish the desired draft to distribute those exact assets.
Configure NuGet.org Trusted Publishing for the package owner, this repository and workflow release-publish.yml. Set the GitHub Actions secret NUGET_USER to the NuGet.org account name. The workflow exchanges GitHub's OIDC token for a short-lived publishing key.
Donation
Please donate, if possible, to an institution of your choice such as child cancer aid or a children's hospice.
License
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 is compatible. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. net11.0 is compatible. |
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 2.0.2 | 45 | 11/18/2026 |
| 1.0.7 | 69,716 | 11/13/2024 |
| 1.0.7-ga1b8a4fa50 | 219 | 11/13/2024 |
| 1.0.5 | 235 | 11/13/2024 |
| 1.0.4 | 246 | 11/13/2024 |
| 1.0.4-g8c581954ef | 209 | 11/13/2024 |
| 0.9.19 | 89,929 | 12/24/2021 |
| 0.9.17 | 1,001 | 12/21/2021 |
| 0.9.16-g5024fcb5c8 | 833 | 12/20/2021 |
| 0.9.14-ge401fdfde5 | 825 | 12/20/2021 |
| 0.9.14-gb29838ccdc | 849 | 12/20/2021 |
| 0.9.8 | 4,725 | 9/29/2020 |
| 0.9.6 | 1,206 | 9/29/2020 |
| 0.9.3 | 1,319 | 4/11/2020 |
| 0.9.2 | 1,224 | 4/11/2020 |
| 0.0.1 | 1,246 | 4/9/2020 |