McMaster.Extensions.CommandLineUtils 2.1.0-alpha

Command-line parsing API. A community-maintained fork of Microsoft.Extensions.CommandLineUtils, plus extras.
Commonly used types:

McMaster.Extensions.CommandLineUtils.CommandLineApplication
McMaster.Extensions.CommandLineUtils.CommandOption
McMaster.Extensions.CommandLineUtils.IConsole
McMaster.Extensions.CommandLineUtils.ArgumentEscaper

This is a prerelease version of McMaster.Extensions.CommandLineUtils.
There is a newer version of this package available.
See the version list below for details.
Install-Package McMaster.Extensions.CommandLineUtils -Version 2.1.0-alpha
dotnet add package McMaster.Extensions.CommandLineUtils --version 2.1.0-alpha
<PackageReference Include="McMaster.Extensions.CommandLineUtils" Version="2.1.0-alpha" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add McMaster.Extensions.CommandLineUtils --version 2.1.0-alpha
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Usage

See detailed examples, see the samples for more examples, such as:

CommandLineApplication is the main entry point for most console apps parsing. There are two primary ways to use this API, using the builder pattern and attributes.

Attribute API

using System;
using McMaster.Extensions.CommandLineUtils;

[HelpOption]
public class Program
{
    public static int Main(string[] args)
        => CommandLineApplication.Execute<Program>(args);

    [Option(Description = "The subject")]
    public string Subject { get; }

    private void OnExecute()
    {
        var subject = Subject ?? "world";
        Console.WriteLine($"Hello {subject}!");
    }
}

Builder API

using System;
using McMaster.Extensions.CommandLineUtils;

public class Program
{
    public static int Main(string[] args)
    {
        var app = new CommandLineApplication();

        app.HelpOption();
        var optionSubject = app.Option("-s|--subject <SUBJECT>", "The subject", CommandOptionType.SingleValue);

        app.OnExecute(() =>
        {
            var subject = optionSubject.HasValue()
                ? optionSubject.Value()
                : "world";

            Console.WriteLine($"Hello {subject}!");
            return 0;
        });

        return app.Execute(args);
    }
}

Usage

See detailed examples, see the samples for more examples, such as:

CommandLineApplication is the main entry point for most console apps parsing. There are two primary ways to use this API, using the builder pattern and attributes.

Attribute API

using System;
using McMaster.Extensions.CommandLineUtils;

[HelpOption]
public class Program
{
    public static int Main(string[] args)
        => CommandLineApplication.Execute<Program>(args);

    [Option(Description = "The subject")]
    public string Subject { get; }

    private void OnExecute()
    {
        var subject = Subject ?? "world";
        Console.WriteLine($"Hello {subject}!");
    }
}

Builder API

using System;
using McMaster.Extensions.CommandLineUtils;

public class Program
{
    public static int Main(string[] args)
    {
        var app = new CommandLineApplication();

        app.HelpOption();
        var optionSubject = app.Option("-s|--subject <SUBJECT>", "The subject", CommandOptionType.SingleValue);

        app.OnExecute(() =>
        {
            var subject = optionSubject.HasValue()
                ? optionSubject.Value()
                : "world";

            Console.WriteLine($"Hello {subject}!");
            return 0;
        });

        return app.Execute(args);
    }
}

Release Notes

2.1.0:
New features:
- Attributes. Simplify command line argument definitions by adding attributes to a class that represents options and arguments.
   - Options defined as [Option] or [Argument], [Subcommand].
   - Command parsing options can be defined with [Command] and [Subcmomand].
   - Special options include [HelpOption] and [VersionOption].
- Async from end to end. Using C# 7.1 and attribute binding, your console app can be async from top to bottom.

New API
- Added OptionAttribute, ArgumentAttribute, CommandAttribute, SubcommandAttribute, HelpOptionAttribute, and VersionOptionAttribute.
- CommandLineApplication.Execute<TApp>() - executes an app where TApp uses attributes to define its options
- CommandLineApplication.ExecuteAsync<TApp>() - sample thing, but async.
- CommandLineApplication.StopParsingHelpOption and StopParsingVerboseOption. When the help and verbose options are matched
  against a command-line flag, the parsing will stop by default. You can turn this off by setting these options if you
  want OnExecute to be invoked no matter what.
- CommandLineApplication.HandleResponseFiles - the parser can treat arguments that begin with '@' as response files.
  Response files contain arguments that will be treated as if they were passed on command line.

Minor bug fixes:
- Add return types to .VerboseOption() and ensure .HasValue() is true when HelpOption or VerboseOption are matched
- Fix a NullReferenceException in some edge cases when parsing args

Showing the top 10 GitHub repositories that depend on McMaster.Extensions.CommandLineUtils:

Repository Stars
icsharpcode/ILSpy
.NET Decompiler
IdentityServer/IdentityServer4
OpenID Connect and OAuth 2.0 Framework for ASP.NET Core
dotnet/BenchmarkDotNet
Powerful .NET library for benchmarking
xunit/xunit
xUnit.net is a free, open source, community-focused unit testing tool for the .NET Framework.
scriptcs/scriptcs
Write C# apps with a text editor, nuget and the power of Roslyn!
fluentmigrator/fluentmigrator
Fluent migrations framework for .NET
MichaCo/CacheManager
CacheManager is an open source caching abstraction layer for .NET written in C#. It supports various cache providers and implements many advanced features.
tonerdo/coverlet
Cross platform code coverage for .NET
filipw/dotnet-script
Run C# scripts from the .NET CLI.
natemcmaster/CommandLineUtils
Command line parsing and utilities for .NET Core and .NET Framework.

Version History

Version Downloads Last updated
2.4.0-alpha.70 88 6/20/2019
2.3.4 42,358 4/11/2019
2.3.3 30,562 3/11/2019
2.3.2 50,161 2/5/2019
2.3.1 13,087 1/19/2019
2.3.0 41,929 1/1/2019
2.3.0-rc.460 253 12/15/2018
2.3.0-beta 715 12/4/2018
2.3.0-alpha 1,883 10/3/2018
2.2.5 199,446 7/2/2018
2.2.4 36,990 5/25/2018
2.2.3 18,242 5/11/2018
2.2.2 16,682 4/28/2018
2.2.1 9,282 4/11/2018
2.2.0 99,882 3/31/2018
2.2.0-rc 802 3/23/2018
2.2.0-beta 538 3/8/2018
2.2.0-alpha 510 2/20/2018
2.1.1 49,791 12/28/2017
2.1.0 1,742 12/13/2017
2.1.0-rc 489 12/7/2017
2.1.0-beta 1,374 11/22/2017
2.1.0-alpha 393 11/11/2017
2.0.1 5,669 10/13/2017
2.0.0 4,138 9/16/2017
Show less