HCaptcha.AspNetCore 2.0.2

dotnet add package HCaptcha.AspNetCore --version 2.0.2
                    
NuGet\Install-Package HCaptcha.AspNetCore -Version 2.0.2
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="HCaptcha.AspNetCore" Version="2.0.2" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="HCaptcha.AspNetCore" Version="2.0.2" />
                    
Directory.Packages.props
<PackageReference Include="HCaptcha.AspNetCore" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add HCaptcha.AspNetCore --version 2.0.2
                    
#r "nuget: HCaptcha.AspNetCore, 2.0.2"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package HCaptcha.AspNetCore@2.0.2
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=HCaptcha.AspNetCore&version=2.0.2
                    
Install as a Cake Addin
#tool nuget:?package=HCaptcha.AspNetCore&version=2.0.2
                    
Install as a Cake Tool

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

MIT License

Product 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

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