.NET Core Command-Line Tools UX Guidelines

This document outlines the User Experience (UX) of the .NET Core command lline tools (CLI).These guideliens are intended for anyone that wants to add a new command to the CLI.

The guidelines presented in this document have been adopted to provide a clear and concise command line syntax that is easy to learn, remember and work with, and that has an added benefit of being familiar to people who have used other command-line interfaces as well as existing Visual Studio users.

Naming the commands

In the .NET Core CLI, commands should be verbs. This rule was adopted because most of the commands do something.

Sub-commands are supported in the CLI, and they are usually nouns. A good example of this is the “dotnet add reference” command. If there is a need to add a subcommand, that subcommand should usually specialize what the parent command does.

Create/Read/Update/Delete (CRUD) commands

New CRUD commands should be named according to the following logic:

• Does the command work on data in the project (either properties or items)? If yes, then it should be added as a noun to the “dotnet add/list/remove/update”, e.g. “dotnet add foo”.

• Does the command work on the solution (SLN) file? If yes, then it should be added as a verb to the “dotnet sln” command.

• Does the command work on a completely new artifact (e.g. a new metadata file that is added in the future)? If yes, it should be created as a top level noun with all of the underlying operations defined as sub-commands.

• If the command adds a new artifact to the project, it should become an item template that is dropped with “dotnet new” command.

If none of the above applies, the proposal should clearly outline why none of the above applies and suggest an alternative naming that will be decided on during the process described above.

If the command works on the project or solution, it must also accept an optional argument that specifies which project or solution to work on. The current convention is for that argument to follow the verb in the CRUD command. For example:

dotnet add <PROJECT> reference <REFERENCE>

All the existing CRUD commands have this argument defined and it will be passed to the sub-command as part of the overall options. The sub-command is expected to consider this optional argument.

Options

CLI follows the GNU convention for options’ format, which is based on the POSIX standard. The summary is:

• Command can have both short and long options.

• The short format starts with a single dash (“-“), and has exactly one letter. The letter is usually the start letter of the longer form of the option, e.g. “-o” for “--output” or any of its words. This provides a good mnemonic.

  • Example: “dotnet build -o path/to/where/to/put/output”

• The long format starts with double dashes (“--“) and can have one or more words. Multiple words are separated by a single dash (“-“).

  • Example: “dotnet test --test-case-filter”

• The double dashes (“--“) on their own mark the argument separator. Anything after this option is passed verbatim to whatever the command starts as a sub-process.

  • Example: “dotnet run -- --app-arg-1”

• Windows-style forward slash options (e.g. “/p”) are supported only for MSBuild parameters.

• PowerShell-style single dashes with a word (e.g. “-Filter”) are not supported.

• Help options are predefined as “-h | --help” and those should be used.

There are common options in the CLI that are reserved for certain concepts. The table below outlines those common options. If a command needs to accept the same options, it should use these and it must not replace their semantics (e.g. use “--output” to mean something different or redefine what “-f” means for just that command).

Long optionShort optionDescription--framework-fSpecifies which framework (target) to use in the invocation.--output-oSpecifies where the output of the command should be placed.--runtime-rSpecifies the runtime ID (RID) to use in the invocation.--configuration-cSpecifies the configuration to use in the invocation.--verbosity-vSpecifies the verbosity level of the command.--help-hShows the help for the command.

One special area is interacting with MSBuild. If a command has the need to do that, there are two additional requirements with regards to options:

1. The commands need to be able to take “/p” parameters in addition to whatever other properties they require.

2. If the command invokes a predefined MSBuild target, it needs to block “/t:<target>” and “/target:<target>” options and throw an error that is pre-defined in the CLI.

It is important to note that commands that invoke user-specified targets should not be submitted to the CLI, since the CLI comes with “dotnet msbuild” command that does precisely that.

Arguments

Arguments can have any name that authors of the commands being added need. We do have predefined argument names for the SLN file and project file. They are defined in the CLI source code and should be used if the command has the need to use those two arguments.

Help messages

Help messages are automatically generated based on the arguments, options and command name. No other work should be required here apart from setting up the above mentioned and their descriptions.

Output

For commands that are invoking MSBuild, the output will be controlled by MSBuild itself.

In case of a long running operation, the command needs to provide a feedback mechanism to the user to help the user reason about whether the command has crashed or is just waiting for I/O. The feedback mechanism guidelines are below:

1. Feedback should not require fonts with special glyphs for display.
2. Pure text is acceptable (e.g. Running background process...) as a feedback mechanism.
3. Spinners that conform to rule #1 above are also acceptable.

Verbosity

If the command interacts with MSBuild, it is required that it can accept a “--verbosity | -v” argument and pass it to MSBuild verbatim.

If the command’s verbosity levels cannot fit naturally in MSBuild’s verbosity levels or the command does not interact with MSBuild but still has an option to set the verbosity, it is the job of the command to map them in the most appropriate way. This way, the verbosity levels will be uniform across all commands which brings consistency to the toolset.

Example

As an example, let us consider a “dotnet configure” command. It doesn’t interact with MSBuild. I wish to have verbosity on it, but it really has only two levels: quiet (just successes or errors) and verbose (every operation) that I've defined for the command. To satisfy the above-mentioned requirement, in my command I would define the “--verbosity | -v” option and would map the arguments in the following way:

• “Quiet” gets mapped naturally to “quiet”

• “Minimal”, “Normal” and “Diagnostic” get mapped into “verbose”