All CLI tools are implemented following a code generation approach
Names of the resulting tasks and properties should be as close as possible to the original CLI tool invocations. The top-level tool
name will generate a
[Name]Tasks class (example). If the CLI tool has no sub-commands, the
tasks collection will only have one entry, resulting in a single method declaration
[Name]Tasks.[Name] (example). Otherwise, multiple objects with matching
definiteArgument must be provided, which will generate
[Name]Tasks.[Name][Postfix] methods (example).
officialUrl field is mandatory (example). Fluent APIs are intended to provide confidence. When in doubt, it must be easy to access the original tool website to get more detailed information.
All available documentation must be provided via the
help field. This applies to the tool (example), the single tasks (example), and for all properties (example). HTML tags must be used for texts; links with
<a>, lists with
<li>, emphasized text with
<em>, code with
<c>, and paragraphs with
pathExecutableresolves executables just like
wheredo, i.e., by checking the
PATHenvironment variable (example).
packageExecutableresolve the path by first checking the build project file for the package ID and then using the supplied version to determine the path of the extracted NuGet package, and then searching the
./toolsdirectory for the given package executable (example). Both fields can receive pipe-separated values to produce a fallback behavior (example).
customExecutableis a flag which will cause the generator to call
GetToolPath, which needs to be implemented manually in a separate file (example).
stringand numeric types will generate
boolwill additionally generate
List<T>will additionally generate
Dictionary<TKey, TValue>will additionally generate
LookupTable<TKey, TValue>will additionally generate
The names for lists, dictionaries and lookup tables must be pluralized.
Readable parameters are to be preferred over shorthands, i.e.,
If a tool provides several sub-commands that share a reasonable number of properties, those can be moved to the
commonTaskProperties that are automatically applied to all tasks (example), or
commonPropertySets (example) that can be applied by reference (example).