Meziantou.FrameworkProcessWrapper Class
Fluent builder for configuring and running processes. Every With* method mutates the current instance with the replaced value. Every Add* method mutates the current instance with the appended value.
public sealed class ProcessWrapperProperties
| Name | Description |
|---|---|
| DefaultLogVerbosity | Gets or sets the default verbosity used in process validation messages and process result string formatting. |
| DefaultProcessFactory | Gets or sets the default process factory used to create process handles. |
DefaultLogVerbosity
ProcessWrapper.csGets or sets the default verbosity used in process validation messages and process result string formatting.
public static ProcessLogVerbosity DefaultLogVerbosity { get; set; }Property value
DefaultProcessFactory
ProcessWrapper.csGets or sets the default process factory used to create process handles.
public static IProcessFactory DefaultProcessFactory { get; set; }Property value
Methods
| Name | Description |
|---|---|
| AddErrorStream(ReadOnlySpan<OutputTarget>) | Adds additional error stream handlers. |
| AddInterceptor(IProcessStartInfoInterceptor) | Adds a global process-start-info interceptor. |
| AddInterceptor(IProcessWrapperInterceptor) | Adds a global process-wrapper interceptor. |
| AddOutputStream(ReadOnlySpan<OutputTarget>) | Adds additional output stream handlers. |
| Create(string) | Creates a new ProcessWrapper for the specified executable. |
| ExecuteAsync(CancellationToken) | Starts the process and returns a ProcessInstance immediately. Await the returned instance to wait for the process to exit and get a ProcessResult. Use ProcessInstance.Kill to stop the process explicitly. |
| ExecuteBufferedAsync(CancellationToken) | Starts the process with output buffering and returns a BufferedProcessInstance immediately. Await the returned instance to wait for the process to exit and get a BufferedProcessResult. Use ProcessInstance.Kill to stop the process explicitly. |
| StartAndForget() | Starts the process without tracking it and returns its process ID. |
| ToString() | Returns the command line representation of this process configuration. |
| WithArguments(IEnumerable<string>) | Sets the arguments for the process, replacing any previously set arguments. |
| WithArguments(ReadOnlySpan<string>) | Sets the arguments for the process, replacing any previously set arguments. |
| WithArguments(string[]) | Sets the arguments for the process, replacing any previously set arguments. |
| WithCredentials(string, SecureString, string?) | Sets alternate Windows credentials used to start the process. |
| WithCredentials(string, string, string?) | Sets alternate Windows credentials used to start the process. |
| WithEnvironmentVariables(Action<ProcessWrapperEnvironmentVariables>) | Configures environment variables using a callback. Accumulates with previous calls. |
| WithEnvironmentVariables(IReadOnlyDictionary<string, string?>) | Configures environment variables from a dictionary. A null value removes the variable. Accumulates with previous calls. |
| WithErrorEncoding(Encoding) | Sets the encoding used to decode standard error. |
| WithErrorStream(ReadOnlySpan<OutputTarget>) | Replaces all error stream handlers with the specified targets. |
| WithInputStream(InputSource) | Sets the input stream to the specified input source. |
| WithInterceptor(IProcessStartInfoInterceptor) | Sets the process-start-info interceptor for this process wrapper instance. |
| WithInterceptor(IProcessWrapperInterceptor) | Sets the process-wrapper interceptor for this process wrapper instance. |
| WithKillOnParentExit(bool) | Sets whether the child process should be killed when the parent process exits. |
| WithLimits(ProcessLimits) | Sets the process limits, replacing previously configured limits. |
| WithLimits(Action<ProcessLimits>) | Configures process limits. Accumulates with previous calls. |
| WithLinuxControlGroup(Action<CGroup2>) | Configures the Linux cgroup used to apply process limits. |
| WithLogVerbosity(ProcessLogVerbosity) | Sets the verbosity used in process validation messages and process result string formatting. |
| WithOutputEncoding(Encoding) | Sets the encoding used to decode standard output. |
| WithOutputStream(ReadOnlySpan<OutputTarget>) | Replaces all output stream handlers with the specified targets. |
| WithProcessFactory(IProcessFactory) | Sets the process factory for this process wrapper instance. |
| WithSearchWorkingDirectory(bool) | Also looks for the executable in the working directory, before the directories listed in PATH. |
| WithStartDetached(bool) | Sets whether the child process should be detached from the parent process. |
| WithStartSuspended(bool) | Sets whether the child process should start in a suspended state. |
| WithUseCredentialsForNetworkingOnly(bool) | Sets whether to use LOGON_NETCREDENTIALS_ONLY when starting the process on Windows. |
| WithValidation(ProcessValidationMode) | Sets process validation rules. |
| WithWindowsJobObject(Action<JobObject>) | Configures the Windows Job Object used to apply process limits. |
| WithWorkingDirectory(string) | Sets the working directory for the process. |
AddErrorStream(ReadOnlySpan<OutputTarget>)
ProcessWrapper.csAdds additional error stream handlers.
public ProcessWrapper AddErrorStream(params scoped ReadOnlySpan<OutputTarget> targets)AddInterceptor overloads
AddInterceptor(IProcessStartInfoInterceptor)
ProcessWrapper.csAdds a global process-start-info interceptor.
public static IDisposable AddInterceptor(IProcessStartInfoInterceptor interceptor)Parameters
interceptorIProcessStartInfoInterceptor
Returns
Remarks
Dispose the returned registration to remove the interceptor.
AddInterceptor(IProcessWrapperInterceptor)
ProcessWrapper.csAdds a global process-wrapper interceptor.
public static IDisposable AddInterceptor(IProcessWrapperInterceptor interceptor)Parameters
interceptorIProcessWrapperInterceptor
Returns
Remarks
Dispose the returned registration to remove the interceptor.
AddOutputStream(ReadOnlySpan<OutputTarget>)
ProcessWrapper.csAdds additional output stream handlers.
public ProcessWrapper AddOutputStream(params scoped ReadOnlySpan<OutputTarget> targets)Create(string)
ProcessWrapper.csCreates a new ProcessWrapper for the specified executable.
public static ProcessWrapper Create(string fileName)ExecuteAsync(CancellationToken)
ProcessWrapper.csStarts the process and returns a ProcessInstance immediately. Await the returned instance to wait for the process to exit and get a ProcessResult. Use ProcessInstance.Kill to stop the process explicitly.
public ProcessInstance ExecuteAsync(CancellationToken cancellationToken = default)ExecuteBufferedAsync(CancellationToken)
ProcessWrapper.csStarts the process with output buffering and returns a BufferedProcessInstance immediately. Await the returned instance to wait for the process to exit and get a BufferedProcessResult. Use ProcessInstance.Kill to stop the process explicitly.
public BufferedProcessInstance ExecuteBufferedAsync(CancellationToken cancellationToken = default)StartAndForget()
ProcessWrapper.csAvailable in: net11.0(not available in the other target frameworks of the package)
- Supported on maccatalyst
- Not supported on ios
- Not supported on tvos
Starts the process without tracking it and returns its process ID.
[SupportedOSPlatform("maccatalyst")]
[UnsupportedOSPlatform("ios")]
[UnsupportedOSPlatform("tvos")]
public int StartAndForget()Returns
ToString()
ProcessWrapper.csReturns the command line representation of this process configuration.
public override string ToString()Returns
Remarks
The executable path and the arguments are always included, regardless of the verbosity set by ProcessWrapper.WithLogVerbosity. Use ProcessResult.ToString or the message of ProcessExecutionException when the rendering has to honor that verbosity, for example to keep a secret passed as an argument out of the logs.
WithArguments overloads
WithArguments(IEnumerable<string>)
ProcessWrapper.csSets the arguments for the process, replacing any previously set arguments.
public ProcessWrapper WithArguments(IEnumerable<string> arguments)WithArguments(ReadOnlySpan<string>)
ProcessWrapper.csSets the arguments for the process, replacing any previously set arguments.
public ProcessWrapper WithArguments(params scoped ReadOnlySpan<string> arguments)WithArguments(string[])
ProcessWrapper.csSets the arguments for the process, replacing any previously set arguments.
public ProcessWrapper WithArguments(params string[] arguments)WithCredentials overloads
WithCredentials(string, SecureString, string?)
ProcessWrapper.cs- Supported on windows
Sets alternate Windows credentials used to start the process.
[SupportedOSPlatform("windows")]
public ProcessWrapper WithCredentials(string userName, SecureString password, string? domain = null)Parameters
userNamestringpasswordSecureStringdomainstring?
Returns
Remarks
userName can be in the user@domain format when domain is not set.
WithCredentials(string, string, string?)
ProcessWrapper.cs- Supported on windows
Sets alternate Windows credentials used to start the process.
[SupportedOSPlatform("windows")]
public ProcessWrapper WithCredentials(string userName, string passwordInClearText, string? domain = null)Parameters
Returns
Remarks
userName can be in the user@domain format when domain is not set.
WithEnvironmentVariables overloads
WithEnvironmentVariables(Action<ProcessWrapperEnvironmentVariables>)
ProcessWrapper.csConfigures environment variables using a callback. Accumulates with previous calls.
public ProcessWrapper WithEnvironmentVariables(Action<ProcessWrapperEnvironmentVariables> configure)WithEnvironmentVariables(IReadOnlyDictionary<string, string?>)
ProcessWrapper.csConfigures environment variables from a dictionary. A null value removes the variable. Accumulates with previous calls.
public ProcessWrapper WithEnvironmentVariables(IReadOnlyDictionary<string, string?> variables)WithErrorEncoding(Encoding)
ProcessWrapper.csSets the encoding used to decode standard error.
public ProcessWrapper WithErrorEncoding(Encoding encoding)WithErrorStream(ReadOnlySpan<OutputTarget>)
ProcessWrapper.csReplaces all error stream handlers with the specified targets.
public ProcessWrapper WithErrorStream(params scoped ReadOnlySpan<OutputTarget> targets)WithInputStream(InputSource)
ProcessWrapper.csSets the input stream to the specified input source.
public ProcessWrapper WithInputStream(InputSource source)WithInterceptor overloads
WithInterceptor(IProcessStartInfoInterceptor)
ProcessWrapper.csSets the process-start-info interceptor for this process wrapper instance.
public ProcessWrapper WithInterceptor(IProcessStartInfoInterceptor interceptor)WithInterceptor(IProcessWrapperInterceptor)
ProcessWrapper.csSets the process-wrapper interceptor for this process wrapper instance.
public ProcessWrapper WithInterceptor(IProcessWrapperInterceptor interceptor)WithKillOnParentExit(bool)
ProcessWrapper.csAvailable in: net11.0(not available in the other target frameworks of the package)
- Supported on android
- Supported on linux
- Supported on windows
Sets whether the child process should be killed when the parent process exits.
[SupportedOSPlatform("android")]
[SupportedOSPlatform("linux")]
[SupportedOSPlatform("windows")]
public ProcessWrapper WithKillOnParentExit(bool killOnParentExit = true)WithLimits overloads
WithLimits(ProcessLimits)
ProcessWrapper.csSets the process limits, replacing previously configured limits.
public ProcessWrapper WithLimits(ProcessLimits limits)WithLimits(Action<ProcessLimits>)
ProcessWrapper.csConfigures process limits. Accumulates with previous calls.
public ProcessWrapper WithLimits(Action<ProcessLimits> configure)WithLinuxControlGroup(Action<CGroup2>)
ProcessWrapper.csConfigures the Linux cgroup used to apply process limits.
public ProcessWrapper WithLinuxControlGroup(Action<CGroup2> configure)WithLogVerbosity(ProcessLogVerbosity)
ProcessWrapper.csSets the verbosity used in process validation messages and process result string formatting.
public ProcessWrapper WithLogVerbosity(ProcessLogVerbosity verbosity)WithOutputEncoding(Encoding)
ProcessWrapper.csSets the encoding used to decode standard output.
public ProcessWrapper WithOutputEncoding(Encoding encoding)WithOutputStream(ReadOnlySpan<OutputTarget>)
ProcessWrapper.csReplaces all output stream handlers with the specified targets.
public ProcessWrapper WithOutputStream(params scoped ReadOnlySpan<OutputTarget> targets)WithProcessFactory(IProcessFactory)
ProcessWrapper.csSets the process factory for this process wrapper instance.
public ProcessWrapper WithProcessFactory(IProcessFactory processFactory)WithSearchWorkingDirectory(bool)
ProcessWrapper.csAlso looks for the executable in the working directory, before the directories listed in PATH.
public ProcessWrapper WithSearchWorkingDirectory(bool searchWorkingDirectory = true)Parameters
searchWorkingDirectorybool
Returns
Remarks
Windows resolves a bare executable name against the current directory before PATH, so this is the native behavior there. POSIX shells deliberately do not.
It is nevertheless disabled by default on every platform, Windows included, for security reasons: a file sitting in the working directory would otherwise take precedence over the command PATH resolves for the same name, letting an untrusted working directory substitute its own executable for the intended one. Only enable it when the working directory is trusted.
WithStartDetached(bool)
ProcessWrapper.csAvailable in: net11.0(not available in the other target frameworks of the package)
Sets whether the child process should be detached from the parent process.
public ProcessWrapper WithStartDetached(bool startDetached = true)WithStartSuspended(bool)
ProcessWrapper.csAvailable in: net11.0(not available in the other target frameworks of the package)
- Supported on macos
- Supported on windows
Sets whether the child process should start in a suspended state.
[SupportedOSPlatform("macos")]
[SupportedOSPlatform("windows")]
public ProcessWrapper WithStartSuspended(bool startSuspended = true)WithUseCredentialsForNetworkingOnly(bool)
ProcessWrapper.cs- Supported on windows
Sets whether to use LOGON_NETCREDENTIALS_ONLY when starting the process on Windows.
[SupportedOSPlatform("windows")]
public ProcessWrapper WithUseCredentialsForNetworkingOnly(bool useCredentialsForNetworkingOnly = true)Parameters
useCredentialsForNetworkingOnlybool
Returns
Remarks
When enabled, this behaves similarly to runas /netonly.
WithValidation(ProcessValidationMode)
ProcessWrapper.csSets process validation rules.
public ProcessWrapper WithValidation(ProcessValidationMode mode)WithWindowsJobObject(Action<JobObject>)
ProcessWrapper.csConfigures the Windows Job Object used to apply process limits.
public ProcessWrapper WithWindowsJobObject(Action<JobObject> configure)WithWorkingDirectory(string)
ProcessWrapper.csSets the working directory for the process.
public ProcessWrapper WithWorkingDirectory(string workingDirectory)Operators
| Name | Description |
|---|---|
| operator |(ProcessWrapper, ProcessWrapper) | Creates a pipeline between 2 commands. |
operator |(ProcessWrapper, ProcessWrapper)
ProcessWrapper.csCreates a pipeline between 2 commands.
public static ProcessPipeline operator |(ProcessWrapper left, ProcessWrapper right)