Skip to content

Resetting System.CommandLine #2338

Open
@KathleenDollard

Description

@KathleenDollard

We are resetting the System.CommandLine project to better align with the current ecosystem, isolate parsing behavior so it can be shares with other parser libraries and clarify long term maintenance. This work is intended to bring System.CommandLine out of preview mode.

System.CommandLine provides command line parsing focused on providing a full featured strongly typed command line parser. It is used by the .NET CLI, many .NET tools, and other console applications. The effort has been primarily volunteer powered and changes are needed to shift maintenance responsibility to the .NET teams and align with changes in the ecosystem.

Going forward, the effort will have three parts:

  • A core parser which we plan to locate in the .NET Libraries
  • An open source full featured parser relying on the core parser and extensible subsystems for end user behavior such as help
  • An open ecosystem to encourage community creation/extension of parsers

We will separate the core parser which offers fast POSIX parsing, while also supporting other parsing styles including most Windows style parsers. This parser will be used by a full featured parser that will provide automatic help, tab completion, error reporting and other end-user features. The core parser itself will not provide any end user features, such as help.

A subsystem layer on top of the core parser will support full featured parsing with individually replaceable components. For example, it will support a help subsystem, and we will release the help system we use in the .NET CLI. CLI authors could select a different help subsystem within this extensibility model. We hope this design will foster creativity in the ecosystem by allowing folks to focus on specific aspects of the CLI experience while reusing the rest of the parser.

Parsers today

System.CommandLine is built on preview .NET CLI parsers and has had thousands of PRs across many years to match Posix guidance and user expectations. System.CommandLine has also been updated for fast parsing. While parsers seem simple, there are many hundreds of nuanced expectations within Posix, and parsing Windows command lines remains important for some tools.

For .NET, in addition to parsing behavior end users have expectations on the format of input and how those values are converted to strongly typed values. These two aspects - parsing behavior and type conversions - are the portion of System.CommandLine that is most stable and fast following performance work last year.

In the last five years, the ecosystem has done interesting things with command line libraries. For example, Spectre.Console has beautiful output and a CLI parser. We have worked with Spectre.Console's primary maintainer, @patriksvensson, who would like Spectre.Console's parser to have a dependency on a .NET-provided core parser, shifting responsibility for consistent POSIX parsing to .NET's core libraries. Working the other way, MSBuild is considering taking a dependency on Spectre.Console for output rendering.

A full featured parse will add a layer that meets end-user expectations for help, tab completion, error reporting and other supporting behavior. It will also provide the API used by CLI authors to supply information.

We believe the best way to build a ecosystem with consistent behavior and vibrant features is to provide a reusable core parser, an extensible model for features, and an open implementation of the features used in the .NET CLI and .NET tools.

The road here and onwards

System.CommandLine began as a side project for some Microsoft folks and has had many successes. Because we were creating a full featured parser, we combined feature behavior with core parser behavior. The long journey to redesign has been challenging and sometimes painful as we worked to balance needs of the community, .NET teams, the API review board, and the System.CommandLine team. We've delayed sharing plans until we had the first iteration of code isolating the parser and confidence in this design.

System.CommandLine will remain largely a community project. We are now aligned in intent and have the support of the API review board and the .NET Libraries team on the core parser, which we expect will be maintained by the .NET Libraries team. We are in the process of designing details of the subsystem layer. Overall, this effort involves very little new code since it mostly involves moving code. We have great tests across the system to make things easier.

There will be changes to the API for existing System.CommandLine CLI authors. The System.CommandLine preview will remain available so you can switch to the new library at your convenience. We intend a separate project to replace Dragonfruit with a simplified API that supports full features and subcommands.

The new project is code named "Powderhouse" and will live in a separate branch to avoid disrupting the existing stable main. The name comes from Powderhouse Square in Somerville, MA, in the Boston area.

We have a team, but we'd always love more help. One of the great aspects of that isolating the elements makes it easy to get involved. If you'd like to contribute, you'll find more in the main-powderhouse branch and with the Powderhouse label.

Metadata

Metadata

Assignees

No one assigned

    Labels

    PowderhouseWork to isolate parser and features

    Type

    No type

    Projects

    Status

    Pinned

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions