Skip to content

Commit

Permalink
Fix description of InformationVariable (#10982)
Browse files Browse the repository at this point in the history
  • Loading branch information
@sdwheeler
sdwheeler authored Mar 26, 2024
1 parent f1ffc51 commit e8c7c29
Show file tree
Hide file tree
Showing 5 changed files with 395 additions and 509 deletions.
174 changes: 79 additions & 95 deletions reference/5.1/Microsoft.PowerShell.Core/About/about_CommonParameters.md
View file
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

0 comments on commit e8c7c29

Please sign in to comment.