Interface IParamService
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:
- Cache (if enabled)
- Command-line arguments
- Environment variables
- Configuration files (e.g.,
appsettings.json) - Secret providers
- Interactive console prompts
- 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
sourcesParamSourceThe 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
paramNamestringThe name of the parameter to retrieve.
defaultValuestringThe 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
paramExpressionExpression<Func<T>>A lambda expression identifying the parameter (e.g.,
() => MyParam).defaultValueTThe value to return if the parameter cannot be resolved.
converterFunc<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
TThe 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
paramNamestringThe name of the parameter to retrieve.
defaultValueTThe value to return if the parameter cannot be resolved.
converterFunc<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
TThe 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
textstringThe 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
paramNamesIEnumerable<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.
cancellationTokenCancellationTokenA 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.