AlastairLundy.ProcessInvoke.Abstractions 1.5.0.1

AlastairLundy.ProcessInvoke.Abstractions

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

For an implementing package, check out AlastairLundy.ProcessInvoke.

Key Abstractions:

• IProcessFactory
• Piping:
  • IProcessPipeHandler
• Builders:
  • IEnvironmentVariablesBuilder
  • IProcessResourcePolicyBuilder
  • IUserCredentialBuilder

Table of Contents

• Features
• Installing ProcessInvoke.Abstractions
  • Compatibility
• Examples
• Contributing to ProcessInvoke.Abstractions
• 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
• Compatible with .NET Standard 2.0 and 2.1 ^1
• 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.

When should I use ProcessInvoke vs CliInvoke?

Use CliInvoke IF any of the following apply:

• You want to programatically execute a Cli Application
• You want to get the output of a Cli Application.
• You want to Pipe the Input or Output of a Cli Application.

Use ProcessInvoke IF ALL the following apply:

• You don't care about getting a Process's Standard Output.
• You're focussed more on starting and/or stopping Processes.
• You don't need Argument Building or Escaping capabilities

Note: Whilst ProcessInvoke is capable of doing most of what CliInvoke is capable of, they are intended for different use cases.

CliInvoke internally uses ProcessInvoke but provides additional abstractions around programatically executing programs and is designed specifically for this task.

How to install and use ProcessInvoke.Abstractions

ProcessInvoke.Abstractions is available on Nuget.

Installing ProcessInvoke.Abstractions

ProcessInvoke.Abstractions' 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

ProcessInvoke.Abstractions 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 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.

Examples

One of the main use cases for ProcessInvoke.Abstractions is intended to be safe Process Running.

Safe Process Running

ProcessInvoke.Abstractions offers safe abstractions around Process Running to avoid accidentally not disposing of Processes after they are executed.

IProcessFactory provides for this in

IProcessFactory

IProcessFactory is an interface for enabling easy Process Creation, Running, and Disposal depending on the methods used.

The From method and its overloads provide for easy standalone process creation. The StartNew method provides for creating and starting new processes easily.

The ContinueWhenExitAsync and ContinueWhenExitBufferedAsync methods provide for safe process running, and disposal after a Process has exited.

This example shows how it might be used:

using AlastairLundy.ProcessInvoke.Abstractions;
// Using namespaces for Dependency Injection code ommitted for clarity

      // Dependency Injection setup code ommitted for clarity

    IProcessFactory _processFactory = serviceProvider.GetRequiredService<IProcessFactory>();
    
    // Define processStartInfo here.
    
    Process process1 = _processFactory.From(processStartInfo);
    
    // This process that is returned is a Process that has been started.
    Process process2 = _processFactory.StartNew(processStartInfo);
    
    // Wait for the Process to finish before safely disposing of it.
   ProcessResult result = await processFactory.ContinueWhenExitAsync(process2);
    
        
    ProcessResult result = await _processRunner.ExecuteProcessAsync(process, ProcessResultValidation.None);

Asynchronous methods in IProcessFactory also allow for an optional CancellationToken parameter.

Some overloads for ContinueWhenExitAsync and ContinueWhenExitBufferedAsync allow for specifying ProcessResultValidation.

How to Contribute

Thank you in advance for considering contributing to ProcessInvoke.

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

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

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