From 234c6989e8914b75dae57fd4fa5f4a1554a856cd Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 26 Mar 2024 10:20:34 -0500 Subject: [PATCH] Fix description of InformationVariable --- .../About/about_CommonParameters.md | 174 ++++++++--------- .../About/about_CommonParameters.md | 182 ++++++++--------- .../About/about_CommonParameters.md | 182 ++++++++--------- .../About/about_CommonParameters.md | 183 ++++++++---------- .../About/about_CommonParameters.md | 183 ++++++++---------- 5 files changed, 395 insertions(+), 509 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_CommonParameters.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_CommonParameters.md index f96e4a8b0743..248bb57d11ea 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_CommonParameters.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_CommonParameters.md @@ -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 @@ -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 @@ -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 @@ -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 @@ -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 @@ -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 @@ -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] @@ -275,7 +272,6 @@ parameter; if you don't add the **InformationAction** common parameter, ```yaml Type: String Aliases: iv - Required: False Position: Named Default value: None @@ -283,6 +279,10 @@ 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 @@ -292,7 +292,6 @@ they're generated. ```yaml Type: Int32 Aliases: ob - Required: False Position: Named Default value: None @@ -334,7 +333,6 @@ to sending the output along the pipeline. ```yaml Type: String Aliases: ov - Required: False Position: Named Default value: None @@ -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 @@ -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 @@ -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 @@ -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 @@ -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 @@ -600,7 +592,6 @@ executing the command. ```yaml Type: SwitchParameter Aliases: wi - Required: False Position: Named Default value: False @@ -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: @@ -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". ``` @@ -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 @@ -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 @@ -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 @@ -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] diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_CommonParameters.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_CommonParameters.md index add265504851..70ccb970383c 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_CommonParameters.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_CommonParameters.md @@ -1,7 +1,7 @@ --- description: Describes the parameters that can be used with any cmdlet. Locale: en-US -ms.date: 10/27/2023 +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-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 @@ -82,7 +82,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 @@ -111,7 +110,6 @@ such as those from the `Write-Error` cmdlet. Type: ActionPreference Aliases: ea Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue - Required: False Position: Named Default value: Depends on preference variable @@ -129,27 +127,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 @@ -158,14 +151,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 @@ -174,7 +169,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 @@ -220,7 +215,6 @@ value of the **InformationAction** parameter. For more information about Type: ActionPreference Aliases: infa Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue - Required: False Position: Named Default value: Depends on preference variable @@ -228,28 +222,23 @@ Accept pipeline input: False Accept wildcard characters: False ``` -`-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. +- `-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 @@ -258,13 +247,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] @@ -275,7 +267,6 @@ parameter; if you don't add the **InformationAction** common parameter, ```yaml Type: String Aliases: iv - Required: False Position: Named Default value: None @@ -283,6 +274,10 @@ 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 @@ -292,7 +287,6 @@ they're generated. ```yaml Type: Int32 Aliases: ob - Required: False Position: Named Default value: None @@ -334,7 +328,6 @@ to sending the output along the pipeline. ```yaml Type: String Aliases: ov - Required: False Position: Named Default value: None @@ -393,7 +386,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 @@ -476,7 +468,6 @@ this parameter works when a command contains the `Write-Verbose` cmdlet. ```yaml Type: SwitchParameter Aliases: vb - Required: False Position: Named Default value: False @@ -489,11 +480,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 @@ -506,7 +496,6 @@ warning message. For example, this parameter works when a command contains the Type: ActionPreference Aliases: wa Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue - Required: False Position: Named Default value: Depends on preference variable @@ -519,19 +508,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: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. +- `-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 @@ -540,12 +525,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 @@ -597,7 +581,6 @@ executing the command. ```yaml Type: SwitchParameter Aliases: wi - Required: False Position: Named Default value: False @@ -611,10 +594,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: @@ -626,7 +608,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". ``` @@ -638,7 +620,6 @@ Prompts you for confirmation before executing the command. ```yaml Type: SwitchParameter Aliases: cf - Required: False Position: Named Default value: Depends on preference variable @@ -650,18 +631,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 @@ -696,7 +676,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 @@ -734,10 +714,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] diff --git a/reference/7.3/Microsoft.PowerShell.Core/About/about_CommonParameters.md b/reference/7.3/Microsoft.PowerShell.Core/About/about_CommonParameters.md index 31e7458cf53b..79040b853e14 100644 --- a/reference/7.3/Microsoft.PowerShell.Core/About/about_CommonParameters.md +++ b/reference/7.3/Microsoft.PowerShell.Core/About/about_CommonParameters.md @@ -1,7 +1,7 @@ --- description: Describes the parameters that can be used with any cmdlet. Locale: en-US -ms.date: 10/27/2023 +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-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 @@ -82,7 +82,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 @@ -111,7 +110,6 @@ such as those from the `Write-Error` cmdlet. Type: ActionPreference Aliases: ea Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue - Required: False Position: Named Default value: Depends on preference variable @@ -129,27 +127,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 @@ -158,14 +151,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 @@ -174,7 +169,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 @@ -220,7 +215,6 @@ value of the **InformationAction** parameter. For more information about Type: ActionPreference Aliases: infa Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue - Required: False Position: Named Default value: Depends on preference variable @@ -228,28 +222,23 @@ Accept pipeline input: False Accept wildcard characters: False ``` -`-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. +- `-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 @@ -258,13 +247,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] @@ -275,7 +267,6 @@ parameter; if you don't add the **InformationAction** common parameter, ```yaml Type: String Aliases: iv - Required: False Position: Named Default value: None @@ -283,6 +274,10 @@ 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 @@ -292,7 +287,6 @@ they're generated. ```yaml Type: Int32 Aliases: ob - Required: False Position: Named Default value: None @@ -334,7 +328,6 @@ to sending the output along the pipeline. ```yaml Type: String Aliases: ov - Required: False Position: Named Default value: None @@ -393,7 +386,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 @@ -478,7 +470,6 @@ this parameter works when a command contains the `Write-Verbose` cmdlet. ```yaml Type: SwitchParameter Aliases: vb - Required: False Position: Named Default value: False @@ -491,11 +482,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 @@ -508,7 +498,6 @@ warning message. For example, this parameter works when a command contains the Type: ActionPreference Aliases: wa Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue - Required: False Position: Named Default value: Depends on preference variable @@ -521,19 +510,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: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. +- `-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 @@ -542,12 +527,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 @@ -599,7 +583,6 @@ executing the command. ```yaml Type: SwitchParameter Aliases: wi - Required: False Position: Named Default value: False @@ -613,10 +596,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: @@ -628,7 +610,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". ``` @@ -640,7 +622,6 @@ Prompts you for confirmation before executing the command. ```yaml Type: SwitchParameter Aliases: cf - Required: False Position: Named Default value: Depends on preference variable @@ -652,18 +633,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 @@ -698,7 +678,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 @@ -736,10 +716,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] diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_CommonParameters.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_CommonParameters.md index 93ce95f01ab5..900b65bf1d5d 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_CommonParameters.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_CommonParameters.md @@ -1,7 +1,7 @@ --- description: Describes the parameters that can be used with any cmdlet. Locale: en-US -ms.date: 10/27/2023 +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-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 @@ -83,7 +83,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 @@ -112,7 +111,6 @@ such as those from the `Write-Error` cmdlet. Type: ActionPreference Aliases: ea Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue - Required: False Position: Named Default value: Depends on preference variable @@ -130,27 +128,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 @@ -159,14 +152,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 @@ -175,7 +170,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 @@ -221,7 +216,6 @@ value of the **InformationAction** parameter. For more information about Type: ActionPreference Aliases: infa Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue - Required: False Position: Named Default value: Depends on preference variable @@ -229,28 +223,23 @@ Accept pipeline input: False Accept wildcard characters: False ``` -`-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. +- `-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 @@ -259,13 +248,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] @@ -276,7 +268,6 @@ parameter; if you don't add the **InformationAction** common parameter, ```yaml Type: String Aliases: iv - Required: False Position: Named Default value: None @@ -284,6 +275,10 @@ 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 @@ -293,7 +288,6 @@ they're generated. ```yaml Type: Int32 Aliases: ob - Required: False Position: Named Default value: None @@ -335,7 +329,6 @@ to sending the output along the pipeline. ```yaml Type: String Aliases: ov - Required: False Position: Named Default value: None @@ -394,7 +387,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 @@ -494,7 +486,6 @@ The valid values are as follows: Type: ActionPreference Aliases: proga Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue - Required: False Position: Named Default value: Depends on preference variable @@ -512,7 +503,6 @@ this parameter works when a command contains the `Write-Verbose` cmdlet. ```yaml Type: SwitchParameter Aliases: vb - Required: False Position: Named Default value: False @@ -525,11 +515,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 @@ -542,7 +531,6 @@ warning message. For example, this parameter works when a command contains the Type: ActionPreference Aliases: wa Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue - Required: False Position: Named Default value: Depends on preference variable @@ -555,19 +543,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: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. +- `-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 @@ -576,12 +560,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 @@ -633,7 +616,6 @@ executing the command. ```yaml Type: SwitchParameter Aliases: wi - Required: False Position: Named Default value: False @@ -647,10 +629,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: @@ -662,7 +643,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". ``` @@ -674,7 +655,6 @@ Prompts you for confirmation before executing the command. ```yaml Type: SwitchParameter Aliases: cf - Required: False Position: Named Default value: Depends on preference variable @@ -686,18 +666,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 @@ -732,7 +711,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 @@ -770,10 +749,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] diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_CommonParameters.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_CommonParameters.md index 24c49c2ebc3c..b4d8a5523647 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_CommonParameters.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_CommonParameters.md @@ -1,7 +1,7 @@ --- description: Describes the parameters that can be used with any cmdlet. Locale: en-US -ms.date: 10/27/2023 +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-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 @@ -83,7 +83,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 @@ -112,7 +111,6 @@ such as those from the `Write-Error` cmdlet. Type: ActionPreference Aliases: ea Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue - Required: False Position: Named Default value: Depends on preference variable @@ -130,27 +128,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 @@ -159,14 +152,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 @@ -175,7 +170,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 @@ -221,7 +216,6 @@ value of the **InformationAction** parameter. For more information about Type: ActionPreference Aliases: infa Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue - Required: False Position: Named Default value: Depends on preference variable @@ -229,28 +223,23 @@ Accept pipeline input: False Accept wildcard characters: False ``` -`-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. +- `-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 @@ -259,13 +248,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] @@ -276,7 +268,6 @@ parameter; if you don't add the **InformationAction** common parameter, ```yaml Type: String Aliases: iv - Required: False Position: Named Default value: None @@ -284,6 +275,10 @@ 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 @@ -293,7 +288,6 @@ they're generated. ```yaml Type: Int32 Aliases: ob - Required: False Position: Named Default value: None @@ -335,7 +329,6 @@ to sending the output along the pipeline. ```yaml Type: String Aliases: ov - Required: False Position: Named Default value: None @@ -394,7 +387,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 @@ -494,7 +486,6 @@ The valid values are as follows: Type: ActionPreference Aliases: proga Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue - Required: False Position: Named Default value: Depends on preference variable @@ -512,7 +503,6 @@ this parameter works when a command contains the `Write-Verbose` cmdlet. ```yaml Type: SwitchParameter Aliases: vb - Required: False Position: Named Default value: False @@ -525,11 +515,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 @@ -542,7 +531,6 @@ warning message. For example, this parameter works when a command contains the Type: ActionPreference Aliases: wa Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue - Required: False Position: Named Default value: Depends on preference variable @@ -555,19 +543,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: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. +- `-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 @@ -576,12 +560,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 @@ -633,7 +616,6 @@ executing the command. ```yaml Type: SwitchParameter Aliases: wi - Required: False Position: Named Default value: False @@ -647,10 +629,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: @@ -662,7 +643,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". ``` @@ -674,7 +655,6 @@ Prompts you for confirmation before executing the command. ```yaml Type: SwitchParameter Aliases: cf - Required: False Position: Named Default value: Depends on preference variable @@ -686,18 +666,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 @@ -732,7 +711,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 @@ -770,10 +749,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]