AlastairLundy.CliInvoke 1.6.1.1

CliInvoke

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

<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 * Executing Commands
• Contributing to CliInvoke
• Roadmap
• License
  • CliRunner Assets
• Acknowledgements

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 ¹
• 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 ²
• SourceLink support

¹ - Polyfill is a dependency only required for .NET Standard 2.0 users. Microsoft.Bcl.HashCode is a dependency only required for .NET Standard 2.0 users.

² - The Specialization library is distributed separately here.

Why use CliInvoke over CliWrap?

• Greater separation of concerns with the Command class - 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

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 be added to .NET Standard 2.0, .NET 8, or .NET 9 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

Fluent ProcessConfiguration building

CliInvoke 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 AlastairLundy.CliInvoke;
using AlastairLundy.CliInvoke.Builders.Abstractions;
using AlastairLundy.CliInvoke.Builders;

using AlastairLundy.Extensions.Processes;

  //Namespace and classs code ommitted for clarity 

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

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

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.

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.