AlastairLundy.CliInvoke.Core 2.0.0-beta.2

CliInvoke.Core

This package contains Process Running and handling abstractions as well as common types used by implementing classes.

For an implementing package, check out CliInvoke.

Key Abstractions:

• IProcessInvoker

• IProcessConfigurationInvoker

• Piping:

  • IProcessPipeHandler

• Fluent Builders:

  • IArgumentsBuilder - An interface to assist with Argument Building and argument escaping.
  • IEnvironmentVariablesBuilder - An interface to assist with setting Environment variables.
  • IProcessConfigurationBuilder - An interface to fluently configure and build ProcessConfiguration objects.
  • IProcessExitConfigurationBuilder - An interface to fluently configure and build ProcessExitConfiguration objects.
  • IProcessResourcePolicyBuilder - An interface to fluently configure and build ProcessResourcePolicy objects.
  • IProcessTimeoutPolicyBuilder
  • IUserCredentialBuilder

Table of Contents

• Features
• Installing CliInvoke.Core
  • Compatibility
• Examples
• Contributing to CliInvoke.Core
• License
• Acknowledgements

Features

• Easy to use safe Process Running classes and interfaces
• Models that help abstract away some of the complicated nature of Process objects
• SourceLink support

How to install and use CliInvoke.Core

CliInvoke.Core is available on the Nuget Gallery here.

Installing CliInvoke.Core

CliInvoke.Core 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.Core can be added to any .NET Standard 2.0, .NET Standard 2.1, .NET 8, or .NET 9 supported project.

The following table details which target platforms are supported for running Processes.

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

^3 - lack of IOS support implies lack of watchOS 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);

Command/Program Execution

How to Contribute

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.

License

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

If you use CliInvoke.Core in your project, please make an exact copy of the contents of CliInvoke.Core'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:

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