en-US/ProcessEx.dll-Help.xml
|
<?xml version="1.0" encoding="utf-8"?> <helpItems schema="maml" xmlns="http://msh"> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>ConvertTo-EscapedArgument</command:name> <command:verb>ConvertTo</command:verb> <command:noun>EscapedArgument</command:noun> <maml:description> <maml:para>Escape argument for the command line.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Escapes the arguments supplied so they are seen as a distinct argument in the command line string. The default escaping logic is based on the Windows C argument standard rules but some applications may not use this standard. Using `-ArgumentEscaping Msi` the escaping logic can be set to escape MSI property keys and values alongside the C rules. When escaping according to the `Msi` rules a `PROPERTY=value` is escaped as follows:</maml:para> <maml:para>+ The `PROPERTY=` is kept as is + The `value` is quoted if it contains whitespace, double quotes, or is empty + The `value` will double up on any double quotes</maml:para> <maml:para>If the argument does not match the MSI `PROPERTY=value` format, it is escaped according to the normal C rules. An MSI property name must begin with either a litter or an underscore followed by letters, numerals, underscores, or periods.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>ConvertTo-EscapedArgument</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The arguments to escape.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ArgumentEscaping</maml:name> <maml:description> <maml:para>The escaping rules to use. The default `Standard` will use the C escaping rules. The `Msi` ruleset will escape MSI property names and values, otherwise falls back to the standard C escaping rules. The `Raw` will not escape any value and return it as is.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ArgumentEscapingMode</command:parameterValue> <dev:type> <maml:name>ArgumentEscapingMode</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Standard</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ArgumentEscaping</maml:name> <maml:description> <maml:para>The escaping rules to use. The default `Standard` will use the C escaping rules. The `Msi` ruleset will escape MSI property names and values, otherwise falls back to the standard C escaping rules. The `Raw` will not escape any value and return it as is.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ArgumentEscapingMode</command:parameterValue> <dev:type> <maml:name>ArgumentEscapingMode</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Standard</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The arguments to escape.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String[]</maml:name> </dev:type> <maml:description> <maml:para>The arguments to escape.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> <maml:description> <maml:para>The escaped arguments.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>--------- Example 1: Escape value using C style rules ---------</maml:title> <dev:code>PS C:\> $arguments = ConvertTo-EscapedArgument $argumentList</dev:code> <dev:remarks> <maml:para>Escapes each argument in `$argumentList` for use with the raw CreateProcess command value.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>------------ Example 2: Escape MSI style properties ------------</maml:title> <dev:code>PS C:\> @( 'FOO' 'A=value' 'B=' 'C=""' 'D=value with space' 'E=value with "quotes" and spaces' '1F=invalid prop wont be escaped on MSI rules' 'C:\path with space' ) | ConvertTo-EscapedArgument -ArgumentEscaping Msi # FOO # A=value # B="" # C="""""" # D="value with space" # E="value with ""quotes"" and spaces" # "1F=invalid prop wont be escaped on MSI rules" # "C:\path with space"</dev:code> <dev:remarks> <maml:para>Escaped each argument using the `Msi` ruleset. Any argument that does not match the MSI `PROPERTY=value` format will be escaped based on the C style rules. Some further notes</maml:para> <maml:para>+ `B=` becomes `B=""` as a way to unset an MSI property + `C=""` becomes `C=""""""` as the `""` as both doubled up and the value is then quoted + `1F=invalid ...` is not treated as an MSI property because they cannot start with numbers</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Parsing C Command-Line Arguments</maml:linkText> <maml:uri>https://docs.microsoft.com/en-us/cpp/c-language/parsing-c-command-line-arguments?view=msvc-170</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Everyone quotes command line arguments the wrong way</maml:linkText> <maml:uri>https://docs.microsoft.com/en-us/archive/blogs/twistylittlepassagesallalike/everyone-quotes-command-line-arguments-the-wrong-way</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>MSI command line options</maml:linkText> <maml:uri>https://learn.microsoft.com/en-us/windows/win32/msi/command-line-options</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>MSI property name restrictions</maml:linkText> <maml:uri>https://learn.microsoft.com/en-us/windows/win32/msi/restrictions-on-property-names</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Copy-HandleToProcess</command:name> <command:verb>Copy</command:verb> <command:noun>HandleToProcess</command:noun> <maml:description> <maml:para>Copy a handle to the target process.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Creates a copy of the handle in the process specified. This can be used for `New-StartupInfo -InheritedHandle` when the `-ParentProcess` parameter is set.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Copy-HandleToProcess</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="InputObject"> <maml:name>Handle</maml:name> <maml:description> <maml:para>The handle to copy to the other process.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle[]</command:parameterValue> <dev:type> <maml:name>SafeHandle[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Process</maml:name> <maml:description> <maml:para>The process to copy the handle to. This can either be a `Process` object or the process identifier.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ProcessIntString</command:parameterValue> <dev:type> <maml:name>ProcessIntString</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>Access</maml:name> <maml:description> <maml:para>The access requested for the new handle. The value is dependent on the type of handle that is being copied. If set to 0 or undefinined the duplicated handle will have the same access as the source handle.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Inherit</maml:name> <maml:description> <maml:para>Marks the duplicated handle are inheritable in the target process. This means the handle will inherit to any processes created by the target process if inheritibility is set when creating the child process.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>OwnHandle</maml:name> <maml:description> <maml:para>The handle in the target process will be disposed when the safe handle outputted by this function is disposed in the source process. This can be dangerous to use if the target process who uses the handle first disposes of it itself.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>Access</maml:name> <maml:description> <maml:para>The access requested for the new handle. The value is dependent on the type of handle that is being copied. If set to 0 or undefinined the duplicated handle will have the same access as the source handle.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="InputObject"> <maml:name>Handle</maml:name> <maml:description> <maml:para>The handle to copy to the other process.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle[]</command:parameterValue> <dev:type> <maml:name>SafeHandle[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Inherit</maml:name> <maml:description> <maml:para>Marks the duplicated handle are inheritable in the target process. This means the handle will inherit to any processes created by the target process if inheritibility is set when creating the child process.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>OwnHandle</maml:name> <maml:description> <maml:para>The handle in the target process will be disposed when the safe handle outputted by this function is disposed in the source process. This can be dangerous to use if the target process who uses the handle first disposes of it itself.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Process</maml:name> <maml:description> <maml:para>The process to copy the handle to. This can either be a `Process` object or the process identifier.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ProcessIntString</command:parameterValue> <dev:type> <maml:name>ProcessIntString</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf"> <maml:name>Confirm</maml:name> <maml:description> <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi"> <maml:name>WhatIf</maml:name> <maml:description> <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Runtime.InteropServices.SafeHandle[]</maml:name> </dev:type> <maml:description> <maml:para>The handles to copy to the target process.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>ProcessEx.Native.SafeDuplicateHandle</maml:name> </dev:type> <maml:description> <maml:para>The duplicated handle that can be used in the target process. Use `[string]$out.DangerousGetHandle()` to get a serialzied representation of the handle to pass to the target process.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>When using `-OwnHandle` the duplicate handle in the target process is closed when the SafeHandle object disposed by the caller. In this scenario keep this handle alive until the target process has finished using it.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>Example 1: Duplicate handle for use with parent process inheritability</maml:title> <dev:code>PS C:\> $parentProcess = Get-Process -Id 6624 PS C:\> $fs = [IO.File]::Open('C:\file.txt', 'Create', 'Write', 'ReadWrite') PS C:\> try { >> $newHandle = Copy-HandleToProcess -Handle $fs.SafeFileHandle -Process $parentProcess -OwnHandle >> } >> finally { >> $fs.Dispose() >> } >> try { >> $si = New-StartupInfo -InheritedHandle $newHandle -ParentProcess $parentProcess >> Start-ProcessEx powershell.exe -StartupInfo $si -Wait >> } >> finally { >> $newHandle.Dispose() >> }</dev:code> <dev:remarks> <maml:para>Duplicates the file handle opened by the caller to the process specified. This duplicated handle is marked to be inherited when creating the new process that has the same parent set as its parent. Because the `-OwnHandle` flag is specified when the handle is disposed it will close the handle in the process it was copied to.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>DuplicateHandle</maml:linkText> <maml:uri>https://docs.microsoft.com/en-us/windows/win32/api/handleapi/nf-handleapi-duplicatehandle</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-ProcessEnvironment</command:name> <command:verb>Get</command:verb> <command:noun>ProcessEnvironment</command:noun> <maml:description> <maml:para>Get the environment variables of a process.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Get the environment variables of a process in the form of a dictionary.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-ProcessEnvironment</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="Id"> <maml:name>Process</maml:name> <maml:description> <maml:para>The process to open. This can either be a `Process` object or the process identifier. If omited the current process will be used.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ProcessIntString[]</command:parameterValue> <dev:type> <maml:name>ProcessIntString[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="Id"> <maml:name>Process</maml:name> <maml:description> <maml:para>The process to open. This can either be a `Process` object or the process identifier. If omited the current process will be used.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ProcessIntString[]</command:parameterValue> <dev:type> <maml:name>ProcessIntString[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>ProcessEx.ProcessIntString[]</maml:name> </dev:type> <maml:description> <maml:para>The `Process` object, process id, or name.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Collections.Generic.Dictionary`2[[System.String, System.Private.CoreLib, Version=6.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e],[System.String, System.Private.CoreLib, Version=6.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e]]</maml:name> </dev:type> <maml:description> <maml:para>A dictionary containing the environment variables. Each key is case insensitive as environment variables on Windows are case insensitive.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>This function uses undocumented APIs to retrieve the environment variables of other processes. There are no guarantees that Windows will modify the APIs used and break this cmdlet in the future.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>Example 1: Get the environment variables of the current process</maml:title> <dev:code>PS C:\> Get-ProcessEnvironment</dev:code> <dev:remarks> <maml:para>Gets the environment variables of the currently running process.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 2: Get the environment variables of a specific process</maml:title> <dev:code>PS C:\> Get-ProcessEnvironment -Id 1234</dev:code> <dev:remarks> <maml:para>Gets the environment variables of the process `1234`.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-ProcessEx</command:name> <command:verb>Get</command:verb> <command:noun>ProcessEx</command:noun> <maml:description> <maml:para>Get info about the process.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Get process information that isn't normally exposed in `Get-Process`.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-ProcessEx</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="Id"> <maml:name>Process</maml:name> <maml:description> <maml:para>The process to open. This can either be a `Process` object or the process identifier.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ProcessIntString[]</command:parameterValue> <dev:type> <maml:name>ProcessIntString[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Access</maml:name> <maml:description> <maml:para>The desired access of the proces shandle the cmdlet will open. Defaults to `AllAccess` but can be restricted depending on what the caller desires.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Terminate</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">CreateThread</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">VMOperation</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">VMRead</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">VMWrite</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">DupHandle</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">CreateProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SetQuota</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SetInformation</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">QueryInformation</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SuspendResume</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">QueryLimitedInformation</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Delete</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ReadControl</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">StandardRightsRead</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">StandardRightsExecute</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">StandardRightsWrite</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">WriteDAC</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">WriteOwner</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">StandardRightsRequired</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Synchronize</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">StandardRightsAll</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">AllAccess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">AccessSystemSecurity</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">GenericAll</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">GenericExecute</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">GenericWrite</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">GenericRead</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">ProcessAccessRights</command:parameterValue> <dev:type> <maml:name>ProcessAccessRights</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Inherit</maml:name> <maml:description> <maml:para>Marks the opened process handle as inheritable to child processes it may spawn later on.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Access</maml:name> <maml:description> <maml:para>The desired access of the proces shandle the cmdlet will open. Defaults to `AllAccess` but can be restricted depending on what the caller desires.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ProcessAccessRights</command:parameterValue> <dev:type> <maml:name>ProcessAccessRights</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Inherit</maml:name> <maml:description> <maml:para>Marks the opened process handle as inheritable to child processes it may spawn later on.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="Id"> <maml:name>Process</maml:name> <maml:description> <maml:para>The process to open. This can either be a `Process` object or the process identifier.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ProcessIntString[]</command:parameterValue> <dev:type> <maml:name>ProcessIntString[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>ProcessEx.ProcessIntString[]</maml:name> </dev:type> <maml:description> <maml:para>The `Process` object, process id, or name.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>ProcessEx.ProcessInfo</maml:name> </dev:type> <maml:description> <maml:para>The `ProcessInfo` of the opened process. This contains properties like the process handle and command line invocation. The `Thread` and `ThreadId` properties will not be set and should not be used with the output of this cmdlet. This object contains the following properties:</maml:para> <maml:para>- `Executable` - The executable of the process</maml:para> <maml:para>- `CommandLine` - The command line used to start the process</maml:para> <maml:para>- `WorkingDirectory` - The working/current directory of the process</maml:para> <maml:para>- `Process` - The `SafeHandle` of the process retrieved</maml:para> <maml:para>- `Thread` - This is not set in the output from `Get-ProcessEx` and should be ignored</maml:para> <maml:para>- `ProcessId` - Also aliased to `Id`, this is the process identifier</maml:para> <maml:para>- `ThreadId` - This is not set in the output from `Get-ProcessEx` and should be ignored</maml:para> <maml:para>- `ParentProcessId` - The process identifier of the parent that spawned this process</maml:para> <maml:para>- `ExitCode` - The exit code of the process, this will not be set if it's still running</maml:para> <maml:para>- `Environment` - The environment variables of the process</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------- Example 1: Get info about the current process --------</maml:title> <dev:code>PS C:\> Get-ProcessEx -Process $pid</dev:code> <dev:remarks> <maml:para>Gets information about the current process</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-StartupInfo</command:name> <command:verb>Get</command:verb> <command:noun>StartupInfo</command:noun> <maml:description> <maml:para>Get the startupinfo for the current process.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Gets the `STARTUPINFO` values set for the current process.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-StartupInfo</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>ProcessEx.StartupInfo</maml:name> </dev:type> <maml:description> <maml:para>The `StartupInfo` value for the current process. Any of the extended thread attribute values, like `ParentProcess`, `ConPTY`, and `InheritedHandle` will not be set as they are used only for creating new processes.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- Example 1 --------------------------</maml:title> <dev:code>PS C:\> Get-StartupInfo</dev:code> <dev:remarks> <maml:para>Gets the `StartupInfo` value for the current process. This can be used to inspect how the process was started by the caller.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>GetStartupInfo</maml:linkText> <maml:uri>https://docs.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getstartupinfow</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>STARTUPINFOW</maml:linkText> <maml:uri>https://docs.microsoft.com/en-us/windows/win32/api/processthreadsapi/ns-processthreadsapi-startupinfow</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Undocumented STARTUPINFO Values</maml:linkText> <maml:uri>http://www.catch22.net/tuts/undocumented-createprocess#</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Get-TokenEnvironment</command:name> <command:verb>Get</command:verb> <command:noun>TokenEnvironment</command:noun> <maml:description> <maml:para>Get environment block for a user token.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Gets the environment variables for the user access token specified. These environment variables can be used with `Start-ProcessEx` and `Start-ProcessWith` to specify custom environment variables for the user desired.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Get-TokenEnvironment</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="none"> <maml:name>Token</maml:name> <maml:description> <maml:para>The access token that is used when building the environment variables. If not specified the current process' access token is used to generate the environment values. The token must have `Query` access and `Duplicate` access if it's a primary token.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle[]</command:parameterValue> <dev:type> <maml:name>SafeHandle[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="none"> <maml:name>Token</maml:name> <maml:description> <maml:para>The access token that is used when building the environment variables. If not specified the current process' access token is used to generate the environment values. The token must have `Query` access and `Duplicate` access if it's a primary token.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle[]</command:parameterValue> <dev:type> <maml:name>SafeHandle[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Runtime.InteropServices.SafeHandle[]</maml:name> </dev:type> <maml:description> <maml:para>The access tokens to build the environment variables from.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Collections.Generic.Dictionary`2[[System.String, System.Private.CoreLib, Version=6.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e],[System.String, System.Private.CoreLib, Version=6.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e]]</maml:name> </dev:type> <maml:description> <maml:para>A dictionary containing the environment variables. Each key is case insensitive as environment variables on Windows are case insensitive.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>Example 1: Modify PATH envvar used for process with access token</maml:title> <dev:code>PS C:\> $env = Get-TokenEnvironment -Token $token PS C:\> $env.PATH += "$([IO.Path]::PathSeparator)C:\folder\bin" PS C:\> Start-ProcessEx -FilePath pwsh.exe -Token $token -Environment $env</dev:code> <dev:remarks> <maml:para>Gets the environment block that would be used with a process spawned with a user access token. The code adds a new entry to the `PATH` env var which is then applied to the new process that is spawned.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>CreateEnvironmentBlock</maml:linkText> <maml:uri>https://docs.microsoft.com/en-us/windows/win32/api/userenv/nf-userenv-createenvironmentblock</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Invoke-ProcessEx</command:name> <command:verb>Invoke</command:verb> <command:noun>ProcessEx</command:noun> <maml:description> <maml:para>Invoke a process inline and capture the output like the call operator.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Invokes a process, waits for it to finish and returns the output back to PowerShell. This is like the builtin call operator `& whoami` but with a few more features. Some features it offers over the call operator are:</maml:para> <maml:para>+ It can capture the raw bytes of the stdout/stderr streams + You can control the encoding used to pipe strings into and decode out of the process through a parameter rather than a global value + You can capture the raw bytes of the process rather than decode it to a string + The command can either be run from a single command line string or escaped through an array of arguments + You can run it as another user through the `-Token` parameter + You can have access to extended startup info attributes like a parent process, ConPTY, explicit handle inheritance, etc</maml:para> <maml:para>Some things that this cmdlet cannot do or is not designed for</maml:para> <maml:para>+ Starting an interactive process - the output can be set to a console but it is not the default + Dealing with env var changes between `pwsh.exe` and `powershell.exe`, use `-UseNewEnvironment` or an explicit `-Environment` block to handle this better + Using the PowerShell minishell `powershell { ... }` does not work</maml:para> <maml:para>The cmdlet is also exposed through the `procex` alias for easier interactive use.</maml:para> <maml:para>It can be used to run a process as another user through the `-Token` parameter but requires the caller to have the `SeAssignPrimaryTokenPrivilege` and `SeIncreaseQuotaPrivilege` privileges which is not granted to an Administrator by default. Like the normal call operator, when a process is complete, the `$LASTEXITCODE` variable will be set to the exit code of the process.</maml:para> <maml:para>By default the cmdlet is set to capture stdout lines in the output stream and stderr lines in the error stream. If `$ErrorActionPreference = 'Stop'` or `-ErrorAction Stop` is set on the cmdlet, any stderr lines will terminate the statement. Either explicitly set `-ErrorAction Continue` or use `-RedirectStderr` to something else to change this behaviour.</maml:para> <maml:para>Use Invoke-ProcessWith (./Invoke-ProcessWith.md)which exposes a similar set of options but without the extra privilege requirement.</maml:para> <maml:para>Use Start-ProcessEx (./Start-ProcessEx.md)to invoke a process in the background.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Invoke-ProcessEx</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ApplicationName</maml:name> <maml:description> <maml:para>Used with `-CommandLine` as the full path to the executable to run. This is useful if the `-CommandLine` executable path contains spaces and you wish to be explicit about what to run.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CommandLine</maml:name> <maml:description> <maml:para>Used instead of `-FilePath` and `-ArgumentList` to run a new process with the literal string provided. This string is not escaped so you need to ensure it is valid for your use case. You can optionally specify `-ApplicationName` with this parameter to be more explicit about what executable to run.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="ConPTYY"> <maml:name>ConPTYHeight</maml:name> <maml:description> <maml:para>The ConPTY height to use when `-UseConPTY` is set. Defaults to `$host.UI.RawUI.BufferSize.Height` or `80` if no host is present.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int16</command:parameterValue> <dev:type> <maml:name>Int16</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="ConPTYX"> <maml:name>ConPTYWidth</maml:name> <maml:description> <maml:para>The ConPTY width to use when `-UseConPTY` is set. Defaults to `$host.UI.RawUI.BufferSize.Width` or `80` if no host is present.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int16</command:parameterValue> <dev:type> <maml:name>Int16</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>DisableInheritance</maml:name> <maml:description> <maml:para>Explicitly disable all the handles in the current process from being inherited with the new process. This cannot be used if `-StartupInfo` has an explicit StandardInput/Output/Error or InheritedHandles list.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Environment</maml:name> <maml:description> <maml:para>A dictionary containing explicit environment variables to use for the new process. These env vars will be used instead of the existing process environment variables if defined. Use `Get-TokenEnvironment` to generate a new environment block that can be modified as needed for the new process. Cannot be used with `-UseNewEnvironment`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">IDictionary</command:parameterValue> <dev:type> <maml:name>IDictionary</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>InputEncoding</maml:name> <maml:description> <maml:para>Sets the encoding used when writing the input strings to the input of the process. Will default to the value of `[Console]::InputEncoding` but can be set to an explicit `Encoding` type or one of the following string values:</maml:para> <maml:para>+ `ASCII` - The 7-bit ASCII encoding + `ANSI` - The current system locale encoding + `BigEndianUnicode` - UTF-16 in Big Endian form + `BigEndianUtf32` - UTF-32 in Big Endian form + `ConsoleInput` - The console input encoding - `[Console]::InputEncoding` (Default) + `ConsoleOutput` - The console output encoding - `[Console]::OutputEncoding` + `OEM` - Same as `ConsoleOutput` + `Unicode` - UTF-16 in Little Endian form + `UTF8` - UTF-8 without a BOM + `UTF8Bom` - UTF-8 with a BOM + `UTF8NoBom` - UTF-8 without a BOM + `UTF32` - UTF-32 in Little Endiam form</maml:para> <maml:para>Using any other string or integer value will call `[System.Text.Encoding]::GetEncoding($_)` to build the encoding object.</maml:para> <maml:para>Setting `-InputEncoding Bytes` does not work as the input must have an encoding to convert the input strings to bytes when writing. This parameter is ignored if `-UseConPTY` is specified as that always outputs as UTF-8.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">EncodingOrByteStream</command:parameterValue> <dev:type> <maml:name>EncodingOrByteStream</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>ConsoleInput</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The input objects to pipe into the process' stdin. Any `byte` or `byte[]` array values will be passed in directly. Any `string` or `string[]` values will be passed in as a line and encoded with the `-InputEncoding` parameter. Other object types will be casted to a string and handled as above.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>OutputEncoding</maml:name> <maml:description> <maml:para>Sets the encoding used when reading the output and error stream bytes. Will default to the value of `[Console]::OutputEncoding` but can be set to an explicit `Encoding` type or one of the following string values:</maml:para> <maml:para>+ `ASCII` - The 7-bit ASCII encoding + `ANSI` - The current system locale encoding + `BigEndianUnicode` - UTF-16 in Big Endian form + `BigEndianUtf32` - UTF-32 in Big Endian form + `Bytes` - Outputs as raw bytes and not a string + `ConsoleInput` - The console input encoding - `[Console]::InputEncoding` + `ConsoleOutput` - The console output encoding - `[Console]::OutputEncoding` (Default) + `OEM` - Same as `ConsoleOutput` + `Unicode` - UTF-16 in Little Endian form + `UTF8` - UTF-8 without a BOM + `UTF8Bom` - UTF-8 with a BOM + `UTF8NoBom` - UTF-8 without a BOM + `UTF32` - UTF-32 in Little Endiam form</maml:para> <maml:para>Using any other string or integer value will call `[System.Text.Encoding]::GetEncoding($_)` to build the encoding object.</maml:para> <maml:para>Setting `-OutputEncoding Bytes` will output the data as raw bytes rather than a string. Unless set to `Bytes`, this parameter is ignored if `-UseConPTY` is specified as that always outputs as UTF-8.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">EncodingOrByteStream</command:parameterValue> <dev:type> <maml:name>EncodingOrByteStream</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>ConsoleOutput</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Raw</maml:name> <maml:description> <maml:para>When set, will output as a single string rather than an array of strings representing each line. If `-OutputEncoding Bytes`, the output is emitted as a single `byte[]` rather than as individual bytes. This only applies to both the output (stdout) and error (stderr) stream .</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>RedirectStderr</maml:name> <maml:description> <maml:para>Redirect the stderr data to another location. Defaults to `Error` which is the PowerShell error stream. Set to `Output` to redirect stderr to the output stream as a string based on `-OutputEncoding`. Set to `Console` to skip capturing stderr together and write it directly to the console. Set to `Null` to discard all output on stderr.</maml:para> <maml:para>This option is ignored if `-UseConPTY` is set as there is no stderr anymore.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Error</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Output</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Console</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Null</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">StdioStreamTarget</command:parameterValue> <dev:type> <maml:name>StdioStreamTarget</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Error</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>RedirectStdout</maml:name> <maml:description> <maml:para>Redirect the stdout data to another location. Defaults to `Output` which is the PowerShell output stream. Set to `Error` to redirect stdout to the error stream as an error record. Set to `Console` to skip capturing stdout together and write it directly to the console. Set to `Null` to discard all output on stdout.</maml:para> <maml:para>This option is ignored if `-UseConPTY` is set as there is no stdout anymore.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Error</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Output</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Console</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Null</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">StdioStreamTarget</command:parameterValue> <dev:type> <maml:name>StdioStreamTarget</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Output</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartupInfo</maml:name> <maml:description> <maml:para>Specify custom startup information as returned by `New-StartupInfo`. It is not possible to use a custom `-StandardInput`, `-StandardOutput`, `-StandardError`, or `-ConPTY` in the startup info.</maml:para> <maml:para>If using a custom parent process, the invoked process will be spawned in a new console and will not inherit the existing one. Using `-RedirectStdout Console` or `-RedirectStderr Console` will not work if using a custom parent process.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StartupInfo</command:parameterValue> <dev:type> <maml:name>StartupInfo</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Token</maml:name> <maml:description> <maml:para>Create the process to run with the access token specified. This access token can be retrieved through other functions like `LogonUser`, duplicating from an existing process, etc. Using this parameter calls `CreateProcessAsUser` instead of `CreateProcess` which requires the `SeIncreaseQuotaPrivilege` privilege. It also requires the `SeAssignPrimaryTokenPrivilege` privilege if the token is not a restricted version of the callers primary token. The `SeAssignPrimaryTokenPrivilege` privilege is not given to administrators by default so check with `whoami.exe /priv` to see if your account has this privilege. The `Start-ProcessWith` cmdlet requires less sensitive privileges and can be used as an alternative to this cmdlet if needed.</maml:para> <maml:para>Be aware that this process will add the Logon Session SID of this token to the station and desktop security descriptor specified by Desktop on `-StartupInfo`. If no startup info was specified then the current station and desktop is used. Running this with multiple tokens could hit the maximum allowed size in a ACL if the station/desktop descriptor is not cleaned up.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle</command:parameterValue> <dev:type> <maml:name>SafeHandle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>UseConPTY</maml:name> <maml:description> <maml:para>Use a Console PTY instead of the standard stdin, stdout, and stderr streams. This replicates running a process in an actual console without any interaction and the output will reflect the data the executable will write to the console. The data will typically contain interactive elements like ANSI escape codes. The input and output encoding is always set to UTF-8 regardless of `-InputEncoding` and `-OutputEncoding` unless `-OutputEncoding Bytes` is specified. In that case the output will be the raw bytes from the output handle. When set `-RedirectStdout` and `-RedirectStderr` will do nothing.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>UseNewEnvironment</maml:name> <maml:description> <maml:para>Instead of inheriting the current process environment variables, use a brand new set of environment variables for the current user. Cannot be used with `-Environment`.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WorkingDirectory</maml:name> <maml:description> <maml:para>The working directory to set for the new process, defaults to the current filesystem location of the PowerShell process if not defined.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Invoke-ProcessEx</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="0" aliases="none"> <maml:name>FilePath</maml:name> <maml:description> <maml:para>The executable to start. Use with `-ArgumentList` to supply a list of argument to this executable.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ArgumentEscaping</maml:name> <maml:description> <maml:para>The argument escaping mode to use when building the values of `-ArgumentList` to the single command line string. The default `Standard` will escape the argument list according to the C style rules where whitespace is fully enclosed as a double quoted string. The `Raw` rule will ignore all escaping and just appeach each argument with a space. The `Msi` rule will quote the argument `FOO=value with space` as `FOO="value with space"`.</maml:para> <maml:para>See ConvertTo-EscapedArgument (./ConvertTo-EscapedArgument.md)for more information.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Standard</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Raw</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Msi</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">ArgumentEscapingMode</command:parameterValue> <dev:type> <maml:name>ArgumentEscapingMode</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Standard</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ArgumentList</maml:name> <maml:description> <maml:para>A list of arguments to run with the `-FilePath`. These arguments are automatically escaped based on the Win32 C argument escaping rules as done by `ConvertTo-EscapedArgument`. The `-ArgumentEscaping` parameter can be used to change the escaping method from the C style to other ones. If you wish to provide arguments as a literal string without escaping use the `-CommandLine` option instead of this and `-FilePath`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="ConPTYY"> <maml:name>ConPTYHeight</maml:name> <maml:description> <maml:para>The ConPTY height to use when `-UseConPTY` is set. Defaults to `$host.UI.RawUI.BufferSize.Height` or `80` if no host is present.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int16</command:parameterValue> <dev:type> <maml:name>Int16</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="ConPTYX"> <maml:name>ConPTYWidth</maml:name> <maml:description> <maml:para>The ConPTY width to use when `-UseConPTY` is set. Defaults to `$host.UI.RawUI.BufferSize.Width` or `80` if no host is present.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int16</command:parameterValue> <dev:type> <maml:name>Int16</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>DisableInheritance</maml:name> <maml:description> <maml:para>Explicitly disable all the handles in the current process from being inherited with the new process. This cannot be used if `-StartupInfo` has an explicit StandardInput/Output/Error or InheritedHandles list.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Environment</maml:name> <maml:description> <maml:para>A dictionary containing explicit environment variables to use for the new process. These env vars will be used instead of the existing process environment variables if defined. Use `Get-TokenEnvironment` to generate a new environment block that can be modified as needed for the new process. Cannot be used with `-UseNewEnvironment`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">IDictionary</command:parameterValue> <dev:type> <maml:name>IDictionary</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>InputEncoding</maml:name> <maml:description> <maml:para>Sets the encoding used when writing the input strings to the input of the process. Will default to the value of `[Console]::InputEncoding` but can be set to an explicit `Encoding` type or one of the following string values:</maml:para> <maml:para>+ `ASCII` - The 7-bit ASCII encoding + `ANSI` - The current system locale encoding + `BigEndianUnicode` - UTF-16 in Big Endian form + `BigEndianUtf32` - UTF-32 in Big Endian form + `ConsoleInput` - The console input encoding - `[Console]::InputEncoding` (Default) + `ConsoleOutput` - The console output encoding - `[Console]::OutputEncoding` + `OEM` - Same as `ConsoleOutput` + `Unicode` - UTF-16 in Little Endian form + `UTF8` - UTF-8 without a BOM + `UTF8Bom` - UTF-8 with a BOM + `UTF8NoBom` - UTF-8 without a BOM + `UTF32` - UTF-32 in Little Endiam form</maml:para> <maml:para>Using any other string or integer value will call `[System.Text.Encoding]::GetEncoding($_)` to build the encoding object.</maml:para> <maml:para>Setting `-InputEncoding Bytes` does not work as the input must have an encoding to convert the input strings to bytes when writing. This parameter is ignored if `-UseConPTY` is specified as that always outputs as UTF-8.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">EncodingOrByteStream</command:parameterValue> <dev:type> <maml:name>EncodingOrByteStream</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>ConsoleInput</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The input objects to pipe into the process' stdin. Any `byte` or `byte[]` array values will be passed in directly. Any `string` or `string[]` values will be passed in as a line and encoded with the `-InputEncoding` parameter. Other object types will be casted to a string and handled as above.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>OutputEncoding</maml:name> <maml:description> <maml:para>Sets the encoding used when reading the output and error stream bytes. Will default to the value of `[Console]::OutputEncoding` but can be set to an explicit `Encoding` type or one of the following string values:</maml:para> <maml:para>+ `ASCII` - The 7-bit ASCII encoding + `ANSI` - The current system locale encoding + `BigEndianUnicode` - UTF-16 in Big Endian form + `BigEndianUtf32` - UTF-32 in Big Endian form + `Bytes` - Outputs as raw bytes and not a string + `ConsoleInput` - The console input encoding - `[Console]::InputEncoding` + `ConsoleOutput` - The console output encoding - `[Console]::OutputEncoding` (Default) + `OEM` - Same as `ConsoleOutput` + `Unicode` - UTF-16 in Little Endian form + `UTF8` - UTF-8 without a BOM + `UTF8Bom` - UTF-8 with a BOM + `UTF8NoBom` - UTF-8 without a BOM + `UTF32` - UTF-32 in Little Endiam form</maml:para> <maml:para>Using any other string or integer value will call `[System.Text.Encoding]::GetEncoding($_)` to build the encoding object.</maml:para> <maml:para>Setting `-OutputEncoding Bytes` will output the data as raw bytes rather than a string. Unless set to `Bytes`, this parameter is ignored if `-UseConPTY` is specified as that always outputs as UTF-8.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">EncodingOrByteStream</command:parameterValue> <dev:type> <maml:name>EncodingOrByteStream</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>ConsoleOutput</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Raw</maml:name> <maml:description> <maml:para>When set, will output as a single string rather than an array of strings representing each line. If `-OutputEncoding Bytes`, the output is emitted as a single `byte[]` rather than as individual bytes. This only applies to both the output (stdout) and error (stderr) stream .</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>RedirectStderr</maml:name> <maml:description> <maml:para>Redirect the stderr data to another location. Defaults to `Error` which is the PowerShell error stream. Set to `Output` to redirect stderr to the output stream as a string based on `-OutputEncoding`. Set to `Console` to skip capturing stderr together and write it directly to the console. Set to `Null` to discard all output on stderr.</maml:para> <maml:para>This option is ignored if `-UseConPTY` is set as there is no stderr anymore.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Error</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Output</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Console</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Null</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">StdioStreamTarget</command:parameterValue> <dev:type> <maml:name>StdioStreamTarget</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Error</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>RedirectStdout</maml:name> <maml:description> <maml:para>Redirect the stdout data to another location. Defaults to `Output` which is the PowerShell output stream. Set to `Error` to redirect stdout to the error stream as an error record. Set to `Console` to skip capturing stdout together and write it directly to the console. Set to `Null` to discard all output on stdout.</maml:para> <maml:para>This option is ignored if `-UseConPTY` is set as there is no stdout anymore.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Error</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Output</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Console</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Null</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">StdioStreamTarget</command:parameterValue> <dev:type> <maml:name>StdioStreamTarget</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Output</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartupInfo</maml:name> <maml:description> <maml:para>Specify custom startup information as returned by `New-StartupInfo`. It is not possible to use a custom `-StandardInput`, `-StandardOutput`, `-StandardError`, or `-ConPTY` in the startup info.</maml:para> <maml:para>If using a custom parent process, the invoked process will be spawned in a new console and will not inherit the existing one. Using `-RedirectStdout Console` or `-RedirectStderr Console` will not work if using a custom parent process.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StartupInfo</command:parameterValue> <dev:type> <maml:name>StartupInfo</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Token</maml:name> <maml:description> <maml:para>Create the process to run with the access token specified. This access token can be retrieved through other functions like `LogonUser`, duplicating from an existing process, etc. Using this parameter calls `CreateProcessAsUser` instead of `CreateProcess` which requires the `SeIncreaseQuotaPrivilege` privilege. It also requires the `SeAssignPrimaryTokenPrivilege` privilege if the token is not a restricted version of the callers primary token. The `SeAssignPrimaryTokenPrivilege` privilege is not given to administrators by default so check with `whoami.exe /priv` to see if your account has this privilege. The `Start-ProcessWith` cmdlet requires less sensitive privileges and can be used as an alternative to this cmdlet if needed.</maml:para> <maml:para>Be aware that this process will add the Logon Session SID of this token to the station and desktop security descriptor specified by Desktop on `-StartupInfo`. If no startup info was specified then the current station and desktop is used. Running this with multiple tokens could hit the maximum allowed size in a ACL if the station/desktop descriptor is not cleaned up.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle</command:parameterValue> <dev:type> <maml:name>SafeHandle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>UseConPTY</maml:name> <maml:description> <maml:para>Use a Console PTY instead of the standard stdin, stdout, and stderr streams. This replicates running a process in an actual console without any interaction and the output will reflect the data the executable will write to the console. The data will typically contain interactive elements like ANSI escape codes. The input and output encoding is always set to UTF-8 regardless of `-InputEncoding` and `-OutputEncoding` unless `-OutputEncoding Bytes` is specified. In that case the output will be the raw bytes from the output handle. When set `-RedirectStdout` and `-RedirectStderr` will do nothing.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>UseNewEnvironment</maml:name> <maml:description> <maml:para>Instead of inheriting the current process environment variables, use a brand new set of environment variables for the current user. Cannot be used with `-Environment`.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WorkingDirectory</maml:name> <maml:description> <maml:para>The working directory to set for the new process, defaults to the current filesystem location of the PowerShell process if not defined.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ApplicationName</maml:name> <maml:description> <maml:para>Used with `-CommandLine` as the full path to the executable to run. This is useful if the `-CommandLine` executable path contains spaces and you wish to be explicit about what to run.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ArgumentEscaping</maml:name> <maml:description> <maml:para>The argument escaping mode to use when building the values of `-ArgumentList` to the single command line string. The default `Standard` will escape the argument list according to the C style rules where whitespace is fully enclosed as a double quoted string. The `Raw` rule will ignore all escaping and just appeach each argument with a space. The `Msi` rule will quote the argument `FOO=value with space` as `FOO="value with space"`.</maml:para> <maml:para>See ConvertTo-EscapedArgument (./ConvertTo-EscapedArgument.md)for more information.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ArgumentEscapingMode</command:parameterValue> <dev:type> <maml:name>ArgumentEscapingMode</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Standard</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ArgumentList</maml:name> <maml:description> <maml:para>A list of arguments to run with the `-FilePath`. These arguments are automatically escaped based on the Win32 C argument escaping rules as done by `ConvertTo-EscapedArgument`. The `-ArgumentEscaping` parameter can be used to change the escaping method from the C style to other ones. If you wish to provide arguments as a literal string without escaping use the `-CommandLine` option instead of this and `-FilePath`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CommandLine</maml:name> <maml:description> <maml:para>Used instead of `-FilePath` and `-ArgumentList` to run a new process with the literal string provided. This string is not escaped so you need to ensure it is valid for your use case. You can optionally specify `-ApplicationName` with this parameter to be more explicit about what executable to run.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="ConPTYY"> <maml:name>ConPTYHeight</maml:name> <maml:description> <maml:para>The ConPTY height to use when `-UseConPTY` is set. Defaults to `$host.UI.RawUI.BufferSize.Height` or `80` if no host is present.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int16</command:parameterValue> <dev:type> <maml:name>Int16</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="ConPTYX"> <maml:name>ConPTYWidth</maml:name> <maml:description> <maml:para>The ConPTY width to use when `-UseConPTY` is set. Defaults to `$host.UI.RawUI.BufferSize.Width` or `80` if no host is present.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int16</command:parameterValue> <dev:type> <maml:name>Int16</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>DisableInheritance</maml:name> <maml:description> <maml:para>Explicitly disable all the handles in the current process from being inherited with the new process. This cannot be used if `-StartupInfo` has an explicit StandardInput/Output/Error or InheritedHandles list.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Environment</maml:name> <maml:description> <maml:para>A dictionary containing explicit environment variables to use for the new process. These env vars will be used instead of the existing process environment variables if defined. Use `Get-TokenEnvironment` to generate a new environment block that can be modified as needed for the new process. Cannot be used with `-UseNewEnvironment`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">IDictionary</command:parameterValue> <dev:type> <maml:name>IDictionary</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="0" aliases="none"> <maml:name>FilePath</maml:name> <maml:description> <maml:para>The executable to start. Use with `-ArgumentList` to supply a list of argument to this executable.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>InputEncoding</maml:name> <maml:description> <maml:para>Sets the encoding used when writing the input strings to the input of the process. Will default to the value of `[Console]::InputEncoding` but can be set to an explicit `Encoding` type or one of the following string values:</maml:para> <maml:para>+ `ASCII` - The 7-bit ASCII encoding + `ANSI` - The current system locale encoding + `BigEndianUnicode` - UTF-16 in Big Endian form + `BigEndianUtf32` - UTF-32 in Big Endian form + `ConsoleInput` - The console input encoding - `[Console]::InputEncoding` (Default) + `ConsoleOutput` - The console output encoding - `[Console]::OutputEncoding` + `OEM` - Same as `ConsoleOutput` + `Unicode` - UTF-16 in Little Endian form + `UTF8` - UTF-8 without a BOM + `UTF8Bom` - UTF-8 with a BOM + `UTF8NoBom` - UTF-8 without a BOM + `UTF32` - UTF-32 in Little Endiam form</maml:para> <maml:para>Using any other string or integer value will call `[System.Text.Encoding]::GetEncoding($_)` to build the encoding object.</maml:para> <maml:para>Setting `-InputEncoding Bytes` does not work as the input must have an encoding to convert the input strings to bytes when writing. This parameter is ignored if `-UseConPTY` is specified as that always outputs as UTF-8.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">EncodingOrByteStream</command:parameterValue> <dev:type> <maml:name>EncodingOrByteStream</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>ConsoleInput</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The input objects to pipe into the process' stdin. Any `byte` or `byte[]` array values will be passed in directly. Any `string` or `string[]` values will be passed in as a line and encoded with the `-InputEncoding` parameter. Other object types will be casted to a string and handled as above.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>OutputEncoding</maml:name> <maml:description> <maml:para>Sets the encoding used when reading the output and error stream bytes. Will default to the value of `[Console]::OutputEncoding` but can be set to an explicit `Encoding` type or one of the following string values:</maml:para> <maml:para>+ `ASCII` - The 7-bit ASCII encoding + `ANSI` - The current system locale encoding + `BigEndianUnicode` - UTF-16 in Big Endian form + `BigEndianUtf32` - UTF-32 in Big Endian form + `Bytes` - Outputs as raw bytes and not a string + `ConsoleInput` - The console input encoding - `[Console]::InputEncoding` + `ConsoleOutput` - The console output encoding - `[Console]::OutputEncoding` (Default) + `OEM` - Same as `ConsoleOutput` + `Unicode` - UTF-16 in Little Endian form + `UTF8` - UTF-8 without a BOM + `UTF8Bom` - UTF-8 with a BOM + `UTF8NoBom` - UTF-8 without a BOM + `UTF32` - UTF-32 in Little Endiam form</maml:para> <maml:para>Using any other string or integer value will call `[System.Text.Encoding]::GetEncoding($_)` to build the encoding object.</maml:para> <maml:para>Setting `-OutputEncoding Bytes` will output the data as raw bytes rather than a string. Unless set to `Bytes`, this parameter is ignored if `-UseConPTY` is specified as that always outputs as UTF-8.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">EncodingOrByteStream</command:parameterValue> <dev:type> <maml:name>EncodingOrByteStream</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>ConsoleOutput</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Raw</maml:name> <maml:description> <maml:para>When set, will output as a single string rather than an array of strings representing each line. If `-OutputEncoding Bytes`, the output is emitted as a single `byte[]` rather than as individual bytes. This only applies to both the output (stdout) and error (stderr) stream .</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>RedirectStderr</maml:name> <maml:description> <maml:para>Redirect the stderr data to another location. Defaults to `Error` which is the PowerShell error stream. Set to `Output` to redirect stderr to the output stream as a string based on `-OutputEncoding`. Set to `Console` to skip capturing stderr together and write it directly to the console. Set to `Null` to discard all output on stderr.</maml:para> <maml:para>This option is ignored if `-UseConPTY` is set as there is no stderr anymore.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StdioStreamTarget</command:parameterValue> <dev:type> <maml:name>StdioStreamTarget</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Error</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>RedirectStdout</maml:name> <maml:description> <maml:para>Redirect the stdout data to another location. Defaults to `Output` which is the PowerShell output stream. Set to `Error` to redirect stdout to the error stream as an error record. Set to `Console` to skip capturing stdout together and write it directly to the console. Set to `Null` to discard all output on stdout.</maml:para> <maml:para>This option is ignored if `-UseConPTY` is set as there is no stdout anymore.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StdioStreamTarget</command:parameterValue> <dev:type> <maml:name>StdioStreamTarget</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Output</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartupInfo</maml:name> <maml:description> <maml:para>Specify custom startup information as returned by `New-StartupInfo`. It is not possible to use a custom `-StandardInput`, `-StandardOutput`, `-StandardError`, or `-ConPTY` in the startup info.</maml:para> <maml:para>If using a custom parent process, the invoked process will be spawned in a new console and will not inherit the existing one. Using `-RedirectStdout Console` or `-RedirectStderr Console` will not work if using a custom parent process.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StartupInfo</command:parameterValue> <dev:type> <maml:name>StartupInfo</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Token</maml:name> <maml:description> <maml:para>Create the process to run with the access token specified. This access token can be retrieved through other functions like `LogonUser`, duplicating from an existing process, etc. Using this parameter calls `CreateProcessAsUser` instead of `CreateProcess` which requires the `SeIncreaseQuotaPrivilege` privilege. It also requires the `SeAssignPrimaryTokenPrivilege` privilege if the token is not a restricted version of the callers primary token. The `SeAssignPrimaryTokenPrivilege` privilege is not given to administrators by default so check with `whoami.exe /priv` to see if your account has this privilege. The `Start-ProcessWith` cmdlet requires less sensitive privileges and can be used as an alternative to this cmdlet if needed.</maml:para> <maml:para>Be aware that this process will add the Logon Session SID of this token to the station and desktop security descriptor specified by Desktop on `-StartupInfo`. If no startup info was specified then the current station and desktop is used. Running this with multiple tokens could hit the maximum allowed size in a ACL if the station/desktop descriptor is not cleaned up.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle</command:parameterValue> <dev:type> <maml:name>SafeHandle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>UseConPTY</maml:name> <maml:description> <maml:para>Use a Console PTY instead of the standard stdin, stdout, and stderr streams. This replicates running a process in an actual console without any interaction and the output will reflect the data the executable will write to the console. The data will typically contain interactive elements like ANSI escape codes. The input and output encoding is always set to UTF-8 regardless of `-InputEncoding` and `-OutputEncoding` unless `-OutputEncoding Bytes` is specified. In that case the output will be the raw bytes from the output handle. When set `-RedirectStdout` and `-RedirectStderr` will do nothing.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>UseNewEnvironment</maml:name> <maml:description> <maml:para>Instead of inheriting the current process environment variables, use a brand new set of environment variables for the current user. Cannot be used with `-Environment`.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WorkingDirectory</maml:name> <maml:description> <maml:para>The working directory to set for the new process, defaults to the current filesystem location of the PowerShell process if not defined.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String[]</maml:name> </dev:type> <maml:description> <maml:para>The strings to write to the stdin of the new process. Each string will be appended with the value of `[Environment]::NewLine`. The encoding of each string is based on the value of `-InputEncoding`.</maml:para> </maml:description> </command:inputType> <command:inputType> <dev:type> <maml:name>System.Object</maml:name> </dev:type> <maml:description> <maml:para>If a `byte` or `byte[]`, this input object will be written as is to the stdin of the new process. All other objects will be casted to a string and written as a line to stdin.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> <maml:description> <maml:para>By default this cmdlet outputs the stdout lines as a string for each line. If `-OutputEncoding Bytes` is set, the output will instead be the bytes of stdout rather than a string. If `-Raw` is specified the output is a single string of the full stdout or a `byte[]` of the stdout if `-OutputEncoding Bytes` is set. There is no output if `-RedirectStdout` is set to `Console`, `Null`, or `Error`.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>This cmdlet is meant to expand on the functionality of calling a specific process.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>----- Example 1: Invokes a process and captures the output -----</maml:title> <dev:code>PS C:\> $out = Invoke-ProcessEx pwsh.exe '-Command' '"test"'</dev:code> <dev:remarks> <maml:para>Invokes `pwsh.exe -Command "test"` and captures the output into the `$out` var. The encoding used defaults to the `[Console]::OutputEncoding` encoding but can be configured with `-OutputEncoding`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>------ Example 2: Invokes a process and pipe data into it ------</maml:title> <dev:code>PS C:\> 'foo', 'bar' | Invoke-ProcessEx pwsh.exe '-Command' '$input'</dev:code> <dev:remarks> <maml:para>Runs the binary `pwsh.exe` and pipes in the strings `foo` and `bar` as lines. The command will just output it back but this shows how strings are piped into the new process.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>------- Example 3: Invoke binary data into a new process -------</maml:title> <dev:code>PS C:\> , (Get-Content -Path something.dll -AsByteStream -Raw) | Invoke-ProcessEx hexdump</dev:code> <dev:remarks> <maml:para>Pipes in raw bytes to the `hexdump` executable. These raw bytes are not subject to `-InputEncoding` and are written as is. The command that wraps `, (Get-Content ...)` is not needed but makes writing the input bytes simpler and more efficient. If running on PowerShell 5.1 change `-AsByteStream` to `-Encoding Bytes`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>------ Example 4: Run binary with custom output encoding ------</maml:title> <dev:code>PS C:\> Invoke-ProcessEx winget list -OutputEncoding UTF8</dev:code> <dev:remarks> <maml:para>Runs the command `winget list` and captures the raw output using the UTF-8 encoding rather than `[Console]::OutputEncoding`. This is useful when interacting with commands that write with a codepage that does not use the console codepage.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>------- Example 5: Redirect stderr to the output stream -------</maml:title> <dev:code># Writes hi to the output stream PS C:\> Invoke-ProcessEx cmd.exe /c 'echo hi 1>&2' -RedirectStderr Output # Also possible to achieve the same thing through pwsh redirection # Note the stderr objects will be an ErrorRecord in this case PS C:\> Invoke-ProcessEx cmd.exe /c 'echo hi 1>&2' 2>&1 # Writes hi as an ErrorRecord PS C:\> Invoke-ProcessEx cmd.exe /c 'echo hi 1>&2'</dev:code> <dev:remarks> <maml:para>The first command will redirect all stderr output to the output stream in PowerShell. These objects are treated as strings like normal stdout. The second command shows how stderr is normally written as an `ErrorRecord` in the error stream. It may be necessary to right `-ErrorAction Continue` so that the error being written does not stop the pipeline if `$ErrorActionPreference = 'Stop'` is set.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>------------- Example 6: Ignore stderr altogether -------------</maml:title> <dev:code>PS C:\> Invoke-ProcessEx cmd.exe /c 'echo stdout && echo stderr 1>&2' -RedirectStderr Null</dev:code> <dev:remarks> <maml:para>Ignores the all data written to the `stderr` stream and just capture the `stdout` data. The same thing can be achieved with `Invoke-ProcessEx cmd.exe /c 'echo stdout && echo stderr 1>&2' 2>$null` but it is more efficient to use `-RedirectStderr Null` so PowerShell does not have to process it.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>------ Example 7: Capture the raw output as a byte array ------</maml:title> <dev:code>PS C:\> Invoke-ProcessEx python '-c' 'print("café")' -OutputEncoding Bytes | Format-Hex # Label: Byte (System.Byte) <3B8382A2> # # Offset Bytes Ascii # 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F # ------ ----------------------------------------------- ----- # 0000000000000000 63 61 66 E9 0D 0A café�� # The above shows the encoding is not UTF-8 but the Windows locale encoding # So we can run the below to capture it properly PS C:\> Invoke-ProcessEx python '-c' 'print("café")' -OutputEncoding ANSI</dev:code> <dev:remarks> <maml:para>Outputs the raw bytes of stdout and pipes them into `Format-Hex` to see the raw data a process will output. This is useful for checking for encoding problems or just capturing raw bytes written by a process that isn't valid strings. Adding `-Raw` will output the data as a single `byte[]` at the end rather than individual bytes.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 8: Run a process with a ConPTY to get the exact console output</maml:title> <dev:code>PS C:\> Invoke-ProcessEx pwsh.exe '-Command' 'Get-Item $PSHome' -UseConPTY</dev:code> <dev:remarks> <maml:para>Runs the process with a Console PTY that allows the caller to act as a console server. This is used to capture and interact with a process as it would with a terminal. The output will most likely contain ANSI escape codes and other interact terminal features that is hard to parse non-interactively. Use `-UseConPTY` with caution as the process and the arguments given must explicitly close the process or else it will hang waiting for input that will never come.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Invoke-ProcessWith</command:name> <command:verb>Invoke</command:verb> <command:noun>ProcessWith</command:noun> <maml:description> <maml:para>Invoke a process inline and capture the output like the call operator with the ability to run as another user or token.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Invokes a process, waits for it to finish and returns the output back to PowerShell. This is like the builtin call operator `& whoami` but with a few more features.</maml:para> <maml:para>Some features it offers over the call operator are:</maml:para> <maml:para>+ It can capture the raw bytes of the stdout/stderr streams + You can control the encoding used to pipe strings into and decode out of the process through a parameter rather than a global value + You can capture the raw bytes of the process rather than decode it to a string + The command can either be run from a single command line string or escaped through an array of arguments + You can run it as another user through the `-Token` or `-Credential` parameter</maml:para> <maml:para>Some things that this cmdlet cannot do or is not designed for</maml:para> <maml:para>+ Starting an interactive process - the output can be set to a console but it is not the default + Dealing with env var changes between `pwsh.exe` and `powershell.exe`, use an explicit `-Environment` block to handle this better + Using the PowerShell minishell `powershell { ... }` does not work</maml:para> <maml:para>The cmdlet is also exposed through the `procwith` alias for easier interactive use.</maml:para> <maml:para>Like the normal call operator, when a process is complete, the `$LASTEXITCODE` variable will be set to the exit code of the process.</maml:para> <maml:para>By default the cmdlet is set to capture stdout lines in the output stream and stderr lines in the error stream. If `$ErrorActionPreference = 'Stop'` or `-ErrorAction Stop` is set on the cmdlet, any stderr lines will terminate the statement. Either explicitly set `-ErrorAction Continue` or use `-RedirectStderr` to something else to change this behaviour.</maml:para> <maml:para>Unlike Invoke-ProcessEx (./Invoke-ProcessEx.md), this cmdlet does not require special privileges that an Administrator user typically does not have. While it can be run by less privileged users some of the things this API cannot do over `Invoke-ProcessEx` are:</maml:para> <maml:para>+ The process is created in a new console window, it is not possible to redirect the stdout/stderr to the existing console directly + There is no way to run a process with a ConPTY, it must be redirected through the stdout/stderr pipes + Extended startup info elements like a parent process, inherited handles, job list is not supported + The Secondary Logon (`seclogon`) service must be running to call this API + The command line length is limited to a maximum of 1024 characters + It is not possible to disable inheritance of all inheritable handles in the current process</maml:para> <maml:para>Use Start-ProcessWith (./Start-ProcessWith.md)to invoke a process in the background.</maml:para> <maml:para>See Invoke-ProcessEx Examples (./Invoke-ProcessEx.md#examples)for some examples that also apply to `Invoke-ProcessWith`.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Invoke-ProcessWith</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ApplicationName</maml:name> <maml:description> <maml:para>Used with `-CommandLine` as the full path to the executable to run. This is useful if the `-CommandLine` executable path contains spaces and you wish to be explicit about what to run.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CommandLine</maml:name> <maml:description> <maml:para>Used instead of `-FilePath` and `-ArgumentList` to run a new process with the literal string provided. This string is not escaped so you need to ensure it is valid for your use case. You can optionally specify `-ApplicationName` with this parameter to be more explicit about what executable to run.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The user credentials to start the new process with. This will use the `CreateProcessWithLogon` API which logs on the user as an interactive logon or a NewCredential (network access change) logon when `-NetCredentialsOnly` is specified. This API can be called by non-admin accounts as it has no sensitive privilege requirements. Because the logon is an interactive logon, UAC restrictions will apply to the new process as it spawns as a limited user token. Use the `-Token` parameter after getting the linked token (requires admin rights) to bypass this UAC behaviour.</maml:para> <maml:para>When `-StartupInfo` specifies a custom station/desktop, the function will add the SID specified by the username to the station and desktop's security descriptor with `AllAccess`. When no startup info or Desktop is not set then the current station/desktop is used without any adjustments to their security descriptors.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Environment</maml:name> <maml:description> <maml:para>A dictionary containing explicit environment variables to use for the new process. These env vars will be used instead of the existing process environment variables if defined. Use `Get-TokenEnvironment` to generate a new environment block that can be modified as needed for the new process.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">IDictionary</command:parameterValue> <dev:type> <maml:name>IDictionary</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>InputEncoding</maml:name> <maml:description> <maml:para>Sets the encoding used when writing the input strings to the input of the process. Will default to the value of `[Console]::InputEncoding` but can be set to an explicit `Encoding` type or one of the following string values:</maml:para> <maml:para>+ `ASCII` - The 7-bit ASCII encoding + `ANSI` - The current system locale encoding + `BigEndianUnicode` - UTF-16 in Big Endian form + `BigEndianUtf32` - UTF-32 in Big Endian form + `ConsoleInput` - The console input encoding - `[Console]::InputEncoding` (Default) + `ConsoleOutput` - The console output encoding - `[Console]::OutputEncoding` + `OEM` - Same as `ConsoleOutput` + `Unicode` - UTF-16 in Little Endian form + `UTF8` - UTF-8 without a BOM + `UTF8Bom` - UTF-8 with a BOM + `UTF8NoBom` - UTF-8 without a BOM + `UTF32` - UTF-32 in Little Endiam form</maml:para> <maml:para>Using any other string or integer value will call `[System.Text.Encoding]::GetEncoding($_)` to build the encoding object.</maml:para> <maml:para>Setting `-InputEncoding Bytes` does not work as the input must have an encoding to convert the input strings to bytes when writing.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">EncodingOrByteStream</command:parameterValue> <dev:type> <maml:name>EncodingOrByteStream</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>ConsoleInput</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The input objects to pipe into the process' stdin. Any `byte` or `byte[]` array values will be passed in directly. Any `string` or `string[]` values will be passed in as a line and encoded with the `-InputEncoding` parameter. Other object types will be casted to a string and handled as above.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>NetCredentialsOnly</maml:name> <maml:description> <maml:para>The credential or token specified will only be used for any outbound authentication attempts, e.g. SMB file access, AD operations, etc. Any local actions will continue to use the callers access token. If using `-Credential`, the username must be in the UPN format `username@REALM.COM`.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>OutputEncoding</maml:name> <maml:description> <maml:para>Sets the encoding used when reading the output and error stream bytes. Will default to the value of `[Console]::OutputEncoding` but can be set to an explicit `Encoding` type or one of the following string values:</maml:para> <maml:para>+ `ASCII` - The 7-bit ASCII encoding + `ANSI` - The current system locale encoding + `BigEndianUnicode` - UTF-16 in Big Endian form + `BigEndianUtf32` - UTF-32 in Big Endian form + `Bytes` - Outputs as raw bytes and not a string + `ConsoleInput` - The console input encoding - `[Console]::InputEncoding` + `ConsoleOutput` - The console output encoding - `[Console]::OutputEncoding` (Default) + `OEM` - Same as `ConsoleOutput` + `Unicode` - UTF-16 in Little Endian form + `UTF8` - UTF-8 without a BOM + `UTF8Bom` - UTF-8 with a BOM + `UTF8NoBom` - UTF-8 without a BOM + `UTF32` - UTF-32 in Little Endiam form</maml:para> <maml:para>Using any other string or integer value will call `[System.Text.Encoding]::GetEncoding($_)` to build the encoding object.</maml:para> <maml:para>Setting `-OutputEncoding Bytes` will output the data as raw bytes rather than a string.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">EncodingOrByteStream</command:parameterValue> <dev:type> <maml:name>EncodingOrByteStream</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>ConsoleOutput</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Raw</maml:name> <maml:description> <maml:para>When set, will output as a single string rather than an array of strings representing each line. If `-OutputEncoding Bytes`, the output is emitted as a single `byte[]` rather than as individual bytes. This only applies to both the output (stdout) and error (stderr) stream .</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>RedirectStderr</maml:name> <maml:description> <maml:para>Redirect the stderr data to another location. Defaults to `Error` which is the PowerShell error stream. Set to `Output` to redirect stderr to the output stream as a string based on `-OutputEncoding`. Set to `Console` to skip capturing stderr together and write it directly to the console. Set to `Null` to discard all output on stderr.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Error</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Output</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Console</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Null</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">StdioStreamTarget</command:parameterValue> <dev:type> <maml:name>StdioStreamTarget</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Error</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>RedirectStdout</maml:name> <maml:description> <maml:para>Redirect the stdout data to another location. Defaults to `Output` which is the PowerShell output stream. Set to `Error` to redirect stdout to the error stream as an error record. Set to `Console` to skip capturing stdout together and write it directly to the console. Set to `Null` to discard all output on stdout.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Error</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Output</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Console</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Null</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">StdioStreamTarget</command:parameterValue> <dev:type> <maml:name>StdioStreamTarget</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Output</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartupInfo</maml:name> <maml:description> <maml:para>Specify custom startup information as returned by `New-StartupInfo`. It is not possible to use a custom `-StandardInput`, `-StandardOutput`, `-StandardError`, or `-ConPTY` in the startup info. The `Invoke-ProcessWith` cmdlet also explicitly sets `ShowWindow` to `Hide` when running ignoring any existing value set there.</maml:para> <maml:para>Certain startup info elemenents cannot be used by the `*With` process style cmdlets like `-ParentProcess`, `-InheritedHandle`, `-JobList`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StartupInfo</command:parameterValue> <dev:type> <maml:name>StartupInfo</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Token</maml:name> <maml:description> <maml:para>Creates the process to run with the specified access token instead of explicit credentials. This access token can be retrieved by using other APIs like `LogonUser` or by duplicating an existing access token of a running process. The token should have been opened with `Query`, `Duplicate`, and `AssignPrimary` rights. The `AdjustSessionId` and `AdjutDefault` access may also be required if using a token from another session, e.g. a `SYSTEM` token. This will use the `CreateProcessWithToken` API which requires the `SeImpersonatePrivilege` privileges usually held by administrators on the host.</maml:para> <maml:para>Be aware that this process will add the Logon Session SID of this token to the station and desktop security descriptor specified by Desktop on `-StartupInfo`. If no startup info was specified then the current station and desktop is used. Running this with multiple tokens could hit the maximum allowed size in a ACL if the station/desktop descriptor is not cleaned up.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle</command:parameterValue> <dev:type> <maml:name>SafeHandle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WithProfile</maml:name> <maml:description> <maml:para>Loads the user profile specified by the `-Credential` or `-Token`, including the `HKCU` registry hive.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WorkingDirectory</maml:name> <maml:description> <maml:para>The working directory to set for the new process, defaults to the current filesystem location of the PowerShell process if not defined.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Invoke-ProcessWith</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="0" aliases="none"> <maml:name>FilePath</maml:name> <maml:description> <maml:para>The executable to start. Use with `-ArgumentList` to supply a list of argument to this executable.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ArgumentEscaping</maml:name> <maml:description> <maml:para>The argument escaping mode to use when building the values of `-ArgumentList` to the single command line string. The default `Standard` will escape the argument list according to the C style rules where whitespace is fully enclosed as a double quoted string. The `Raw` rule will ignore all escaping and just appeach each argument with a space. The `Msi` rule will quote the argument `FOO=value with space` as `FOO="value with space"`.</maml:para> <maml:para>See ConvertTo-EscapedArgument (./ConvertTo-EscapedArgument.md)for more information.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Standard</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Raw</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Msi</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">ArgumentEscapingMode</command:parameterValue> <dev:type> <maml:name>ArgumentEscapingMode</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ArgumentList</maml:name> <maml:description> <maml:para>A list of arguments to run with the `-FilePath`. These arguments are automatically escaped based on the Win32 C argument escaping rules as done by `ConvertTo-EscapedArgument`. The `-ArgumentEscaping` parameter can be used to change the escaping method from the C style to other ones. If you wish to provide arguments as a literal string without escaping use the `-CommandLine` option instead of this and `-FilePath`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The user credentials to start the new process with. This will use the `CreateProcessWithLogon` API which logs on the user as an interactive logon or a NewCredential (network access change) logon when `-NetCredentialsOnly` is specified. This API can be called by non-admin accounts as it has no sensitive privilege requirements. Because the logon is an interactive logon, UAC restrictions will apply to the new process as it spawns as a limited user token. Use the `-Token` parameter after getting the linked token (requires admin rights) to bypass this UAC behaviour.</maml:para> <maml:para>When `-StartupInfo` specifies a custom station/desktop, the function will add the SID specified by the username to the station and desktop's security descriptor with `AllAccess`. When no startup info or Desktop is not set then the current station/desktop is used without any adjustments to their security descriptors.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Environment</maml:name> <maml:description> <maml:para>A dictionary containing explicit environment variables to use for the new process. These env vars will be used instead of the existing process environment variables if defined. Use `Get-TokenEnvironment` to generate a new environment block that can be modified as needed for the new process.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">IDictionary</command:parameterValue> <dev:type> <maml:name>IDictionary</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>InputEncoding</maml:name> <maml:description> <maml:para>Sets the encoding used when writing the input strings to the input of the process. Will default to the value of `[Console]::InputEncoding` but can be set to an explicit `Encoding` type or one of the following string values:</maml:para> <maml:para>+ `ASCII` - The 7-bit ASCII encoding + `ANSI` - The current system locale encoding + `BigEndianUnicode` - UTF-16 in Big Endian form + `BigEndianUtf32` - UTF-32 in Big Endian form + `ConsoleInput` - The console input encoding - `[Console]::InputEncoding` (Default) + `ConsoleOutput` - The console output encoding - `[Console]::OutputEncoding` + `OEM` - Same as `ConsoleOutput` + `Unicode` - UTF-16 in Little Endian form + `UTF8` - UTF-8 without a BOM + `UTF8Bom` - UTF-8 with a BOM + `UTF8NoBom` - UTF-8 without a BOM + `UTF32` - UTF-32 in Little Endiam form</maml:para> <maml:para>Using any other string or integer value will call `[System.Text.Encoding]::GetEncoding($_)` to build the encoding object.</maml:para> <maml:para>Setting `-InputEncoding Bytes` does not work as the input must have an encoding to convert the input strings to bytes when writing.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">EncodingOrByteStream</command:parameterValue> <dev:type> <maml:name>EncodingOrByteStream</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>ConsoleInput</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The input objects to pipe into the process' stdin. Any `byte` or `byte[]` array values will be passed in directly. Any `string` or `string[]` values will be passed in as a line and encoded with the `-InputEncoding` parameter. Other object types will be casted to a string and handled as above.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>NetCredentialsOnly</maml:name> <maml:description> <maml:para>The credential or token specified will only be used for any outbound authentication attempts, e.g. SMB file access, AD operations, etc. Any local actions will continue to use the callers access token. If using `-Credential`, the username must be in the UPN format `username@REALM.COM`.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>OutputEncoding</maml:name> <maml:description> <maml:para>Sets the encoding used when reading the output and error stream bytes. Will default to the value of `[Console]::OutputEncoding` but can be set to an explicit `Encoding` type or one of the following string values:</maml:para> <maml:para>+ `ASCII` - The 7-bit ASCII encoding + `ANSI` - The current system locale encoding + `BigEndianUnicode` - UTF-16 in Big Endian form + `BigEndianUtf32` - UTF-32 in Big Endian form + `Bytes` - Outputs as raw bytes and not a string + `ConsoleInput` - The console input encoding - `[Console]::InputEncoding` + `ConsoleOutput` - The console output encoding - `[Console]::OutputEncoding` (Default) + `OEM` - Same as `ConsoleOutput` + `Unicode` - UTF-16 in Little Endian form + `UTF8` - UTF-8 without a BOM + `UTF8Bom` - UTF-8 with a BOM + `UTF8NoBom` - UTF-8 without a BOM + `UTF32` - UTF-32 in Little Endiam form</maml:para> <maml:para>Using any other string or integer value will call `[System.Text.Encoding]::GetEncoding($_)` to build the encoding object.</maml:para> <maml:para>Setting `-OutputEncoding Bytes` will output the data as raw bytes rather than a string.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">EncodingOrByteStream</command:parameterValue> <dev:type> <maml:name>EncodingOrByteStream</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>ConsoleOutput</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Raw</maml:name> <maml:description> <maml:para>When set, will output as a single string rather than an array of strings representing each line. If `-OutputEncoding Bytes`, the output is emitted as a single `byte[]` rather than as individual bytes. This only applies to both the output (stdout) and error (stderr) stream .</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>RedirectStderr</maml:name> <maml:description> <maml:para>Redirect the stderr data to another location. Defaults to `Error` which is the PowerShell error stream. Set to `Output` to redirect stderr to the output stream as a string based on `-OutputEncoding`. Set to `Console` to skip capturing stderr together and write it directly to the console. Set to `Null` to discard all output on stderr.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Error</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Output</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Console</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Null</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">StdioStreamTarget</command:parameterValue> <dev:type> <maml:name>StdioStreamTarget</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Error</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>RedirectStdout</maml:name> <maml:description> <maml:para>Redirect the stdout data to another location. Defaults to `Output` which is the PowerShell output stream. Set to `Error` to redirect stdout to the error stream as an error record. Set to `Console` to skip capturing stdout together and write it directly to the console. Set to `Null` to discard all output on stdout.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">Error</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Output</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Console</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Null</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">StdioStreamTarget</command:parameterValue> <dev:type> <maml:name>StdioStreamTarget</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Output</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartupInfo</maml:name> <maml:description> <maml:para>Specify custom startup information as returned by `New-StartupInfo`. It is not possible to use a custom `-StandardInput`, `-StandardOutput`, `-StandardError`, or `-ConPTY` in the startup info. The `Invoke-ProcessWith` cmdlet also explicitly sets `ShowWindow` to `Hide` when running ignoring any existing value set there.</maml:para> <maml:para>Certain startup info elemenents cannot be used by the `*With` process style cmdlets like `-ParentProcess`, `-InheritedHandle`, `-JobList`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StartupInfo</command:parameterValue> <dev:type> <maml:name>StartupInfo</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Token</maml:name> <maml:description> <maml:para>Creates the process to run with the specified access token instead of explicit credentials. This access token can be retrieved by using other APIs like `LogonUser` or by duplicating an existing access token of a running process. The token should have been opened with `Query`, `Duplicate`, and `AssignPrimary` rights. The `AdjustSessionId` and `AdjutDefault` access may also be required if using a token from another session, e.g. a `SYSTEM` token. This will use the `CreateProcessWithToken` API which requires the `SeImpersonatePrivilege` privileges usually held by administrators on the host.</maml:para> <maml:para>Be aware that this process will add the Logon Session SID of this token to the station and desktop security descriptor specified by Desktop on `-StartupInfo`. If no startup info was specified then the current station and desktop is used. Running this with multiple tokens could hit the maximum allowed size in a ACL if the station/desktop descriptor is not cleaned up.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle</command:parameterValue> <dev:type> <maml:name>SafeHandle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WithProfile</maml:name> <maml:description> <maml:para>Loads the user profile specified by the `-Credential` or `-Token`, including the `HKCU` registry hive.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WorkingDirectory</maml:name> <maml:description> <maml:para>The working directory to set for the new process, defaults to the current filesystem location of the PowerShell process if not defined.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ApplicationName</maml:name> <maml:description> <maml:para>Used with `-CommandLine` as the full path to the executable to run. This is useful if the `-CommandLine` executable path contains spaces and you wish to be explicit about what to run.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ArgumentEscaping</maml:name> <maml:description> <maml:para>The argument escaping mode to use when building the values of `-ArgumentList` to the single command line string. The default `Standard` will escape the argument list according to the C style rules where whitespace is fully enclosed as a double quoted string. The `Raw` rule will ignore all escaping and just appeach each argument with a space. The `Msi` rule will quote the argument `FOO=value with space` as `FOO="value with space"`.</maml:para> <maml:para>See ConvertTo-EscapedArgument (./ConvertTo-EscapedArgument.md)for more information.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ArgumentEscapingMode</command:parameterValue> <dev:type> <maml:name>ArgumentEscapingMode</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ArgumentList</maml:name> <maml:description> <maml:para>A list of arguments to run with the `-FilePath`. These arguments are automatically escaped based on the Win32 C argument escaping rules as done by `ConvertTo-EscapedArgument`. The `-ArgumentEscaping` parameter can be used to change the escaping method from the C style to other ones. If you wish to provide arguments as a literal string without escaping use the `-CommandLine` option instead of this and `-FilePath`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CommandLine</maml:name> <maml:description> <maml:para>Used instead of `-FilePath` and `-ArgumentList` to run a new process with the literal string provided. This string is not escaped so you need to ensure it is valid for your use case. You can optionally specify `-ApplicationName` with this parameter to be more explicit about what executable to run.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The user credentials to start the new process with. This will use the `CreateProcessWithLogon` API which logs on the user as an interactive logon or a NewCredential (network access change) logon when `-NetCredentialsOnly` is specified. This API can be called by non-admin accounts as it has no sensitive privilege requirements. Because the logon is an interactive logon, UAC restrictions will apply to the new process as it spawns as a limited user token. Use the `-Token` parameter after getting the linked token (requires admin rights) to bypass this UAC behaviour.</maml:para> <maml:para>When `-StartupInfo` specifies a custom station/desktop, the function will add the SID specified by the username to the station and desktop's security descriptor with `AllAccess`. When no startup info or Desktop is not set then the current station/desktop is used without any adjustments to their security descriptors.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Environment</maml:name> <maml:description> <maml:para>A dictionary containing explicit environment variables to use for the new process. These env vars will be used instead of the existing process environment variables if defined. Use `Get-TokenEnvironment` to generate a new environment block that can be modified as needed for the new process.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">IDictionary</command:parameterValue> <dev:type> <maml:name>IDictionary</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="0" aliases="none"> <maml:name>FilePath</maml:name> <maml:description> <maml:para>The executable to start. Use with `-ArgumentList` to supply a list of argument to this executable.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>InputEncoding</maml:name> <maml:description> <maml:para>Sets the encoding used when writing the input strings to the input of the process. Will default to the value of `[Console]::InputEncoding` but can be set to an explicit `Encoding` type or one of the following string values:</maml:para> <maml:para>+ `ASCII` - The 7-bit ASCII encoding + `ANSI` - The current system locale encoding + `BigEndianUnicode` - UTF-16 in Big Endian form + `BigEndianUtf32` - UTF-32 in Big Endian form + `ConsoleInput` - The console input encoding - `[Console]::InputEncoding` (Default) + `ConsoleOutput` - The console output encoding - `[Console]::OutputEncoding` + `OEM` - Same as `ConsoleOutput` + `Unicode` - UTF-16 in Little Endian form + `UTF8` - UTF-8 without a BOM + `UTF8Bom` - UTF-8 with a BOM + `UTF8NoBom` - UTF-8 without a BOM + `UTF32` - UTF-32 in Little Endiam form</maml:para> <maml:para>Using any other string or integer value will call `[System.Text.Encoding]::GetEncoding($_)` to build the encoding object.</maml:para> <maml:para>Setting `-InputEncoding Bytes` does not work as the input must have an encoding to convert the input strings to bytes when writing.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">EncodingOrByteStream</command:parameterValue> <dev:type> <maml:name>EncodingOrByteStream</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>ConsoleInput</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>InputObject</maml:name> <maml:description> <maml:para>The input objects to pipe into the process' stdin. Any `byte` or `byte[]` array values will be passed in directly. Any `string` or `string[]` values will be passed in as a line and encoded with the `-InputEncoding` parameter. Other object types will be casted to a string and handled as above.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Object</command:parameterValue> <dev:type> <maml:name>Object</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>NetCredentialsOnly</maml:name> <maml:description> <maml:para>The credential or token specified will only be used for any outbound authentication attempts, e.g. SMB file access, AD operations, etc. Any local actions will continue to use the callers access token. If using `-Credential`, the username must be in the UPN format `username@REALM.COM`.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>OutputEncoding</maml:name> <maml:description> <maml:para>Sets the encoding used when reading the output and error stream bytes. Will default to the value of `[Console]::OutputEncoding` but can be set to an explicit `Encoding` type or one of the following string values:</maml:para> <maml:para>+ `ASCII` - The 7-bit ASCII encoding + `ANSI` - The current system locale encoding + `BigEndianUnicode` - UTF-16 in Big Endian form + `BigEndianUtf32` - UTF-32 in Big Endian form + `Bytes` - Outputs as raw bytes and not a string + `ConsoleInput` - The console input encoding - `[Console]::InputEncoding` + `ConsoleOutput` - The console output encoding - `[Console]::OutputEncoding` (Default) + `OEM` - Same as `ConsoleOutput` + `Unicode` - UTF-16 in Little Endian form + `UTF8` - UTF-8 without a BOM + `UTF8Bom` - UTF-8 with a BOM + `UTF8NoBom` - UTF-8 without a BOM + `UTF32` - UTF-32 in Little Endiam form</maml:para> <maml:para>Using any other string or integer value will call `[System.Text.Encoding]::GetEncoding($_)` to build the encoding object.</maml:para> <maml:para>Setting `-OutputEncoding Bytes` will output the data as raw bytes rather than a string.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">EncodingOrByteStream</command:parameterValue> <dev:type> <maml:name>EncodingOrByteStream</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>ConsoleOutput</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Raw</maml:name> <maml:description> <maml:para>When set, will output as a single string rather than an array of strings representing each line. If `-OutputEncoding Bytes`, the output is emitted as a single `byte[]` rather than as individual bytes. This only applies to both the output (stdout) and error (stderr) stream .</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>RedirectStderr</maml:name> <maml:description> <maml:para>Redirect the stderr data to another location. Defaults to `Error` which is the PowerShell error stream. Set to `Output` to redirect stderr to the output stream as a string based on `-OutputEncoding`. Set to `Console` to skip capturing stderr together and write it directly to the console. Set to `Null` to discard all output on stderr.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StdioStreamTarget</command:parameterValue> <dev:type> <maml:name>StdioStreamTarget</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Error</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>RedirectStdout</maml:name> <maml:description> <maml:para>Redirect the stdout data to another location. Defaults to `Output` which is the PowerShell output stream. Set to `Error` to redirect stdout to the error stream as an error record. Set to `Console` to skip capturing stdout together and write it directly to the console. Set to `Null` to discard all output on stdout.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StdioStreamTarget</command:parameterValue> <dev:type> <maml:name>StdioStreamTarget</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>Output</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartupInfo</maml:name> <maml:description> <maml:para>Specify custom startup information as returned by `New-StartupInfo`. It is not possible to use a custom `-StandardInput`, `-StandardOutput`, `-StandardError`, or `-ConPTY` in the startup info. The `Invoke-ProcessWith` cmdlet also explicitly sets `ShowWindow` to `Hide` when running ignoring any existing value set there.</maml:para> <maml:para>Certain startup info elemenents cannot be used by the `*With` process style cmdlets like `-ParentProcess`, `-InheritedHandle`, `-JobList`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StartupInfo</command:parameterValue> <dev:type> <maml:name>StartupInfo</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Token</maml:name> <maml:description> <maml:para>Creates the process to run with the specified access token instead of explicit credentials. This access token can be retrieved by using other APIs like `LogonUser` or by duplicating an existing access token of a running process. The token should have been opened with `Query`, `Duplicate`, and `AssignPrimary` rights. The `AdjustSessionId` and `AdjutDefault` access may also be required if using a token from another session, e.g. a `SYSTEM` token. This will use the `CreateProcessWithToken` API which requires the `SeImpersonatePrivilege` privileges usually held by administrators on the host.</maml:para> <maml:para>Be aware that this process will add the Logon Session SID of this token to the station and desktop security descriptor specified by Desktop on `-StartupInfo`. If no startup info was specified then the current station and desktop is used. Running this with multiple tokens could hit the maximum allowed size in a ACL if the station/desktop descriptor is not cleaned up.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle</command:parameterValue> <dev:type> <maml:name>SafeHandle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WithProfile</maml:name> <maml:description> <maml:para>Loads the user profile specified by the `-Credential` or `-Token`, including the `HKCU` registry hive.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WorkingDirectory</maml:name> <maml:description> <maml:para>The working directory to set for the new process, defaults to the current filesystem location of the PowerShell process if not defined.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.String[]</maml:name> </dev:type> <maml:description> <maml:para>The strings to write to the stdin of the new process. Each string will be appended with the value of `[Environment]::NewLine`. The encoding of each string is based on the value of `-InputEncoding`.</maml:para> </maml:description> </command:inputType> <command:inputType> <dev:type> <maml:name>System.Object</maml:name> </dev:type> <maml:description> <maml:para>If a `byte` or `byte[]`, this input object will be written as is to the stdin of the new process. All other objects will be casted to a string and written as a line to stdin.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.String</maml:name> </dev:type> <maml:description> <maml:para>By default this cmdlet outputs the stdout lines as a string for each line. If `-OutputEncoding Bytes` is set, the output will instead be the bytes of stdout rather than a string. If `-Raw` is specified the output is a single string of the full stdout or a `byte[]` of the stdout if `-OutputEncoding Bytes` is set. There is no output if `-RedirectStdout` is set to `Console`, `Null`, or `Error`.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>This cmdlet is meant to expand on the functionality of calling a specific process.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- Example 1 --------------------------</maml:title> <dev:code>PS C:\> $cred = Get-Credential PS C:\> $out = Invoke-ProcessWith whoami -Credential $cred</dev:code> <dev:remarks> <maml:para>Invokes `whoami` but as the user supplied by the `-Credential` value.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-ConPTY</command:name> <command:verb>New</command:verb> <command:noun>ConPTY</command:noun> <maml:description> <maml:para>Create a new pseudo console object.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Create a new psuedo console object that can be used to read/write data to a child process.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-ConPTY</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="0" aliases="X"> <maml:name>Width</maml:name> <maml:description> <maml:para>The number of vertical characters of the new buffer.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int16</command:parameterValue> <dev:type> <maml:name>Int16</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="1" aliases="Y"> <maml:name>Height</maml:name> <maml:description> <maml:para>The number of horizontal characters of the new buffer.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int16</command:parameterValue> <dev:type> <maml:name>Int16</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="none"> <maml:name>InputPipe</maml:name> <maml:description> <maml:para>A readable file or pipe handle that represents data to write as the input to the buffer. The input bytes should be representable as a UTF-8 encoded string.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle</command:parameterValue> <dev:type> <maml:name>SafeHandle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="3" aliases="none"> <maml:name>OutputPipe</maml:name> <maml:description> <maml:para>A writable file or pipe handle that represents data to read as the output of the buffer. The bytes should be representable as a UTF-8 encoded string.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle</command:parameterValue> <dev:type> <maml:name>SafeHandle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>InheritCursor</maml:name> <maml:description> <maml:para>The created ConPTY session will attempt to inherit the cursor position of the parent console.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="1" aliases="Y"> <maml:name>Height</maml:name> <maml:description> <maml:para>The number of horizontal characters of the new buffer.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int16</command:parameterValue> <dev:type> <maml:name>Int16</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>InheritCursor</maml:name> <maml:description> <maml:para>The created ConPTY session will attempt to inherit the cursor position of the parent console.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="2" aliases="none"> <maml:name>InputPipe</maml:name> <maml:description> <maml:para>A readable file or pipe handle that represents data to write as the input to the buffer. The input bytes should be representable as a UTF-8 encoded string.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle</command:parameterValue> <dev:type> <maml:name>SafeHandle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="3" aliases="none"> <maml:name>OutputPipe</maml:name> <maml:description> <maml:para>A writable file or pipe handle that represents data to read as the output of the buffer. The bytes should be representable as a UTF-8 encoded string.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle</command:parameterValue> <dev:type> <maml:name>SafeHandle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="0" aliases="X"> <maml:name>Width</maml:name> <maml:description> <maml:para>The number of vertical characters of the new buffer.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int16</command:parameterValue> <dev:type> <maml:name>Int16</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Int16</maml:name> </dev:type> <maml:description> <maml:para>The `Width` and `Height` as pipeline input by property name.</maml:para> </maml:description> </command:inputType> <command:inputType> <dev:type> <maml:name>System.Runtime.InteropServices.SafeHandle</maml:name> </dev:type> <maml:description> <maml:para>The `InputPipe` and `OutputPipe` as pipeline input by property name.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>ProcessEx.Native.SafeConsoleHandle</maml:name> </dev:type> <maml:description> <maml:para>The `SafeConsoleHandle` representing the ConPTY. This should be disposed with `.Dispose()` when it is no longer needed to free up host resources.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>The ConPTY is a new concept introduced in Windows 10 1809 build. It is meant to provide an easy server side console API that applications can use to host console applications like a terminal.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>----------- Example 1: Create ConPTY backed by files -----------</maml:title> <dev:code>PS C:\> $inputStream = [IO.FileStream]::Open('C:\temp\input', 'Open', >> 'Read', 'ReadWrite') PS C:\> $outputStream = [IO.FileStream]::Open('C:\temp\output', 'Create', >> 'Write', 'ReadWrite') PS C:\> $conPTYParams = @{ >> Width = 80 >> Height = 60 >> InputPipe = $inputStream.SafeFileHandle >> OutputPipe = $outputStream.SafeFileHandle >> } PS C:\> $conPTY = New-ConPty @conPTYParams PS C:\> $conPTY.Dispose() # Should be disposed when finished.</dev:code> <dev:remarks> <maml:para>Create a ConPTY that will pipe data from `C:\temp\input` into the ConPTY and write data from the ConPTY to `C:\temp\output`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>------ Example 2: Create ConPTY backed by anonymous pipes ------</maml:title> <dev:code>PS C:\> $inputPipe = [System.IO.Pipes.AnonymousPipeServerStream]::new("Out", "Inheritable") PS C:\> $outputPipe = [System.IO.Pipes.AnonymousPipeServerStream]::new("In", "Inheritable") PS C:\> $conPTYParams = @{ >> Width = 80 >> Height = 60 >> InputPipe = $inputPipe.ClientSafePipeHandle >> OutputPipe = $outputPipe.ClientSafePipeHandle >> } PS C:\> $pty = New-ConPTY @conPTYParams PS C:\> try { >> $inputPipe.ClientSafePipeHandle.Dispose() >> $outputPipe.ClientSafePipeHandle.Dispose() >> $si = New-StartupInfo -ConPTY $pty >> $proc = Start-ProcessEx powershell -StartupInfo $si -PassThru >> } >> finally { >> $pty.Dispose() >> }</dev:code> <dev:remarks> <maml:para>Create a ConPTY that will transmit data to and from an anonymous pipe created by the caller. The caller can then read and write data on the server ends of the pipe to communicate with the child process.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Introducing the Windows Pseudo Console (ConPTY)</maml:linkText> <maml:uri>https://devblogs.microsoft.com/commandline/windows-command-line-introducing-the-windows-pseudo-console-conpty/</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>CreatePseudoConsole</maml:linkText> <maml:uri>https://docs.microsoft.com/en-us/windows/console/createpseudoconsole</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>New-StartupInfo</command:name> <command:verb>New</command:verb> <command:noun>StartupInfo</command:noun> <maml:description> <maml:para>Create a StartupInfo object for creating a process.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Create the StartupInfo object that defines the low level details used to create a process.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-StartupInfo</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ConPTY</maml:name> <maml:description> <maml:para>The pseudo console handle that represents the console input and output pipelines. Use `New-ConsolePTY` to create this handle. This cannot be set alongside the StandardInput/Output/Error parameters. This will not work with `-ParentProcess` as there is no way to open the ConPTY in the parent process for inheritance. This will not work with `Start-ProcessWith` due to the restrictions in the underlying APIs it calls.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle</command:parameterValue> <dev:type> <maml:name>SafeHandle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CountChars</maml:name> <maml:description> <maml:para>Size of the console screen buffer.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Size</command:parameterValue> <dev:type> <maml:name>Size</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Desktop</maml:name> <maml:description> <maml:para>The name of the Windows Desktop or both the Windows Desktop and Station (`station\desktop`) for the new process. If not set then it defaults to the current station and desktop. Spawning a process on another station is not thread safe as the process of granting rights to the user must swap the current process station to the target one to access the desktop specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>FillAttribute</maml:name> <maml:description> <maml:para>Used to control the color of the background and foreground of the new console process.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ConsoleFill</command:parameterValue> <dev:type> <maml:name>ConsoleFill</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Flags</maml:name> <maml:description> <maml:para>Flags to set for the new process. Some flags are always set when other startup info parameters are specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StartupInfoFlags</command:parameterValue> <dev:type> <maml:name>StartupInfoFlags</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>InheritedHandle</maml:name> <maml:description> <maml:para>A list of handles to explicit allow the new process to inherit from. If omitted then the child will inherit all the parent process' handles that were opened with inheritability if the process was created with inheritability. When `-ParentProcess` is not set, all these handles will be changed to an inheritable handle in the current process. When `-ParentProcess` is set then these handles need to be a valid handle in the parent process itself. Use `Copy-HandleToProcess` with `-Inherit` and `-OwnHandle` to open them in the parent process for it to be a valid handle for inheritance by the new process. Not having an inherited handle in the parent process will cause a failure when trying to start the process. This will not work with `Start-ProcessWith` due to the restrictions in the underlying APIs it calls.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle[]</command:parameterValue> <dev:type> <maml:name>SafeHandle[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>JobList</maml:name> <maml:description> <maml:para>A list of job handles to be assigned to the child process. If omitted then the child will be assigned the job of the calling process if it is part of any job. This requires Windows 10, Server 2016, or newer to be used. This will not work with `Start-ProcessWith` due to the restrictions in the underlying APIs it calls.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle[]</command:parameterValue> <dev:type> <maml:name>SafeHandle[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ParentProcess</maml:name> <maml:description> <maml:para>The parent process to create this as a child for. If the parent process is running under a different user or a different elevation context of the current user then this will fail unless you are running as SYSTEM. This will not work with `Start-ProcessWith` due to the restrictions in the underlying APIs it calls.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ProcessIntString</command:parameterValue> <dev:type> <maml:name>ProcessIntString</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Position</maml:name> <maml:description> <maml:para>The window position with X being the horizontal offset and Y being the vertical offset from the top left corner of the screen.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Coordinates</command:parameterValue> <dev:type> <maml:name>Coordinates</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Reserved</maml:name> <maml:description> <maml:para>This parameter refers to the string `lpReserved` field in the `STARTUPINFO` structure used to create a process. It is unused and undocumented in Windows.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Reserved2</maml:name> <maml:description> <maml:para>This parameter refers to the byte `lpReserved2` field and `cbReserved2` in the `STARTUPINFO` structure. This is unused and undocumented but has some used for sneaking data into a process.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Byte[]</command:parameterValue> <dev:type> <maml:name>Byte[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Title</maml:name> <maml:description> <maml:para>This does not apply to GUI processes and console processes created in the same console. For a new console process created with a new console window this is the title to display in the title bar and if not set the executable path is used.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WindowSize</maml:name> <maml:description> <maml:para>The size of the window to create.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Size</command:parameterValue> <dev:type> <maml:name>Size</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WindowStyle</maml:name> <maml:description> <maml:para>The window style of the new process.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">WindowStyle</command:parameterValue> <dev:type> <maml:name>WindowStyle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>New-StartupInfo</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CountChars</maml:name> <maml:description> <maml:para>Size of the console screen buffer.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Size</command:parameterValue> <dev:type> <maml:name>Size</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Desktop</maml:name> <maml:description> <maml:para>The name of the Windows Desktop or both the Windows Desktop and Station (`station\desktop`) for the new process. If not set then it defaults to the current station and desktop. Spawning a process on another station is not thread safe as the process of granting rights to the user must swap the current process station to the target one to access the desktop specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>FillAttribute</maml:name> <maml:description> <maml:para>Used to control the color of the background and foreground of the new console process.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ConsoleFill</command:parameterValue> <dev:type> <maml:name>ConsoleFill</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Flags</maml:name> <maml:description> <maml:para>Flags to set for the new process. Some flags are always set when other startup info parameters are specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StartupInfoFlags</command:parameterValue> <dev:type> <maml:name>StartupInfoFlags</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>InheritedHandle</maml:name> <maml:description> <maml:para>A list of handles to explicit allow the new process to inherit from. If omitted then the child will inherit all the parent process' handles that were opened with inheritability if the process was created with inheritability. When `-ParentProcess` is not set, all these handles will be changed to an inheritable handle in the current process. When `-ParentProcess` is set then these handles need to be a valid handle in the parent process itself. Use `Copy-HandleToProcess` with `-Inherit` and `-OwnHandle` to open them in the parent process for it to be a valid handle for inheritance by the new process. Not having an inherited handle in the parent process will cause a failure when trying to start the process. This will not work with `Start-ProcessWith` due to the restrictions in the underlying APIs it calls.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle[]</command:parameterValue> <dev:type> <maml:name>SafeHandle[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>JobList</maml:name> <maml:description> <maml:para>A list of job handles to be assigned to the child process. If omitted then the child will be assigned the job of the calling process if it is part of any job. This requires Windows 10, Server 2016, or newer to be used. This will not work with `Start-ProcessWith` due to the restrictions in the underlying APIs it calls.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle[]</command:parameterValue> <dev:type> <maml:name>SafeHandle[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ParentProcess</maml:name> <maml:description> <maml:para>The parent process to create this as a child for. If the parent process is running under a different user or a different elevation context of the current user then this will fail unless you are running as SYSTEM. This will not work with `Start-ProcessWith` due to the restrictions in the underlying APIs it calls.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ProcessIntString</command:parameterValue> <dev:type> <maml:name>ProcessIntString</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Position</maml:name> <maml:description> <maml:para>The window position with X being the horizontal offset and Y being the vertical offset from the top left corner of the screen.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Coordinates</command:parameterValue> <dev:type> <maml:name>Coordinates</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Reserved</maml:name> <maml:description> <maml:para>This parameter refers to the string `lpReserved` field in the `STARTUPINFO` structure used to create a process. It is unused and undocumented in Windows.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Reserved2</maml:name> <maml:description> <maml:para>This parameter refers to the byte `lpReserved2` field and `cbReserved2` in the `STARTUPINFO` structure. This is unused and undocumented but has some used for sneaking data into a process.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Byte[]</command:parameterValue> <dev:type> <maml:name>Byte[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StandardError</maml:name> <maml:description> <maml:para>A writable SafeHandle that is set to the new process' stderr pipe. This handle will be explicitly set as inheritable process wide even if it wasn't opened as an inheritable object. This cannot be used with `-DisableInheritance` on `Start-ProcessEx`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle</command:parameterValue> <dev:type> <maml:name>SafeHandle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StandardInput</maml:name> <maml:description> <maml:para>A readable SafeHandle that is set to the new process' stdin pipe. This handle will be explicitly set as inheritable process wide even if it wasn't opened as an inheritable object. This cannot be used with with `-DisableInheritance` on `Start-ProcessEx`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle</command:parameterValue> <dev:type> <maml:name>SafeHandle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StandardOutput</maml:name> <maml:description> <maml:para>A writable SafeHandle that is set to the new process' stdout pipe. This handle will be explicitly set as inheritable process wide even if it wasn't opened as an inheritable object. This cannot be used with `-DisableInheritance` on `Start-ProcessEx`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle</command:parameterValue> <dev:type> <maml:name>SafeHandle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Title</maml:name> <maml:description> <maml:para>This does not apply to GUI processes and console processes created in the same console. For a new console process created with a new console window this is the title to display in the title bar and if not set the executable path is used.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WindowSize</maml:name> <maml:description> <maml:para>The size of the window to create.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Size</command:parameterValue> <dev:type> <maml:name>Size</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WindowStyle</maml:name> <maml:description> <maml:para>The window style of the new process.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">WindowStyle</command:parameterValue> <dev:type> <maml:name>WindowStyle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ConPTY</maml:name> <maml:description> <maml:para>The pseudo console handle that represents the console input and output pipelines. Use `New-ConsolePTY` to create this handle. This cannot be set alongside the StandardInput/Output/Error parameters. This will not work with `-ParentProcess` as there is no way to open the ConPTY in the parent process for inheritance. This will not work with `Start-ProcessWith` due to the restrictions in the underlying APIs it calls.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle</command:parameterValue> <dev:type> <maml:name>SafeHandle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CountChars</maml:name> <maml:description> <maml:para>Size of the console screen buffer.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Size</command:parameterValue> <dev:type> <maml:name>Size</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Desktop</maml:name> <maml:description> <maml:para>The name of the Windows Desktop or both the Windows Desktop and Station (`station\desktop`) for the new process. If not set then it defaults to the current station and desktop. Spawning a process on another station is not thread safe as the process of granting rights to the user must swap the current process station to the target one to access the desktop specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>FillAttribute</maml:name> <maml:description> <maml:para>Used to control the color of the background and foreground of the new console process.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ConsoleFill</command:parameterValue> <dev:type> <maml:name>ConsoleFill</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Flags</maml:name> <maml:description> <maml:para>Flags to set for the new process. Some flags are always set when other startup info parameters are specified.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StartupInfoFlags</command:parameterValue> <dev:type> <maml:name>StartupInfoFlags</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>InheritedHandle</maml:name> <maml:description> <maml:para>A list of handles to explicit allow the new process to inherit from. If omitted then the child will inherit all the parent process' handles that were opened with inheritability if the process was created with inheritability. When `-ParentProcess` is not set, all these handles will be changed to an inheritable handle in the current process. When `-ParentProcess` is set then these handles need to be a valid handle in the parent process itself. Use `Copy-HandleToProcess` with `-Inherit` and `-OwnHandle` to open them in the parent process for it to be a valid handle for inheritance by the new process. Not having an inherited handle in the parent process will cause a failure when trying to start the process. This will not work with `Start-ProcessWith` due to the restrictions in the underlying APIs it calls.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle[]</command:parameterValue> <dev:type> <maml:name>SafeHandle[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>JobList</maml:name> <maml:description> <maml:para>A list of job handles to be assigned to the child process. If omitted then the child will be assigned the job of the calling process if it is part of any job. This requires Windows 10, Server 2016, or newer to be used. This will not work with `Start-ProcessWith` due to the restrictions in the underlying APIs it calls.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle[]</command:parameterValue> <dev:type> <maml:name>SafeHandle[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ParentProcess</maml:name> <maml:description> <maml:para>The parent process to create this as a child for. If the parent process is running under a different user or a different elevation context of the current user then this will fail unless you are running as SYSTEM. This will not work with `Start-ProcessWith` due to the restrictions in the underlying APIs it calls.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ProcessIntString</command:parameterValue> <dev:type> <maml:name>ProcessIntString</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Position</maml:name> <maml:description> <maml:para>The window position with X being the horizontal offset and Y being the vertical offset from the top left corner of the screen.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Coordinates</command:parameterValue> <dev:type> <maml:name>Coordinates</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Reserved</maml:name> <maml:description> <maml:para>This parameter refers to the string `lpReserved` field in the `STARTUPINFO` structure used to create a process. It is unused and undocumented in Windows.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Reserved2</maml:name> <maml:description> <maml:para>This parameter refers to the byte `lpReserved2` field and `cbReserved2` in the `STARTUPINFO` structure. This is unused and undocumented but has some used for sneaking data into a process.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Byte[]</command:parameterValue> <dev:type> <maml:name>Byte[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StandardError</maml:name> <maml:description> <maml:para>A writable SafeHandle that is set to the new process' stderr pipe. This handle will be explicitly set as inheritable process wide even if it wasn't opened as an inheritable object. This cannot be used with `-DisableInheritance` on `Start-ProcessEx`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle</command:parameterValue> <dev:type> <maml:name>SafeHandle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StandardInput</maml:name> <maml:description> <maml:para>A readable SafeHandle that is set to the new process' stdin pipe. This handle will be explicitly set as inheritable process wide even if it wasn't opened as an inheritable object. This cannot be used with with `-DisableInheritance` on `Start-ProcessEx`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle</command:parameterValue> <dev:type> <maml:name>SafeHandle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StandardOutput</maml:name> <maml:description> <maml:para>A writable SafeHandle that is set to the new process' stdout pipe. This handle will be explicitly set as inheritable process wide even if it wasn't opened as an inheritable object. This cannot be used with `-DisableInheritance` on `Start-ProcessEx`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle</command:parameterValue> <dev:type> <maml:name>SafeHandle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Title</maml:name> <maml:description> <maml:para>This does not apply to GUI processes and console processes created in the same console. For a new console process created with a new console window this is the title to display in the title bar and if not set the executable path is used.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WindowSize</maml:name> <maml:description> <maml:para>The size of the window to create.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Size</command:parameterValue> <dev:type> <maml:name>Size</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WindowStyle</maml:name> <maml:description> <maml:para>The window style of the new process.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">WindowStyle</command:parameterValue> <dev:type> <maml:name>WindowStyle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>ProcessEx.StartupInfo</maml:name> </dev:type> <maml:description> <maml:para>The startup info object that can be used when starting a new process.</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>---------- Example 1: Start process with custom title ----------</maml:title> <dev:code>PS C:\> $si = New-StartupInfo -Title "My Application" PS C:\> Start-ProcessEx my_app.exe -StartupInfo $si</dev:code> <dev:remarks> <maml:para>Starts a new process with a custom title in the console window.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>---------- Example 2: Create StartupInfo with ConPTY ----------</maml:title> <dev:code>PS C:\> $inputStream = [IO.FileStream]::Open('C:\temp\input', 'Open', >> 'Read', 'ReadWrite') PS C:\> $outputStream = [IO.FileStream]::Open('C:\temp\output', 'Create', >> 'Write', 'ReadWrite') PS C:\> $conPTYParams = @{ >> Width = 80 >> Height = 60 >> InputPipe = $inputStream.SafeFileHandle >> OutputPipe = $outputStream.SafeFileHandle >> } PS C:\> $conPTY = New-ConPty @conPtyParams PS C:\> try { >> $si = New-StartupInfo -ConPTY $conPTY >> Start-ProcessEx cmd.exe -StartupInfo $si -Wait >> } >> finally { >> $conPTY.Dispose() >> }</dev:code> <dev:remarks> <maml:para>Create a ConPTY that will pipe data from `C:\temp\input` into the ConPTY and write data from the ConPTY to `C:\temp\output`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>--- Example 3: Create StartupInfo with custom parent process ---</maml:title> <dev:code>PS C:\> $parentProc = Get-Process -Id 1535 PS C:\> $pipe = [System.IO.Pipes.AnonymousPipeServerStream]::new("In", "None") PS C:\> $dupParams = @{ >> Handle = $pipe.ClientSafePipeHandle >> Process = $parentProc >> Inherit = $true >> OwnHandle = $true >> } PS C:\> $dupPipe = Copy-HandleToProcess @dupParams PS C:\> $pipe.DisposeLocalCopyOfClientHandle() PS C:\> try { >> $si = New-StartupInfo -InheritedHandle $dupPIpe -ParentProcess $parentProc >> Start-ProcessEx powershell '-File' 'my_script.ps1' -StartupInfo $si >> } >> finally { >> # Can close $dupPipe in $parentProc once the process has started >> $dupPipe.Dispose() >> }</dev:code> <dev:remarks> <maml:para>Creates a `StartupInfo` with a parent process and explicit handles to implement from this parent process. These handles must exist in the parent process specified rather than the current process and must also be marked as inheritable. To copy a handle in the current process to the new parent process, use `Copy-HandleToProcess`.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>STARTUPINFOW</maml:linkText> <maml:uri>https://docs.microsoft.com/en-us/windows/win32/api/processthreadsapi/ns-processthreadsapi-startupinfow</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Undocumented STARTUPINFO Values</maml:linkText> <maml:uri>http://www.catch22.net/tuts/undocumented-createprocess#</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Resize-ConPTY</command:name> <command:verb>Resize</command:verb> <command:noun>ConPTY</command:noun> <maml:description> <maml:para>Resize a ConPTY buffer.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Resizes the width and height of a ConPTY buffer.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Resize-ConPTY</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="InputObject"> <maml:name>ConPTY</maml:name> <maml:description> <maml:para>The ConPTY to resize as created by `New-ConPTY`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle[]</command:parameterValue> <dev:type> <maml:name>SafeHandle[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="X"> <maml:name>Width</maml:name> <maml:description> <maml:para>The new width of the ConPTY</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int16</command:parameterValue> <dev:type> <maml:name>Int16</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="Y"> <maml:name>Height</maml:name> <maml:description> <maml:para>The new height of the ConPTY.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int16</command:parameterValue> <dev:type> <maml:name>Int16</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName, ByValue)" position="0" aliases="InputObject"> <maml:name>ConPTY</maml:name> <maml:description> <maml:para>The ConPTY to resize as created by `New-ConPTY`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle[]</command:parameterValue> <dev:type> <maml:name>SafeHandle[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="Y"> <maml:name>Height</maml:name> <maml:description> <maml:para>The new height of the ConPTY.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int16</command:parameterValue> <dev:type> <maml:name>Int16</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="X"> <maml:name>Width</maml:name> <maml:description> <maml:para>The new width of the ConPTY</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int16</command:parameterValue> <dev:type> <maml:name>Int16</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>System.Runtime.InteropServices.SafeHandle[]</maml:name> </dev:type> <maml:description> <maml:para>The ConPTY to resize.</maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- Example 1 --------------------------</maml:title> <dev:code>PS C:\> Resize-ConPTY -ConPTY $conPTY -Width 160 -Heigth 120</dev:code> <dev:remarks> <maml:para>Resizes the buffer of the supplied ConPTY to have a width of 160 characters and a height of 120 characters.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Introducing the Windows Pseudo Console (ConPTY)</maml:linkText> <maml:uri>https://devblogs.microsoft.com/commandline/windows-command-line-introducing-the-windows-pseudo-console-conpty/</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>ResizePseudocConsole</maml:linkText> <maml:uri>https://docs.microsoft.com/en-us/windows/console/resizepseudoconsole</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Start-ProcessEx</command:name> <command:verb>Start</command:verb> <command:noun>ProcessEx</command:noun> <maml:description> <maml:para>Start a new process.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Like `Start-Process` but exposes a few more low level options and focuses specifically on the Win32 API `CreateProcess` or `CreateProcessAsUser` when `-Token` is specified.</maml:para> <maml:para>Use Invoke-ProcessEx (./Invoke-ProcessEx.md)to run a process and capture the output inline.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Start-ProcessEx</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ApplicationName</maml:name> <maml:description> <maml:para>Used with `-CommandLine` as the full path to the executable to run. This is useful if the `-CommandLine` executable path contains spaces and you wish to be explicit about what to run.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CommandLine</maml:name> <maml:description> <maml:para>Used instead of `-FilePath` and `-ArgumentList` to run a new process with the literal string provided. This string is not escaped so you need to ensure it is valid for your use case. You can optionally specify `-ApplicationName` with this parameter to be more explicit about what executable to run.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CreationFlags</maml:name> <maml:description> <maml:para>The process CreationFlags to set when starting the process. Defaults to `None` if `-StartupInfo` contains a ConPTY otherwise the default is `NewConsole` to ensure the console application is created in a new console window instead of sharing the existing console. You should not set `NewConsole` if a ConPTY is specified as that will have the new process ignore the ConPTY and use the new conhost allocated. You cannot set `Suspended` with the `-Wait` parameter.</maml:para> <maml:para>A suspended process can be started by calling `[ProcessEx.ProcessRunner]::ResumeThread($proc.Thread)`.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">None</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">DebugProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">DebugOnlyThisProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Suspended</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">DetachedProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">NewConsole</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">NormalPriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">IdlePriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">HighPriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">RealtimePriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">NewProcessGroup</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">UnicodeEnvironment</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SeparateWowVDM</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SharedWowVDM</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ForceDOS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">BelowNormalPriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">AboveNormalPriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">InheritParentAffinity</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">InheritCallerPriority</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProtectedProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ExtendedStartupinfoPresent</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProcessModeBackgroundBegin</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProcessModeBackgroundEnd</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SecureProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">BreakawayFromJob</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">PreserveCodeAuthzLevel</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">DefaultErrorMode</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">NoWindow</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProfileUser</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProfileKernel</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProfileServer</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">IgnoreSystemDefault</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">CreationFlags</command:parameterValue> <dev:type> <maml:name>CreationFlags</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>DisableInheritance</maml:name> <maml:description> <maml:para>Explicitly disable all the handles in the current process from being inherited with the new process. This cannot be used if `-StartupInfo` has an explicit StandardInput/Output/Error or InheritedHandles list.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Environment</maml:name> <maml:description> <maml:para>A dictionary containing explicit environment variables to use for the new process. These env vars will be used instead of the existing process environment variables if defined. Use `Get-TokenEnvironment` to generate a new environment block that can be modified as needed for the new process. Cannot be used with `-UseNewEnvironment`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">IDictionary</command:parameterValue> <dev:type> <maml:name>IDictionary</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Return the `ProcessInfo` object for the process that was started.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ProcessAttribute</maml:name> <maml:description> <maml:para>Set the security descriptor and inheritbility of the new process handle.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SecurityAttributes</command:parameterValue> <dev:type> <maml:name>SecurityAttributes</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartupInfo</maml:name> <maml:description> <maml:para>The process StartupInfo details to use when starting the new process. Use the `New-StartupInfo` command to define this value based on your needs.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StartupInfo</command:parameterValue> <dev:type> <maml:name>StartupInfo</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ThreadAttribute</maml:name> <maml:description> <maml:para>Set the security descriptor and inheritbility of the new thread handle.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SecurityAttributes</command:parameterValue> <dev:type> <maml:name>SecurityAttributes</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Token</maml:name> <maml:description> <maml:para>Create the process to run with the access token specified. This access token can be retrieved through other functions like `LogonUser`, duplicating from an existing process, etc. Using this parameter calls `CreateProcessAsUser` instead of `CreateProcess` which requires the `SeIncreaseQuotaPrivilege` privilege. It also requires the `SeAssignPrimaryTokenPrivilege` privilege if the token is not a restricted version of the callers primary token. The `SeAssignPrimaryTokenPrivilege` privilege is not given to administrators by default so check with `whoami.exe /priv` to see if your account has this privilege. The `Start-ProcessWith` cmdlet requires less sensitive privileges and can be used as an alternative to this cmdlet if needed.</maml:para> <maml:para>Be aware that this process will add the Logon Session SID of this token to the station and desktop security descriptor specified by Desktop on `-StartupInfo`. If no startup info was specified then the current station and desktop is used. Running this with multiple tokens could hit the maximum allowed size in a ACL if the station/desktop descriptor is not cleaned up.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle</command:parameterValue> <dev:type> <maml:name>SafeHandle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>UseNewEnvironment</maml:name> <maml:description> <maml:para>Instead of inheriting the current process environment variables, use a brand new set of environment variables for the current user. Cannot be used with `-Environment`.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Wait</maml:name> <maml:description> <maml:para>Wait for the process and any of the processes they may spawn to finish before returning. This cannot be set with `-CreationFlags Suspended`.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WorkingDirectory</maml:name> <maml:description> <maml:para>The working directory to set for the new process, defaults to the current filesystem location of the PowerShell process if not defined.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Start-ProcessEx</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="0" aliases="none"> <maml:name>FilePath</maml:name> <maml:description> <maml:para>The executable to start. Use with `-ArgumentList` to supply a list of argument to this executable.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ArgumentList</maml:name> <maml:description> <maml:para>A list of arguments to run with the `-FilePath`. These arguments are automatically escaped based on the Win32 C argument escaping rules as done by `ConvertTo-EscapedArgument`. If you wish to provide arguments as a literal string without escaping use the `-CommandLine` option instead of this and `-FilePath`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CreationFlags</maml:name> <maml:description> <maml:para>The process CreationFlags to set when starting the process. Defaults to `None` if `-StartupInfo` contains a ConPTY otherwise the default is `NewConsole` to ensure the console application is created in a new console window instead of sharing the existing console. You should not set `NewConsole` if a ConPTY is specified as that will have the new process ignore the ConPTY and use the new conhost allocated. You cannot set `Suspended` with the `-Wait` parameter.</maml:para> <maml:para>A suspended process can be started by calling `[ProcessEx.ProcessRunner]::ResumeThread($proc.Thread)`.</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">None</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">DebugProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">DebugOnlyThisProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Suspended</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">DetachedProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">NewConsole</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">NormalPriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">IdlePriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">HighPriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">RealtimePriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">NewProcessGroup</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">UnicodeEnvironment</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SeparateWowVDM</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SharedWowVDM</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ForceDOS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">BelowNormalPriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">AboveNormalPriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">InheritParentAffinity</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">InheritCallerPriority</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProtectedProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ExtendedStartupinfoPresent</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProcessModeBackgroundBegin</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProcessModeBackgroundEnd</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SecureProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">BreakawayFromJob</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">PreserveCodeAuthzLevel</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">DefaultErrorMode</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">NoWindow</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProfileUser</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProfileKernel</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProfileServer</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">IgnoreSystemDefault</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">CreationFlags</command:parameterValue> <dev:type> <maml:name>CreationFlags</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>DisableInheritance</maml:name> <maml:description> <maml:para>Explicitly disable all the handles in the current process from being inherited with the new process. This cannot be used if `-StartupInfo` has an explicit StandardInput/Output/Error or InheritedHandles list.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Environment</maml:name> <maml:description> <maml:para>A dictionary containing explicit environment variables to use for the new process. These env vars will be used instead of the existing process environment variables if defined. Use `Get-TokenEnvironment` to generate a new environment block that can be modified as needed for the new process. Cannot be used with `-UseNewEnvironment`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">IDictionary</command:parameterValue> <dev:type> <maml:name>IDictionary</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Return the `ProcessInfo` object for the process that was started.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ProcessAttribute</maml:name> <maml:description> <maml:para>Set the security descriptor and inheritbility of the new process handle.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SecurityAttributes</command:parameterValue> <dev:type> <maml:name>SecurityAttributes</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartupInfo</maml:name> <maml:description> <maml:para>The process StartupInfo details to use when starting the new process. Use the `New-StartupInfo` command to define this value based on your needs.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StartupInfo</command:parameterValue> <dev:type> <maml:name>StartupInfo</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ThreadAttribute</maml:name> <maml:description> <maml:para>Set the security descriptor and inheritbility of the new thread handle.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SecurityAttributes</command:parameterValue> <dev:type> <maml:name>SecurityAttributes</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Token</maml:name> <maml:description> <maml:para>Create the process to run with the access token specified. This access token can be retrieved through other functions like `LogonUser`, duplicating from an existing process, etc. Using this parameter calls `CreateProcessAsUser` instead of `CreateProcess` which requires the `SeIncreaseQuotaPrivilege` privilege. It also requires the `SeAssignPrimaryTokenPrivilege` privilege if the token is not a restricted version of the callers primary token. The `SeAssignPrimaryTokenPrivilege` privilege is not given to administrators by default so check with `whoami.exe /priv` to see if your account has this privilege. The `Start-ProcessWith` cmdlet requires less sensitive privileges and can be used as an alternative to this cmdlet if needed.</maml:para> <maml:para>Be aware that this process will add the Logon Session SID of this token to the station and desktop security descriptor specified by Desktop on `-StartupInfo`. If no startup info was specified then the current station and desktop is used. Running this with multiple tokens could hit the maximum allowed size in a ACL if the station/desktop descriptor is not cleaned up.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle</command:parameterValue> <dev:type> <maml:name>SafeHandle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>UseNewEnvironment</maml:name> <maml:description> <maml:para>Instead of inheriting the current process environment variables, use a brand new set of environment variables for the current user. Cannot be used with `-Environment`.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Wait</maml:name> <maml:description> <maml:para>Wait for the process and any of the processes they may spawn to finish before returning. This cannot be set with `-CreationFlags Suspended`.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WorkingDirectory</maml:name> <maml:description> <maml:para>The working directory to set for the new process, defaults to the current filesystem location of the PowerShell process if not defined.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ApplicationName</maml:name> <maml:description> <maml:para>Used with `-CommandLine` as the full path to the executable to run. This is useful if the `-CommandLine` executable path contains spaces and you wish to be explicit about what to run.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ArgumentList</maml:name> <maml:description> <maml:para>A list of arguments to run with the `-FilePath`. These arguments are automatically escaped based on the Win32 C argument escaping rules as done by `ConvertTo-EscapedArgument`. If you wish to provide arguments as a literal string without escaping use the `-CommandLine` option instead of this and `-FilePath`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CommandLine</maml:name> <maml:description> <maml:para>Used instead of `-FilePath` and `-ArgumentList` to run a new process with the literal string provided. This string is not escaped so you need to ensure it is valid for your use case. You can optionally specify `-ApplicationName` with this parameter to be more explicit about what executable to run.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CreationFlags</maml:name> <maml:description> <maml:para>The process CreationFlags to set when starting the process. Defaults to `None` if `-StartupInfo` contains a ConPTY otherwise the default is `NewConsole` to ensure the console application is created in a new console window instead of sharing the existing console. You should not set `NewConsole` if a ConPTY is specified as that will have the new process ignore the ConPTY and use the new conhost allocated. You cannot set `Suspended` with the `-Wait` parameter.</maml:para> <maml:para>A suspended process can be started by calling `[ProcessEx.ProcessRunner]::ResumeThread($proc.Thread)`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">CreationFlags</command:parameterValue> <dev:type> <maml:name>CreationFlags</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>DisableInheritance</maml:name> <maml:description> <maml:para>Explicitly disable all the handles in the current process from being inherited with the new process. This cannot be used if `-StartupInfo` has an explicit StandardInput/Output/Error or InheritedHandles list.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Environment</maml:name> <maml:description> <maml:para>A dictionary containing explicit environment variables to use for the new process. These env vars will be used instead of the existing process environment variables if defined. Use `Get-TokenEnvironment` to generate a new environment block that can be modified as needed for the new process. Cannot be used with `-UseNewEnvironment`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">IDictionary</command:parameterValue> <dev:type> <maml:name>IDictionary</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="0" aliases="none"> <maml:name>FilePath</maml:name> <maml:description> <maml:para>The executable to start. Use with `-ArgumentList` to supply a list of argument to this executable.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Return the `ProcessInfo` object for the process that was started.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ProcessAttribute</maml:name> <maml:description> <maml:para>Set the security descriptor and inheritbility of the new process handle.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SecurityAttributes</command:parameterValue> <dev:type> <maml:name>SecurityAttributes</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartupInfo</maml:name> <maml:description> <maml:para>The process StartupInfo details to use when starting the new process. Use the `New-StartupInfo` command to define this value based on your needs.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StartupInfo</command:parameterValue> <dev:type> <maml:name>StartupInfo</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ThreadAttribute</maml:name> <maml:description> <maml:para>Set the security descriptor and inheritbility of the new thread handle.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SecurityAttributes</command:parameterValue> <dev:type> <maml:name>SecurityAttributes</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Token</maml:name> <maml:description> <maml:para>Create the process to run with the access token specified. This access token can be retrieved through other functions like `LogonUser`, duplicating from an existing process, etc. Using this parameter calls `CreateProcessAsUser` instead of `CreateProcess` which requires the `SeIncreaseQuotaPrivilege` privilege. It also requires the `SeAssignPrimaryTokenPrivilege` privilege if the token is not a restricted version of the callers primary token. The `SeAssignPrimaryTokenPrivilege` privilege is not given to administrators by default so check with `whoami.exe /priv` to see if your account has this privilege. The `Start-ProcessWith` cmdlet requires less sensitive privileges and can be used as an alternative to this cmdlet if needed.</maml:para> <maml:para>Be aware that this process will add the Logon Session SID of this token to the station and desktop security descriptor specified by Desktop on `-StartupInfo`. If no startup info was specified then the current station and desktop is used. Running this with multiple tokens could hit the maximum allowed size in a ACL if the station/desktop descriptor is not cleaned up.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle</command:parameterValue> <dev:type> <maml:name>SafeHandle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>UseNewEnvironment</maml:name> <maml:description> <maml:para>Instead of inheriting the current process environment variables, use a brand new set of environment variables for the current user. Cannot be used with `-Environment`.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Wait</maml:name> <maml:description> <maml:para>Wait for the process and any of the processes they may spawn to finish before returning. This cannot be set with `-CreationFlags Suspended`.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WorkingDirectory</maml:name> <maml:description> <maml:para>The working directory to set for the new process, defaults to the current filesystem location of the PowerShell process if not defined.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para>No output if `-PassThru` is not specified.</maml:para> </maml:description> </command:returnValue> <command:returnValue> <dev:type> <maml:name>ProcessEx.ProcessInfo</maml:name> </dev:type> <maml:description> <maml:para>If `-PassThru` is specified the cmdlet will output the `ProcessInfo` of the process. This contains the process and starting thread handle as well as the command invocation details.</maml:para> <maml:para>This object contains the following properties:</maml:para> <maml:para>- `Executable` - The executable of the process</maml:para> <maml:para>- `CommandLine` - The command line used to start the process</maml:para> <maml:para>- `WorkingDirectory` - The working/current directory of the process</maml:para> <maml:para>- `Process` - The `SafeHandle` of the process created</maml:para> <maml:para>- `Thread` - The `SafeHandle` of the main thread</maml:para> <maml:para>- `ProcessId` - Also aliased to `Id`, this is the process identifier</maml:para> <maml:para>- `ThreadId` - The identifier of the main thread</maml:para> <maml:para>- `ParentProcessId` - The process identifier of the parent that spawned this process</maml:para> <maml:para>- `ExitCode` - The exit code of the process, this will not be set if it's still running</maml:para> <maml:para>- `Environment` - The environment variables of the process</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>------------ Example 1: Start a new console process ------------</maml:title> <dev:code>PS C:\> Start-ProcessEx -FilePath powershell.exe</dev:code> <dev:remarks> <maml:para>Starts `powershell.exe` in a new console window.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>---------- Example 2: Start a process with arguments ----------</maml:title> <dev:code>PS C:\> Start-ProcessEx -FilePath pwsh.exe -ArgumentList '-NoProfile', '-Command', 'echo "hi"'</dev:code> <dev:remarks> <maml:para>Starts `pwsh.exe` with the command arguments `-NoProfile -Command echo "hi"`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>- Example 3: Start a process without escaping the command line -</maml:title> <dev:code>PS C:\> $id = '{e97fa56f-daee-434f-ae00-5fab3d0b054a}' PS C:\> $cmd = 'msiexec.exe /x {0} /qn TEST="my prop"' -f $id PS C:\> Start-ProcessEx -CommandLine $cmd</dev:code> <dev:remarks> <maml:para>Runs the process with the literal command line value `msiexec.exe /x {e97fa56f-daee-434f-ae00-5fab3d0b054a} /qn TEST="my prop"`. If the argument `Test="my prop"` was used with `-ArgumentList` it would be escaped as the literal value `"Test=\"my prop\""`. Using the `-CommandLine` parameter will disable any escaping rules and run the raw command exactly as it was passed in.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>- Example 4: Start a process with redirected stdout to a file -</maml:title> <dev:code>PS C:\> $fs = [IO.File]::Open('C:\stdout.txt', 'Create', 'Write', 'ReadWrite') PS C:\> try .. $si = New-StartupInfo -StandardOutput $fs.SafeFileHandle .. Start-ProcessEx -FilePath cmd.exe /c echo hi -StartupInfo $si -Wait .. } .. finally { .. $fs.Dispose() .. }</dev:code> <dev:remarks> <maml:para>Runs a process with the stdout redirected to the file at `C:\stdout.txt`.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>Online Version:</maml:linkText> <maml:uri></maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>CreateProcess</maml:linkText> <maml:uri>https://docs.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>CreateProcessAsUser</maml:linkText> <maml:uri>https://docs.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessasuserw</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Windows Privileges</maml:linkText> <maml:uri>https://docs.microsoft.com/en-us/windows/win32/secauthz/privilege-constants</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp"> <command:details> <command:name>Start-ProcessWith</command:name> <command:verb>Start</command:verb> <command:noun>ProcessWith</command:noun> <maml:description> <maml:para>Start a new process with credentials or a token.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Like `Start-Process` but exposes a few more low level options and focuses specifically on the Win32 API `CreateProcessWithLogon` or `CreateProcessWithToken`. Use this instead of `Start-ProcessEx` if you wish to start a process as another user but do no have the `SeAssignPrimaryTokenPrivilege` privileges required by the `-Token` parameter on that cmdlet.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Start-ProcessWith</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ApplicationName</maml:name> <maml:description> <maml:para>Used with `-CommandLine` as the full path to the executable to run. This is useful if the `-CommandLine` executable path contains spaces and you wish to be explicit about what to run.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CommandLine</maml:name> <maml:description> <maml:para>Used instead of `-FilePath` and `-ArgumentList` to run a new process with the literal string provided. This string is not escaped so you need to ensure it is valid for your use case. You can optionally specify `-ApplicationName` with this parameter to be more explicit about what executable to run.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CreationFlags</maml:name> <maml:description> <maml:para>The process CreationFlags to set when starting the process. Defaults to `NewConsole`, `CreateDefaultErrorMode`, `CreateNewProcessGroup` to ensure the console application is created in a new console window instead of sharing the existing console. You cannot set `Suspended` with the `-Wait` parameter. It is not possible to omit `NewConsole`, a process spawned by this cmdlet must be done in a new console.</maml:para> <maml:para>A suspended process can be started by calling `[ProcessEx.ProcessRunner]::ResumeThread($proc.Thread)`</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">None</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">DebugProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">DebugOnlyThisProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Suspended</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">DetachedProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">NewConsole</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">NormalPriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">IdlePriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">HighPriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">RealtimePriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">NewProcessGroup</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">UnicodeEnvironment</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SeparateWowVDM</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SharedWowVDM</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ForceDOS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">BelowNormalPriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">AboveNormalPriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">InheritParentAffinity</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">InheritCallerPriority</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProtectedProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ExtendedStartupinfoPresent</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProcessModeBackgroundBegin</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProcessModeBackgroundEnd</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SecureProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">BreakawayFromJob</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">PreserveCodeAuthzLevel</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">DefaultErrorMode</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">NoWindow</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProfileUser</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProfileKernel</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProfileServer</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">IgnoreSystemDefault</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">CreationFlags</command:parameterValue> <dev:type> <maml:name>CreationFlags</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The user credentials to start the new process with. This will use the `CreateProcessWithLogon` API which logs on the user as an interactive logon or a NewCredential (network access change) logon when `-NetCredentialsOnly` is specified. This API can be called by non-admin accounts as it has no sensitive privilege requirements. Because the logon is an interactive logon, UAC restrictions will apply to the new process as it spawns as a limited user token. Use the `-Token` parameter after getting the linked token (requires admin rights) to bypass this UAC behaviour.</maml:para> <maml:para>When `-StartupInfo` specifies a custom station/desktop, the function will add the SID specified by the username to the station and desktop's security descriptor with `AllAccess`. When no startup info or Desktop is not set then the current station/desktop is used without any adjustments to their security descriptors.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Environment</maml:name> <maml:description> <maml:para>A dictionary containing explicit environment variables to use for the new process. These env vars will be used instead of the existing process environment variables if defined. Use `Get-TokenEnvironment` to generate a new environment block that can be modified as needed for the new process.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">IDictionary</command:parameterValue> <dev:type> <maml:name>IDictionary</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>NetCredentialsOnly</maml:name> <maml:description> <maml:para>The credential or token specified will only be used for any outbound authentication attempts, e.g. SMB file access, AD operations, etc. Any local actions will continue to use the callers access token. If using `-Credential`, the username must be in the UPN format `username@REALM.COM`.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Return the `ProcessInfo` object for the process that was started.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartupInfo</maml:name> <maml:description> <maml:para>The process StartupInfo details to use when starting the new process. Use the `New-StartupInfo` command to define this value based on your needs.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StartupInfo</command:parameterValue> <dev:type> <maml:name>StartupInfo</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Wait</maml:name> <maml:description> <maml:para>Wait for the process and any of the processes they may spawn to finish before returning. This cannot be set with `-CreationFlags Suspended`.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WithProfile</maml:name> <maml:description> <maml:para>Loads the user profile specified by the `-Credential` or `-Token`, including the `HKCU` registry hive.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WorkingDirectory</maml:name> <maml:description> <maml:para>The working directory to set for the new process, defaults to the current filesystem location of the PowerShell process if not defined.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Start-ProcessWith</maml:name> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ApplicationName</maml:name> <maml:description> <maml:para>Used with `-CommandLine` as the full path to the executable to run. This is useful if the `-CommandLine` executable path contains spaces and you wish to be explicit about what to run.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CommandLine</maml:name> <maml:description> <maml:para>Used instead of `-FilePath` and `-ArgumentList` to run a new process with the literal string provided. This string is not escaped so you need to ensure it is valid for your use case. You can optionally specify `-ApplicationName` with this parameter to be more explicit about what executable to run.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CreationFlags</maml:name> <maml:description> <maml:para>The process CreationFlags to set when starting the process. Defaults to `NewConsole`, `CreateDefaultErrorMode`, `CreateNewProcessGroup` to ensure the console application is created in a new console window instead of sharing the existing console. You cannot set `Suspended` with the `-Wait` parameter. It is not possible to omit `NewConsole`, a process spawned by this cmdlet must be done in a new console.</maml:para> <maml:para>A suspended process can be started by calling `[ProcessEx.ProcessRunner]::ResumeThread($proc.Thread)`</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">None</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">DebugProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">DebugOnlyThisProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Suspended</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">DetachedProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">NewConsole</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">NormalPriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">IdlePriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">HighPriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">RealtimePriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">NewProcessGroup</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">UnicodeEnvironment</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SeparateWowVDM</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SharedWowVDM</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ForceDOS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">BelowNormalPriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">AboveNormalPriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">InheritParentAffinity</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">InheritCallerPriority</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProtectedProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ExtendedStartupinfoPresent</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProcessModeBackgroundBegin</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProcessModeBackgroundEnd</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SecureProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">BreakawayFromJob</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">PreserveCodeAuthzLevel</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">DefaultErrorMode</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">NoWindow</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProfileUser</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProfileKernel</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProfileServer</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">IgnoreSystemDefault</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">CreationFlags</command:parameterValue> <dev:type> <maml:name>CreationFlags</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Environment</maml:name> <maml:description> <maml:para>A dictionary containing explicit environment variables to use for the new process. These env vars will be used instead of the existing process environment variables if defined. Use `Get-TokenEnvironment` to generate a new environment block that can be modified as needed for the new process.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">IDictionary</command:parameterValue> <dev:type> <maml:name>IDictionary</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>NetCredentialsOnly</maml:name> <maml:description> <maml:para>The credential or token specified will only be used for any outbound authentication attempts, e.g. SMB file access, AD operations, etc. Any local actions will continue to use the callers access token. If using `-Credential`, the username must be in the UPN format `username@REALM.COM`.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Return the `ProcessInfo` object for the process that was started.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartupInfo</maml:name> <maml:description> <maml:para>The process StartupInfo details to use when starting the new process. Use the `New-StartupInfo` command to define this value based on your needs.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StartupInfo</command:parameterValue> <dev:type> <maml:name>StartupInfo</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Token</maml:name> <maml:description> <maml:para>Creates the process to run with the specified access token instead of explicit credentials. This access token can be retrieved by using other APIs like `LogonUser` or by duplicating an existing access token of a running process. The token should have been opened with `Query`, `Duplicate`, and `AssignPrimary` rights. The `AdjustSessionId` and `AdjutDefault` access may also be required if using a token from another session, e.g. a `SYSTEM` token. This will use the `CreateProcessWithToken` API which requires the `SeImpersonatePrivilege` privileges usually held by administrators on the host.</maml:para> <maml:para>Be aware that this process will add the Logon Session SID of this token to the station and desktop security descriptor specified by Desktop on `-StartupInfo`. If no startup info was specified then the current station and desktop is used. Running this with multiple tokens could hit the maximum allowed size in a ACL if the station/desktop descriptor is not cleaned up.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle</command:parameterValue> <dev:type> <maml:name>SafeHandle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Wait</maml:name> <maml:description> <maml:para>Wait for the process and any of the processes they may spawn to finish before returning. This cannot be set with `-CreationFlags Suspended`.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WithProfile</maml:name> <maml:description> <maml:para>Loads the user profile specified by the `-Credential` or `-Token`, including the `HKCU` registry hive.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WorkingDirectory</maml:name> <maml:description> <maml:para>The working directory to set for the new process, defaults to the current filesystem location of the PowerShell process if not defined.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Start-ProcessWith</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="0" aliases="none"> <maml:name>FilePath</maml:name> <maml:description> <maml:para>The executable to start. Use with `-ArgumentList` to supply a list of argument to this executable.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ArgumentList</maml:name> <maml:description> <maml:para>A list of arguments to run with the `-FilePath`. These arguments are automatically escaped based on the Win32 C argument escaping rules as done by `ConvertTo-EscapedArgument`. If you wish to provide arguments as a literal string without escaping use the `-CommandLine` option instead of this and `-FilePath`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CreationFlags</maml:name> <maml:description> <maml:para>The process CreationFlags to set when starting the process. Defaults to `NewConsole`, `CreateDefaultErrorMode`, `CreateNewProcessGroup` to ensure the console application is created in a new console window instead of sharing the existing console. You cannot set `Suspended` with the `-Wait` parameter. It is not possible to omit `NewConsole`, a process spawned by this cmdlet must be done in a new console.</maml:para> <maml:para>A suspended process can be started by calling `[ProcessEx.ProcessRunner]::ResumeThread($proc.Thread)`</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">None</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">DebugProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">DebugOnlyThisProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Suspended</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">DetachedProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">NewConsole</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">NormalPriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">IdlePriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">HighPriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">RealtimePriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">NewProcessGroup</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">UnicodeEnvironment</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SeparateWowVDM</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SharedWowVDM</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ForceDOS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">BelowNormalPriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">AboveNormalPriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">InheritParentAffinity</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">InheritCallerPriority</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProtectedProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ExtendedStartupinfoPresent</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProcessModeBackgroundBegin</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProcessModeBackgroundEnd</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SecureProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">BreakawayFromJob</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">PreserveCodeAuthzLevel</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">DefaultErrorMode</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">NoWindow</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProfileUser</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProfileKernel</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProfileServer</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">IgnoreSystemDefault</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">CreationFlags</command:parameterValue> <dev:type> <maml:name>CreationFlags</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The user credentials to start the new process with. This will use the `CreateProcessWithLogon` API which logs on the user as an interactive logon or a NewCredential (network access change) logon when `-NetCredentialsOnly` is specified. This API can be called by non-admin accounts as it has no sensitive privilege requirements. Because the logon is an interactive logon, UAC restrictions will apply to the new process as it spawns as a limited user token. Use the `-Token` parameter after getting the linked token (requires admin rights) to bypass this UAC behaviour.</maml:para> <maml:para>When `-StartupInfo` specifies a custom station/desktop, the function will add the SID specified by the username to the station and desktop's security descriptor with `AllAccess`. When no startup info or Desktop is not set then the current station/desktop is used without any adjustments to their security descriptors.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Environment</maml:name> <maml:description> <maml:para>A dictionary containing explicit environment variables to use for the new process. These env vars will be used instead of the existing process environment variables if defined. Use `Get-TokenEnvironment` to generate a new environment block that can be modified as needed for the new process.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">IDictionary</command:parameterValue> <dev:type> <maml:name>IDictionary</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>NetCredentialsOnly</maml:name> <maml:description> <maml:para>The credential or token specified will only be used for any outbound authentication attempts, e.g. SMB file access, AD operations, etc. Any local actions will continue to use the callers access token. If using `-Credential`, the username must be in the UPN format `username@REALM.COM`.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Return the `ProcessInfo` object for the process that was started.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartupInfo</maml:name> <maml:description> <maml:para>The process StartupInfo details to use when starting the new process. Use the `New-StartupInfo` command to define this value based on your needs.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StartupInfo</command:parameterValue> <dev:type> <maml:name>StartupInfo</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Wait</maml:name> <maml:description> <maml:para>Wait for the process and any of the processes they may spawn to finish before returning. This cannot be set with `-CreationFlags Suspended`.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WithProfile</maml:name> <maml:description> <maml:para>Loads the user profile specified by the `-Credential` or `-Token`, including the `HKCU` registry hive.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WorkingDirectory</maml:name> <maml:description> <maml:para>The working directory to set for the new process, defaults to the current filesystem location of the PowerShell process if not defined.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> <command:syntaxItem> <maml:name>Start-ProcessWith</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="0" aliases="none"> <maml:name>FilePath</maml:name> <maml:description> <maml:para>The executable to start. Use with `-ArgumentList` to supply a list of argument to this executable.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ArgumentList</maml:name> <maml:description> <maml:para>A list of arguments to run with the `-FilePath`. These arguments are automatically escaped based on the Win32 C argument escaping rules as done by `ConvertTo-EscapedArgument`. If you wish to provide arguments as a literal string without escaping use the `-CommandLine` option instead of this and `-FilePath`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CreationFlags</maml:name> <maml:description> <maml:para>The process CreationFlags to set when starting the process. Defaults to `NewConsole`, `CreateDefaultErrorMode`, `CreateNewProcessGroup` to ensure the console application is created in a new console window instead of sharing the existing console. You cannot set `Suspended` with the `-Wait` parameter. It is not possible to omit `NewConsole`, a process spawned by this cmdlet must be done in a new console.</maml:para> <maml:para>A suspended process can be started by calling `[ProcessEx.ProcessRunner]::ResumeThread($proc.Thread)`</maml:para> </maml:description> <command:parameterValueGroup> <command:parameterValue required="false" command:variableLength="false">None</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">DebugProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">DebugOnlyThisProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">Suspended</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">DetachedProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">NewConsole</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">NormalPriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">IdlePriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">HighPriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">RealtimePriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">NewProcessGroup</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">UnicodeEnvironment</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SeparateWowVDM</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SharedWowVDM</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ForceDOS</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">BelowNormalPriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">AboveNormalPriorityClass</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">InheritParentAffinity</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">InheritCallerPriority</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProtectedProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ExtendedStartupinfoPresent</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProcessModeBackgroundBegin</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProcessModeBackgroundEnd</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">SecureProcess</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">BreakawayFromJob</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">PreserveCodeAuthzLevel</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">DefaultErrorMode</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">NoWindow</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProfileUser</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProfileKernel</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">ProfileServer</command:parameterValue> <command:parameterValue required="false" command:variableLength="false">IgnoreSystemDefault</command:parameterValue> </command:parameterValueGroup> <command:parameterValue required="true" variableLength="false">CreationFlags</command:parameterValue> <dev:type> <maml:name>CreationFlags</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Environment</maml:name> <maml:description> <maml:para>A dictionary containing explicit environment variables to use for the new process. These env vars will be used instead of the existing process environment variables if defined. Use `Get-TokenEnvironment` to generate a new environment block that can be modified as needed for the new process.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">IDictionary</command:parameterValue> <dev:type> <maml:name>IDictionary</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>NetCredentialsOnly</maml:name> <maml:description> <maml:para>The credential or token specified will only be used for any outbound authentication attempts, e.g. SMB file access, AD operations, etc. Any local actions will continue to use the callers access token. If using `-Credential`, the username must be in the UPN format `username@REALM.COM`.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Return the `ProcessInfo` object for the process that was started.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartupInfo</maml:name> <maml:description> <maml:para>The process StartupInfo details to use when starting the new process. Use the `New-StartupInfo` command to define this value based on your needs.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StartupInfo</command:parameterValue> <dev:type> <maml:name>StartupInfo</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Token</maml:name> <maml:description> <maml:para>Creates the process to run with the specified access token instead of explicit credentials. This access token can be retrieved by using other APIs like `LogonUser` or by duplicating an existing access token of a running process. The token should have been opened with `Query`, `Duplicate`, and `AssignPrimary` rights. The `AdjustSessionId` and `AdjutDefault` access may also be required if using a token from another session, e.g. a `SYSTEM` token. This will use the `CreateProcessWithToken` API which requires the `SeImpersonatePrivilege` privileges usually held by administrators on the host.</maml:para> <maml:para>Be aware that this process will add the Logon Session SID of this token to the station and desktop security descriptor specified by Desktop on `-StartupInfo`. If no startup info was specified then the current station and desktop is used. Running this with multiple tokens could hit the maximum allowed size in a ACL if the station/desktop descriptor is not cleaned up.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle</command:parameterValue> <dev:type> <maml:name>SafeHandle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Wait</maml:name> <maml:description> <maml:para>Wait for the process and any of the processes they may spawn to finish before returning. This cannot be set with `-CreationFlags Suspended`.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WithProfile</maml:name> <maml:description> <maml:para>Loads the user profile specified by the `-Credential` or `-Token`, including the `HKCU` registry hive.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WorkingDirectory</maml:name> <maml:description> <maml:para>The working directory to set for the new process, defaults to the current filesystem location of the PowerShell process if not defined.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ApplicationName</maml:name> <maml:description> <maml:para>Used with `-CommandLine` as the full path to the executable to run. This is useful if the `-CommandLine` executable path contains spaces and you wish to be explicit about what to run.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>ArgumentList</maml:name> <maml:description> <maml:para>A list of arguments to run with the `-FilePath`. These arguments are automatically escaped based on the Win32 C argument escaping rules as done by `ConvertTo-EscapedArgument`. If you wish to provide arguments as a literal string without escaping use the `-CommandLine` option instead of this and `-FilePath`.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue> <dev:type> <maml:name>String[]</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CommandLine</maml:name> <maml:description> <maml:para>Used instead of `-FilePath` and `-ArgumentList` to run a new process with the literal string provided. This string is not escaped so you need to ensure it is valid for your use case. You can optionally specify `-ApplicationName` with this parameter to be more explicit about what executable to run.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>CreationFlags</maml:name> <maml:description> <maml:para>The process CreationFlags to set when starting the process. Defaults to `NewConsole`, `CreateDefaultErrorMode`, `CreateNewProcessGroup` to ensure the console application is created in a new console window instead of sharing the existing console. You cannot set `Suspended` with the `-Wait` parameter. It is not possible to omit `NewConsole`, a process spawned by this cmdlet must be done in a new console.</maml:para> <maml:para>A suspended process can be started by calling `[ProcessEx.ProcessRunner]::ResumeThread($proc.Thread)`</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">CreationFlags</command:parameterValue> <dev:type> <maml:name>CreationFlags</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Credential</maml:name> <maml:description> <maml:para>The user credentials to start the new process with. This will use the `CreateProcessWithLogon` API which logs on the user as an interactive logon or a NewCredential (network access change) logon when `-NetCredentialsOnly` is specified. This API can be called by non-admin accounts as it has no sensitive privilege requirements. Because the logon is an interactive logon, UAC restrictions will apply to the new process as it spawns as a limited user token. Use the `-Token` parameter after getting the linked token (requires admin rights) to bypass this UAC behaviour.</maml:para> <maml:para>When `-StartupInfo` specifies a custom station/desktop, the function will add the SID specified by the username to the station and desktop's security descriptor with `AllAccess`. When no startup info or Desktop is not set then the current station/desktop is used without any adjustments to their security descriptors.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">PSCredential</command:parameterValue> <dev:type> <maml:name>PSCredential</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Environment</maml:name> <maml:description> <maml:para>A dictionary containing explicit environment variables to use for the new process. These env vars will be used instead of the existing process environment variables if defined. Use `Get-TokenEnvironment` to generate a new environment block that can be modified as needed for the new process.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">IDictionary</command:parameterValue> <dev:type> <maml:name>IDictionary</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="0" aliases="none"> <maml:name>FilePath</maml:name> <maml:description> <maml:para>The executable to start. Use with `-ArgumentList` to supply a list of argument to this executable.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>NetCredentialsOnly</maml:name> <maml:description> <maml:para>The credential or token specified will only be used for any outbound authentication attempts, e.g. SMB file access, AD operations, etc. Any local actions will continue to use the callers access token. If using `-Credential`, the username must be in the UPN format `username@REALM.COM`.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Return the `ProcessInfo` object for the process that was started.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga"> <maml:name>ProgressAction</maml:name> <maml:description> <maml:para>New common parameter introduced in PowerShell 7.4.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue> <dev:type> <maml:name>ActionPreference</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>StartupInfo</maml:name> <maml:description> <maml:para>The process StartupInfo details to use when starting the new process. Use the `New-StartupInfo` command to define this value based on your needs.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">StartupInfo</command:parameterValue> <dev:type> <maml:name>StartupInfo</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Token</maml:name> <maml:description> <maml:para>Creates the process to run with the specified access token instead of explicit credentials. This access token can be retrieved by using other APIs like `LogonUser` or by duplicating an existing access token of a running process. The token should have been opened with `Query`, `Duplicate`, and `AssignPrimary` rights. The `AdjustSessionId` and `AdjutDefault` access may also be required if using a token from another session, e.g. a `SYSTEM` token. This will use the `CreateProcessWithToken` API which requires the `SeImpersonatePrivilege` privileges usually held by administrators on the host.</maml:para> <maml:para>Be aware that this process will add the Logon Session SID of this token to the station and desktop security descriptor specified by Desktop on `-StartupInfo`. If no startup info was specified then the current station and desktop is used. Running this with multiple tokens could hit the maximum allowed size in a ACL if the station/desktop descriptor is not cleaned up.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">SafeHandle</command:parameterValue> <dev:type> <maml:name>SafeHandle</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Wait</maml:name> <maml:description> <maml:para>Wait for the process and any of the processes they may spawn to finish before returning. This cannot be set with `-CreationFlags Suspended`.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WithProfile</maml:name> <maml:description> <maml:para>Loads the user profile specified by the `-Credential` or `-Token`, including the `HKCU` registry hive.</maml:para> </maml:description> <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>WorkingDirectory</maml:name> <maml:description> <maml:para>The working directory to set for the new process, defaults to the current filesystem location of the PowerShell process if not defined.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">String</command:parameterValue> <dev:type> <maml:name>String</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> </command:inputTypes> <command:returnValues> <command:returnValue> <dev:type> <maml:name>None</maml:name> </dev:type> <maml:description> <maml:para>No output if `-PassThru` is not specified.</maml:para> </maml:description> </command:returnValue> <command:returnValue> <dev:type> <maml:name>ProcessEx.ProcessInfo</maml:name> </dev:type> <maml:description> <maml:para>If `-PassThru` is specified the cmdlet will output the `ProcessInfo` of the process. This contains the process and starting thread handle as well as the command invocation details.</maml:para> <maml:para>This object contains the following properties:</maml:para> <maml:para>- `Executable` - The executable of the process</maml:para> <maml:para>- `CommandLine` - The command line used to start the process</maml:para> <maml:para>- `WorkingDirectory` - The working/current directory of the process</maml:para> <maml:para>- `Process` - The `SafeHandle` of the process created</maml:para> <maml:para>- `Thread` - The `SafeHandle` of the main thread</maml:para> <maml:para>- `ProcessId` - Also aliased to `Id`, this is the process identifier</maml:para> <maml:para>- `ThreadId` - The identifier of the main thread</maml:para> <maml:para>- `ParentProcessId` - The process identifier of the parent that spawned this process</maml:para> <maml:para>- `ExitCode` - The exit code of the process, this will not be set if it's still running</maml:para> <maml:para>- `Environment` - The environment variables of the process</maml:para> </maml:description> </command:returnValue> </command:returnValues> <maml:alertSet> <maml:alert> <maml:para>This cmdlet uses the `CreateProcessWithLogon` or `CreateProcessWithToken` APIs which rely on the secondary logon service in Windows. While it requires fewer privileges than `CreateProcessAsUser` (`Start-ProcessEx -Token ...`) there are some disadvantages:</maml:para> <maml:para>- The maximum command line length is 1024 characters (`-ArgumentList` or `-CommandLine`)</maml:para> <maml:para>- You cannot specify the process or thread security attributes for a custom security descriptor or inheribility options on either</maml:para> <maml:para>- Handles in the current process cannot be inherited into the child process, you can still specify STDIO handles</maml:para> <maml:para>- You cannot specify any extended startup information like a parent proces, inherited handles, or a pseudo console</maml:para> <maml:para>- The environment is not inherited from the current process, it will be created from scratch from the new user profile</maml:para> <maml:para>- The console is always created in a new window and cannot inherit the current console</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>--- Example 1: Start a powershell with explicit credentials ---</maml:title> <dev:code>PS C:\> $cred = Get-Credential PS C:\> Start-ProcessWith powershell -Credential $cred</dev:code> <dev:remarks> <maml:para>Starts PowerShell with the explicit user defined by the credential. This process will be running with an interactive logon</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>--- Example 2: Start process as another user with arguments ---</maml:title> <dev:code>PS C:\> $cred = Get-Credential PS C:\> Start-ProcessWith -FilePath pwsh.exe -ArgumentList '-NoProfile', '-Command', 'echo "hi"' -Credential $cred</dev:code> <dev:remarks> <maml:para>Starts `pwsh.exe` with command arguments `-NoProfile -Command echo "hi"` as the user specified.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>Example 3: Start process as another user without escaping the command line</maml:title> <dev:code>PS C:\> $cred = Get-Credential PS C:\> $id = '{e97fa56f-daee-434f-ae00-5fab3d0b054a}' PS C:\> $cmd = 'msiexec.exe /x {0} /qn TEST="my prop"' -f $id PS C:\> Start-ProcessWith -CommandLine $cmd -Credential $cred</dev:code> <dev:remarks> <maml:para>Runs the process with the literal command line value `msiexec.exe /x {e97fa56f-daee-434f-ae00-5fab3d0b054a} /qn TEST="my prop"` as the user specified by the credential. If the argument `Test="my prop"` was used with `-ArgumentList` it would be escaped as the literal value `"Test=\"my prop\""`. Using the `-CommandLine` parameter will disable any escaping rules and run the raw command exactly as it was passed in.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>- Example 4: Start a process with redirected stdout to a file -</maml:title> <dev:code>PS C:\> $cred = Get-Credential PS C:\> $fs = [IO.File]::Open('C:\stdout.txt', 'Create', 'Write', 'ReadWrite') PS C:\> try .. $si = New-StartupInfo -StandardOutput $fs.SafeFileHandle .. Start-ProcessWith -FilePath cmd.exe /c echo hi -StartupInfo $si -Wait -Credential $cred .. } .. finally { .. $fs.Dispose() .. }</dev:code> <dev:remarks> <maml:para>Runs a process as the user specified with the stdout redirected to the file at `C:\stdout.txt`.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>----------- Example 5: Start a process with a token -----------</maml:title> <dev:code>PS C:\> Add-Type -Namespace Advapi32 -Name Methods -MemberDefinition @' >> [DllImport("Advapi32.dll", CharSet = CharSet.Unicode, SetLastError = true)] >> private static extern bool LogonUserW( >> string lpszUsername, >> string lpszDomain, >> string lpszPassword, >> int dwLogonType, >> int dwLogonProvider, >> out Microsoft.Win32.SafeHandles.SafeAccessTokenHandle phToken); >> >> public static Microsoft.Win32.SafeHandles.SafeAccessTokenHandle LogonUser( >> string username, string domain, string password, int logonType, >> int logonProvider) >> { >> Microsoft.Win32.SafeHandles.SafeAccessTokenHandle token; >> if (!LogonUserW(username, domain, password, logonType, logonProvider, out token)) >> throw new System.ComponentModel.Win32Exception(); >> return token; >> } >> '@ PS C:\> $LOGON32_LOGON_BATCH = 4 PS C:\> $LOGON32_PROVIDER_DEFAULT = 0 PS C:\> $token = [Advapi32.Methods]::LogonUser("user", "domain", "pass", >> $LOGON32_LOGON_BATCH, $LOGON32_PROVIDER_DEFAULT) PS C:\> try { >> Start-ProcessWith powershell -Token $token >> } >> finally { >> $token.Dispose() >> }</dev:code> <dev:remarks> <maml:para>Creates a new PowerShell process running under a batch logon of a custom user. The token is created using PInvoke by calling `LogonUser`.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks> <maml:navigationLink> <maml:linkText>CreateProcessWithLogon</maml:linkText> <maml:uri>https://docs.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-createprocesswithlogonw</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>CreateProcessWithToken</maml:linkText> <maml:uri>https://docs.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-createprocesswithtokenw</maml:uri> </maml:navigationLink> <maml:navigationLink> <maml:linkText>Windows Privileges</maml:linkText> <maml:uri>https://docs.microsoft.com/en-us/windows/win32/secauthz/privilege-constants</maml:uri> </maml:navigationLink> </command:relatedLinks> </command:command> </helpItems> |