GoogleReCaptcha.Core 1.1.0

dotnet add package GoogleReCaptcha.Core --version 1.1.0
NuGet\Install-Package GoogleReCaptcha.Core -Version 1.1.0
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="GoogleReCaptcha.Core" Version="1.1.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add GoogleReCaptcha.Core --version 1.1.0
#r "nuget: GoogleReCaptcha.Core, 1.1.0"
#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.
// Install GoogleReCaptcha.Core as a Cake Addin
#addin nuget:?package=GoogleReCaptcha.Core&version=1.1.0

// Install GoogleReCaptcha.Core as a Cake Tool
#tool nuget:?package=GoogleReCaptcha.Core&version=1.1.0

GoogleReCaptcha.Core

A small library for using Google reCAPTCHA v2 or v3 within an ASP.NET MVC applications. Features standard methods for configuring reCAPTCHA via appsettings.json or custom. Has ability to call Google's verify endpoint after submission of page forms. Supports v2 and v3 versions; v3 is default version assumed to be used.

Follow the steps below to utilize this library to add Google reCAPTCHA support to your projects.


Install the NuGet Package

You can install the package from NuGet to your project from within Visual studio or from command line:

Install-Package GoogleReCaptcha.Core

... or using dotnet CLI:

dotnet add package GoogleReCaptcha.Core

Add Service In Startup

You will need to add a call to AddGoogleReCaptchaV3 in your Startup class' ConfigureServices method. The version below retrieves its settings from appsettings.json:

public IConfiguration Configuration { get; }

public Startup(IConfiguration configuration)
{
    Configuration = configuration;
}

public void ConfigureServices(IServiceCollection services)
{
    ...

    services.AddGoogleReCaptchaV3(Configuration); // Add Google reCAPTCHA v3 support

    ...
}

Or, you could supply the reCAPTCHA configuration settings directly like this below (not recommended; use appsettings.json so you can attempt to hide items like SiteKey and SecretKey):

public void ConfigureServices(IServiceCollection services)
{
    ...

    // Add Google reCAPTCHA v3 support
    services.AddGoogleReCaptchaV3(() =>
    {
        return new ReCaptchaV3Settings
        {
            SiteKey = "<YOUR-SITE-KEY>",
            SecretKey = "<YOUR-SECRET-KEY>"
        };
    });

    ...
}

Startup Settings Configuration

You can apply your Google reCAPTCHA v3 configuration settings in appsettings.json like so:

{
...
    "GoogleReCaptcha": {
        "V3": {
            "Enabled": true,
            "LibUrl": "https://www.google.com/recaptcha/api.js",
            "ApiUrl": "https://www.google.com/recaptcha/api",
            "SiteKey": "<YOUR-SITE-KEY>", // Do not add here; add to environment var ~: GoogleReCaptcha__V3__SitetKey
            "SecretKey": "", // Do not add here; add to environment var ~: GoogleReCaptcha__V3__SecretKey
            "DefaultPassingScore": 0.7
        }
    }
...
}

The service collection extension method AddGoogleReCaptchaV3(IConfiguration) by default looks for your settings in the configuration section GoogleReCaptcha:V3.


Usage On Forms (MVC Only)

When you have the GoogleReCaptcha.Core services configured and its tag helpers imported you can use them inside your views.

You will need these items to utilize Google reCAPTCHA in your forms:

Import Tag Helpers

This library comes with tag helpers to get your reCAPTCHA configuration settings and features into your view's forms.

You will need to add the tag helpers in your views path, probably in the ~/Views/Shared/_ViewImports.cshtml file, like so:

@addTagHelper *, GoogleReCaptcha.Core

Add ReCaptcha Script

Add the Google reCAPTCHA script using the </g-recaptcha-script> tag. This will pull the Google reCAPTCHA javascript library into your view with your settings applied:

<g-recaptcha-script></g-recaptcha-script>

You can use your own </script> tag if you would like, and still enforce your own settings:

<script g-recaptcha-from-settings="true" ... ></script>

Add reCAPTCHA Aware Submit Button

You will need to add the Google reCAPTCHA aware submit button using </g-recaptcha-submit-button>. This tag helper will apply Google's required data attributes into a new </button> element in your view using your settings. It applies submit value to the data-action attribute. The default data-callback will be a function you will need to define later named onGReCaptchaV3Submit that accepts Google's reCAPTCHA token value for the current form's processing.

Apply the submit button like so:

<g-recaptcha-submit-button></g-recaptcha-submit-button>

You can treat this tag like any other </button> tag; example using Bootstrap and Fontawesome with button:

<g-recaptcha-submit-button class="btn btn-primary"><span class="fa fa-arrow-circle-up"></span> Submit</g-recaptcha-submit-button>

Add reCAPTCHA JS Function

By default the </g-recaptcha-script> is looking for a javascript function named onGReCaptchaV3Submit which accepts one value, the token for the current form's processing. You can define this function and form as below:

Javascript function for Google reCAPTCHA support (either on the view/page, or in another script file as src ref):

function onGReCaptchaV3Submit(token) {
    
    ...

    // Programmatically submit the identifiable form
    document.querySelector('#myForm').submit();
}

... very simple form view concept:


<form id="myForm" method="post" asp-antiforgery="true">
    
    ...

    
    <g-recaptcha-submit-button></g-recaptcha-submit-button>

</form>

...

<g-recaptcha-script></g-recaptcha-script>

Usage In Action Methods - Verify reCAPTCHA (MVC Only)

Inside your MVC controllers we can call to Google's reCAPTCHA API to verify its evaluation of your POST action methods via the token that is placed into the form. In the example here we have a HomeController which accepts a POST at action method Index(model). We call the verify service like so:

[HttpPost]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Index(HomeModel model)
{
    ...

    // Call Google reCAPTCHA API to verify if bot
    if (!await ReCaptchaService.VerifyAsync())
    {
        // Reject this model's data because it might be a bot's data
        ...
    }

    ...
}

The VerifyAsync() method, for V3, will determine if the action is valid based on a successful response, and based on if the response's score is greater-than-or-equal-to your passing score supplied by the DefaultPassingScore property in your settings. Or you can provide your own with the overloaded, VerifyAsync(float), method.

The call above requires that your controller accepts constructor DI which assigns to a property both based on IReCaptchaService, or IReCaptchaV3Service, like this:

public IReCaptchaService ReCaptchaService { get; }

public HomeController(IReCaptchaService reCaptchaService)
{
    ReCaptchaService = reCaptchaService;
}

reCAPTCHA v2 Invisible

To use Google's reCAPTCHA v2 invisible variant in this tool you simply setup your project as you would the v3 version except you will configure v2 with v2 settings:

  1. Add a call to AddGoogleReCaptchaV2 in your Startup class' ConfigureServices method
  2. Configure v2 settings; similar to v3 but possibly under a GoogleReCaptcha:V2 entry in your appsettings.json file. Note v2 settings are different then v3; it supports Theme and Size, but not DefaultPassingScore.
  3. Configure your razor pages the same as the v3 version show above this section

reCAPTCHA v2 Widget

To use Google's reCAPTCHA v2 widget you will need to do the following:

  1. Add a call to AddGoogleReCaptchaV2 in your Startup class' ConfigureServices method
  2. Configure v2 settings; similar to v3 but possibly under a GoogleReCaptcha:V2 entry in your appsettings.json file. Note v2 settings are different then v3; it supports Theme and Size, but not DefaultPassingScore.
  3. Use the script tag helper, </g-recaptcha-script>, as normal
  4. Use the widget tag helper, </g-recaptcha-widget>, on your razor page where you wish the checkbox widget to be shown
  5. Apply a submit script/button as normal to submit your form
  6. (Optional) To use the HTML Helpers you will need to (helpers example in example project @ ~/Views/HomeV2/Explicit.cshtml):
    1. Add a call to UseGoogleReCaptchaHtmlHelperSupport in your Startup class' Configure method
    2. Add an a using for the GoogleReCaptcha.Core.Mvc namespace in a view that is on the path of your resulting razor page; possibly in _ViewImports.cshtml like: @using GoogleReCaptcha.Core.Mvc

Do NOT use the button tag helper, </g-recaptcha-submit-button>, on your razor pages for v2 widget support.

Widget Tag Helper

The widget tag helper, </g-recaptcha-widget>, supports all the data attributes defined by Google. See Google's reCAPTCHA g-recaptcha tag attributes documentation for help on their use.


License

This library/package is license under the Don't Be A Dick public license. So, you know, don't be one.


Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  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. 
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
1.1.0 2,606 5/24/2023
1.0.0 530 11/16/2021
1.0.0-rc.2 194 6/18/2021
1.0.0-rc.1 128 6/9/2021
0.2.1 407 4/16/2021
0.2.0 397 4/15/2021
0.1.1 355 4/12/2021
0.1.0 406 4/9/2021