Skip to content

Commit 00b0f30

Browse files
sdwheelersdwheeler
authored
Fixes #11098 - REPL behavior only applies to standard input scenarios (#11289)
* REPL behavior only applies to standard input scenarios * More editorial
1 parent 2330fe7 commit 00b0f30

File tree

4 files changed

+186
-178
lines changed

4 files changed

+186
-178
lines changed

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

Lines changed: 84 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -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`
62+
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`).
4971

50-
Executes the specified commands (and any parameters), one statement at a time,
51-
as though they were typed at the PowerShell command prompt, and then exits,
52-
unless the `NoExit` parameter is specified.
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,19 +171,24 @@ hi there
111171
out
112172
```
113173

114-
If the input code does not parse correctly, the statement isn't executed. The
115-
process exit code is determined by status of the last (executed) command within
116-
the script block. The exit code is `0` when `$?` is `$true` or `1` when `$?` is
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.
179+
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
117182
`$false`. If the last command is an external program or a PowerShell script
118183
that explicitly sets an exit code other than `0` or `1`, that exit code is
119-
converted to `1` for process exit code. To preserve the specific exit code, add
120-
`exit $LASTEXITCODE` to your command string or script block.
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>.
121188

122-
For more information, see `$LASTEXITCODE` in [about_Automatic_Variables][03].
123-
124-
Similarly, the value 1 is returned when a script-terminating
125-
(runspace-terminating) error, such as a `throw` or `-ErrorAction Stop`, occurs
126-
or when execution is interrupted with <kbd>Ctrl</kbd>+<kbd>C</kbd>.
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].
127192

128193
### -ConfigurationName \<string\>
129194

@@ -151,69 +216,6 @@ not change the PowerShell execution policy that's set in the registry. For
151216
information about PowerShell execution policies, including a list of valid
152217
values, see [about_Execution_Policies][04].
153218

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

219221
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: 34 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -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,19 +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-
The statements in the file are executed, one statement at a time, as though
105-
they were typed at the PowerShell command prompt. If a statement in the file
106-
doesn't parse correctly, the statement isn't executed. The process exit code is
107-
determined by status of the last (executed) command within the script block.
108-
With normal termination, the exit code is always `0`. When the script file
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
109111
terminates with an `exit` command, the process exit code is set to the numeric
110112
argument used with the `exit` command.
111113

112-
For more information, see `$LASTEXITCODE` in [about_Automatic_Variables][02].
113-
114114
Similar to `-Command`, when a script-terminating error occurs, the exit code is
115115
set to `1`. However, unlike with `-Command`, when the execution is interrupted
116-
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].
117118

118119
> [!NOTE]
119120
> As of PowerShell 7.2, the **File** parameter only accepts `.ps1` files on
@@ -123,10 +124,6 @@ with <kbd>Ctrl</kbd>+<kbd>C</kbd> the exit code is `0`.
123124
124125
### -Command | -c
125126

126-
Executes the specified commands (and any parameters), one statement at a time,
127-
as though they were typed at the PowerShell command prompt, and then exits,
128-
unless the `NoExit` parameter is specified.
129-
130127
The value of **Command** can be `-`, a script block, or a string. If the value
131128
of **Command** is `-`, the command text is read from standard input.
132129

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

167-
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
168165
input. You must redirect standard input when using the **Command** parameter
169166
with standard input. For example:
170167

@@ -176,7 +173,7 @@ with standard input. For example:
176173
% { "$_ there" }
177174
178175
"out"
179-
'@ | powershell -NoProfile -Command -
176+
'@ | pwsh -NoProfile -Command -
180177
```
181178

182179
This example produces the following output:
@@ -187,19 +184,24 @@ hi there
187184
out
188185
```
189186

190-
If the input code does not parse correctly, the statement isn't executed. The
191-
process exit code is determined by status of the last (executed) command within
192-
the script block. The exit code is `0` when `$?` is `$true` or `1` when `$?` is
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.
192+
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
193195
`$false`. If the last command is an external program or a PowerShell script
194196
that explicitly sets an exit code other than `0` or `1`, that exit code is
195-
converted to `1` for process exit code. To preserve the specific exit code, add
196-
`exit $LASTEXITCODE` to your command string or script block.
197-
198-
For more information, see `$LASTEXITCODE` in [about_Automatic_Variables][02].
199-
200-
Similarly, the value 1 is returned when a script-terminating
201-
(runspace-terminating) error, such as a `throw` or `-ErrorAction Stop`, occurs
202-
or when execution is interrupted with <kbd>Ctrl</kbd>+<kbd>C</kbd>.
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].
203205

204206
### -ConfigurationName | -config
205207

0 commit comments

Comments
 (0)