Show / Hide Table of Contents

    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.

    Copyright © Matthias Koch
    MIT License
    Slack | Gitter | GitHub | Twitter
    Back to top