McMaster.Extensions.CommandLineUtils 2.2.0

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

Install-Package McMaster.Extensions.CommandLineUtils -Version 2.2.0
dotnet add package McMaster.Extensions.CommandLineUtils --version 2.2.0
paket add McMaster.Extensions.CommandLineUtils --version 2.2.0
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

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);
    }
}

Utilities

The library also includes other utilities for interaction with the console. These include:

  • ArgumentEscaper - use to escape arguments when starting a new command line process.
     var args = new [] { "Arg1", "arg with space", "args ' with \"" quotes" };
     Process.Start("echo", ArgumentEscaper.EscapeAndConcatenate(args));
    
  • Prompt - for getting feedback from users. A few examples:
    // allows y/n responses
    Prompt.GetYesNo("Do you want to proceed?");
    
    // masks input as '*'
    Prompt.GetPassword("Password: ");
    
  • DotNetExe - finds the path to the dotnet.exe file used to start a .NET Core process
    Process.Start(DotNetExe.FullPathOrDefault(), "run");
    

And more! See the docs for more API, such as IConsole, IReporter, and others.

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);
    }
}

Utilities

The library also includes other utilities for interaction with the console. These include:

  • ArgumentEscaper - use to escape arguments when starting a new command line process.
     var args = new [] { "Arg1", "arg with space", "args ' with \"" quotes" };
     Process.Start("echo", ArgumentEscaper.EscapeAndConcatenate(args));
    
  • Prompt - for getting feedback from users. A few examples:
    // allows y/n responses
    Prompt.GetYesNo("Do you want to proceed?");
    
    // masks input as '*'
    Prompt.GetPassword("Password: ");
    
  • DotNetExe - finds the path to the dotnet.exe file used to start a .NET Core process
    Process.Start(DotNetExe.FullPathOrDefault(), "run");
    

And more! See the docs for more API, such as IConsole, IReporter, and others.

Release Notes

New features:
 - Added more validation attributes.
    - Add the `[FileExists]` attribute
    - Add the `[FileOrDirectoryExists]` attribute
    - Add the `[DirectoryExists]` attribute
    - Add the `[LegalFilePath]` attribute
    - Add the `[AllowedValues]` attribute
 - Added a new, fluent API for validation.
    - Added `Option().Accepts()` and `Argument().Accepts()`
    - Add `.ExistingFile()`
    - Add `.ExistingFileOrDirectory()`
    - Add `.ExistingDirectory()`
    - Add `.EmailAddress()`
    - Add `.LegalFilePath()`
    - Add `.MinLength(length)`
    - Add `.MaxLength(length)`
    - Add `.RegularExpression(pattern)`
    - Add `.Values(string[] allowedValues)`
    - Add `.Range(min, max)`
 - Add `CommandOptionType.SingleOrNoValue`.
   - Options of this type can be a switch, or have a value but only in the form `--param:value` or `--param=value`.
   - Support mapping `ValueTuple<bool,T>` to `CommandOptionType.SingleOrNoValue`
 - Generic commands, options, and arguments
   - Added `CommandLineApplication<TModel>`. This allows associating an application with a specific .NET type
   - Add support for `Option<T>` and `Argument<T>`
 - Convention API
    - Adds support for writing your own conventions to convert command line arguments into a .NET type
    - Add API to use a dozen of built-in conventions

Other enhancements:
 - Support parsing enums
 - @rmcc13 - `HelpOption` can be set to be inherited by all subcommands
 - @atruskie - Support for parsing double and floats
 - @sebastienros - Support for case-insensitive options
 - @atruskie: Add support for user-defined value parsers using `IValueParser` and `CommandLineApplication.ValueParsers`.
 - Add support for constructor injection and dependency injection by providing a custom service provider
 - Parse these values to boolean: T, t, F, f, 0, 1
 - Add `VersionOptionFromMember` to use a property or method as the source of version information

See more details here: https://github.com/natemcmaster/CommandLineUtils/blob/master/CHANGELOG.md#v220

Version History

Version Downloads Last updated
2.2.4 2,408 5/25/2018
2.2.3 1,924 5/11/2018
2.2.2 2,950 4/28/2018
2.2.1 3,298 4/11/2018
2.2.0 (current) 9,505 3/31/2018
2.2.0-rc 491 3/23/2018
2.2.0-beta 347 3/8/2018
2.2.0-alpha 285 2/20/2018
2.1.1 14,975 12/28/2017
2.1.0 1,042 12/13/2017
2.1.0-rc 237 12/7/2017
2.1.0-beta 550 11/22/2017
2.1.0-alpha 163 11/11/2017
2.0.1 3,037 10/13/2017
2.0.0 2,191 9/16/2017