Skip to content

Getting Started#

What is CommandDotNet?#

CommandDotNet is modern framework for building modern CLI apps

Out of the box support for commands, sub-commands, validations, dependency injection, piping and streaming, enums & custom types, typo suggestions, prompting, passwords, response files and much more!

Favors POSIX conventions

Includes test tools used by the framework to test all features of the framework.

Modify and extend the functionality of the framework through configuration and middleware.

Support#

For bugs, create an issue

For questions and feature requests, start a discussion

Credits 🎉#

Special thanks to Drew Burlingame for continuous support and contributions

Installation#

CommandDotNet can be installed from nuget.org

dotnet add package CommandDotNet

Install-Package CommandDotNet

Let's build a calculator#

Let's say you want to create a calculator console application which can perform 2 operations:

  1. Addition
  2. Subtraction

It prints the results on console.

Let's begin with creating the class

public class Calculator
{
    public void Add(int value1, int value2)
    {
        Console.WriteLine($"Answer:  {value1 + value2}");
    }

    public void Subtract(int value1, int value2)
    {
        Console.WriteLine($"Answer:  {value1 - value2}");
    }
}

Now that we have our calculator ready, let's see about how we can call it from command line.

class Program
{
    static int Main(string[] args)
    {
        return new AppRunner<Calculator>().Run(args);
    }
}

Assuming our application's name is example.dll

let's try and run this app from command line using dotnet

~
$ dotnet example.dll --help
Usage: dotnet example.dll [command]

Commands:

  Add
  Subtract

Use "dotnet example.dll [command] --help" for more information about a command.

Voila!

So, as you might have already guessed, it is detecting methods of the calculator class. How about adding some helpful description.

[Command(Description = "Performs mathematical calculations")]
public class Calculator
{
    [Command(Description = "Adds two numbers")]
    public void Add(int value1, int value2)
    {
        Console.WriteLine($"Answer:  {value1 + value2}");
    }

    [Command(Description = "Subtracts two numbers")]
    public void Subtract(int value1, int value2)
    {
        Console.WriteLine($"Answer:  {value1 - value2}");
    }
}

This should do it.

Let's see how the help appears now.

~
$ dotnet example.dll --help
Performs mathematical calculations

Usage: dotnet example.dll [command]

Commands:

  Add       Adds two numbers
  Subtract  Subtracts two numbers

Use "dotnet example.dll [command] --help" for more information about a command.

Descriptions are not required but can be very useful depending upon the complexity of your app and the audience.

Now let's see help for the Add command.

~
$ dotnet example.dll Add --help
Adds two numbers

Usage: dotnet example.dll Add [arguments]

Arguments:

  x  <NUMBER>

  y  <NUMBER>

Here we see arguments for addition and their type. See the Arguments section for more options.

Let's try and add two numbers.

~
$ dotnet example.dll Add 40 20
Answer: 60

Let's add some tests#

public class PipedInputTests
{
    [Test]
    public void Add_Given2Numbers_Should_OutputSum()
    {
        var result = new AppRunner<Calculator>().RunInMem("Add 40 20");
        result.ExitCode.Should().Be(0);
        result.Console.Out.Should().Be(@"60");
    }
}

note: Should() is a feature of the FluentAssertions library and will be used in many examples.

public class PipedInputTests
{
    [Test]
    public void Add_Given2Numbers_Should_OutputSum()
    {
        new AppRunner<Calculator>().Verify(new Scenario
        {
            When = { Args = "Add 40 20" },
            Then = { Output = @"60" }
        });
    }
}

See Test Tools in the Testing help section for more details

Opt-In to additional features#

In the Program.Main, we configured the app with the basic feature set. 

    return new AppRunner<Calculator>().Run(args);

To take advantage of many more additional features, such as debug & parse directives, ctrl+c support, prompting, piping, response files and typo suggestions, add UseDefaultMiddleware()

    return new AppRunner<Calculator>()
        .UseDefaultMiddleware()
        .Run(args);

see Default Middleware for more details and options for using default middleware.

Next Steps#

You get the gist of this library now. This may be all you need to start your app.

Check out the

  • Commands section for more about defining commands, subcommands and arguments.

  • Arguments section for more about defining arguments.

  • Argument Values section for more about providing values to arguments.

  • Help section for options to modify help and other help features.

  • Diagnostics section for a rich set of tools to simplify troubleshooting

  • Other Features section to see the additional features available.

  • Extensibility section if the framework is missing a feature you need and you're interested in adding it yourself. For questions, ping us on our Discord channel or create a GitHub Issue

  • Test Tools section for a test package to test console output with this framework. These tools enable you to provide end-to-end testing with the same experience as the console as well as testing middleware and other extensibility components. This package is used to test all of the CommandDotNet features.

Back to top