Migrate to System.CommandLine 2.0.0-beta5

[dougcunha]

Summary

System.CommandLine 2.0.0-beta5 introduces several breaking changes that require code updates throughout the project. This issue tracks the migration effort.

References

• Migration guide

Breaking changes to address

• Renaming:
  • Several properties and types have been renamed (e.g., Option.IsRequired → Option.Required, Symbol.IsHidden → Symbol.Hidden, etc.).
  • Parser is now CommandLineParser and is a static class.
• Mutable collections:
  • Collections like Arguments, Options, Subcommands, Validators, and Aliases are now mutable collections. Use .Add() and .Remove() directly instead of AddArgument, AddOption, etc.
• Names and aliases:
  • The name is now a mandatory parameter for all Option<T>, Argument<T>, and Command constructors. Aliases are provided as params. The description must be set via the Description property.
  • The Aliases property no longer includes the name itself.
• Default values and custom parsing:
  • Use the DefaultValueFactory property for default values.
  • Use the CustomParser property for custom parsing.
• Handler and invocation:
  • SetHandler is now SetAction.
  • The handler signature has changed: it now receives ParseResult (and optionally CancellationToken). InvocationContext was removed.
  • ICommandHandler and related interfaces were removed.
• Configuration:
  • CommandLineBuilder and related APIs were replaced by a mutable CommandLineConfiguration.
  • IConsole and related interfaces were removed. Use TextWriter for output.
• Parsing and invocation:
  • Command.Parse returns a ParseResult, which exposes Invoke and InvokeAsync methods.
• Global options
  • The method Command.AddGlobalOption was removed and now all global options should be added as a option on the parent/root command with the property Recursive = true

Migration steps

• Update all usages of renamed types and properties.
• Refactor all usages of Command.InvokeAsync(args) to Command.Parse(args).InvokeAsync().
• Refactor all usages of AddArgument, AddOption, etc., to use the new mutable collections Arguments.Add and Options.Add.
• Refactor all usages of AddGlobalOption to use Options.Add and set the property Recursive = true
• Update all Option and Argument constructors to provide the name and aliases as required.
• Refactor command handlers to use SetAction and update signatures to use ParseResult and CancellationToken.
• Update configuration and output handling to use the new APIs.
• Update tests and mocks to match the new API surface.

Acceptance criteria

• The project builds and all tests pass using System.CommandLine 2.0.0-beta5.
• Test coverage should aim to cover 100% of the code base. Minimum of 95% is acceptable.
• All obsolete API usages are removed.

---

This is a breaking change and will require coordinated updates across commands, tests, and startup/configuration code.