CliInvoke.Specializations 3.0.0

CliInvoke.Specializations

This readme covers the CliInvoke Specializations library.

Looking for the CliInvoke Readme?

Usage

CliInvoke.Specializations ships two specializations:

• CmdProcessConfiguration — An easier way to execute processes and commands through Windows' cmd.exe.
• PowershellProcessConfiguration — An easier way to execute processes and commands through the modern Cross-Platform open source PowerShell (PowerShell is not installed by CliInvoke and is expected to be installed if you plan to use it.)

All Command specialization classes come with an already configured TargetFilePath that points to the relevant executable.

Quick start with CliRun

The fastest path is the static CliRun helper. Build a configuration and await the result.

using CliInvoke;
using CliInvoke.Core;
using CliInvoke.Specializations.Configurations;

// Run a PowerShell command using the cross-platform pwsh executable.
using PowershellProcessConfiguration config = new PowershellProcessConfiguration("-Command Get-Process");

BufferedProcessResult result = await CliRun.RunBufferedAsync(config, ProcessExitConfiguration.CreateGraceful());

CliRun also exposes RunAsync (returns a ProcessResult) and FireAndForget for fire-and-forget execution.

Dependency Injection

If you prefer to resolve an invoker from a dependency injection container, call AddCliInvoke() (namespace CliInvoke.Extensions, shipped in the main CliInvoke package). This registers the core services, the IProcessInvoker implementation, the IRunnerConfigurationFactory, and the IExternalProcessFactory.

AddCliInvokeSpecializations

AddCliInvokeSpecializations() (namespace CliInvoke.Extensions, shipped in this package) registers the Specializations middleware types — PowerShellMiddleware, CmdMiddleware, DefaultShellMiddleware, and ShellMiddlewareOptions — so that the convenience builder extensions UsePowerShell(), UseCmd(), and UseDefaultShell() can resolve them from the DI container.

DefaultShellMiddleware detects the user's default shell (pwsh, Windows PowerShell, or cmd) and wraps the command in it automatically. Use it when you want cross-platform shell detection instead of targeting a specific shell.

AddCliInvoke() is required. AddCliInvokeSpecializations() only registers middleware types; it does not register core CliInvoke services. You must call AddCliInvoke() as well, or the invoker, process factory, and other core services will not be available.

Both registrations accept an optional ServiceLifetime parameter (default Scoped). The two calls are independent and can be chained in either order, but both must use the same lifetime — middleware lifetimes are matched to the invoker lifetime to avoid capturing scoped services into a singleton:

using CliInvoke.Extensions;
using Microsoft.Extensions.DependencyInjection;

ServiceCollection services = new ServiceCollection();

// AddCliInvoke() is required — it registers core services.
// AddCliInvokeSpecializations() registers the Cmd/PowerShell/DefaultShell middleware types.
services.AddCliInvoke(builder => builder.UsePowerShell().UseCmd())
    .AddCliInvokeSpecializations();

using IServiceProvider serviceProvider = services.BuildServiceProvider();

Calling AddCliInvoke(builder => builder.UsePowerShell()) without AddCliInvokeSpecializations() compiles but throws InvalidOperationException when the invoker is first resolved, because the PowerShellMiddleware type is not registered in the container.

CmdProcessConfiguration

The CmdProcessConfiguration TargetFilePath points to Windows' copy of cmd.exe. This is only supported on Windows.

using CliInvoke;
using CliInvoke.Core;
using CliInvoke.Core.Extensibility;
using CliInvoke.Specializations.Configurations;

    // DI setup omitted for clarity

IProcessInvoker _processInvoker = serviceProvider.GetRequiredService<IProcessInvoker>();
IRunnerConfigurationFactory _runnerConfigurationFactory = serviceProvider.GetRequiredService<IRunnerConfigurationFactory>();

ProcessConfiguration runnerConfig = new CmdProcessConfiguration("Your arguments go here",
    false, true, Environment.SystemDirectory);

ProcessConfiguration config = new ProcessConfiguration("Path/To/Exe", "With/Arguments");
ProcessConfiguration processToRun = _runnerConfigurationFactory.CreateRunnerConfiguration(config, runnerConfig);

BufferedProcessResult result = await _processInvoker.ExecuteBufferedAsync(processToRun);

To discard the output, call ExecuteAsync() instead:

// Same setup as above, then:
ProcessResult result = await _processInvoker.ExecuteAsync(processToRun);

PowershellProcessConfiguration

PowershellProcessConfiguration.TargetFilePath points to the installed copy of cross-platform PowerShell. Supported on the platforms that pwsh supports.

using CliInvoke;
using CliInvoke.Core;
using CliInvoke.Core.Extensibility;
using CliInvoke.Specializations.Configurations;

// DI setup omitted for clarity

IProcessInvoker _processInvoker = serviceProvider.GetRequiredService<IProcessInvoker>();
IRunnerConfigurationFactory _runnerConfigurationFactory = serviceProvider.GetRequiredService<IRunnerConfigurationFactory>();

ProcessConfiguration runnerConfig = new PowershellProcessConfiguration("-Command Get-Process",
    false, true);

ProcessConfiguration config = new ProcessConfiguration("Path/To/Exe", "With/Arguments");
ProcessConfiguration processToRun = _runnerConfigurationFactory.CreateRunnerConfiguration(config, runnerConfig);

BufferedProcessResult result = await _processInvoker.ExecuteBufferedAsync(processToRun);

Dedicated invokers

CliInvoke.Specializations also ships two convenience invoker wrappers — CmdProcessInvoker and PowershellProcessInvoker (namespace CliInvoke.Specializations) — that implement IProcessInvoker with the relevant middleware (CmdMiddleware / PowerShellMiddleware) applied. They run commands through cmd.exe / pwsh directly without manually building a runner configuration.

Both are constructed from an IExternalProcessFactory, which AddCliInvoke() (main CliInvoke package) registers in the container:

using CliInvoke.Core;
using CliInvoke.Core.Factories;
using CliInvoke.Specializations;
using CliInvoke.Specializations.Configurations;

// Resolve the external process factory registered by AddCliInvoke().
IExternalProcessFactory factory = serviceProvider.GetRequiredService<IExternalProcessFactory>();

// CmdProcessInvoker applies CmdMiddleware and runs through cmd.exe (Windows only).
using CmdProcessInvoker cmdInvoker = new CmdProcessInvoker(factory);

using CmdProcessConfiguration cmdConfig = new CmdProcessConfiguration("echo hello", false, true);
ProcessResult result = await cmdInvoker.ExecuteAsync(cmdConfig);

PowershellProcessInvoker works the same way and is supported on the platforms that cross-platform PowerShell supports.

Licensing

CliInvoke and CliInvoke Specializations are licensed under the MPL 2.0 license.

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