AlastairLundy.CliInvoke.Core 2.0.0-rc.1

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

• IProcessConfigurationFactory

• 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

Features

• Clear separation of concerns between Process Configuration Builders, Process Configuration Models, and Invokers.
• Supports .NET Standard 2.0, .NET 8 and newer TFMs, and has few dependencies.
• Has Dependency Injection extensions to make using it a breeze.
• Support for specific specializations such as running executables or commands via Windows Powershell or CMD on Windows ¹
• SourceLink support

¹ Specializations library distributed separately.

Why CliInvoke?

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 8, or .NET 9 or newer 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.

Examples

Simple ProcessConfiguration creation with Factory Pattern

This approach uses the IProcessConfigurationFactory interface factory to create a ProcessConfiguration. It requires fewer parameters and sets up more defaults for you.

It can be provided with a Action<IProcessConfigurationBuilder> configure optional parameter where greater control 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.Core.Factories;
using AlastairLundy.CliInvoke.Core;
using AlastairLundy.CliIinvoke;

using Microsoft.Extensions.DependencyInjection;

// Dependency Injection setup code ommitted for clarity

// Get IProcessConfigurationFactory 
IProcessConfigurationFactory processConfigFactory = serviceProvider.GetRequiredService<IProcessConfigurationFactory>();

// Get IProcessConfigurationInvoker
IProcessConfigurationInvoker _invoker_ = serviceProvider.GetRequiredService<IProcessConfigurationInvoker>();

// Simply create the process configuration.
ProcessConfiguration configuration = processConfigFactory.Create("path/to/exe", "arguments");

// Run the process configuration and get the results.
ProcessResult result = await _invoker.ExecuteAsync(configuration, CancellationToken.None);

Buffered Execution Example

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

using AlastairLundy.CliInvoke.Core.Factories;
using AlastairLundy.CliInvoke.Core;
using AlastairLundy.CliIinvoke;

using Microsoft.Extensions.DependencyInjection;

// Dependency Injection setup code ommitted for clarity

// Get IProcessConfigurationFactory 
IProcessConfigurationFactory processConfigFactory = serviceProvider.GetRequiredService<IProcessConfigurationFactory>();

// Get IProcessConfigurationInvoker
IProcessConfigurationInvoker _invoker_ = serviceProvider.GetRequiredService<IProcessConfigurationInvoker>();

// Simply create the process configuration.
ProcessConfiguration configuration = processConfigFactory.Create("path/to/exe", "arguments");

// Run the process configuration and get the results.
BufferedProcessResult result = await _invoker.ExecuteBufferedAsync(configuration, CancellationToken.None);

Advanced Configuration with Builders

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 Microsoft.Extensions.DependencyInjection;

  //Namespace and class code ommitted for clarity 

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

  // 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.Builders;

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

using Microsoft.Extensions.DependencyInjection;


  //Namespace and class code ommitted for clarity 

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

  // Fluently configure your Command.
  IProcessConfigurationBuilder builder = new ProcessConfigurationBuilder("Path/To/Executable")
                            .WithArguments(["arg1", "arg2"])
                            .WithWorkingDirectory("/Path/To/Directory")
                            .RedirectStandardOutput(true)
                           .RedirectStandardError(true);
  
  // 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 _processInvoker.ExecuteBufferedAsync(config);

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
• Polyfill for simplifying .NET Standard 2.0 support

For more information, please see the THIRD_PARTY_NOTICES file.