CSharpEssentials.GcpSecretManager 8.0.0

dotnet add package CSharpEssentials.GcpSecretManager --version 8.0.0
                    
NuGet\Install-Package CSharpEssentials.GcpSecretManager -Version 8.0.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="CSharpEssentials.GcpSecretManager" Version="8.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="CSharpEssentials.GcpSecretManager" Version="8.0.0" />
                    
Directory.Packages.props
<PackageReference Include="CSharpEssentials.GcpSecretManager" />
                    
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 CSharpEssentials.GcpSecretManager --version 8.0.0
                    
#r "nuget: CSharpEssentials.GcpSecretManager, 8.0.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.
#:package CSharpEssentials.GcpSecretManager@8.0.0
                    
#: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=CSharpEssentials.GcpSecretManager&version=8.0.0
                    
Install as a Cake Addin
#tool nuget:?package=CSharpEssentials.GcpSecretManager&version=8.0.0
                    
Install as a Cake Tool

CSharpEssentials.GcpSecretManager

Loads Google Cloud Secret Manager secrets into .NET configuration as ordinary IConfiguration keys. It reads one or more projects, configured in code or in appsettings.json, fetches secrets in parallel batches and retries transient gRPC failures through CSharpEssentials.Resilience.

Installation

dotnet add package CSharpEssentials.GcpSecretManager

This package is not Native AOT compatible: it builds on Google.Cloud.SecretManager.V1, and the Google Cloud .NET libraries do not support trimming or Native AOT yet. Trimming them raises IL2026 and IL2104 warnings from Google.Api.Gax.Grpc, Google.Apis.Core, Google.Protobuf and Newtonsoft.Json, and the maintainers track support as backlog work (google-cloud-dotnet#13328).

Setup in code

using CSharpEssentials.GcpSecretManager;            // ProjectSecretConfiguration
using CSharpEssentials.GcpSecretManager.Extensions; // AddGcpSecretManager

builder.Configuration.AddGcpSecretManager(options =>
{
    options.AddProject(new ProjectSecretConfiguration
    {
        ProjectId = "my-gcp-project",
        PrefixFilters = new[] { "MyApp__" }
    });
});

string connectionString = builder.Configuration["MyApp:ConnectionStrings:Default"]!;

AddGcpSecretManager extends IConfigurationManager (builder.Configuration of a WebApplicationBuilder or HostApplicationBuilder). Secrets are loaded once, synchronously, when it is called (ConfigurationManager builds the added source immediately); there is no reload. The client uses Application Default Credentials unless options.CredentialsPath points to a credentials file. At least one project is required, otherwise AddGcpSecretManager throws ArgumentException.

ProjectSecretConfiguration:

Property Notes
ProjectId Required.
Region Optional. Reads regional secrets of projects/{id}/locations/{region} through the endpoint secretmanager.{region}.rep.googleapis.com.
PrefixFilters Load only secrets whose id starts with one of these prefixes (case-sensitive).
SecretIds Load these secrets by id, in addition to the prefix matches. With neither PrefixFilters nor SecretIds, every secret of the project is loaded.
RawSecretIds, RawSecretPrefixes Secrets kept as one string and not parsed as JSON (see below).

SecretManagerConfigurationOptions (namespace CSharpEssentials.GcpSecretManager.Configuration) is a sealed record. Besides CredentialsPath, Projects, Loader and LoggerFactory it has BatchSize (secrets read in parallel per project, default 10) and PageSize (secrets per list request, default 300, 0 lets the server choose). Setting BatchSize to zero or less, or PageSize below zero, throws ArgumentOutOfRangeException. AddProject returns the options for chaining.

The latest version of every secret is read. Keys are case-insensitive, like the rest of .NET configuration: database__password is read as Database:Password. When several projects or secrets produce the same key, ignoring case, the first one wins (projects in the order you added them).

Setup from appsettings.json

{
  "GoogleSecretManager": {
    "Projects": [
      { "ProjectId": "my-project", "PrefixFilters": ["Prod__"] }
    ]
  }
}
using CSharpEssentials.GcpSecretManager.Extensions;

builder.Configuration.AddGcpSecretManager();

Without a callback, AddGcpSecretManager() reads the projects from the GoogleSecretManager section and throws InvalidOperationException when the section, its projects or a ProjectId is missing. With a callback the section is not read; set options.LoadFromAppSettings = true to read it too, and options.ConfigurationSectionName to use another section. The section is read from the sources added before the call, so call AddGcpSecretManager after appsettings.json (the default builder.Configuration already has it). Every ProjectSecretConfiguration property can be set in the section.

Key mapping

The secret id has every __ replaced by :, so MyApp__ConnectionStrings__Default becomes MyApp:ConnectionStrings:Default.

To use another rule or another selection of secrets, implement ISecretManagerConfigurationLoader (GetKey(Secret), GetKey(string), ShouldLoadSecret(Secret, ProjectSecretConfiguration), namespace CSharpEssentials.GcpSecretManager.Configuration) and assign it to options.Loader.

JSON secrets

A secret whose value is a JSON object or array is also flattened into configuration keys. The secret's own key keeps the raw text, and every value below it gets a child key, with : between object names and array indexes:

Secret MyApp__Database Keys
{"Host":"db","Ports":[5432,5433]} MyApp:Database (the raw JSON), MyApp:Database:Host = db, MyApp:Database:Ports:0 = 5432, MyApp:Database:Ports:1 = 5433

Bind the section as usual (builder.Configuration.GetSection("MyApp:Database").Get<DatabaseOptions>()). A value that is not valid JSON is kept as a plain string. List the secret in RawSecretIds, or by prefix in RawSecretPrefixes, to keep a JSON text (a certificate, a service account file) as one value without child keys.

Logging

Configuration providers are built before dependency injection exists, so the provider does not resolve a logger and writes nothing by default. Pass an ILoggerFactory to get diagnostics (per-secret progress at Debug, failures at Error):

using ILoggerFactory loggerFactory = LoggerFactory.Create(b => b.AddConsole());

builder.Configuration.AddGcpSecretManager(options =>
{
    options.LoggerFactory = loggerFactory;
    options.AddProject(new ProjectSecretConfiguration { ProjectId = "my-gcp-project" });
});

Retries

Listing a project's secrets and accessing each secret version go through RetryIfFailed with a shouldRetry predicate. Only ResourceExhausted and Unavailable are retried: 3 retries with exponential backoff (2 s, 4 s, 8 s). The client library's own retry for secret access is turned off, so these are the only retries for it. Any other status, such as PermissionDenied or NotFound, fails at once. When a call fails for good, the original RpcException is logged once at Error: a listing failure skips that project, an access failure skips that secret, and loading continues.

Upgrading from 7.x

  • BatchSize must be greater than zero and PageSize must not be negative; other values now throw ArgumentOutOfRangeException when set. Before, a BatchSize of zero or less hung startup and a negative PageSize loaded no secrets. Remove the setting or use a valid value.
  • Configuration keys from secrets are now case-insensitive. Before, database__password did not match Database:Password, and secrets whose ids differ only by case (Key and key) gave two keys; now the first one in list order wins. Rename such secrets if you need both values.
Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  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.  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. 
.NET Core netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.1 is compatible. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos 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
8.0.0 159 11/9/2026
7.0.0 162 10/20/2026
6.5.2 125 10/10/2026
6.5.1 107 10/10/2026
6.5.0 119 10/9/2026
6.4.0 105 10/9/2026
6.3.0 106 10/8/2026
6.2.0 114 10/8/2026
6.1.0 118 10/7/2026
6.0.0 113 10/7/2026
5.2.1 122 10/7/2026
5.2.0 114 10/7/2026
5.1.0 115 10/7/2026
5.0.0 114 10/6/2026
4.1.0 123 10/6/2026
4.0.0 117 10/5/2026
3.2.3 209 5/31/2026
3.2.2 143 5/31/2026
3.2.1 141 5/31/2026
3.2.0 135 5/30/2026
Loading failed