Where can I find updated documentation?

[jamerst]

trafficstars

I'm currently using the latest build on nuget.org (2.0.0-beta4.22272.1). This version is over a year old and thus is missing several bug fixes.

The bug fix I need specifically is #2212, so I attempted to use a newer version from the daily builds feed.

However, I ran into many issues trying to migrate to the version due to the significant API changes between the two versions. I managed to work some of it out, but I have not been able to find any documentation at all for the new version. Even just a list of breaking changes would help, but the complete lack of documentation has made migration next to impossible.

I still haven't been able to work out how to migrate the following:

• Custom binders using BinderBase<T> - BinderBase doesn't exist any more, and I can't find a replacement
• RootCommand.SetHandler - again, no longer exists
• RootCommand.Invoke/RootCommand.InvokeAsync - also no longer exists

If documentation does exist for the new version, this should really be added to the main README. It would also be very helpful to have some information around migration, e.g. a list of breaking changes at a minimum.

[KalleOlaviNiemitalo]

Would it be feasible to backport the fix and publish beta5 without any api changes?

[jamerst]

It's quite a simple fix, so it should be possible to backport it (assuming the parsing architecture hasn't changed significantly).

[KalleOlaviNiemitalo]

Well, I thought "publish beta5" would be the risky part, if .NET SDK 7.0.305 is now using System.CommandLine 2.0.0-beta4.22526.1 with API changes, and 2.0.0-beta5 would be a higher version but no longer have those changes.

git cherry-pick 94d5994c11f8c1e2bd4105b01ffb8d922e409830 on top of 2.0.0-beta4.22272.1 hits a conflict in src/System.CommandLine/Parsing/ParseOperation.cs, because of the return/break change in https://github.com/dotnet/command-line-api/pull/2040 and the whitespace change in https://github.com/dotnet/command-line-api/pull/2164. OK, that's pretty simple to resolve. There is another conflict in src/System.CommandLine/ParseResult.cs but the https://github.com/dotnet/command-line-api/pull/2212 changes in that file don't even look necessary for the bug fix.

[bhehe]

Stumbling through the learning curves myself and struggling with old ways, new ways, finding old and outdated docs or blogs/videos. There's another issue on here calling for more up to date reference examples that would go a long ways on this front as well. Having a clear indication of what is current and relevant for green field efforts and the examples to support those is really needed.

Excited to see where this goes, but it's been a bit of a rough patch to get started and effective with using it due to these type of needs. Seems like it's been a very long road to GA for these packages as I was looking into them quite some time ago it seems and I'm just now really trying to implement them beyond curiosity.

[EricZimmerman]

this used to be getting development work quite a bit, seems stagnated now. no releases in quite a while.

[Balkoth]

• Custom binders using BinderBase<T> - BinderBase doesn't exist any more, and I can't find a replacement
• RootCommand.SetHandler - again, no longer exists
• RootCommand.Invoke/RootCommand.InvokeAsync - also no longer exists

Does anyone have guidance or examples on how to overcome these specific issues?

[Balkoth]

Figured some of this out by myself:

internal static class Program
{
  private static int Main(string[] args)
  {
    // Define a static local function to create an option with a description.
    static CliOption CreateOption<T>(string name, string description)
      => new CliOption<T>(name) { Description = description };

    // Create options for the export command.
    CliOption[] exportOptions = new CliOption[]
    {
      CreateOption<bool>("--reports", "Exports reports."),
      CreateOption<bool>("--files", "Exports files.")
    };

    // Create options for the check command.
    CliOption[] checkOptions = new CliOption[]
    {
      CreateOption<bool>("--reports", "Checks reports."),
      CreateOption<bool>("--files", "Checks files.")
    };

    // Create a root command containing the sub commands.
    CliRootCommand rootCommand = new CliRootCommand
    {
      new CliCommand("export", "Writes files.").WithHandler<bool, bool>(HandleExport, exportOptions),
      new CliCommand("check", "Checks options.").WithHandler<bool, bool>(HandleCheck, checkOptions)
    };

    // Create the configuration from the root command.
    CliConfiguration configuration = new CliConfiguration(rootCommand);

    // Pass args to invoke.
    return configuration.Invoke(args);
  }

  private static int HandleExport(bool reports, bool files)
  {
    return 0;
  }

  private static int HandleCheck(bool reports, bool files)
  {
    return 0;
  }
}

internal static class Extensions
{
  public static CliCommand WithHandler<T1, T2>(this CliCommand command, Func<T1, T2, int> handler, CliOption[] options)
  {
    options.ForEach(command.Add);
    command.SetAction(pr => handler(options[0].GetValue<T1>(pr), options[1].GetValue<T2>(pr)));
    return command;
  }

  private static T GetValue<T>(this CliOption option, ParseResult parseResult)
  {
    return parseResult.GetValue((CliOption<T>)option)!;
  }
}