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 escaping logic is based on the Windows C argument standard rules but some applications may not use this standard.</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:syntaxItem> </command:syntax> <command:parameters> <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: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 --------------------------</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: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> </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="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="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: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: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: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: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:syntaxItem> </command:syntax> <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:syntaxItem> </command:syntax> <command:parameters> <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>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: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="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="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="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="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: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="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: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="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="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="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="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="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="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="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="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> |