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.