AlastairLundy.CliInvoke 2.0.0-beta.2

CliInvoke

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

Launch processes, redirect standard input and output streams, await process completion and so much more.

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

Table of Contents

• Features
• Why CliInvoke?
• Installing CliInvoke
  • Installing CliInvoke
  • Supported Platforms
• CliInvoke Examples
  • Running Programs/Commands
  • Safe Process Running
• Contributing to CliInvoke
• Roadmap
• License
  • CliRunner Assets
• Acknowledgements

Features

• Promotes the single responsibility principle and separation of concerns
• Supports .NET 8 and newer TFMs, and has few dependencies.
• Dependency Injection extensions to make using CliInvoke a breeze.
• Support for specific specializations such as running executables or commands via Windows Powershell or CMD on Windows ¹
• SourceLink support

¹ - The Specialization library is distributed separately here.

Why use CliInvoke over CliWrap?

• Greater separation of concerns - Command Building, Command Running, and Command 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
• Uses .NET's built in Process type.

How to install and use CliInvoke

CliInvoke is available on Nuget.

These are the CliInvoke projects:

• CliInvoke - The main CliInvoke package.
• CliInvoke.Extensions
• CliInvoke.Specializations

Installing CliInvoke

CliInvoke's packages can be installed via the .NET SDK CLI, Nuget via your IDE or code editor's package interface, or via the Nuget website.

Supported Platforms

CliInvoke can currently be added to .NET 8, or .NET 9 or newer supported projects.

The following table details which target platforms are supported for executing commands via CliInvoke.

³ - See the Process class documentation for more info.

⁴ - 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.

Using CliInvoke / Examples

The two main use cases for CliInvoke are intended to be:

1. executing Programs/Commands programatically which involves using abstractions to improve the experience of external Program/Command running.
2. safe Process Running which involves avoiding the pitfalls of the Process class whilst still dealing with ProcessStartInfo.

CliInvoke provides both options to give developers a choice in the approach they adopt. They are both equally safe and valid.

Approaches

Safe Process Running

CliInvoke offers safe abstractions around Process Running to avoid accidentally not disposing of Processes, along with avoiding other pitfalls.

IProcessInvoker and IProcessConfigurationInvoker are both equally capable of fulfilling this criterion, however IProcessInvoker works with ProcessStartInfo objects and IProcessConfigurationInvoker works with ProcessConfiguration objects.

If you don't want to use CliInvoke's abstractions around Processes, such as ProcessConfiguration and CliInvoke's other primitives, then IProcessInvoker is a better fit.

Note: Neither IProcessInvoker nor IProcessConfigurationInvoker are dependent upon on the other to work.

IProcessInvoker

IProcessInvoker is an interface for creating, running, and safely disposing of Processes based on ProcessStartInfo objects.

The ExecuteAsync, ExecuteBufferedExitAsync, ExecutePipedExitAsync methods provide for:

1. process creation
2. safe process running (including process disposal, even in the case of an Exception)
3. gathering the results of the Process's execution (varies depending on the specific method)
4. disposing of the Process after it has exited
5. returning the gathered Process execution results

These examples show how they might be used:

Running Programs/Commands

Because of how much of a minefield the Process class is and how difficult it can be to configure correctly, CliInvoke provides some abstractions to make it easier to configure Programs/Commands to be run.

CliInvoke provides fluent builder interfaces and implementing classes to easily configure ProcessConfiguration. ProcessConfiguration is CliInvoke's main form of Process configuration (hence the name).

The use of ProcessConfiguration can be avoided if you want to stick with ProcessStartInfo for configuration, but this means IProcessInvoker is the appropriate interface to use for creating and executing Processes.

Approach Examples

IProcessInvoker

ExecuteAsync

using AlastairLundy.CliInvoke.Core;
using AlastairLundy.CliInvoke.Core.Primitives;

// Using namespaces for Dependency Injection code ommitted for clarity

      // Dependency Injection setup code ommitted for clarity

    IProcessInvoker _processInvoker = serviceProvider.GetRequiredService<IProcessInvoker>();
    
    // Define processStartInfo here
    
    // This process is created, executed, disposed of, and the results returned.
    ProcessResult process = await _processInvoker.ExecuteAsync(processStartInfo, ProcessResourcePolicy.Default,
        ProcessTimeoutPolicy.None, ProcessResultValidation.ExitCodeZero);

ExecuteBufferedAsync

using AlastairLundy.CliInvoke.Core;
using AlastairLundy.CliInvoke.Core.Primitives;

// Using namespaces for Dependency Injection code ommitted for clarity

      // Dependency Injection setup code ommitted for clarity

    IProcessInvoker _processInvoker = serviceProvider.GetRequiredService<IProcessInvoker>();
    
    // Define processStartInfo here
    
    // This process is created, executed, disposed of, and the results returned.
    BufferedProcessResult process = await _processInvoker.ExecuteBufferedAsync(processStartInfo, ProcessResourcePolicy.Default,
        ProcessTimeoutPolicy.None, ProcessResultValidation.ExitCodeZero);

IProcessConfigurationInvoker

The following examples shows how to configure and build a ProcessConfiguration depending on whether Buffering the output is desired.

Non-Buffered Execution Example

This example gets a non buffered ProcessResult that contains basic process exit code, id, and other information.

using AlastairLundy.CliInvoke;
using AlastairLundy.CliInvoke.Core;

using AlastairLundy.CliInvoke.Builders;
using AlastairLundy.CliInvoke.Core.Builders;

using AlastairLundy.CliInvoke.Core.Primitives;

  //Namespace and class code ommitted for clarity 

  // ServiceProvider and Dependency Injection setup code ommitted for clarity
  
  IProcessConfigurationInvoker _processConfigInvoker = serviceProvider.GetRequiredService<IProcessConfigurationInvoker>();

  // Fluently configure your Command.
  IProcessConfigurationBuilder builder = new ProcessConfigurationBuilder("Path/To/Executable")
                            .WithArguments(["arg1", "arg2"])
                            .WithWorkingDirectory("/Path/To/Directory");
  
  // Build it as a ProcessConfiguration object when you're ready to use it.
  ProcessConfiguration config = builder.Build();
  
  // Execute the process through ProcessInvoker and get the results.
ProcessResult result = await _processConfigInvoker.ExecuteAsync(config);

Buffered Execution Example

This example gets a BufferedProcessResult which contains redirected StandardOutput and StandardError as strings.

using AlastairLundy.CliInvoke;
using AlastairLundy.CliInvoke.Core;

using AlastairLundy.CliInvoke.Builders;
using AlastairLundy.CliInvoke.Core.Builders;

using AlastairLundy.CliInvoke.Core.Primitives;

  //Namespace and class code ommitted for clarity 

  // ServiceProvider and Dependency Injection setup code ommitted for clarity
  
  IProcessConfigurationInvoker _processConfigInvoker = serviceProvider.GetRequiredService<IProcessConfigurationInvoker>();

  // Fluently configure your Command.
  IProcessConfigurationBuilder builder = new ProcessConfigurationBuilder("Path/To/Executable")
                            .WithArguments(["arg1", "arg2"])
                            .WithWorkingDirectory("/Path/To/Directory");
  
  // Build it as a ProcessConfiguration object when you're ready to use it.
  ProcessConfiguration config = builder.Build();
  
  // Execute the process through ProcessInvoker and get the results.
BufferedProcessResult result = await _processConfigInvoker.ExecuteBufferedAsync(config);

How to Build CliInvoke's code

Requirements

CliInvoke requires the latest .NET release SDK to be installed to target all supported TFM (Target Framework Moniker) build targets.

Currently, the required .NET SDK is .NET 9.

The current build targets include:

• .NET 8
• .NET 9
• .NET Standard 2.0 (for CliInvoke 1.x only)

Any version of the .NET 9 SDK can be used, but using the latest version is preferred.

Versioning new releases

CliInvoke aims to follow Semantic versioning with [Major].[Minor].[Build] for most circumstances and an optional .[Revision] when only a configuration change is made, or a new build of a preview release is made.

Pre-releases

Pre-release versions should have a suffix of -alpha, -beta, -rc, or -preview followed by a . and what pre-release version number they are. The number should be incremented by 1 after each release unless it only contains a configuration change, or another packaging, or build change. An example pre-release version may look like 1.1.0-alpha.2 , this version string would indicate it is the 2nd alpha pre-release version of 1.1.0 .

Stable Releases

Stable versions should follow semantic versioning and should only increment the Revision number if a release only contains configuration or build packaging changes, with no change in functionality, features, or even bug or security fixes.

Releases that only implement bug fixes should see the Build version incremented.

Releases that add new non-breaking changes should increment the Minor version. Minor breaking changes may be permitted in Minor version releases where doing so is necessary to maintain compatibility with an existing supported platform, or an existing piece of code that requires a breaking change to continue to function as intended.

Releases that add major breaking changes or significantly affect the API should increment the Major version. Major version releases should not be released with excessive frequency and should be released when there is a genuine need for the API to change significantly for the improvement of the project.

Building for Testing

You can build for testing by building the desired project within your IDE or VS Code, or manually by entering the following command: dotnet build -c Debug.

If you encounter any bugs or issues, try running the CliInvoke.Tests project and setting breakpoints in the affected CliInvoke project's code where appropriate. Failing that, please report the issue if one doesn't already exist for the bug(s).

Building for Release

Before building a release build, ensure you apply the relevant changes to the relevant .csproj file corresponding to the package you are trying to build:

• Update the Package Version variable
• Update the project file's Changelog
• Remove/replace the CliInvoke icon if distributing a non-official release build to a wider audience. See CliInvoke Assets for more details.

You should ensure the project builds under debug settings before producing a release build.

Producing Release Builds

To manually build a project for release, enter dotnet build -c Release /p:ContinuousIntegrationBuild=true for a release with SourceLink enabled or just dotnet build -c Release for a build without SourceLink.

Builds should generally always include Source Link and symbol packages if intended for wider distribution.

NOTES:

• CliInvoke.Specializations and CliInvoke.Extensions both take a dependency on the CliInvoke base package from Nuget - For the respective libraries to use a newer CliInvoke version, that version must be published on Nuget.

How to Contribute to CliInvoke

Thank you in advance for considering contributing to CliInvoke.

Please see the CONTRIBUTING.md file for code and localization contributions.

If you want to file a bug report or suggest a potential feature to add, please check out the GitHub issues page to see if a similar or identical issue is already open. If there is not already a relevant issue filed, please file one here and follow the respective guidance from the appropriate issue template.

Thanks.

CliInvoke's Roadmap

CliInvoke aims to make working with Commands and external processes easier.

Whilst an initial set of features are available in version 1, there is room for more features, and for modifications of existing features in future updates.

That being said, all stable releases from 1.0 onwards must be stable and should not contain regressions.

Future updates should aim focus on one or more of the following:

• Improved ease of use
• Improved stability
• New features
• Enhancing existing features

License

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

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

CliInvoke Assets

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

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

Acknowledgements

Projects

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

• CliWrap for inspiring this project
• Polyfill for simplifying .NET Standard 2.0 support

For more information, please see the THIRD_PARTY_NOTICES file.