CliRunner 1.0.0-beta.1

CliRunner

CliRunner is a library for interacting with Command Line Interfaces and wrapping around executables.

<img src="https://github.com/alastairlundy/CliRunner/blob/main/.assets/icon.png" width="192" height="192" alt="CliRunner Logo">

Features

• Promotes the single responsibility principle and separation of concerns
• For .NET 8 and newer TFMs CliRunner has few dependencies.
• Compatible with .NET Standard 2.0 and 2.1 ^1
• Dependency Injection extensions to make using it easier.
• Support for specific specializations such as running executables or commands via Windows Powershell or CMD on Windows ^2
• SourceLink support

^1 - Polyfill is a dependency only required for .NET Standard 2.0 and 2.1 users. Microsoft.Bcl.HashCode is a dependency only required for .NET Standard 2.0 users.

^2 - The Specialization library is distributed separately.

Why use CliRunner over CliWrap?

• Greater separation of concerns with the Command class - Command Building, Command Running, andCommand Pipe handling are moved to separate classes.
• Supports Dependency Injection
• Classes and code follow the Single Responsibility Principle
• No hidden or additional licensing terms are required beyond the source code license.
• No imported C code - This library is entirely written in C#.
• No lock in regarding Piping support - Use .NET's StreamWriter and StreamReader classes as inputs and outputs respectively.
• Uses .NET's built in Process type.

Supported Platforms

This can be added to any .NET Standard 2.0, .NET Standard 2.1, .NET 8, or .NET 9 supported project.

^3 - See the Process class documentation for more info.

^4 - Lack of watchOS support is implied by lack of IOS support since watchOS is based on IOS.

Note: This library has not been tested on Android or Tizen!

Installation

• CliRunner Nuget or dotnet add package CliRunner
• CliRunner.Extensions.DependencyInjection Nuget or dotnet add package CliRunner.Extensions.DependencyInjection

Usage

Main Use Cases

One of the main use cases for CliRunner is intended to be executing programs programatically, but other valid use cases also exist such as safer Process Running.

Executing Commands

CliRunner enables use of a fluent builder style of syntax to easily configure and run Commands.

The following example shows how to configure and build a Command that returns a BufferedProcessResult which contains redirected StandardOutput and StandardError as strings.

using CliRunner;
using CliRunner.Builders.Abstractions;
using CliRunner.Builders;

  //Namespace and classs code ommitted for clarity 

  // ServiceProvider and Dependency Injection code ommitted for clarity
  
  ICommandRunner _commandRunner = serviceProvider.GetRequiredService<ICommandRunner>();

  // Fluently configure your Command.
  ICommandBuilder builder = new CommandBuilder("Path/To/Executable")
                            .WithArguments(["arg1", "arg2"])
                            .WithWorkingDirectory("/Path/To/Directory");
  
  // Build it as a Command object when you're ready to use it.
  Command command = builder.Build();
  
  // Execute the command through CommandRunner and get the results.
BufferedProcessResult result = await _commandRunner.ExecuteBufferedAsync(command);

Safe(r) Process Running

CliRunner also offers safer abstractions around Process Running to avoid accidentally not disposing of Processes after they are executed.

If directly executing the process and receiving a ProcessResult or BufferedProcessResult object is desirable you should use IProcessRunner as a service.

If you don't wish to immediately dispose of the Process after executing it, but plan to dispose of it later then IProcessRunnerUtility provides more flexibility.

IProcessRunner

Note: IProcessRunner and it's implementation class's execution methods do require a ProcessResultValidation argument to be passed, that configures whether validation should be performed on the Process' exit code. A default value for the parameter is intentionally not provided, as it is up to the user to decide whether they require exit code validation.

This example shows how it might be used:

using CliRunner.Runners;
using CliRunner.Runners.Abstractions;
// Using namespaces for Dependency Injection code ommitted for clarity

//Namespace and classs code ommitted for clarity 

      // ServiceProvider and Dependency Injection code ommitted for clarity

    IProcessRunner _processRunner = serviceProvider.GetRequiredService<IProcessRunner>();
    

    ProcessResult result = await _processRunner.ExecuteProcessAsync(process, ProcessResultValidation.None);

Asynchronous methods in IProcessRunner do provide an optional CancellationToken parameter.

Synchronous methods are available in IProcessRunner but should be used as a last resort, in situations where using async and await are not possible.

IProcessRunnerUtility

The naming of IProcessRunnerUtility is deliberately similar to IProcessRunner as it is the utility interface (and corresponding implementing class) that IProcessRunner uses behind the scenes for functionality.

Usage of IProcessRunnerUtility is most appropriate when greater flexibility is required than what IProcessRunner provides.

For instance, you can keep a Process object alive for as long as needed, and then dispose of it later.

using CliRunner.Runners;
using CliRunner.Runners.Abstractions;
// Using namespaces for Dependency Injection code ommitted for clarity

//Namespace and classs code ommitted for clarity 

      // ServiceProvider and Dependency Injection code ommitted for clarity

    IProcessRunnerUtility _processRunnerUtility = serviceProvider.GetRequiredService<IProcessRunnerUtility>();
    
    // Result Validation and Cancellation token are optional parameters.
    int exitCode = await _processRunnerUtility.ExecuteAsync(process);
    
    // Getting the result afterwards is done manually.
    ProcessResult = await _processRunnerUtility.GetResultAsync(process);
    
    // Code continuing to use process object ommitted.
    
    
    // Dispose of Process when no longer needed.
    _processRunnerUtility.DisposeOfProcess(process);

Some synchronous methods are available in IProcessRunnerUtility but should be used as a last resort, in situations where using async and await are not possible.

License

CliRunner is licensed under the MPL 2.0 license. If you modify any of CliRunner's files then the modified files must be licensed under the MPL 2.0 .

If you use CliRunner in your project please make an exact copy of the contents of CliRunner's LICENSE.txt file available either in your third party licenses txt file or as a separate txt file.

Assets

CliRunner's Icon is NOT licensed under the MPL 2.0 license and are licensed under Copyright with all rights reserved to me (Alastair Lundy).

If you fork CliRunner and re-distribute it, please replace the usage of the icon unless you have prior written agreements from me.

Acknowledgements

This project would like to thank the following projects for their work:

• CliWrap for inspiring this project
• Polyfill for simplifying .NET Standard 2.0 & 2.1 support
• Microsoft.Bcl.HashCode for providing a backport of the HashCode class and static methods to .NET Standard 2.0

For more information, please see the THIRD_PARTY_NOTICES file.