Page 26 - MSDN Magazine, March 2019

ESSENTIAL .NET
Parse the
Command Line with
System.CommandLine
Mark Michaelis
Going all the way back to. NET Framework 1.0, I’ve been astounded that there’s been no simple way for developers to parse the command line of their applications. Applications start execu- tion from the Main method, but the arguments are passed in as an array (string[] args) with no differentiation between which items in the array are commands, options, arguments and the like.
I wrote about this problem in a previous article (“How to Con- tribute to Microsoft Open Source Software Projects,” msdn.com/ magazine/mt830359), and described my work with Microsoft’s Jon Sequeira. Sequeira has lead an open source team of developers to create a new command-line parser that can accept command-line arguments and parse them into an API called System.Command- Line, which does three things:
• Allows for the configuration of a command line.
• Enables parsing of command-line generic arguments (tokens) into distinct constructs, where each word on the command line is a token. (Technically, command-line hosts allow for
the combining of words into a single token using quotes.) • Invokes functionality that’s configured to execute based on
the command-line value.
The constructs supported include commands, options, arguments, directives, delimiters and aliases. Here’s a description of each construct: Commands: These are the actions that are supported by the application command line. Consider, for example, git. Some of the built-in commands for git are branch, add, status, commit and push. Technically, the commands specified after the executable name are, in fact, subcommands. Subcommands to the root com- mand—the name of the executable itself (for example, git.exe)— may themselves have their own subcommands. For instance, the command “dotnet add package” has “dotnet” as the root command, “add” as a subcommand and “package” as the subcommand to add
(perhaps call it the sub-subcommand?).
Options: These provide a way to modify the behavior of a
command. For example, the dotnet build command includes the --no-restore option, which you can specify to disable the restore command from running implicitly (and instead relying on prior execution of the restore command). As the name implies, options are generally not a required element of a command.
Arguments: Both commands and options can have associated values. For example, the dotnet new command includes the tem- plate name. This value is required when you specify the new command. Similarly, options may have values associated with them. Again, with dotnet new, the --name option has an argument for specifying the name of the project. The value associated with a command or option is called the argument.
Directives: These are commands that are cross-cutting for all appli- cations. For example, a redirect command can force all output (stderr and stdout) to go into an .xml format. Because directives are part of
This article discusses:
• System.CommandLine—a new API for parsing the command line that launches an application
• Support for self-contained applications, including on Linux Technologies discussed:
.NET Core, System.CommandLine
20 msdn magazine