CSharpEssentials.GcpSecretManager
8.0.0
dotnet add package CSharpEssentials.GcpSecretManager --version 8.0.0
NuGet\Install-Package CSharpEssentials.GcpSecretManager -Version 8.0.0
<PackageReference Include="CSharpEssentials.GcpSecretManager" Version="8.0.0" />
<PackageVersion Include="CSharpEssentials.GcpSecretManager" Version="8.0.0" />
<PackageReference Include="CSharpEssentials.GcpSecretManager" />
paket add CSharpEssentials.GcpSecretManager --version 8.0.0
#r "nuget: CSharpEssentials.GcpSecretManager, 8.0.0"
#:package CSharpEssentials.GcpSecretManager@8.0.0
#addin nuget:?package=CSharpEssentials.GcpSecretManager&version=8.0.0
#tool nuget:?package=CSharpEssentials.GcpSecretManager&version=8.0.0
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
BatchSizemust be greater than zero andPageSizemust not be negative; other values now throwArgumentOutOfRangeExceptionwhen set. Before, aBatchSizeof zero or less hung startup and a negativePageSizeloaded no secrets. Remove the setting or use a valid value.- Configuration keys from secrets are now case-insensitive. Before,
database__passworddid not matchDatabase:Password, and secrets whose ids differ only by case (Keyandkey) gave two keys; now the first one in list order wins. Rename such secrets if you need both values.
| Product | Versions 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. |
-
.NETStandard 2.1
- CSharpEssentials.Core (>= 8.0.0)
- CSharpEssentials.Resilience (>= 8.0.0)
- Google.Cloud.SecretManager.V1 (>= 2.6.0)
- Microsoft.Extensions.Configuration (>= 9.0.4)
- Microsoft.Extensions.Configuration.Binder (>= 9.0.4)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 9.0.4)
- Microsoft.Extensions.Logging.Abstractions (>= 9.0.4)
- Polly.Core (>= 8.0.0 && < 9.0.0)
- System.Text.Json (>= 9.0.4)
-
net10.0
- CSharpEssentials.Core (>= 8.0.0)
- CSharpEssentials.Resilience (>= 8.0.0)
- Google.Cloud.SecretManager.V1 (>= 2.6.0)
- Microsoft.Extensions.Configuration (>= 9.0.4)
- Microsoft.Extensions.Configuration.Binder (>= 9.0.4)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 9.0.4)
- Microsoft.Extensions.Logging.Abstractions (>= 9.0.4)
- Polly.Core (>= 8.0.0 && < 9.0.0)
-
net11.0
- CSharpEssentials.Core (>= 8.0.0)
- CSharpEssentials.Resilience (>= 8.0.0)
- Google.Cloud.SecretManager.V1 (>= 2.6.0)
- Microsoft.Extensions.Configuration (>= 9.0.4)
- Microsoft.Extensions.Configuration.Binder (>= 9.0.4)
- Polly.Core (>= 8.0.0 && < 9.0.0)
-
net9.0
- CSharpEssentials.Core (>= 8.0.0)
- CSharpEssentials.Resilience (>= 8.0.0)
- Google.Cloud.SecretManager.V1 (>= 2.6.0)
- Microsoft.Extensions.Configuration (>= 9.0.4)
- Microsoft.Extensions.Configuration.Binder (>= 9.0.4)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 9.0.4)
- Microsoft.Extensions.Logging.Abstractions (>= 9.0.4)
- Polly.Core (>= 8.0.0 && < 9.0.0)
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 |