Interface ISecretsProvider
Defines a contract for retrieving sensitive configuration values (secrets) from a secure storage provider.
public interface ISecretsProvider
Examples
// 1. Implement the interface
public class MySecretsProvider : ISecretsProvider
{
public async ValueTask<string?> GetSecretAsync(string key, CancellationToken cancellationToken) =>
await MySecureStore.GetAsync(key, cancellationToken);
}
// 2. Register the provider from your partial build class
static partial void OnConfigureHostBuilder(IHostApplicationBuilder builder) =>
builder.Services.AddSingleton<ISecretsProvider, MySecretsProvider>();
// 3. Use a secret parameter in a target
[SecretDefinition("my-api-key", "An API key.")]
string MyApiKey => GetParam(() => MyApiKey);
Remarks
This interface is the core of the Atom framework's secret management system, enabling secure retrieval of sensitive data like API keys and connection strings. Implementations can integrate with various backends such as Azure Key Vault or .NET User Secrets.
The framework automatically discovers and queries registered providers when resolving parameters marked with SecretDefinitionAttribute. Providers are queried in descending Priority order (ties preserve registration order), creating a fallback chain (e.g., from a cloud provider to local user secrets).
Before a build executes its targets, Atom asynchronously prefetches the secret parameters used by the targets
that will run, passing the build's cancellation token (which is signalled when the host stops). Parameter
property getters (GetParam(() => MySecret)) are synchronous, so a secret that was not prefetched (for
example, one read by name from a provider or a target that is not part of the run) is resolved by blocking
on GetSecretAsync(string, CancellationToken) with System.Threading.CancellationToken.None. Atom runs as a console
application without a System.Threading.SynchronizationContext, so this does not deadlock, but implementations
should still enforce their own timeouts for network calls.
Properties
Priority
Gets the resolution priority of the secrets provider.
int Priority { get; }
Property Value
- int
Remarks
Providers with a higher priority value are queried first when resolving secrets among multiple providers; providers with equal priority are queried in registration order. The default value is 0.
Methods
GetSecretAsync(string, CancellationToken)
Asynchronously retrieves a secret value by its key.
ValueTask<string?> GetSecretAsync(string key, CancellationToken cancellationToken)
Parameters
keystringThe unique identifier for the secret to retrieve (the parameter's argument name).
cancellationTokenCancellationTokenA token that is cancelled when the build is cancelled or the host is stopping. It is System.Threading.CancellationToken.None when the secret is resolved synchronously outside the prefetch phase.
Returns
- ValueTask<string>
The secret value associated with the key, or
nullif the secret is not found in this provider.
Remarks
Implementations should return null rather than throwing an exception if a key is not found,
allowing the framework to query other registered providers. Results are not cached by the provider
contract; Atom caches resolved values in IParamService.