Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fixes #6239 - Document appropriate use of Start-Process #9168

Merged
merged 3 commits into from
Aug 25, 2022
Merged

Fixes #6239 - Document appropriate use of Start-Process #9168

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
92820f5
Document appropriate use of Start-Process
sdwheeler Aug 25, 2022
f9b72a4
Fix example 8 parameter usage
sdwheeler Aug 25, 2022
6e2b16a
Fix typos
sdwheeler Aug 25, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 58 additions & 29 deletions reference/5.1/Microsoft.PowerShell.Management/Start-Process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml
Locale: en-US
Module Name: Microsoft.PowerShell.Management
ms.date: 09/20/2021
ms.date: 08/25/2022
online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/start-process?view=powershell-5.1&WT.mc_id=ps-gethelp
schema: 2.0.0
title: Start-Process
Expand Down Expand Up @@ -38,8 +38,8 @@ The `Start-Process` cmdlet starts one or more processes on the local computer. B
in the current process.

To specify the program that runs in the process, enter an executable file or script file, or a file
that can be opened by using a program on the computer. If you specify a non-executable file,
`Start-Process` starts the program that is associated with the file, similar to the `Invoke-Item`
that can be opened using a program on the computer. If you specify a non-executable file,
`Start-Process` starts the program that's associated with the file, similar to the `Invoke-Item`
cmdlet.

You can use the parameters of `Start-Process` to specify options, such as loading a user profile,
Expand All @@ -50,7 +50,7 @@ starting the process in a new window, or using alternate credentials.
### Example 1: Start a process that uses default values

This example starts a process that uses the `Sort.exe` file in the current folder. The command uses
all of the default values, including the default window style, working folder, and credentials.
all the default values, including the default window style, working folder, and credentials.

```powershell
Start-Process -FilePath "sort.exe"
Expand All @@ -66,7 +66,7 @@ Start-Process -FilePath "myfile.txt" -WorkingDirectory "C:\PS-Test" -Verb Print

### Example 3: Start a process to sort items to a new file

This example starts a process that sorts items in the `Testsort.txt` file and returns the sorted
This example starts a process that sorts items in the `TestSort.txt` file and returns the sorted
items in the `Sorted.txt` files. Any errors are written to the `SortError.txt` file. The
**UseNewEnvironment** parameter specifies that the process runs with its own environment variables.

Expand Down Expand Up @@ -95,7 +95,7 @@ Start-Process -FilePath "notepad" -Wait -WindowStyle Maximized

### Example 5: Start PowerShell as an administrator

This example starts PowerShell by using the **Run as administrator** option.
This example starts PowerShell using the **Run as administrator** option.

```powershell
Start-Process -FilePath "powershell" -Verb RunAs
Expand All @@ -107,7 +107,7 @@ This example shows how to find the verbs that can be used when starting a proces
verbs are determined by the filename extension of the file that runs in the process.

```powershell
$startExe = New-Object System.Diagnostics.ProcessStartInfo -Args PowerShell.exe
$startExe = New-Object System.Diagnostics.ProcessStartInfo -Args powershell.exe
$startExe.verbs
```

Expand All @@ -118,9 +118,9 @@ runasuser
```

The example uses `New-Object` to create a **System.Diagnostics.ProcessStartInfo** object for
**PowerShell.exe**, the file that runs in the PowerShell process. The **Verbs** property of the
**ProcessStartInfo** object shows that you can use the **Open** and **RunAs** verbs with
`PowerShell.exe`, or with any process that runs a `.exe` file.
`powershell.exe`, the file that runs in the PowerShell process. The **Verbs** property of the
**ProcessStartInfo** object shows that you can use the **Open** and `RunAs` verbs with
`powershell.exe`, or with any process that runs a `.exe` file.

### Example 7: Specifying arguments to the process

Expand All @@ -130,10 +130,30 @@ Note that the first command specifies a string as **ArgumentList**. The second c
array.

```powershell
Start-Process -FilePath "$env:comspec" -ArgumentList "/c dir `"%systemdrive%\program files`""
Start-Process -FilePath "$env:comspec" -ArgumentList "/c","dir","`"%systemdrive%\program files`""
Start-Process -FilePath "$env:comspec" -ArgumentList "/c dir `"%SystemDrive%\Program Files`""
Start-Process -FilePath "$env:comspec" -ArgumentList "/c","dir","`"%SystemDrive%\Program Files`""
```

### Example 8: Run a command as an Administrator using alternate credentials

On Windows, you can run `Start-Process -Verb RunAs` to start a process with elevated permissions.
This elevates the current user's context. The **Credential** parameter allows you to specify an
alternate username and password, allowing you to start a process in a different user content.
However, the **Credential** and **Verb** parameters can't be used together.

To start a process with elevated rights, using alternate credentials, you must first start
PowerShell using the alternate credentials, then use `Start-Process` to start the process with
elevated rights.

```powershell
$cred = Get-Credential
$args = '-noprofile -command "Start-Process cmd.exe -Verb RunAs -args /k"'
Start-Process pwsh.exe -Credential $cred -WindowStyle Hidden -ArgumentList $args
```

The example starts `cmd.exe` with elevated permissions from a PowerShell session that is running
under alternate credentials.

## PARAMETERS

### -ArgumentList
Expand All @@ -143,12 +163,12 @@ be accepted as a single string with the arguments separated by spaces, or as an
separated by commas. The cmdlet joins the array into a single string with each element of the array
separated by a single space.

The outer quotes of the PowerShell strings are not included when the **ArgumentList** values are
The outer quotes of the PowerShell strings aren't included when the **ArgumentList** values are
passed to the new process. If parameters or parameter values contain a space or quotes, they need to
be surrounded with escaped double quotes. For more information, see
[about_Quoting_Rules](../Microsoft.PowerShell.Core/About/about_Quoting_Rules.md).

For the best results, use a single **ArgumentList** value containing all of the arguments and any
For the best results, use a single **ArgumentList** value containing all the arguments and any
needed quote characters.

```yaml
Expand Down Expand Up @@ -194,7 +214,7 @@ Accept wildcard characters: False
### -FilePath

Specifies the optional path and filename of the program that runs in the process. Enter the name of
an executable file or of a document, such as a `.txt` or `.doc` file, that is associated with a
an executable file or of a document, such as a `.txt` or `.doc` file, that's associated with a
program on the computer. This parameter is required.

If you specify only a filename, use the **WorkingDirectory** parameter to specify the path.
Expand All @@ -216,7 +236,7 @@ Accept wildcard characters: False
Indicates that this cmdlet loads the Windows user profile stored in the `HKEY_USERS` registry key
for the current user.

This parameter does not affect the PowerShell profiles. For more information, see
This parameter doesn't affect the PowerShell profiles. For more information, see
[about_Profiles](../Microsoft.PowerShell.Core/About/about_Profiles.md).

```yaml
Expand All @@ -236,7 +256,7 @@ Accept wildcard characters: False
Start the new process in the current console window. By default on Windows, PowerShell opens a new
window.

You cannot use the **NoNewWindow** and **WindowStyle** parameters in the same command.
You can't use the **NoNewWindow** and **WindowStyle** parameters in the same command.

```yaml
Type: System.Management.Automation.SwitchParameter
Expand All @@ -252,7 +272,7 @@ Accept wildcard characters: False

### -PassThru

Returns a process object for each process that the cmdlet started. By default, this cmdlet does not
Returns a process object for each process that the cmdlet started. By default, this cmdlet doesn't
generate any output.

```yaml
Expand Down Expand Up @@ -385,11 +405,15 @@ Accept wildcard characters: False

### -WindowStyle

Specifies the state of the window that is used for the new process. The acceptable values for this
parameter are: **Normal**, **Hidden**, **Minimized**, and **Maximized**. The default value is
**Normal**.
Specifies the state of the window that's used for the new process. The default value is `Normal`.
The acceptable values for this parameter are:

You cannot use the **WindowStyle** and **NoNewWindow** parameters in the same command.
- `Normal`
- `Hidden`
- `Minimized`
- `Maximized`

You can't use the **WindowStyle** and **NoNewWindow** parameters in the same command.

```yaml
Type: System.Diagnostics.ProcessWindowStyle
Expand All @@ -407,8 +431,8 @@ Accept wildcard characters: False
### -WorkingDirectory

Specifies the location that the new process should start in. The default is the location of the
executable file or document being started. Wildcards are not supported. The path name must not
contain characters that would be interpreted as wildcards.
executable file or document being started. Wildcards aren't supported. The path must not contain
characters that would be interpreted as wildcards.

```yaml
Type: System.String
Expand All @@ -433,24 +457,29 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable

### None

You cannot pipe input to this cmdlet.
You can't pipe input to this cmdlet.

## OUTPUTS

### None, System.Diagnostics.Process

This cmdlet generates a **System.Diagnostics.Process** object, if you specify the **PassThru**
parameter. Otherwise, this cmdlet does not return any output.
parameter. Otherwise, this cmdlet doesn't return any output.

## NOTES

Native commands are executable files installed in the operating system. These executables can be run
from any command-line shell, like PowerShell. Usually you run the command exactly as you would in
`bash` or `cmd.exe`. The `Start-Process` cmdlet can be used to run any native commands, but should
only be used when you need to control how the command is executed.

By default, `Start-Process` launches a process _asynchronously_. Control is instantly returned to
PowerShell even if the new process is still running.

- On the local system, the launched process lives on independent from the calling process.
- On a remote system, the new process is terminated when the remote session ends, immediately
following the `Start-Process` command. Therefore, you cannot use `Start-Process` in a remote session
expecting the launched process to outlive the session.
following the `Start-Process` command. Therefore, you can't use `Start-Process` in a remote
session expecting the launched process to outlive the session.

If you do need to use `Start-Process` in a remote session, invoke it with the **Wait** parameter. Or
you could use other methods to create a new process on the remote system.
Expand All @@ -463,7 +492,7 @@ On Windows, the most common use case for `Start-Process` is to use the **Wait**
progress until the new process exits. On non-Windows system, this is rarely needed since the default
behavior for command-line applications is equivalent to `Start-Process -Wait`.

This cmdlet is implemented by using the **Start** method of the **System.Diagnostics.Process**
This cmdlet is implemented using the **Start** method of the **System.Diagnostics.Process**
class. For more information about this method, see
[Process.Start Method](/dotnet/api/system.diagnostics.process.start#overloads).

Expand Down
Loading