Important: This changelog is no longer maintained and will be removed in the future. Going forward, new versions of this package will have the corresponding release notes published on GitHub Releases.
- Renamed
PipeSource.FromMemory(...)toPipeSource.FromBytes(...)for consistency with similar methods in the wider .NET framework. The old method is still available but marked as obsolete. - Fixed an issue where piping very large output through
PipeTarget.Merge(...)could result in a deadlock if one of the underlying targets failed with an exception.
- Fixed an issue where
ListenAsync()missed events when wrapping a process that printed a single line to the console and exited immediately.
- Added an overload of
PipeTarget.ToDelegate(...)that accepts aFunc<Stream, CancellationToken, Task>delegate. This is the preferred overload to use with asynchronous delegates, as it allows you to leverage the provided cancellation token to abort the pipe early. - Fixed an issue where the
ListenAsync()method accepted graceful and forceful cancellation tokens in the wrong order.
- Added the
Command.WithTargetFile(...)configuration method that can be used to modify the target file path of the command. - Improved support for older target frameworks via polyfills.
- Added support for graceful cancellation via interrupt signals. The new functionality is accessible using an overload of
ExecuteAsync()(as well asExecuteBufferedAsync(),ListenAsync(), andObserve()) that accepts an additional cancellation token. The first cancellation token parameter corresponds to a forceful cancellation request that results in immediate process termination (same as the previously available behavior), while the second cancellation token parameter corresponds to a graceful cancellation request that manifests in an interrupt signal. The underlying process may handle the interrupt signal to perform last-minute critical work before finally exiting on its own terms. Please refer to the updated Timeout and cancellation section in the readme for more details. - Changed how the
CommandExecutionExceptionis thrown inExecuteBufferedAsync()when the process exits with a non-zero exit code. Now, instead of replacing the underlying exception, the exception contains the standard error data as part of the message and also includes the underlying exception (thrown inExecuteAsync()) as inner exception. - Fixed an issue where the command events from the
Observe()execution model sometimes arrived out of order.
- Added
LoadUserProfileoption toCredentialsand the correspondingLoadUserProfile()method toCredentialsBuilder. Setting this option totruewill load the user profile when starting the process. Only supported on Windows. - Improved wording in some exception messages.
- Improved cancellation handling in all execution models by attaching the triggered
CancellationTokento producedOperationCanceledExceptions. - Fixed an issue where using
PipeSource.FromFile(...)with a non-existing file did not throw an exception.
- Added
PipeSource.Create(...)andPipeTarget.Create(...)factory methods that can be used to create anonymous instances ofPipeSourceandPipeTarget. This approach can be convenient if you need to implement a customPipeSourceorPipeTargetbut don't want to define a new class. (Thanks @Cédric Luthi) - Updated inline documentation for
PipeTarget.Nullwith additional information clarifying the difference in behavior between that target andPipeTarget.ToStream(Stream.Null).
- Improved process execution performance by not setting
CreateNoWindowtofalsewhen running inside a console application. This change reduces performance overhead by up to 60% in some cases. (Thanks @Retik) - Improved overall performance by making use of
IAsyncDisposableon streams where it is available. - Marked configuration methods on
Commandwith thePureattribute. The compiler will now produce a warning if you call any of these methods without using the returned value.
- Fixed an issue where calling
Cli.Wrap(...).ExecuteAsync()returned an invalidCommandTask(withProcessIdequal to0) when the process failed to start. It happened because the associated exception was thrown in an asynchronous context instead of getting propagated immediately. This issue caused event stream execution models (Observe()andListenAsync()) to incorrectly yieldStartedCommandEventeven if the process has not actually been able to start.
- Added automatic resolving of script files on Windows (i.e.
.batand.cmdfiles). Previously, if you didCli.Wrap("foo"), the underlying implementation ofSystem.Diagnostic.Processwould try to findfooin several locations, including directories listed in the PATH environment variable. On Windows, however, this only worked for.exefiles, meaning that it wouldn't findfoo.cmdorfoo.bateven if they existed on the PATH. This was an issue withCli.Wrap("npm")andCli.Wrap("az")because those CLI tools are implemented as.cmdscripts on Windows. CliWrap now attempts to resolve those paths itself. (Thanks @AliReZa Sabouri) - Improved exception thrown when the underlying process fails to start. It now contains the target file path, which can be helpful to identify the exact command that failed. (Thanks @Mohamed Hassan)
- Added an overload of
EnvironmentVariablesBuilder.Set(...)that takes a dictionary parameter. This lets you set multiple environment variables at once by passing a dictionary when callingCli.Wrap("foo").WithEnvironmentVariables(env => ...). - Added an overload of pipe operator for configuring a byte array as a pipe source.
- Added the ability to remove an inherited environment variable by setting its value to
null. (Thanks @Ville Penttinen)
- Added
ExitCodeandCommandproperties toCommandExecutionException. These properties can be inspected to retrieve the exit code returned by the process and the command that triggered the exception. (Thanks @Philip)
- Added
PipeSource.FromFile(...)andPipeTarget.ToFile(...)as convenience shorthands for creating pipes that work withFileStreaminstances. - Added overloads for
ArgumentsBuilder.Add(...)that takeIFormatProviderinstead ofCultureInfo. In a future major version, the overloads that takeCultureInfowill be removed. - Improved performance of
PipeSource.NullandPipeTarget.Null. - Signed assembly. (Thanks @lazyboy1)
Known incompatibility issue: Using CliWrap together with ConfigureAwait.Fody, in code compiled with .NET 5.0 SDK or higher, results in a NullReferenceException at run time. The recommended workaround is to call ConfigureAwait(...) on CliWrap.CommandTask<T> manually or to disable ConfigureAwait.Fody altogether.
- Fixed an issue where
PipeTarget.ToDelegate(...), as well as execution models that depend on it (i.e. observable and async streams), didn't treat standalone\rcharacter as a valid linebreak. (Thanks @koryphaee)
- Fixed an issue where
Command.ExecuteAsync(...)sometimes threwInvalidOperationExceptionindicating that the process has already exited. This problem only happened on Linux and macOS when the process exited too quickly. - Improved performance and memory usage in async event stream execution model.
- Fixed an issue where
Command.ExecuteAsync(...)sometimes returned before the process actually exited, in case cancellation was requested. Now, this method only returns when the process has fully terminated or if the termination has failed for whatever reason. - Fixed an issue where specifying password without also specifying domain resulted in the password being incorrectly ignored.
- Improved performance and memory usage in all execution models. (Thanks @Maarten Balliauw and @Miha Zupan)
- Added optimization for
PipeTarget.Merge(...)that flattens inner targets in case they also represent merged targets. - Added
CommandTask.ConfigureAwait(...)as a shorthand forCommandTask.Task.ConfigureAwait(...).
- Added support for specifying user credentials when you want to run a command as a different user. This can be done by calling
cmd.WithCredentials(...). Domain and password options are only supported on Windows, while username can be set on any operating system. (Thanks @Michi)
- Fixed an issue where
PipeTarget.Merge(...)worked incorrectly when processing large stdout written in a single operation (more than 81920 bytes at a time). (Thanks @Tom Pažourek) - Replaced
[DebuggerDisplay]attribute with an implementation ofToString()on types deriving fromCommandEvent. CallingcommandEvent.ToString()now yields an informative string that can be useful in debugging. This change shouldn't have any unwanted side effects.
- Added an option to disable automatic argument escaping to
cmd.WithArguments(string[])as well asbuilder.Add(...). You can use it to escape the arguments yourself if the application requires it. - Added an option to enable or disable auto-flushing for
PipeTarget.ToStream(...)andPipeSource.FromStream(...). If enabled, data will be copied as soon as it's available instead of waiting for the buffer to fill up. This is enabled by default, which is different from the previous behavior, although this change is not breaking for most scenarios. - Fixed an issue where command execution threw an exception if the wrapped application didn't read stdin completely. The exception is now caught and ignored as it's not really an exceptional situation if the stdin contains excess data which is discarded by the wrapped application.
- Fixed an issue where command execution waited for piped stdin to resolve next bytes, even if the wrapped application didn't try to read them. This avoids unnecessary delay (which can be infinite if the stream never resolves) when the wrapped application doesn't need the rest of the stdin to complete execution.
- Fixed an issue where
PipeTarget.Merge(...)worked incorrectly when used withPipeTarget.ToDelegate(...), causing the latter to yield lines even where there were no line breaks.
- Added error handling for when the internal call to
Process.Start()returnsfalse. This will now throw a more descriptive exception than it did previously.
- Fixed an issue where piping stdin to an executable that also writes stdout caused a deadlock when the stdout was beyond a certain size.
- Slightly improved performance by using
TaskCreationOptions.RunContinuationsAsynchronouslywhere appropriate. (Thanks @Georg Jung) - Added DebuggerDisplay attribute to derivatives of
CommandEventto aid in debugging. (Thanks @Zoltán Lehóczky)
- Complete rework of the library.
- Added extensive support for piping.
- Multitude of improvements and breaking changes.
Refer to the migration guide to see how you can update your old code to work with CliWrap v3.0.
Check out the new readme to see the whole list of new features.
- Added callbacks that trigger when stdout/stderr streams are closed. (Thanks @Daniel15)
- Added an overload for
SetCancellationTokenthat acceptskillEntireProcessTree. Passingtrueto this option will make CliWrap attempt to kill the entire process tree when cancellation is requested, as opposed to only the parent process. Note, this option is only available on .NET Framework 4.5+ and .NET Core 3.0+. (Thanks @M-Patrone) - Removed ReSharper annotations.
- Added
ProcessIdproperty toCli. You can use it to get the ID of the underlying process as soon as it's started.
- Fixed an issue where
ExecuteandExecuteAsyncdidn't return immediately after the execution was canceled. - Fixed an issue where setting the same environment variable twice resulted in an error.
- Improved exception message in
ExitCodeValidationExceptionandStandardErrorValidationException.
- Added an overload for
SetArgumentsthat takes a list. You can pass multiple arguments and they will be automatically encoded to preserve whitespace and other special characters. - Fixed some typos in documentation.
- Fixed an issue where
ExecuteAndForgetwas throwing an exception if the underlying process outlived the execution of the method.
ExitCodeValidationExceptionandStandardErrorValidationExceptionnow display both exit code and standard error inside the message. Useful when a process reported a non-zero exit code but the actual error message is in stderr.- Removed
netcoreapp1.0target.
- Added
Cli.Wrapstatic method to replacenew Cli()for a more fluent interface. This also makes it so you're dealing withICliinstead ofClithroughout the entire method chain. - Standard error validation is now disabled by default. This change was made because quite a few CLIs (e.g. git, ffmpeg) write progress to stderr.
- Changed
ExecuteandExecuteAsyncto complete only after the process exits, regardless of cancellation. This fixes a problem where the underlying process could live for some brief moments after those methods returned, in case of cancellation. - If
ExecuteorExecuteAsyncis canceled, the underlying process will now be killed without waiting for standard input to write completely. - Reworked underlying process handling to improve performance and maintainability. The
ExecuteandExecuteAsyncmethods are now virtually the same in terms of code, unlike before, where they were considerably different.
- Added
ExecutionResulttoExitCodeValidationExceptionandStandardErrorValidationException. This way additional information can be inspected during debugging. ExitCodeValidationExceptionandStandardErrorValidationExceptionare now derived fromExecutionResultValidationException.- Improved cancellation handling in synchronous workflow.
- Cancellation token is now used when writing stdin in asynchronous workflow.
- Methods that used to return an instance of
Clinow returnICliwhere applicable.
- Re-designed the API so that it follows the builder pattern. Execution parameters are now supplied using chainable methods on the
Cliinstead of viaExecutionInput. Things likeBufferHandlerandCancellationTokenare now also configured in the same manner. Refer to the readme to see updated usage examples. - It is now also possible to pipe a raw stream to standard input, instead of just a text string.
- Removed
ExecutionInput,CliSettings,BufferHandler,EncodingSettings. - Renamed
ExecutionOutputtoExecutionResult. - Removed
ExecutionResult.HasErrorandExecutionResult.ThrowIfError(). - Added an option to automatically throw an exception when the underlying process reports a non-zero exit code. Is enabled by default.
- Added an option to automatically throw an exception when the underlying process writes anything to standard error. Is enabled by default.
- Fixed exception messages not appearing in Visual Studio's exception popup.
StandardErrorExceptionnow shows the value ofStandardErrorinMessage.
- Added
IClito aid in testing.
- Made input model classes more accessible by removing immutability.
Clinow throws exception if used after getting disposed.
- Fixed another process leak when canceling synchronous
Execute.
- Refactored additional
Cliconstructor parameters into a separate class calledCliSettings. This is breaking if you used to supply more than 1 parameter to the constructor. ExecuteandExecuteAsyncno longer depend on process getting successfully killed. An attempt to kill it is made but if it's not successful, no exception is thrown.- All
CancellationTokencallbacks are now exception-safe. - Fixed an issue where
CancellationTokenwould throw an out-of-scope exception when the process could not be killed. - Fixed a race condition when an execution task is completed and canceled at the same time.
- Added
EncodingSettingsto customize stream encoding. - Added some ReSharper annotations to improve warnings and suggestions.
- Execution start and exit times are now calculated separately, without accessing
Processinstance. - Execution start and exit times are now
DateTimeOffsetinstead ofDateTime. - Fixed an issue that prevented CliWrap from properly working on Linux.