Skip to content

Commit d0ab688

Browse files
TaojunshenTaojunshen
authored
Merge pull request #11291 from MicrosoftDocs/main
7/23/2024 PM Publish
2 parents bfe884f + a38d38d commit d0ab688

File tree

5 files changed

+218
-190
lines changed

5 files changed

+218
-190
lines changed

‎reference/5.1/Microsoft.PowerShell.Core/About/about_PowerShell_exe.md‎

Lines changed: 87 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
description: Explains how to use the `powershell.exe` command-line interface. Displays the command-line parameters and describes the syntax.
33
Locale: en-US
4-
ms.date: 01/03/2024
4+
ms.date: 07/23/2024
55
no-no-loc: [-Command, -ConfigurationName , -EncodedCommand, -ExecutionPolicy, -File, -Help, -InputFormat, -Mta, -NoExit, -NoLogo, -NonInteractive, -NoProfile, -OutputFormat, -PSConsoleFile, -Sta, -Version, -WindowStyle]
66
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_powershell_exe?view=powershell-5.1&WT.mc_id=ps-gethelp
77
schema: 2.0.0
@@ -45,11 +45,71 @@ PowerShell[.exe] -Help | -? | /?
4545

4646
## Parameters
4747

48-
### -Command
48+
All parameters are case-insensitive.
49+
50+
### -File - | \<filePath\> \<args\>
51+
52+
The value of **File** can be `-` or a filepath and optional parameters. If the
53+
value of **File** is `-`, then commands are read from standard input.
54+
55+
If the value of **File** is a filepath, the script runs in the local scope
56+
("dot-sourced") of the new session, so that the functions and variables that
57+
the script creates are available in that new session. Enter the script filepath
58+
and any parameters. **File** _must_ be the last parameter in the command. All
59+
values typed after the **File** parameter are interpreted as the script
60+
filepath and parameters passed to that script. For example:
61+
`-File .\Get-Script.ps1 -Domain Central`
4962

50-
Executes the specified commands (and any parameters) as though they were typed
51-
at the PowerShell command prompt, and then exits, unless the `NoExit`
52-
parameter is specified.
63+
Typically, the switch parameters of a script are either included or omitted.
64+
For example, the following command uses the **All** parameter of the
65+
`Get-Script.ps1` script file: `-File .\Get-Script.ps1 -All`
66+
67+
In rare cases, you might need to provide a **Boolean** value for a parameter.
68+
It isn't possible to pass an explicit boolean value for a switch parameter when
69+
running a script in this way. This limitation was removed in PowerShell 6
70+
(`pwsh.exe`).
71+
72+
Parameters passed to the script are passed as literal strings, after
73+
interpretation by the current shell. For example, if you are in `cmd.exe` and
74+
want to pass an environment variable value, you would use the `cmd.exe` syntax:
75+
`powershell.exe -File .\test.ps1 -TestParam %windir%`
76+
77+
In contrast, running `powershell.exe -File .\test.ps1 -TestParam $env:windir`
78+
in `cmd.exe` results in the script receiving the literal string `$env:windir`
79+
because it has no special meaning to the current `cmd.exe` shell. The
80+
`$env:windir` style of environment variable reference _can_ be used inside a
81+
**Command** parameter, since there it's interpreted as PowerShell code.
82+
83+
Similarly, if you want to execute the same command from a _Batch script_, you
84+
would use `%~dp0` instead of `.\` or `$PSScriptRoot` to represent the current
85+
execution directory: `pwsh -File %~dp0test.ps1 -TestParam %windir%`. If you use
86+
`.\test.ps1` instead, PowerShell throws an error because it can't find the
87+
literal path `.\test.ps1`
88+
89+
> [!NOTE]
90+
> The **File** parameter can't support scripts using a parameter that expects
91+
> an array of argument values. This, unfortunately, is a limitation of how a
92+
> native command gets argument values. When you call a native executable (such
93+
> as `powershell` or `pwsh`), it doesn't know what to do with an array, so
94+
> it's passed as a string.
95+
96+
If the value of **File** is `-`, then commands are read from standard input.
97+
Running `powershell -File -` without redirected standard input starts a regular
98+
session. This is the same as not specifying the `File` parameter at all. When
99+
reading from standard input, the input statements are executed one statement at
100+
a time as though they were typed at the PowerShell command prompt. If a
101+
statement doesn't parse correctly, the statement isn't executed. The process
102+
exit code is determined by status of the last (executed) command. With
103+
successful execution, the exit code is always `0`. When the script file
104+
terminates with an `exit` command, the process exit code is set to the numeric
105+
argument used with the `exit` command.
106+
107+
Similar to `-Command`, when a script-terminating error occurs, the exit code is
108+
set to `1`. However, unlike with `-Command`, when the execution is interrupted
109+
with <kbd>Ctrl</kbd>+<kbd>C</kbd> the exit code is `0`. For more information,
110+
see `$LASTEXITCODE` in [about_Automatic_Variables][03].
111+
112+
### -Command
53113

54114
The value of **Command** can be `-`, a script block, or a string. If the value
55115
of **Command** is `-`, the command text is read from standard input.
@@ -66,10 +126,10 @@ powershell -Command {Get-WinEvent -LogName security}
66126
```
67127

68128
In `cmd.exe`, there is no such thing as a script block (or **ScriptBlock**
69-
type), so the value passed to **Command** will _always_ be a string. You can
70-
write a script block inside the string, but instead of being executed it will
71-
behave exactly as though you typed it at a typical PowerShell prompt, printing
72-
the contents of the script block back out to you.
129+
type), so the value passed to **Command** is _always_ a string. You can write a
130+
script block inside the string, but instead of being executed it behaves
131+
exactly as though you typed it at a typical PowerShell prompt, printing the
132+
contents of the script block back out to you.
73133

74134
A string passed to **Command** is still executed as PowerShell code, so the
75135
script block curly braces are often not required in the first place when
@@ -88,7 +148,7 @@ When called from within an existing PowerShell session, the results are
88148
returned to the parent shell as deserialized XML objects, not live objects. For
89149
other shells, the results are returned as strings.
90150

91-
If the value of **Command** is `-`, the command text is read from standard
151+
If the value of **Command** is `-`, the commands are read from standard
92152
input. You must redirect standard input when using the **Command** parameter
93153
with standard input. For example:
94154

@@ -111,18 +171,24 @@ hi there
111171
out
112172
```
113173

114-
The process exit code is determined by status of the last (executed) command
115-
within the script block. The exit code is `0` when `$?` is `$true` or `1` when
116-
`$?` is `$false`. If the last command is an external program or a PowerShell
117-
script that explicitly sets an exit code other than `0` or `1`, that exit code
118-
is converted to `1` for process exit code. To preserve the specific exit code,
119-
add `exit $LASTEXITCODE` to your command string or script block.
120-
121-
For more information, see `$LASTEXITCODE` in [about_Automatic_Variables][03].
174+
When reading from standard input, the input is parsed and executed one
175+
statement at a time, as though they were typed at the PowerShell command
176+
prompt. If the input code doesn't parse correctly, the statement isn't
177+
executed. Unless you use the `-NoExit` parameter, the PowerShell session exits
178+
when there is no more input to read from standard input.
122179

123-
Similarly, the value 1 is returned when a script-terminating
124-
(runspace-terminating) error, such as a `throw` or `-ErrorAction Stop`, occurs
125-
or when execution is interrupted with <kbd>Ctrl</kbd>+<kbd>C</kbd>.
180+
The process exit code is determined by status of the last (executed) command
181+
within the input. The exit code is `0` when `$?` is `$true` or `1` when `$?` is
182+
`$false`. If the last command is an external program or a PowerShell script
183+
that explicitly sets an exit code other than `0` or `1`, that exit code is
184+
converted to `1` for process exit code. Similarly, the value 1 is returned when
185+
a script-terminating (runspace-terminating) error, such as a `throw` or
186+
`-ErrorAction Stop`, occurs or when execution is interrupted with
187+
<kbd>Ctrl</kbd>+<kbd>C</kbd>.
188+
189+
To preserve the specific exit code, add `exit $LASTEXITCODE` to your command
190+
string or script block. For more information, see `$LASTEXITCODE` in
191+
[about_Automatic_Variables][02].
126192

127193
### -ConfigurationName \<string\>
128194

@@ -150,65 +216,6 @@ not change the PowerShell execution policy that's set in the registry. For
150216
information about PowerShell execution policies, including a list of valid
151217
values, see [about_Execution_Policies][04].
152218

153-
### -File - | \<filePath\> \<args\>
154-
155-
If the value of **File** is `-`, the command text is read from standard input.
156-
Running `powershell -File -` without redirected standard input starts a regular
157-
session. This is the same as not specifying the **File** parameter at all.
158-
159-
If the value of **File** is a filepath, the script runs in the local scope
160-
("dot-sourced") of the new session, so that the functions and variables that
161-
the script creates are available in that new session. Enter the script filepath
162-
and any parameters. **File** must be the last parameter in the command. All
163-
values typed after the **File** parameter are interpreted as the script
164-
filepath and parameters passed to that script.
165-
166-
Parameters passed to the script are passed as literal strings, after
167-
interpretation by the current shell. For example, if you are in **cmd.exe** and
168-
want to pass an environment variable value, you would use the **cmd.exe**
169-
syntax: `powershell.exe -File .\test.ps1 -TestParam %windir%`
170-
171-
In contrast, running `powershell.exe -File .\test.ps1 -TestParam $env:windir`
172-
in **cmd.exe** results in the script receiving the literal string `$env:windir`
173-
because it has no special meaning to the current **cmd.exe** shell. The
174-
`$env:windir` style of environment variable reference _can_ be used inside a
175-
**Command** parameter, since there it will be interpreted as PowerShell code.
176-
177-
Similarly, if you want to execute the same command from a **Batch script**, you
178-
would use `%~dp0` instead of `.\` or `$PSScriptRoot` to represent the current
179-
execution directory: `powershell.exe -File %~dp0test.ps1 -TestParam %windir%`.
180-
If you instead used `.\test.ps1`, PowerShell would throw an error because it
181-
can't find the literal path `.\test.ps1`
182-
183-
When the value of **File** is a filepath, **File** _must_ be the last parameter
184-
in the command because any characters typed after the **File** parameter name
185-
are interpreted as the script filepath followed by the script parameters.
186-
187-
You can include the script parameters and values in the value of the **File**
188-
parameter. For example: `-File .\Get-Script.ps1 -Domain Central`
189-
190-
Typically, the switch parameters of a script are either included or omitted.
191-
For example, the following command uses the **All** parameter of the
192-
`Get-Script.ps1` script file: `-File .\Get-Script.ps1 -All`
193-
194-
In rare cases, you might need to provide a **Boolean** value for a parameter.
195-
It isn't possible to pass an explicit boolean value for a switch parameter when
196-
running a script in this way. This limitation was removed in PowerShell 6
197-
(`pwsh.exe`).
198-
199-
> [!NOTE]
200-
> The **File** parameter can't support scripts using a parameter that expects
201-
> an array of argument values. This, unfortunately, is a limitation of how a
202-
> native command gets argument values. When you call a native executable (such
203-
> as `powershell` or `pwsh`), it doesn't know what to do with an array, so
204-
> it's passed as a string.
205-
206-
When the script file terminates with an `exit` command, the process exit code
207-
is set to the numeric argument used with the `exit` command. With normal
208-
termination, the exit code is always `0`.
209-
210-
For more information, see `$LASTEXITCODE` in [about_Automatic_Variables][03].
211-
212219
### -InputFormat {Text | XML}
213220

214221
Describes the format of data sent to PowerShell. Valid values are `Text` (text

‎reference/7.2/Microsoft.PowerShell.Core/About/about_Pwsh.md‎

Lines changed: 38 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
description: Explains how to use the `pwsh` command-line interface. Displays the command-line parameters and describes the syntax.
33
Locale: en-US
4-
ms.date: 01/10/2024
4+
ms.date: 07/23/2024
55
no-loc: [-File, -f, -Command, -c, -ConfigurationName, -config, -CustomPipeName, -EncodedCommand, -e, -ec, -ExecutionPolicy, -ex, -ep, -InputFormat, -inp, -if, -Interactive, -i, -Login, -l, -MTA, -NoExit, -noe, -NoLogo, -nol, -NonInteractive, -noni, -NoProfile, -nop, -OutputFormat, -o, -of, -SettingsFile, -settings, -SSHServerMode, -sshs, -STA, -Version, -v, -WindowStyle, -w, -WorkingDirectory, -wd, -Help]
66
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_pwsh?view=powershell-7.2&WT.mc_id=ps-gethelp
77
schema: 2.0.0
@@ -55,9 +55,8 @@ All parameters are case-insensitive.
5555

5656
### -File | -f
5757

58-
If the value of `File` is `-`, the command text is read from standard input.
59-
Running `pwsh -File -` without redirected standard input starts a regular
60-
session. This is the same as not specifying the `File` parameter at all.
58+
The value of **File** can be `-` or a filepath and optional parameters. If the
59+
value of **File** is `-`, then commands are read from standard input.
6160

6261
This is the default parameter if no parameters are present but values are
6362
present in the command line. The specified script runs in the local scope
@@ -68,8 +67,8 @@ characters typed after the File parameter name are interpreted as the script
6867
filepath followed by the script parameters.
6968

7069
Typically, the switch parameters of a script are either included or omitted.
71-
For example, the following command uses the All parameter of the
72-
Get-Script.ps1 script file: `-File .\Get-Script.ps1 -All`
70+
For example, the following command uses the **All** parameter of the
71+
`Get-Script.ps1` script file: `-File .\Get-Script.ps1 -All`
7372

7473
In rare cases, you might need to provide a **Boolean** value for a switch
7574
parameter. To provide a **Boolean** value for a switch parameter in the value
@@ -91,8 +90,8 @@ because it has no special meaning to the current `cmd.exe` shell. The
9190
Similarly, if you want to execute the same command from a _Batch script_, you
9291
would use `%~dp0` instead of `.\` or `$PSScriptRoot` to represent the current
9392
execution directory: `pwsh -File %~dp0test.ps1 -TestParam %windir%`. If you
94-
instead used `.\test.ps1`, PowerShell would throw an error because it can't
95-
find the literal path `.\test.ps1`
93+
use `.\test.ps1` instead, PowerShell throws an error because it can't find the
94+
literal path `.\test.ps1`
9695

9796
> [!NOTE]
9897
> The **File** parameter can't support scripts using a parameter that expects
@@ -101,15 +100,21 @@ find the literal path `.\test.ps1`
101100
> as `powershell` or `pwsh`), it doesn't know what to do with an array, so
102101
> it's passed as a string.
103102
104-
When the script file terminates with an `exit` command, the process exit code
105-
is set to the numeric argument used with the `exit` command. With normal
106-
termination, the exit code is always `0`.
107-
108-
For more information, see `$LASTEXITCODE` in [about_Automatic_Variables][02].
103+
If the value of **File** is `-`, then commands are read from standard input.
104+
Running `pwsh -File -` without redirected standard input starts a regular
105+
session. This is the same as not specifying the `File` parameter at all. When
106+
reading from standard input, the input statements are executed one statement at
107+
a time as though they were typed at the PowerShell command prompt. If a
108+
statement doesn't parse correctly, the statement isn't executed. The process exit code is
109+
determined by status of the last (executed) command within the input. With
110+
normal termination, the exit code is always `0`. When the script file
111+
terminates with an `exit` command, the process exit code is set to the numeric
112+
argument used with the `exit` command.
109113

110114
Similar to `-Command`, when a script-terminating error occurs, the exit code is
111115
set to `1`. However, unlike with `-Command`, when the execution is interrupted
112-
with <kbd>Ctrl</kbd>+<kbd>C</kbd> the exit code is `0`.
116+
with <kbd>Ctrl</kbd>+<kbd>C</kbd> the exit code is `0`. For more information,
117+
see `$LASTEXITCODE` in [about_Automatic_Variables][02].
113118

114119
> [!NOTE]
115120
> As of PowerShell 7.2, the **File** parameter only accepts `.ps1` files on
@@ -119,10 +124,6 @@ with <kbd>Ctrl</kbd>+<kbd>C</kbd> the exit code is `0`.
119124
120125
### -Command | -c
121126

122-
Executes the specified commands (and any parameters) as though they were typed
123-
at the PowerShell command prompt, and then exits, unless the `NoExit`
124-
parameter is specified.
125-
126127
The value of **Command** can be `-`, a script block, or a string. If the value
127128
of **Command** is `-`, the command text is read from standard input.
128129

@@ -160,7 +161,7 @@ When called from within an existing PowerShell session, the results are
160161
returned to the parent shell as deserialized XML objects, not live objects. For
161162
other shells, the results are returned as strings.
162163

163-
If the value of **Command** is `-`, the command text is read from standard
164+
If the value of **Command** is `-`, the commands are read from standard
164165
input. You must redirect standard input when using the **Command** parameter
165166
with standard input. For example:
166167

@@ -172,7 +173,7 @@ with standard input. For example:
172173
% { "$_ there" }
173174
174175
"out"
175-
'@ | powershell -NoProfile -Command -
176+
'@ | pwsh -NoProfile -Command -
176177
```
177178

178179
This example produces the following output:
@@ -183,18 +184,24 @@ hi there
183184
out
184185
```
185186

186-
The process exit code is determined by status of the last (executed) command
187-
within the script block. The exit code is `0` when `$?` is `$true` or `1` when
188-
`$?` is `$false`. If the last command is an external program or a PowerShell
189-
script that explicitly sets an exit code other than `0` or `1`, that exit code
190-
is converted to `1` for process exit code. To preserve the specific exit code,
191-
add `exit $LASTEXITCODE` to your command string or script block.
192-
193-
For more information, see `$LASTEXITCODE` in [about_Automatic_Variables][02].
187+
When reading from standard input, the input is parsed and executed one
188+
statement at a time, as though they were typed at the PowerShell command
189+
prompt. If the input code doesn't parse correctly, the statement isn't
190+
executed. Unless you use the `-NoExit` parameter, the PowerShell session exits
191+
when there is no more input to read from standard input.
194192

195-
Similarly, the value 1 is returned when a script-terminating
196-
(runspace-terminating) error, such as a `throw` or `-ErrorAction Stop`, occurs
197-
or when execution is interrupted with <kbd>Ctrl</kbd>+<kbd>C</kbd>.
193+
The process exit code is determined by status of the last (executed) command
194+
within the input. The exit code is `0` when `$?` is `$true` or `1` when `$?` is
195+
`$false`. If the last command is an external program or a PowerShell script
196+
that explicitly sets an exit code other than `0` or `1`, that exit code is
197+
converted to `1` for process exit code. Similarly, the value 1 is returned when
198+
a script-terminating (runspace-terminating) error, such as a `throw` or
199+
`-ErrorAction Stop`, occurs or when execution is interrupted with
200+
<kbd>Ctrl</kbd>+<kbd>C</kbd>.
201+
202+
To preserve the specific exit code, add `exit $LASTEXITCODE` to your command
203+
string or script block. For more information, see `$LASTEXITCODE` in
204+
[about_Automatic_Variables][02].
198205

199206
### -ConfigurationName | -config
200207

0 commit comments

Comments
 (0)