Parameter Declaration

Build automation often requires to incorporate parameters that are dynamic or secret. Such parameters can either be passed via command-line arguments or environment variables. Dynamic parameters can have default values, that are only overridden on demand. Meanwhile, secret parameters should never appear in clear text in the build implementation. NUKE offers a declarative approach to define build input parameters by decorating fields and properties with the Parameter attribute:

[Parameter]
readonly string Configuration { get; } = IsLocalBuild ? "Debug" : "Release";

This example defines Configuration as a parameter with a default value of Debug for local builds, and Release for server builds. The default value can easily be overriden by setting an environment variable or passing it from the command-line:

$ build --configuration Release

A declared parameter can also have a description and will automatically show up in the help output of the build.

Note

The resolution of parameters is very forgiving. For instance, a parameter ApiKey can be passed with pascal-casing -ApiKey or lisp-casing --api-key. Minor typing mistakes can be detected from calculating the Levenshtein distance and are reported as warnings. However, in practice it is more convenient to use the global tool shell-completion.

Supported Types

String values passed as parameters can be automatically converted into a variety of types. Out-of-the-box, NUKE supports primitive types like bool, string, and other numeric types:

Parameter Type	Input	Injected Value
string	none	null
string	--param value	value
int	none	0
bool	--param	true
bool	--param false	false
bool? / int?	none	null

Also arrays of the above are supported:

Parameter Type	Input	Injected Value
string[]	none	null
string[]	--param	new string[0]
int[]	--param 1 2	new[] { 1, 2 }

Even more exotic types are supported, like AbsolutePath and types deriving from Enumeration (mostly used for CLI tools):

Parameter Type	Input	Injected Value
AbsolutePath	--param /bin/etc	/bin/etc
AbsolutePath	--param ./etc	/bin/etc
MSBuildVerbosity	--param minimal	MSBuildVerbosity.Minimal

Note

Custom conversions can be added by implementing a TypeConverter, which should take the string value and convert it to the complex object. In fact, the conversion for AbsolutePath is implemented this way.