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

Jump to bottom

3/26/2024 PM Publish #10985

Merged
merged 1 commit into from
Mar 26, 2024
Merged

3/26/2024 PM Publish #10985

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
174 changes: 79 additions & 95 deletions reference/5.1/Microsoft.PowerShell.Core/About/about_CommonParameters.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
description: Describes the parameters that can be used with any cmdlet.
Locale: en-US
ms.date: 01/21/2022
ms.date: 03/25/2024
no-loc: [Debug, Verbose, Confirm]
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_commonparameters?view=powershell-5.1&WT.mc_id=ps-gethelp
schema: 2.0.0
Expand Down Expand Up @@ -81,7 +81,6 @@ example, this parameter works when a command contains the `Write-Debug` cmdlet.
```yaml
Type: SwitchParameter
Aliases: db

Required: False
Position: Named
Default value: False
Expand Down Expand Up @@ -132,27 +131,22 @@ The **ErrorAction** parameter has no effect on terminating errors (such as
missing data, parameters that aren't valid, or insufficient permissions) that
prevent a command from completing successfully.

`-ErrorAction:Break` Enters the debugger when an error occurs or an exception
is raised.

`-ErrorAction:Continue` displays the error message and continues executing the
command. `Continue` is the default.

`-ErrorAction:Ignore` suppresses the error message and continues executing the
command. Unlike **SilentlyContinue**, **Ignore** doesn't add the error message
to the `$Error` automatic variable. The **Ignore** value is introduced in
PowerShell 3.0.

`-ErrorAction:Inquire` displays the error message and prompts you for
confirmation before continuing execution. This value is rarely used.

`-ErrorAction:SilentlyContinue` suppresses the error message and continues
executing the command.

`-ErrorAction:Stop` displays the error message and stops executing the command.

`-ErrorAction:Suspend` is only available for workflows which aren't supported
in PowerShell 6 and beyond.
- `-ErrorAction:Break` Enters the debugger when an error occurs or an exception
is raised.
- `-ErrorAction:Continue` displays the error message and continues executing
the command. `Continue` is the default.
- `-ErrorAction:Ignore` suppresses the error message and continues executing
the command. Unlike **SilentlyContinue**, **Ignore** doesn't add the error
message to the `$Error` automatic variable. The **Ignore** value is
introduced in PowerShell 3.0.
- `-ErrorAction:Inquire` displays the error message and prompts you for
confirmation before continuing execution. This value is rarely used.
- `-ErrorAction:SilentlyContinue` suppresses the error message and continues
executing the command.
- `-ErrorAction:Stop` displays the error message and stops executing the
command.
- `-ErrorAction:Suspend` is only available for workflows which aren't supported
in PowerShell 6 and beyond.

> [!NOTE]
> The **ErrorAction** parameter overrides, but doesn't replace the value of the
Expand All @@ -161,14 +155,16 @@ in PowerShell 6 and beyond.

### -ErrorVariable

**ErrorVariable** stores error messages about the command in the specified
variable and in the `$Error` automatic variable. For more information, see
[about_Automatic_Variables][02]
Error records are automatically store in the `$Error` automatic variable. For
more information, see [about_Automatic_Variables][02].

When you use the **ErrorVariable** parameter on a command, PowerShell also
stores the error records emitted by the command in the variable specified by
the parameter.

```yaml
Type: String
Aliases: ev

Required: False
Position: Named
Default value: None
Expand All @@ -177,7 +173,7 @@ Accept wildcard characters: False
```

By default, new error messages overwrite error messages that are already stored
in the variable. To append the error message to the variable content, type a
in the variable. To append the error message to the variable content, put a
plus sign (`+`) before the variable name.

For example, the following command creates the `$a` variable and then stores any
Expand Down Expand Up @@ -231,25 +227,23 @@ Accept pipeline input: False
Accept wildcard characters: False
```

`-InformationAction:Stop` stops a command or script at an occurrence of the
`Write-Information` command.

`-InformationAction:Ignore` suppresses the informational message and continues
running the command. Unlike **SilentlyContinue**, **Ignore** completely forgets the
informational message; it doesn't add the informational message to the
information stream.

`-InformationAction:Inquire` displays the informational message that you specify
in a `Write-Information` command, then asks whether you want to continue.

`-InformationAction:Continue` displays the informational message, and continues
running.

`-InformationAction:Suspend` isn't supported on PowerShell 6 and higher as it
is only available for workflows.

`-InformationAction:SilentlyContinue` no effect as the informational message
aren't (Default) displayed, and the script continues without interruption.
- `-InformationAction:Break` Enters the debugger at an occurrence of the
`Write-Information` command.
- `-InformationAction:Stop` stops a command or script at an occurrence of the
`Write-Information` command.
- `-InformationAction:Ignore` suppresses the informational message and
continues running the command. Unlike **SilentlyContinue**, **Ignore**
completely forgets the informational message; it doesn't add the
informational message to the information stream.
- `-InformationAction:Inquire` displays the informational message that you
specify in a `Write-Information` command, then asks whether you want to
continue.
- `-InformationAction:Continue` displays the informational message, and
continues running.
- `-InformationAction:Suspend` isn't supported on PowerShell 6 and higher as it
is only available for workflows.
- `-InformationAction:SilentlyContinue` no effect as the informational message
aren't (Default) displayed, and the script continues without interruption.

> [!NOTE]
> The **InformationAction** parameter overrides, but doesn't replace the
Expand All @@ -258,13 +252,16 @@ aren't (Default) displayed, and the script continues without interruption.

### -InformationVariable

Introduced in PowerShell 5.0. Within the command or script in which it's used,
the **InformationVariable** common parameter stores in a variable a string that
you specify by adding the `Write-Information` command. `Write-Information`
values are shown depending on the value of the **InformationAction** common
parameter; if you don't add the **InformationAction** common parameter,
`Write-Information` strings are shown depending on the value of the
`$InformationPreference` preference variable. For more information about
Introduced in PowerShell 5.0. When you use the **InformationVariable** common
parameter, information records are stored in a the variable specify by the
parameter. And PowerShell cmdlet can write information records to the
**Information** stream. You can also use the `Write-Information` cmdlet to
write information records.

Information records are displayed as messages in the console by default. You
can control the display of information record by using the
**InformationAction** common parameter. You can also change the behavior using
the `$InformationPreference` preference variable. For more information about
`$InformationPreference`, see [about_Preference_Variables][03].

> [!NOTE]
Expand All @@ -275,14 +272,17 @@ parameter; if you don't add the **InformationAction** common parameter,
```yaml
Type: String
Aliases: iv

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
```

By default, new information record overwrite values that are already stored in
the variable. To append the error message to the variable content, put a plus
sign (`+`) before the variable name.

### -OutBuffer

Determines the number of objects to accumulate in a buffer before any objects
Expand All @@ -292,7 +292,6 @@ they're generated.
```yaml
Type: Int32
Aliases: ob

Required: False
Position: Named
Default value: None
Expand Down Expand Up @@ -334,7 +333,6 @@ to sending the output along the pipeline.
```yaml
Type: String
Aliases: ov

Required: False
Position: Named
Default value: None
Expand Down Expand Up @@ -393,7 +391,6 @@ allows a command to _feed back_ its output to a previous command (or itself).
```yaml
Type: String
Aliases: pv

Required: False
Position: Named
Default value: None
Expand Down Expand Up @@ -481,7 +478,6 @@ this parameter works when a command contains the `Write-Verbose` cmdlet.
```yaml
Type: SwitchParameter
Aliases: vb

Required: False
Position: Named
Default value: False
Expand All @@ -494,11 +490,10 @@ variable for the current command. Because the default value of the
`$VerbosePreference` variable is **SilentlyContinue**, verbose messages aren't
displayed by default.

`-Verbose:$true` has the same effect as `-Verbose`

`-Verbose:$false` suppresses the display of verbose messages. Use this
parameter when the value of `$VerbosePreference` isn't **SilentlyContinue**
(the default).
- `-Verbose:$true` has the same effect as `-Verbose`
- `-Verbose:$false` suppresses the display of verbose messages. Use this
parameter when the value of `$VerbosePreference` isn't **SilentlyContinue**
(the default).

### -WarningAction

Expand All @@ -524,17 +519,15 @@ variable for the current command. Because the default value of the
`$WarningPreference` variable is **Continue**, warnings are displayed and
execution continues unless you use the **WarningAction** parameter.

`-WarningAction:Continue` displays the warning messages and continues executing
the command. `Continue` is the default.

`-WarningAction:Inquire` displays the warning message and prompts you for
confirmation before continuing execution. This value is rarely used.

`-WarningAction:SilentlyContinue` suppresses the warning message and continues
executing the command.

`-WarningAction:Stop` displays the warning message and stops executing the
command.
- `-WarningAction:Break` enters the debugger when a warning occurs.
- `-WarningAction:Continue` displays the warning messages and continues
executing the command. `Continue` is the default.
- `-WarningAction:Inquire` displays the warning message and prompts you for
confirmation before continuing execution. This value is rarely used.
- `-WarningAction:SilentlyContinue` suppresses the warning message and
continues executing the command.
- `-WarningAction:Stop` displays the warning message and stops executing the
command.

> [!NOTE]
> The **WarningAction** parameter overrides, but doesn't replace the value of
Expand All @@ -543,12 +536,11 @@ command.

### -WarningVariable

Stores warnings about the command in the specified variable.
Stores warning records about the command in the specified variable.

```yaml
Type: String
Aliases: wv

Required: False
Position: Named
Default value: None
Expand Down Expand Up @@ -600,7 +592,6 @@ executing the command.
```yaml
Type: SwitchParameter
Aliases: wi

Required: False
Position: Named
Default value: False
Expand All @@ -614,10 +605,9 @@ variable for the current command. Because the default value of the
without the **WhatIf** parameter. For more information, see
[about_Preference_Variables][03].

`-WhatIf:$true` has the same effect as `-WhatIf`.

`-WhatIf:$false` suppresses the automatic WhatIf behavior that results when the
value of the `$WhatIfPreference` variable is 1.
- `-WhatIf:$true` has the same effect as `-WhatIf`.
- `-WhatIf:$false` suppresses the automatic WhatIf behavior that results when
the value of the `$WhatIfPreference` variable is 1.

For example, the following command uses the `-WhatIf` parameter in a
`Remove-Item` command:
Expand All @@ -629,7 +619,7 @@ Remove-Item Date.csv -WhatIf
Instead of removing the item, PowerShell lists the operations it would do and
the items that would be affected. This command produces the following output:

```output
```Output
What if: Performing operation "Remove File" on
Target "C:\ps-test\date.csv".
```
Expand All @@ -641,7 +631,6 @@ Prompts you for confirmation before executing the command.
```yaml
Type: SwitchParameter
Aliases: cf

Required: False
Position: Named
Default value: Depends on preference variable
Expand All @@ -653,18 +642,17 @@ The **Confirm** parameter overrides the value of the `$ConfirmPreference`
variable for the current command. The default value is true. For more
information, see [about_Preference_Variables][03].

`-Confirm:$true` has the same effect as `-Confirm`.

`-Confirm:$false` suppresses automatic confirmation, which occurs when the
value of `$ConfirmPreference` is less than or equal to the estimated risk of
the cmdlet.
- `-Confirm:$true` has the same effect as `-Confirm`.
- `-Confirm:$false` suppresses automatic confirmation, which occurs when the
value of `$ConfirmPreference` is less than or equal to the estimated risk of
the cmdlet.

For example, the following command uses the **Confirm** parameter with a
`Remove-Item` command. Before removing the item, PowerShell lists the
operations it would do and the items that would be affected, and asks for
approval.

```
```powershell
PS C:\ps-test> Remove-Item tmp*.txt -Confirm

Confirm
Expand Down Expand Up @@ -699,7 +687,7 @@ temporarily while the user checks the help for a command parameter. After
obtaining the needed information, the user types "exit" to end the nested
prompt and then selects the Yes (y) response to the Confirm query.

```
```powershell
PS C:\ps-test> New-Item -ItemType File -Name Test.txt -Confirm

Confirm
Expand Down Expand Up @@ -737,10 +725,6 @@ Mode LastWriteTime Length Name
-a--- 8/27/2010 2:41 PM 0 test.txt
```

## Keywords

about_Common_Parameters

## See also

- [about_Preference_Variables][03]
Expand Down
Loading