Table of Contents

Interface IParamService

Namespace
Invex.Atom.Build.Params
Assembly
Invex.Atom.Build.dll

Defines a service for resolving and managing build parameters from various sources.

public interface IParamService

Remarks

The service resolves parameters from the following sources in order of precedence:

  1. Cache (if enabled)
  2. Command-line arguments
  3. Environment variables
  4. Configuration files (e.g., appsettings.json)
  5. Secret providers
  6. Interactive console prompts
  7. Default value

This service is central to the framework's parameter handling, providing features for type conversion, secret masking, and caching.

Methods

CreateDefaultValuesOnlyScope()

Creates a disposable scope that temporarily causes parameter resolution to be suppressed, returning only default values (when they exist).

IDisposable CreateDefaultValuesOnlyScope()

Returns

IDisposable

An System.IDisposable that restores the previous state upon disposal.

CreateNoCacheScope()

Creates a disposable scope within which parameter caching is temporarily disabled.

IDisposable CreateNoCacheScope()

Returns

IDisposable

An System.IDisposable that restores the previous cache state upon disposal.

CreateOverrideSourcesScope(ParamSource)

Creates a disposable scope that temporarily overrides parameter sources.

IDisposable CreateOverrideSourcesScope(ParamSource sources)

Parameters

sources ParamSource

The parameter sources to use within the scope.

Returns

IDisposable

An System.IDisposable that restores the previous state upon disposal.

GetParam(string, string?)

Retrieves a string parameter value by its name.

string? GetParam(string paramName, string? defaultValue = null)

Parameters

paramName string

The name of the parameter to retrieve.

defaultValue string

The value to return if the parameter cannot be resolved.

Returns

string

The resolved string parameter value, or the default value if not found.

GetParam<T>(Expression<Func<T?>>, T?, Func<string?, T?>?)

Retrieves a parameter value using a lambda expression to identify the parameter.

T? GetParam<T>(Expression<Func<T?>> paramExpression, T? defaultValue = default, Func<string?, T?>? converter = null)

Parameters

paramExpression Expression<Func<T>>

A lambda expression identifying the parameter (e.g., () => MyParam).

defaultValue T

The value to return if the parameter cannot be resolved.

converter Func<string, T>

An optional function to convert the resolved string value to the target type.

Returns

T

The resolved parameter value, or the default value if not found.

Type Parameters

T

The target type of the parameter.

GetParam<T>(string, T?, Func<string?, T?>?)

Retrieves a parameter value by its name.

T? GetParam<T>(string paramName, T? defaultValue = default, Func<string?, T?>? converter = null)

Parameters

paramName string

The name of the parameter to retrieve.

defaultValue T

The value to return if the parameter cannot be resolved.

converter Func<string, T>

An optional function to convert the resolved string value to the target type.

Returns

T

The resolved parameter value, or the default value if not found.

Type Parameters

T

The target type of the parameter.

MaskMatchingSecrets(string)

Replaces known secret values in the provided text with a mask (e.g. "*****").

string MaskMatchingSecrets(string text)

Parameters

text string

The text to scan and mask.

Returns

string

The text with any resolved secret values replaced by a mask.

PrefetchSecretsAsync(IEnumerable<string>, CancellationToken)

Asynchronously resolves the given secret parameters from the registered ISecretsProvider instances and caches the results, so that later synchronous GetParam calls do not block on provider network calls.

Task PrefetchSecretsAsync(IEnumerable<string> paramNames, CancellationToken cancellationToken)

Parameters

paramNames IEnumerable<string>

The names of the parameters to prefetch. Parameters that are not secrets, that do not allow Secrets, that were already prefetched, or that can be resolved from the cache, command-line arguments, environment variables or configuration are skipped.

cancellationToken CancellationToken

A token passed to each GetSecretAsync(string, CancellationToken) call.

Returns

Task

A task that completes when all requested secrets have been queried.

Remarks

The build executor calls this for the secret parameters of every target that will run, using the build's cancellation token. A secret that is not prefetched is still resolved on demand by blocking on the providers. The default implementation does nothing.