diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Operators.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Operators.md index 54a67a8828d2..36d11d3d7f12 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Operators.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Operators.md @@ -1,7 +1,7 @@ --- description: Describes the operators that are supported by PowerShell. Locale: en-US -ms.date: 09/25/2023 +ms.date: 09/26/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_operators?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Operators @@ -114,6 +114,8 @@ expressions. For example: `(1 + 2) / 3` However, in PowerShell, there are additional behaviors. +#### Grouping result expressions + `(...)` allows you to let output from a _command_ participate in an expression. For example: @@ -126,8 +128,35 @@ True > Wrapping a command in parentheses causes the automatic variable `$?` to be > set to `$true`, even when the enclosed command itself set `$?` to `$false`. > For example, `(Get-Item /Nosuch); $?` unexpectedly yields **True**. For -> more information about `$?`, see -> [about_Automatic_Variables][06]. +> more information about `$?`, see [about_Automatic_Variables][06]. + +#### Piping grouped expressions + +When used as the first segment of a pipeline, wrapping a command or expression +in parentheses invariably causes _enumeration_ of the expression result. If the +parentheses wrap a _command_, it's run to completion with all output _collected +in memory_ before the results are sent through the pipeline. + +For example, the outputs for these statements are different: + +```powershell +PS> ConvertFrom-Json '["a", "b"]' | ForEach-Object { "The value is '$_'" } + +The value is 'a b' + +PS> (ConvertFrom-Json '["a", "b"]') | ForEach-Object { "The value is '$_'" } + +The value is 'a' +The value is 'b' +``` + +Grouping an expression before piping also ensures that subsequent +object-by-object processing can't interfere with the enumeration the command +uses to produce its output. + +For example, piping the output from `Get-ChildItem` to `Rename-Item` can have +unexpected effects where an item is renamed, then discovered again and renamed +a second time. #### Grouping assignment statements @@ -184,34 +213,6 @@ in the body of the `if` statement. > between the assignment operator (`=`) and the equality-comparison operator > (`-eq`). -#### Piping grouped expressions - -When used as the first segment of a pipeline, wrapping a command or expression -in parentheses invariably causes _enumeration_ of the expression result. If the -parentheses wrap a _command_, it's run to completion with all output _collected -in memory_ before the results are sent through the pipeline. - -For example, the outputs for these statements are different: - -```powershell -PS> ConvertFrom-Json '["a", "b"]' | ForEach-Object { "The value is '$_'" } - -The value is 'a b' - -PS> (ConvertFrom-Json '["a", "b"]') | ForEach-Object { "The value is '$_'" } - -The value is 'a' -The value is 'b' -``` - -Grouping an expression before piping also ensures that subsequent -object-by-object processing can't interfere with the enumeration the command -uses to produce its output. - -For example, piping the output from `Get-ChildItem` to `Rename-Item` can have -unexpected effects where an item is renamed, then discovered again and renamed -a second time. - ### Subexpression operator `$( )` Returns the result of one or more statements. For a single result, returns a diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Write-Host.md b/reference/5.1/Microsoft.PowerShell.Utility/Write-Host.md index 2dbb1e0dd22a..2e1c1e62daf2 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Write-Host.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Write-Host.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 12/12/2022 +ms.date: 09/26/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/write-host?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: Write-Host @@ -24,10 +24,10 @@ Write-Host [[-Object] ] [-NoNewline] [-Separator ] [-ForegroundC ## DESCRIPTION The `Write-Host` cmdlet's primary purpose is to produce for-(host)-display-only output, such as -printing colored text like when prompting the user for input in conjunction with [Read-Host](Read-Host.md). -`Write-Host` uses the [ToString()](/dotnet/api/system.object.tostring) method to write the -output. By contrast, to output data to the pipeline, use [Write-Output](Write-Output.md) or implicit -output. +printing colored text like when prompting the user for input in conjunction with +[Read-Host](Read-Host.md). `Write-Host` uses the [ToString()](/dotnet/api/system.object.tostring) +method to write the output. By contrast, to output data to the pipeline, use +[Write-Output](Write-Output.md) or implicit output. You can specify the color of text by using the `ForegroundColor` parameter, and you can specify the background color by using the `BackgroundColor` parameter. The Separator parameter lets you specify @@ -122,22 +122,22 @@ thereby suppresses it. For more information, see Specifies the background color. There is no default. The acceptable values for this parameter are: -- Black -- DarkBlue -- DarkGreen -- DarkCyan -- DarkRed -- DarkMagenta -- DarkYellow -- Gray -- DarkGray -- Blue -- Green -- Cyan -- Red -- Magenta -- Yellow -- White +- `Black` +- `DarkBlue` +- `DarkGreen` +- `DarkCyan` +- `DarkRed` +- `DarkMagenta` +- `DarkYellow` +- `Gray` +- `DarkGray` +- `Blue` +- `Green` +- `Cyan` +- `Red` +- `Magenta` +- `Yellow` +- `White` ```yaml Type: System.ConsoleColor @@ -156,22 +156,22 @@ Accept wildcard characters: False Specifies the text color. There is no default. The acceptable values for this parameter are: -- Black -- DarkBlue -- DarkGreen -- DarkCyan -- DarkRed -- DarkMagenta -- DarkYellow -- Gray -- DarkGray -- Blue -- Green -- Cyan -- Red -- Magenta -- Yellow -- White +- `Black` +- `DarkBlue` +- `DarkGreen` +- `DarkCyan` +- `DarkRed` +- `DarkMagenta` +- `DarkYellow` +- `Gray` +- `DarkGray` +- `Blue` +- `Green` +- `Cyan` +- `Red` +- `Magenta` +- `Yellow` +- `White` ```yaml Type: System.ConsoleColor diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_ANSI_Terminals.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_ANSI_Terminals.md index 22380f31680e..fcf1468c1b02 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_ANSI_Terminals.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_ANSI_Terminals.md @@ -1,7 +1,7 @@ --- description: Describes the features of PowerShell that use ANSI escape sequences and the terminal hosts that support them. Locale: en-US -ms.date: 06/30/2023 +ms.date: 09/26/2023 schema: 2.0.0 title: about ANSI terminals --- @@ -91,22 +91,22 @@ The following members control how or when ANSI formatting is used: - The `$PSStyle.Background` and `$PSStyle.Foreground` members are strings that contain the ANSI escape sequences for the 16 standard console colors. - - **Black** - - **BrightBlack** - - **White** - - **BrightWhite** - - **Red** - - **BrightRed** - - **Magenta** - - **BrightMagenta** - - **Blue** - - **BrightBlue** - - **Cyan** - - **BrightCyan** - - **Green** - - **BrightGreen** - - **Yellow** - - **BrightYellow** + - `Black` + - `BrightBlack` + - `White` + - `BrightWhite` + - `Red` + - `BrightRed` + - `Magenta` + - `BrightMagenta` + - `Blue` + - `BrightBlue` + - `Cyan` + - `BrightCyan` + - `Green` + - `BrightGreen` + - `Yellow` + - `BrightYellow` The values are settable and can contain any number of ANSI escape sequences. There is also a `FromRgb()` method to specify 24-bit color. There are two @@ -118,7 +118,7 @@ The following members control how or when ANSI formatting is used: ``` Either of the following examples set the background color the 24-bit color - **Beige**. + `Beige`. ```powershell $PSStyle.Background.FromRgb(245, 245, 220) diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Operators.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Operators.md index bc7882034d34..e556905a584e 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Operators.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Operators.md @@ -1,7 +1,7 @@ --- description: Describes the operators that are supported by PowerShell. Locale: en-US -ms.date: 09/25/2023 +ms.date: 09/26/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_operators?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Operators @@ -114,6 +114,8 @@ expressions. For example: `(1 + 2) / 3` However, in PowerShell, there are additional behaviors. +#### Grouping result expressions + `(...)` allows you to let output from a _command_ participate in an expression. For example: @@ -122,6 +124,17 @@ PS> (Get-Item *.txt).Count -gt 10 True ``` +#### Piping grouped expressions + +When used as the first segment of a pipeline, wrapping a command or expression +in parentheses invariably causes _enumeration_ of the expression result. If the +parentheses wrap a _command_, it's run to completion with all output _collected +in memory_ before the results are sent through the pipeline. + +Grouping an expression before piping also ensures that subsequent +object-by-object processing can't interfere with the enumeration the command +uses to produce its output. + #### Grouping assignment statements Ungrouped assignment statements don't output values. When grouping an @@ -177,17 +190,6 @@ in the body of the `if` statement. > between the assignment operator (`=`) and the equality-comparison operator > (`-eq`). -#### Piping grouped expressions - -When used as the first segment of a pipeline, wrapping a command or expression -in parentheses invariably causes _enumeration_ of the expression result. If the -parentheses wrap a _command_, it's run to completion with all output _collected -in memory_ before the results are sent through the pipeline. - -Grouping an expression before piping also ensures that subsequent -object-by-object processing can't interfere with the enumeration the command -uses to produce its output. - ### Subexpression operator `$( )` Returns the result of one or more statements. For a single result, returns a diff --git a/reference/7.2/Microsoft.PowerShell.Utility/Write-Host.md b/reference/7.2/Microsoft.PowerShell.Utility/Write-Host.md index 32ba83626787..b9e157453c9f 100644 --- a/reference/7.2/Microsoft.PowerShell.Utility/Write-Host.md +++ b/reference/7.2/Microsoft.PowerShell.Utility/Write-Host.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 12/12/2022 +ms.date: 09/26/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/write-host?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: Write-Host @@ -24,10 +24,10 @@ Write-Host [[-Object] ] [-NoNewline] [-Separator ] [-ForegroundC ## DESCRIPTION The `Write-Host` cmdlet's primary purpose is to produce for-(host)-display-only output, such as -printing colored text like when prompting the user for input in conjunction with [Read-Host](Read-Host.md). -`Write-Host` uses the [ToString()](/dotnet/api/system.object.tostring) method to write the -output. By contrast, to output data to the pipeline, use [Write-Output](Write-Output.md) or implicit -output. +printing colored text like when prompting the user for input in conjunction with +[Read-Host](Read-Host.md). `Write-Host` uses the [ToString()](/dotnet/api/system.object.tostring) +method to write the output. By contrast, to output data to the pipeline, use +[Write-Output](Write-Output.md) or implicit output. You can specify the color of text by using the `ForegroundColor` parameter, and you can specify the background color by using the `BackgroundColor` parameter. The Separator parameter lets you specify @@ -122,22 +122,22 @@ thereby suppresses it. For more information, see Specifies the background color. There is no default. The acceptable values for this parameter are: -- Black -- DarkBlue -- DarkGreen -- DarkCyan -- DarkRed -- DarkMagenta -- DarkYellow -- Gray -- DarkGray -- Blue -- Green -- Cyan -- Red -- Magenta -- Yellow -- White +- `Black` +- `DarkBlue` +- `DarkGreen` +- `DarkCyan` +- `DarkRed` +- `DarkMagenta` +- `DarkYellow` +- `Gray` +- `DarkGray` +- `Blue` +- `Green` +- `Cyan` +- `Red` +- `Magenta` +- `Yellow` +- `White` ```yaml Type: System.ConsoleColor @@ -156,22 +156,22 @@ Accept wildcard characters: False Specifies the text color. There is no default. The acceptable values for this parameter are: -- Black -- DarkBlue -- DarkGreen -- DarkCyan -- DarkRed -- DarkMagenta -- DarkYellow -- Gray -- DarkGray -- Blue -- Green -- Cyan -- Red -- Magenta -- Yellow -- White +- `Black` +- `DarkBlue` +- `DarkGreen` +- `DarkCyan` +- `DarkRed` +- `DarkMagenta` +- `DarkYellow` +- `Gray` +- `DarkGray` +- `Blue` +- `Green` +- `Cyan` +- `Red` +- `Magenta` +- `Yellow` +- `White` ```yaml Type: System.ConsoleColor diff --git a/reference/7.3/Microsoft.PowerShell.Core/About/about_ANSI_Terminals.md b/reference/7.3/Microsoft.PowerShell.Core/About/about_ANSI_Terminals.md index 12aec39021ad..cbb04e4c5e0d 100644 --- a/reference/7.3/Microsoft.PowerShell.Core/About/about_ANSI_Terminals.md +++ b/reference/7.3/Microsoft.PowerShell.Core/About/about_ANSI_Terminals.md @@ -1,7 +1,7 @@ --- description: Describes the features of PowerShell that use ANSI escape sequences and the terminal hosts that support them. Locale: en-US -ms.date: 06/30/2023 +ms.date: 09/26/2023 schema: 2.0.0 title: about ANSI terminals --- @@ -91,22 +91,22 @@ The following members control how or when ANSI formatting is used: - The `$PSStyle.Background` and `$PSStyle.Foreground` members are strings that contain the ANSI escape sequences for the 16 standard console colors. - - **Black** - - **BrightBlack** - - **White** - - **BrightWhite** - - **Red** - - **BrightRed** - - **Magenta** - - **BrightMagenta** - - **Blue** - - **BrightBlue** - - **Cyan** - - **BrightCyan** - - **Green** - - **BrightGreen** - - **Yellow** - - **BrightYellow** + - `Black` + - `BrightBlack` + - `White` + - `BrightWhite` + - `Red` + - `BrightRed` + - `Magenta` + - `BrightMagenta` + - `Blue` + - `BrightBlue` + - `Cyan` + - `BrightCyan` + - `Green` + - `BrightGreen` + - `Yellow` + - `BrightYellow` The values are settable and can contain any number of ANSI escape sequences. There is also a `FromRgb()` method to specify 24-bit color. There are two @@ -118,7 +118,7 @@ The following members control how or when ANSI formatting is used: ``` Either of the following examples set the background color the 24-bit color - **Beige**. + `Beige`. ```powershell $PSStyle.Background.FromRgb(245, 245, 220) diff --git a/reference/7.3/Microsoft.PowerShell.Core/About/about_Operators.md b/reference/7.3/Microsoft.PowerShell.Core/About/about_Operators.md index 131d9671c8e6..ba9967388fd0 100644 --- a/reference/7.3/Microsoft.PowerShell.Core/About/about_Operators.md +++ b/reference/7.3/Microsoft.PowerShell.Core/About/about_Operators.md @@ -1,7 +1,7 @@ --- description: Describes the operators that are supported by PowerShell. Locale: en-US -ms.date: 09/25/2023 +ms.date: 09/26/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_operators?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Operators @@ -114,6 +114,8 @@ expressions. For example: `(1 + 2) / 3` However, in PowerShell, there are additional behaviors. +#### Grouping result expressions + `(...)` allows you to let output from a _command_ participate in an expression. For example: @@ -122,6 +124,17 @@ PS> (Get-Item *.txt).Count -gt 10 True ``` +#### Piping grouped expressions + +When used as the first segment of a pipeline, wrapping a command or expression +in parentheses invariably causes _enumeration_ of the expression result. If the +parentheses wrap a _command_, it's run to completion with all output _collected +in memory_ before the results are sent through the pipeline. + +Grouping an expression before piping also ensures that subsequent +object-by-object processing can't interfere with the enumeration the command +uses to produce its output. + #### Grouping assignment statements Ungrouped assignment statements don't output values. When grouping an @@ -177,17 +190,6 @@ in the body of the `if` statement. > between the assignment operator (`=`) and the equality-comparison operator > (`-eq`). -#### Piping grouped expressions - -When used as the first segment of a pipeline, wrapping a command or expression -in parentheses invariably causes _enumeration_ of the expression result. If the -parentheses wrap a _command_, it's run to completion with all output _collected -in memory_ before the results are sent through the pipeline. - -Grouping an expression before piping also ensures that subsequent -object-by-object processing can't interfere with the enumeration the command -uses to produce its output. - ### Subexpression operator `$( )` Returns the result of one or more statements. For a single result, returns a diff --git a/reference/7.3/Microsoft.PowerShell.Utility/Write-Host.md b/reference/7.3/Microsoft.PowerShell.Utility/Write-Host.md index acfc524dcf33..f60c0e268e2e 100644 --- a/reference/7.3/Microsoft.PowerShell.Utility/Write-Host.md +++ b/reference/7.3/Microsoft.PowerShell.Utility/Write-Host.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 12/12/2022 +ms.date: 09/26/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/write-host?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: Write-Host @@ -24,10 +24,10 @@ Write-Host [[-Object] ] [-NoNewline] [-Separator ] [-ForegroundC ## DESCRIPTION The `Write-Host` cmdlet's primary purpose is to produce for-(host)-display-only output, such as -printing colored text like when prompting the user for input in conjunction with [Read-Host](Read-Host.md). -`Write-Host` uses the [ToString()](/dotnet/api/system.object.tostring) method to write the -output. By contrast, to output data to the pipeline, use [Write-Output](Write-Output.md) or implicit -output. +printing colored text like when prompting the user for input in conjunction with +[Read-Host](Read-Host.md). `Write-Host` uses the [ToString()](/dotnet/api/system.object.tostring) +method to write the output. By contrast, to output data to the pipeline, use +[Write-Output](Write-Output.md) or implicit output. You can specify the color of text by using the `ForegroundColor` parameter, and you can specify the background color by using the `BackgroundColor` parameter. The Separator parameter lets you specify @@ -122,22 +122,22 @@ thereby suppresses it. For more information, see Specifies the background color. There is no default. The acceptable values for this parameter are: -- Black -- DarkBlue -- DarkGreen -- DarkCyan -- DarkRed -- DarkMagenta -- DarkYellow -- Gray -- DarkGray -- Blue -- Green -- Cyan -- Red -- Magenta -- Yellow -- White +- `Black` +- `DarkBlue` +- `DarkGreen` +- `DarkCyan` +- `DarkRed` +- `DarkMagenta` +- `DarkYellow` +- `Gray` +- `DarkGray` +- `Blue` +- `Green` +- `Cyan` +- `Red` +- `Magenta` +- `Yellow` +- `White` ```yaml Type: System.ConsoleColor @@ -156,22 +156,22 @@ Accept wildcard characters: False Specifies the text color. There is no default. The acceptable values for this parameter are: -- Black -- DarkBlue -- DarkGreen -- DarkCyan -- DarkRed -- DarkMagenta -- DarkYellow -- Gray -- DarkGray -- Blue -- Green -- Cyan -- Red -- Magenta -- Yellow -- White +- `Black` +- `DarkBlue` +- `DarkGreen` +- `DarkCyan` +- `DarkRed` +- `DarkMagenta` +- `DarkYellow` +- `Gray` +- `DarkGray` +- `Blue` +- `Green` +- `Cyan` +- `Red` +- `Magenta` +- `Yellow` +- `White` ```yaml Type: System.ConsoleColor diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_ANSI_Terminals.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_ANSI_Terminals.md index 5ba1d5ace526..1113135067e6 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_ANSI_Terminals.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_ANSI_Terminals.md @@ -1,7 +1,7 @@ --- description: Describes the features of PowerShell that use ANSI escape sequences and the terminal hosts that support them. Locale: en-US -ms.date: 06/30/2023 +ms.date: 09/26/2023 schema: 2.0.0 title: about ANSI terminals --- @@ -95,22 +95,22 @@ The following members control how or when ANSI formatting is used: - The `$PSStyle.Background` and `$PSStyle.Foreground` members are strings that contain the ANSI escape sequences for the 16 standard console colors. - - **Black** - - **BrightBlack** - - **White** - - **BrightWhite** - - **Red** - - **BrightRed** - - **Magenta** - - **BrightMagenta** - - **Blue** - - **BrightBlue** - - **Cyan** - - **BrightCyan** - - **Green** - - **BrightGreen** - - **Yellow** - - **BrightYellow** + - `Black` + - `BrightBlack` + - `White` + - `BrightWhite` + - `Red` + - `BrightRed` + - `Magenta` + - `BrightMagenta` + - `Blue` + - `BrightBlue` + - `Cyan` + - `BrightCyan` + - `Green` + - `BrightGreen` + - `Yellow` + - `BrightYellow` The values are settable and can contain any number of ANSI escape sequences. There is also a `FromRgb()` method to specify 24-bit color. There are two @@ -122,7 +122,7 @@ The following members control how or when ANSI formatting is used: ``` Either of the following examples set the background color the 24-bit color - **Beige**. + `Beige`. ```powershell $PSStyle.Background.FromRgb(245, 245, 220) diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Operators.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Operators.md index 52d92324609c..17769f3cc4f5 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Operators.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Operators.md @@ -1,7 +1,7 @@ --- description: Describes the operators that are supported by PowerShell. Locale: en-US -ms.date: 09/25/2023 +ms.date: 09/26/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_operators?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Operators @@ -114,6 +114,8 @@ expressions. For example: `(1 + 2) / 3` However, in PowerShell, there are additional behaviors. +#### Grouping result expressions + `(...)` allows you to let output from a _command_ participate in an expression. For example: @@ -122,6 +124,17 @@ PS> (Get-Item *.txt).Count -gt 10 True ``` +#### Piping grouped expressions + +When used as the first segment of a pipeline, wrapping a command or expression +in parentheses invariably causes _enumeration_ of the expression result. If the +parentheses wrap a _command_, it's run to completion with all output _collected +in memory_ before the results are sent through the pipeline. + +Grouping an expression before piping also ensures that subsequent +object-by-object processing can't interfere with the enumeration the command +uses to produce its output. + #### Grouping assignment statements Ungrouped assignment statements don't output values. When grouping an @@ -177,17 +190,6 @@ in the body of the `if` statement. > between the assignment operator (`=`) and the equality-comparison operator > (`-eq`). -#### Piping grouped expressions - -When used as the first segment of a pipeline, wrapping a command or expression -in parentheses invariably causes _enumeration_ of the expression result. If the -parentheses wrap a _command_, it's run to completion with all output _collected -in memory_ before the results are sent through the pipeline. - -Grouping an expression before piping also ensures that subsequent -object-by-object processing can't interfere with the enumeration the command -uses to produce its output. - ### Subexpression operator `$( )` Returns the result of one or more statements. For a single result, returns a diff --git a/reference/7.4/Microsoft.PowerShell.Utility/Write-Host.md b/reference/7.4/Microsoft.PowerShell.Utility/Write-Host.md index 89c58d6d652a..a8eb4ab67315 100644 --- a/reference/7.4/Microsoft.PowerShell.Utility/Write-Host.md +++ b/reference/7.4/Microsoft.PowerShell.Utility/Write-Host.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 12/12/2022 +ms.date: 09/26/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/write-host?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: Write-Host @@ -24,10 +24,10 @@ Write-Host [[-Object] ] [-NoNewline] [-Separator ] [-ForegroundC ## DESCRIPTION The `Write-Host` cmdlet's primary purpose is to produce for-(host)-display-only output, such as -printing colored text like when prompting the user for input in conjunction with [Read-Host](Read-Host.md). -`Write-Host` uses the [ToString()](/dotnet/api/system.object.tostring) method to write the -output. By contrast, to output data to the pipeline, use [Write-Output](Write-Output.md) or implicit -output. +printing colored text like when prompting the user for input in conjunction with +[Read-Host](Read-Host.md). `Write-Host` uses the [ToString()](/dotnet/api/system.object.tostring) +method to write the output. By contrast, to output data to the pipeline, use +[Write-Output](Write-Output.md) or implicit output. You can specify the color of text by using the `ForegroundColor` parameter, and you can specify the background color by using the `BackgroundColor` parameter. The Separator parameter lets you specify @@ -122,22 +122,22 @@ thereby suppresses it. For more information, see Specifies the background color. There is no default. The acceptable values for this parameter are: -- Black -- DarkBlue -- DarkGreen -- DarkCyan -- DarkRed -- DarkMagenta -- DarkYellow -- Gray -- DarkGray -- Blue -- Green -- Cyan -- Red -- Magenta -- Yellow -- White +- `Black` +- `DarkBlue` +- `DarkGreen` +- `DarkCyan` +- `DarkRed` +- `DarkMagenta` +- `DarkYellow` +- `Gray` +- `DarkGray` +- `Blue` +- `Green` +- `Cyan` +- `Red` +- `Magenta` +- `Yellow` +- `White` ```yaml Type: System.ConsoleColor @@ -156,22 +156,22 @@ Accept wildcard characters: False Specifies the text color. There is no default. The acceptable values for this parameter are: -- Black -- DarkBlue -- DarkGreen -- DarkCyan -- DarkRed -- DarkMagenta -- DarkYellow -- Gray -- DarkGray -- Blue -- Green -- Cyan -- Red -- Magenta -- Yellow -- White +- `Black` +- `DarkBlue` +- `DarkGreen` +- `DarkCyan` +- `DarkRed` +- `DarkMagenta` +- `DarkYellow` +- `Gray` +- `DarkGray` +- `Blue` +- `Green` +- `Cyan` +- `Red` +- `Magenta` +- `Yellow` +- `White` ```yaml Type: System.ConsoleColor diff --git a/reference/docs-conceptual/how-to-use-docs.md b/reference/docs-conceptual/how-to-use-docs.md index eff0ffc7b826..96e42b366ff8 100644 --- a/reference/docs-conceptual/how-to-use-docs.md +++ b/reference/docs-conceptual/how-to-use-docs.md @@ -63,10 +63,22 @@ Major Minor Build Revision ## Finding articles -There are two ways to search for content in Docs. The simplest way is to use the filter box under -the version selector. Just enter a word that appears in the title of an article. The filter displays -a list of matching articles. You can also select the option to search the entire site from that -list. +There are two ways to search for content in Docs. + +- The search box in the site-level navigation bar searches the entire site. It returns a list of + matching articles from all documentation sets. +- The TOC filter box under the version selector allows filtering by words that appear in the title + of an article. The filter displays a list of matching articles as you type. You can also select + the option to search for the words in an article. When you search from here, the search is + limited to the PowerShell documentation. + +In the following example, the search in the site-level navigation bar returns 840 results for the +word `idempotent`. Entering the word `invoke` in the TOC filter box shows a list of articles that +contain the word `invoke` in the title. Entering the word `idempotent` in the TOC filter shows no +articles. Clicking the search link searches for `idempotent` in the PowerShell documentation. This +search only returns 9 results. + +![Animation showing how to use the search features.][05] ## Downloading the documentation as a PDF @@ -102,3 +114,4 @@ This site contains documentation for the following topics: [02]: media/how-to-use-docs/how-to-use.gif [03]: media/how-to-use-docs/pdf-button.gif [04]: media/how-to-use-docs/version-search.gif +[05]: media/how-to-use-docs/search-scope.gif diff --git a/reference/docs-conceptual/install/Installing-PowerShell-on-Windows.md b/reference/docs-conceptual/install/Installing-PowerShell-on-Windows.md index 36649ab92769..2de55ce2c412 100644 --- a/reference/docs-conceptual/install/Installing-PowerShell-on-Windows.md +++ b/reference/docs-conceptual/install/Installing-PowerShell-on-Windows.md @@ -1,6 +1,6 @@ --- description: Information about installing PowerShell on Windows -ms.date: 06/30/2023 +ms.date: 09/26/2023 title: Installing PowerShell on Windows --- # Installing PowerShell on Windows @@ -84,11 +84,12 @@ The installer creates a shortcut in the Windows Start Menu. > [!NOTE] > PowerShell 7.3 installs to a new directory and runs side-by-side with Windows PowerShell 5.1. -> PowerShell 7.3 is an in-place upgrade that replaces PowerShell 7.0 and lower. +> PowerShell 7.3 is an in-place upgrade that removes previous versions of PowerShell 7. Preview +> versions of PowerShell can be installed side-by-side with other versions of PowerShell. > > - PowerShell 7.3 is installed to `$env:ProgramFiles\PowerShell\7` > - The `$env:ProgramFiles\PowerShell\7` folder is added to `$env:PATH` -> - Folders for previously released versions are deleted +> - Folders for previously released versions PowerShell are deleted > > If you need to run PowerShell 7.3 side-by-side with other versions, use the [ZIP install][20] > method to install the other version to a different folder. diff --git a/reference/docs-conceptual/install/Installing-PowerShell-on-macOS.md b/reference/docs-conceptual/install/Installing-PowerShell-on-macOS.md index 7451197b5342..6a41fd2bfd61 100644 --- a/reference/docs-conceptual/install/Installing-PowerShell-on-macOS.md +++ b/reference/docs-conceptual/install/Installing-PowerShell-on-macOS.md @@ -1,6 +1,6 @@ --- description: Information about installing PowerShell on macOS -ms.date: 06/28/2023 +ms.date: 09/26/2023 title: Installing PowerShell on macOS --- @@ -11,10 +11,10 @@ PowerShell 7.0 or higher require macOS 10.13 and higher. All packages are availa check the list of [Supported versions][07] below. > [!NOTE] -> PowerShell 7.3 is an in-place upgrade that removes previous versions of PowerShell. -> -> If you need to run an older version of PowerShell side-by-side with PowerShell 7.3, install -> the version you want using the [binary archive][04] method. +> PowerShell 7.3 is an in-place upgrade that removes previous versions of PowerShell 7. Preview +> versions of PowerShell can be installed side-by-side with other versions of PowerShell. If you +> need to run PowerShell 7.3 side-by-side with a previous version, reinstall the previous version +> using the [binary archive][05] method. ## Installation of latest stable release via Homebrew on macOS 10.13 or higher diff --git a/reference/docs-conceptual/install/install-alpine.md b/reference/docs-conceptual/install/install-alpine.md index 30cdb9da3adc..bb1528d83896 100644 --- a/reference/docs-conceptual/install/install-alpine.md +++ b/reference/docs-conceptual/install/install-alpine.md @@ -1,6 +1,6 @@ --- description: Information about installing PowerShell on Alpine Linux -ms.date: 06/28/2023 +ms.date: 09/26/2023 title: Installing PowerShell on Alpine Linux --- # Installing PowerShell on Alpine Linux @@ -10,15 +10,15 @@ All packages are available on our GitHub [releases][03] page. After the package check the list of [Supported versions][02] below. > [!NOTE] -> PowerShell 7.3 is an in-place upgrade that removes previous versions of PowerShell. -> -> If you need to run PowerShell 7.3 side-by-side with a previous version, reinstall the previous -> version using the [binary archive][05] method. +> PowerShell 7.3 is an in-place upgrade that removes previous versions of PowerShell 7. Preview +> versions of PowerShell can be installed side-by-side with other versions of PowerShell. If you +> need to run PowerShell 7.3 side-by-side with a previous version, reinstall the previous version +> using the [binary archive][05] method. ## Installation steps -Installation on Alpine is based on downloading tar.gz package from the [releases][03] page. -The URL to the package depends on the version of PowerShell you want to install. +Installation on Alpine is based on downloading tar.gz package from the [releases][03] page. The URL +to the package depends on the version of PowerShell you want to install. - PowerShell 7.3.7 - `https://github.com/PowerShell/PowerShell/releases/download/v7.3.7/powershell-7.3.7-linux-alpine-x64.tar.gz` - PowerShell 7.2.14 - `https://github.com/PowerShell/PowerShell/releases/download/v7.2.14/powershell-7.2.14-linux-alpine-x64.tar.gz` @@ -64,7 +64,7 @@ sudo ln -s /opt/microsoft/powershell/7/pwsh /usr/bin/pwsh pwsh ``` -## Uninstall PowerShell from Alpine +## Uninstall PowerShell ```sh sudo rm -rf /usr/bin/pwsh /opt/microsoft/powershell @@ -73,12 +73,16 @@ sudo rm -rf /usr/bin/pwsh /opt/microsoft/powershell ## PowerShell paths - `$PSHOME` is `/opt/microsoft/powershell/7/` -- User profiles are read from `~/.config/powershell/profile.ps1` -- Default profiles are read from `$PSHOME/profile.ps1` -- User modules are read from `~/.local/share/powershell/Modules` -- Shared modules are read from `/usr/local/share/powershell/Modules` -- Default modules are read from `$PSHOME/Modules` -- PSReadLine history is recorded to `~/.local/share/powershell/PSReadLine/ConsoleHost_history.txt` +- The profiles scripts are stored in the following locations: + - AllUsersAllHosts - `$PSHOME/profile.ps1` + - AllUsersCurrentHost - `$PSHOME/Microsoft.PowerShell_profile.ps1` + - CurrentUserAllHosts - `~/.config/powershell/profile.ps1` + - CurrentUserCurrentHost - `~/.config/powershell/Microsoft.PowerShell_profile.ps1` +- Modules are stored in the following locations: + - User modules - `~/.local/share/powershell/Modules` + - Shared modules - `/usr/local/share/powershell/Modules` + - Default modules - `$PSHOME/Modules` +- PSReadLine history is recorded in `~/.local/share/powershell/PSReadLine/ConsoleHost_history.txt` The profiles respect PowerShell's per-host configuration, so the default host-specific profiles exists at `Microsoft.PowerShell_profile.ps1` in the same locations. diff --git a/reference/docs-conceptual/install/install-debian.md b/reference/docs-conceptual/install/install-debian.md index d20fc89e7cae..e14b4da71774 100644 --- a/reference/docs-conceptual/install/install-debian.md +++ b/reference/docs-conceptual/install/install-debian.md @@ -1,74 +1,112 @@ --- description: Information about installing PowerShell on Debian Linux -ms.date: 07/03/2023 -title: Installing PowerShell on Debian Linux +ms.date: 09/26/2023 +title: Installing PowerShell on Debian --- -# Installing PowerShell on Debian Linux +# Installing PowerShell on Debian -All packages are available on our GitHub [releases][04] page. After the package is installed, run -`pwsh` from a terminal. Run `pwsh-preview` if you installed a preview release. Before installing, -check the list of [Supported versions][03] below. +All packages are available on our GitHub [releases][02] page. Before installing, +check the list of [Supported versions][01] below. After the package is installed, run +`pwsh` from a terminal. Run `pwsh-preview` if you installed a preview release. > [!NOTE] -> PowerShell 7.3 is an in-place upgrade that removes previous versions of PowerShell. -> -> If you need to run PowerShell 7.3 side-by-side with a previous version, reinstall the previous -> version using the [binary archive][07] method. +> PowerShell 7.3 is an in-place upgrade that removes previous versions of PowerShell 7. Preview +> versions of PowerShell can be installed side-by-side with other versions of PowerShell. If you +> need to run PowerShell 7.3 side-by-side with a previous version, reinstall the previous version +> using the [binary archive][05] method. Debian uses APT (Advanced Package Tool) as a package manager. -## Installation via direct download +## Installation on Debian 10 or 11 via the Package Repository -PowerShell 7.2 introduced a universal package that makes installation easier. Download the universal -package from the [releases][04] page onto the Debian 10 machine. The link to the current version is: +Microsoft builds and supports a variety of software products for Linux systems and makes them +available via Linux packaging clients (apt, dnf, yum, etc). These Linux software packages are hosted +on the _Linux package repository for Microsoft products_, [https://packages.microsoft.com][03], also +known as _PMC_. -- PowerShell 7.3.7 - `https://github.com/PowerShell/PowerShell/releases/download/v7.3.7/powershell_7.3.7-1.deb_amd64.deb` -- PowerShell 7.2.14 - `https://github.com/PowerShell/PowerShell/releases/download/v7.2.14/powershell-lts_7.2.14-1.deb_amd64.deb` +Installing PowerShell from PMC is the preferred method of installation. -## Installation on Debian 11 via Package Repository +> [!NOTE] +> This script only works for supported versions of Debian. -PowerShell for Linux is published to package repositories for easy installation and updates. +```sh +################################### +# Prerequisites -The preferred method is as follows: +# Update the list of packages +sudo apt-get update -```sh -# Save the public repository GPG keys -curl https://packages.microsoft.com/keys/microsoft.asc | sudo gpg --yes --dearmor --output /usr/share/keyrings/microsoft.gpg +# Install pre-requisite packages. +sudo apt-get install -y wget + +# Get the version of Debian +source /etc/os-release -# Register the Microsoft Product feed -sudo sh -c 'echo "deb [arch=amd64 signed-by=/usr/share/keyrings/microsoft.gpg] https://packages.microsoft.com/repos/microsoft-debian-bullseye-prod bullseye main" > /etc/apt/sources.list.d/microsoft.list' +# Download the Microsoft repository GPG keys +wget -q https://packages.microsoft.com/config/debian/$VERSION_ID/packages-microsoft-prod.deb +# Register the Microsoft repository GPG keys +sudo dpkg -i packages-microsoft-prod.deb + +# Delete the the Microsoft repository GPG keys file +rm packages-microsoft-prod.deb + +# Update the list of packages after we added packages.microsoft.com +sudo apt-get update + +################################### # Install PowerShell -sudo apt update && sudo apt install -y powershell +sudo apt-get install -y powershell # Start PowerShell pwsh ``` -## Installation on Debian 10 via Package Repository +## Installation via direct download -PowerShell for Linux is published to package repositories for easy installation and updates. +PowerShell 7.2 introduced a universal package that makes installation easier. Download the universal +package from the [releases][02] page onto your Debian machine. -The preferred method is as follows: +The link to the current version is: -```sh -# Download the Microsoft repository GPG keys -wget https://packages.microsoft.com/config/debian/10/packages-microsoft-prod.deb +- PowerShell 7.3.7 universal package for supported versions of Debian + - `https://github.com/PowerShell/PowerShell/releases/download/v7.3.7/powershell_7.3.7-1.deb_amd64.deb` +- PowerShell 7.2.14 universal package for supported versions of Debian + - `https://github.com/PowerShell/PowerShell/releases/download/v7.2.14/powershell-lts_7.2.14-1.deb_amd64.deb` +- PowerShell 7.4-preview.5 universal package for supported versions of Debian + - `https://github.com/PowerShell/PowerShell/releases/download/v7.4.0-preview.5/powershell-preview_7.4.0-preview.5-1.deb_amd64.deb` -# Register the Microsoft repository GPG keys -sudo dpkg -i packages-microsoft-prod.deb +The following shell script downloads and installs the current preview release of PowerShell. You can +change the URL to download a the version of PowerShell you want to install. -# Update the list of products +```sh +################################### +# Prerequisites + +# Update the list of packages sudo apt-get update -# Install PowerShell -sudo apt-get install -y powershell +# Install pre-requisite packages. +sudo apt-get install -y wget -# Start PowerShell -pwsh +# Download the PowerShell package file +wget https://github.com/PowerShell/PowerShell/releases/download/v7.4.0-preview.5/powershell-preview_7.4.0-preview.5-1.deb_amd64.deb + +################################### +# Install the PowerShell package +sudo dpkg -i powershell-preview_7.4.0-preview.5-1.deb_amd64.deb + +# Resolve missing dependencies and finish the install (if necessary) +sudo apt-get install -f + +# Delete the downloaded package file +rm powershell-preview_7.4.0-preview.5-1.deb_amd64.deb + +# Start PowerShell Preview +pwsh-preview ``` -## Uninstallation +## Uninstall PowerShell ```sh sudo apt-get remove powershell @@ -77,17 +115,18 @@ sudo apt-get remove powershell ## PowerShell paths - `$PSHOME` is `/opt/microsoft/powershell/7/` -- User profiles are read from `~/.config/powershell/profile.ps1` -- Default profiles are read from `$PSHOME/profile.ps1` -- User modules are read from `~/.local/share/powershell/Modules` -- Shared modules are read from `/usr/local/share/powershell/Modules` -- Default modules are read from `$PSHOME/Modules` -- PSReadLine history is recorded to `~/.local/share/powershell/PSReadLine/ConsoleHost_history.txt` - -The profiles respect PowerShell's per-host configuration, so the default host-specific profiles -exists at `Microsoft.PowerShell_profile.ps1` in the same locations. - -PowerShell respects the [XDG Base Directory Specification][05] on Linux. +- The profiles scripts are stored in the following locations: + - AllUsersAllHosts - `$PSHOME/profile.ps1` + - AllUsersCurrentHost - `$PSHOME/Microsoft.PowerShell_profile.ps1` + - CurrentUserAllHosts - `~/.config/powershell/profile.ps1` + - CurrentUserCurrentHost - `~/.config/powershell/Microsoft.PowerShell_profile.ps1` +- Modules are stored in the following locations: + - User modules - `~/.local/share/powershell/Modules` + - Shared modules - `/usr/local/share/powershell/Modules` + - Default modules - `$PSHOME/Modules` +- PSReadLine history is recorded in `~/.local/share/powershell/PSReadLine/ConsoleHost_history.txt` + +PowerShell respects the [XDG Base Directory Specification][04] on Linux. ## Supported versions @@ -97,10 +136,11 @@ PowerShell respects the [XDG Base Directory Specification][05] on Linux. Microsoft supports the installation methods in this document. There may be other methods of installation available from other third-party sources. While those tools and methods may work, -Microsoft cannot support those methods. +Microsoft can't support those methods. -[03]: #supported-versions -[04]: https://aka.ms/PowerShell-Release?tag=stable -[05]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html -[07]: install-other-linux.md#binary-archives +[01]: #supported-versions +[02]: https://aka.ms/PowerShell-Release?tag=stable +[03]: https://packages.microsoft.com +[04]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html +[05]: install-other-linux.md#binary-archives diff --git a/reference/docs-conceptual/install/install-rhel.md b/reference/docs-conceptual/install/install-rhel.md index 1407db1bf861..b020c33b9af5 100644 --- a/reference/docs-conceptual/install/install-rhel.md +++ b/reference/docs-conceptual/install/install-rhel.md @@ -1,95 +1,111 @@ --- description: Information about installing PowerShell on Red Hat Enterprise Linux (RHEL) -ms.date: 06/28/2023 +ms.date: 09/26/2023 title: Installing PowerShell on Red Hat Enterprise Linux (RHEL) --- # Installing PowerShell on Red Hat Enterprise Linux (RHEL) -All packages are available on our GitHub [releases][05] page. After the package is installed, run -`pwsh` from a terminal. Run `pwsh-preview` if you installed a preview release. Before installing, -check the list of [Supported versions][03] below. +All packages are available on our GitHub [releases][02] page. Before installing, +check the list of [Supported versions][01] below. After the package is installed, run +`pwsh` from a terminal. Run `pwsh-preview` if you installed a preview release. > [!NOTE] -> PowerShell 7.3 is an in-place upgrade that removes previous versions of PowerShell. -> -> If you need to run PowerShell 7.3 side-by-side with a previous version, reinstall the previous -> version using the [binary archive][07] method. +> PowerShell 7.3 is an in-place upgrade that removes previous versions of PowerShell 7. Preview +> versions of PowerShell can be installed side-by-side with other versions of PowerShell. If you +> need to run PowerShell 7.3 side-by-side with a previous version, reinstall the previous version +> using the [binary archive][05] method. -RHEL 7 uses yum and RHEL 8 uses the dnf package manager. +RHEL 7 uses `yum` and RHEL 8 and higher uses the `dnf` package manager. -## Installation via Package Repository +## Installation via the Package Repository -PowerShell for Linux is published to official Microsoft repositories for easy installation and -updates. +Microsoft builds and supports a variety of software products for Linux systems and makes them +available via Linux packaging clients (apt, dnf, yum, etc). These Linux software packages are hosted +on the _Linux package repository for Microsoft products_, [https://packages.microsoft.com][03], also +known as _PMC_. -On RHEL 9: - -The PowerShell RPMs aren't published to the RHEL 9 repository yet. For RHEL 9, you need to +Installing PowerShell from PMC is the preferred method of installation. The PowerShell RPMs aren't +published to the RHEL 9 repository yet. For RHEL 9, you need to [install PowerShell via direct download](#installation-via-direct-download). -On RHEL 8: +> [!NOTE] +> This script only works for supported versions of RHEL. ```sh -# Register the Microsoft RedHat repository -curl https://packages.microsoft.com/config/rhel/8/prod.repo | sudo tee /etc/yum.repos.d/microsoft.repo - -# Install PowerShell -sudo dnf install --assumeyes powershell - -# Start PowerShell -pwsh -``` +################################### +# Prerequisites + +# Get version of RHEL +source /etc/os-release +if [ $(bc<<<"$VERSION_ID < 8") = 1 ] +then majorver=7 +elif [ $(bc<<<"$VERSION_ID < 9") = 1 ] +then majorver=8 +else majorver=9 +fi -As superuser, register the Microsoft repository once. After registration, you can update PowerShell -with `sudo dnf upgrade powershell`. - -On RHEL 7: - -```sh # Register the Microsoft RedHat repository -curl https://packages.microsoft.com/config/rhel/7/prod.repo | sudo tee /etc/yum.repos.d/microsoft.repo - -# Install PowerShell -sudo yum install --assumeyes powershell - -# Start PowerShell -pwsh +curl -sSL -O https://packages.microsoft.com/config/rhel/$majorver/packages-microsoft-prod.rpm + +# Register the Microsoft repository keys +sudo rpm -i packages-microsoft-prod.rpm + +# Delete the repository keys after installing +rm packages-microsoft-prod.rpm + +# RHEL 7.x uses yum and RHEL 8+ uses dnf +if [ $(bc<<<"$majorver < 8") ] +then + # Update package index files + sudo yum update + # Install PowerShell + sudo yum install powershell -y +else + # Update package index files + sudo dnf update + # Install PowerShell + sudo dnf install powershell -y +fi ``` -As superuser, register the Microsoft repository once. After registration, you can update PowerShell -with `sudo yum update powershell`. +## Installation via direct download -### Installation via direct download +PowerShell 7.2 introduced a universal package that makes installation easier. Download the universal +package from the [releases][02] page onto your RHEL machine. -Starting with version 7.2, PowerShell is distributed as a universal RPM package. Previous versions -of PowerShell had separate package for each OS. Download the RPM package you need onto your CentOS -machine. +The link to the current version is: -- PowerShell 7.3.7 - `https://github.com/PowerShell/PowerShell/releases/download/v7.3.7/powershell-7.3.7-1.rh.x86_64.rpm` -- PowerShell 7.2.14- `https://github.com/PowerShell/PowerShell/releases/download/v7.2.14/powershell-lts-7.2.14-1.rh.x86_64.rpm` +- PowerShell 7.3.7 universal package for supported versions of RHEL +- `https://github.com/PowerShell/PowerShell/releases/download/v7.3.7/powershell-7.3.7-1.rh.x86_64.rpm` +- PowerShell 7.2.14 universal package for supported versions of RHEL +- `https://github.com/PowerShell/PowerShell/releases/download/v7.2.14/powershell-lts-7.2.14-1.rh.x86_64.rpm` +- PowerShell 7.4-preview.5 universal package for supported versions of RHEL + - `https://github.com/PowerShell/PowerShell/releases/download/v7.4.0-preview.5/powershell-preview-7.4.0_preview.5-1.rh.x86_64.rpm` -Use the following shell command to install the latest RPM package on the target version of RHEL. -Change the URL in the following shell commands to match the version you need. +The following shell script downloads and installs the current preview release of PowerShell. You can +change the URL to download a the version of PowerShell you want to install. -On RHEL 9: +On RHEL 8 or 9: ```sh sudo dnf install https://github.com/PowerShell/PowerShell/releases/download/v7.3.7/powershell-7.3.7-1.rh.x86_64.rpm ``` -On RHEL 8: +On RHEL 7: ```sh -sudo dnf install https://github.com/PowerShell/PowerShell/releases/download/v7.3.7/powershell-7.3.7-1.rh.x86_64.rpm +sudo yum install https://github.com/PowerShell/PowerShell/releases/download/v7.3.7/powershell-7.3.7-1.rh.x86_64.rpm ``` -On RHEL 7: +## Uninstall PowerShell + +On RHEL 8 or 9: ```sh -sudo yum install https://github.com/PowerShell/PowerShell/releases/download/v7.3.7/powershell-7.3.7-1.rh.x86_64.rpm +sudo dnf remove powershell ``` -## Uninstallation - Red Hat Enterprise Linux (RHEL) 7 +On RHEL 7: ```sh sudo yum remove powershell @@ -98,23 +114,24 @@ sudo yum remove powershell ## Support for Arm processors PowerShell 7.2 and newer supports running on RHEL using a 64-bit Arm processor. Use the binary -archive installation method of installing PowerShell that is described in -[Alternate ways to install PowerShell on Linux][07]. +archive installation method of installing PowerShell that's described in +[Alternate ways to install PowerShell on Linux][05]. ## PowerShell paths - `$PSHOME` is `/opt/microsoft/powershell/7/` -- User profiles are read from `~/.config/powershell/profile.ps1` -- Default profiles are read from `$PSHOME/profile.ps1` -- User modules are read from `~/.local/share/powershell/Modules` -- Shared modules are read from `/usr/local/share/powershell/Modules` -- Default modules are read from `$PSHOME/Modules` -- PSReadLine history is recorded to `~/.local/share/powershell/PSReadLine/ConsoleHost_history.txt` - -The profiles respect PowerShell's per-host configuration, so the default host-specific profiles -exists at `Microsoft.PowerShell_profile.ps1` in the same locations. - -PowerShell respects the [XDG Base Directory Specification][06] on Linux. +- The profiles scripts are stored in the following locations: + - AllUsersAllHosts - `$PSHOME/profile.ps1` + - AllUsersCurrentHost - `$PSHOME/Microsoft.PowerShell_profile.ps1` + - CurrentUserAllHosts - `~/.config/powershell/profile.ps1` + - CurrentUserCurrentHost - `~/.config/powershell/Microsoft.PowerShell_profile.ps1` +- Modules are stored in the following locations: + - User modules - `~/.local/share/powershell/Modules` + - Shared modules - `/usr/local/share/powershell/Modules` + - Default modules - `$PSHOME/Modules` +- PSReadLine history is recorded in `~/.local/share/powershell/PSReadLine/ConsoleHost_history.txt` + +PowerShell respects the [XDG Base Directory Specification][04] on Linux. ## Supported versions @@ -124,10 +141,11 @@ PowerShell respects the [XDG Base Directory Specification][06] on Linux. Microsoft supports the installation methods in this document. There may be other methods of installation available from other third-party sources. While those tools and methods may work, -Microsoft cannot support those methods. +Microsoft can't support those methods. -[03]: #supported-versions -[05]: https://aka.ms/PowerShell-Release?tag=stable -[06]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html -[07]: install-other-linux.md#binary-archives +[01]: #supported-versions +[02]: https://aka.ms/PowerShell-Release?tag=stable +[03]: https://packages.microsoft.com +[04]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html +[05]: install-other-linux.md#binary-archives diff --git a/reference/docs-conceptual/install/install-ubuntu.md b/reference/docs-conceptual/install/install-ubuntu.md index 3dd588daa646..62452f6274f1 100644 --- a/reference/docs-conceptual/install/install-ubuntu.md +++ b/reference/docs-conceptual/install/install-ubuntu.md @@ -1,85 +1,112 @@ --- description: Information about installing PowerShell on Ubuntu -ms.date: 06/28/2023 +ms.date: 09/26/2023 title: Installing PowerShell on Ubuntu --- # Installing PowerShell on Ubuntu -All packages are available on our GitHub [releases][04] page. After the package is installed, -run `pwsh` from a terminal. Run `pwsh-preview` if you installed a preview release. Before -installing, check the list of [Supported versions][03] below. +All packages are available on our GitHub [releases][02] page. Before installing, +check the list of [Supported versions][01] below. After the package is installed, run +`pwsh` from a terminal. Run `pwsh-preview` if you installed a preview release. > [!NOTE] -> PowerShell 7.3 is an in-place upgrade that removes previous versions of PowerShell. -> -> If you need to run PowerShell 7.3 side-by-side with a previous version, reinstall the previous -> version using the [binary archive][07] method. +> PowerShell 7.3 is an in-place upgrade that removes previous versions of PowerShell 7. Preview +> versions of PowerShell can be installed side-by-side with other versions of PowerShell. If you +> need to run PowerShell 7.3 side-by-side with a previous version, reinstall the previous version +> using the [binary archive][05] method. Ubuntu uses APT (Advanced Package Tool) as a package manager. -## Installation via Package Repository +## Installation via Package Repository the Package Repository -PowerShell for Linux is published to package repositories for easy installation and updates. The URL -to the package varies by OS version: +Microsoft builds and supports a variety of software products for Linux systems and makes them +available via Linux packaging clients (apt, dnf, yum, etc). These Linux software packages are hosted +on the _Linux package repository for Microsoft products_, [https://packages.microsoft.com][03], also +known as _PMC_. -- Ubuntu 22.04 - `https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb` -- Ubuntu 20.04 - `https://packages.microsoft.com/config/ubuntu/20.04/packages-microsoft-prod.deb` -- Ubuntu 18.04 - `https://packages.microsoft.com/config/ubuntu/18.04/packages-microsoft-prod.deb` - -Use the following shell commands to install PowerShell on the target OS. +Installing PowerShell from PMC is the preferred method of installation. > [!NOTE] -> This only works for supported versions of Ubuntu. +> This script only works for supported versions of Ubuntu. ```sh +################################### +# Prerequisites + # Update the list of packages sudo apt-get update + # Install pre-requisite packages. sudo apt-get install -y wget apt-transport-https software-properties-common -# Download the Microsoft repository GPG keys -wget -q "https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/packages-microsoft-prod.deb" -# Register the Microsoft repository GPG keys + +# Get the version of Ubuntu +source /etc/os-release + +# Download the Microsoft repository keys +wget -q https://packages.microsoft.com/config/ubuntu/$VERSION_ID/packages-microsoft-prod.deb + +# Register the Microsoft repository keys sudo dpkg -i packages-microsoft-prod.deb -# Delete the the Microsoft repository GPG keys file + +# Delete the the Microsoft repository keys file rm packages-microsoft-prod.deb + # Update the list of packages after we added packages.microsoft.com sudo apt-get update + +################################### # Install PowerShell sudo apt-get install -y powershell + # Start PowerShell pwsh ``` -As superuser, register the Microsoft repository once. After registration, you can update -PowerShell with `sudo apt-get install powershell`. +## Installation via direct download -## Installation via Direct Download +PowerShell 7.2 introduced a universal package that makes installation easier. Download the universal +package from the [releases][02] page onto your Ubuntu machine. -PowerShell 7.2 introduced a universal package that makes installation easier. Download the installer -package from the [releases][04] page onto the Ubuntu machine. The link to the current -version is: +The link to the current version is: -- PowerShell 7.3.7 (universal package) for any supported version of Ubuntu +- PowerShell 7.3.7 universal package for supported versions of Ubuntu - `https://github.com/PowerShell/PowerShell/releases/download/v7.3.7/powershell_7.3.7-1.deb_amd64.deb` -- PowerShell 7.2.14 (universal package) for any supported version of Ubuntu +- PowerShell 7.2.14 universal package for supported versions of Ubuntu - `https://github.com/PowerShell/PowerShell/releases/download/v7.2.14/powershell-lts_7.2.14-1.deb_amd64.deb` +- PowerShell 7.4-preview.5 universal package for supported versions of Ubuntu + - `https://github.com/PowerShell/PowerShell/releases/download/v7.4.0-preview.5/powershell-preview_7.4.0-preview.5-1.deb_amd64.deb` -Use the following shell commands to install the package. Change the filename of the package to match -the version you downloaded. +The following shell script downloads and installs the current preview release of PowerShell. You can +change the URL to download a the version of PowerShell you want to install. ```sh -# Install the downloaded package -sudo dpkg -i powershell-lts_7.3.7-1.deb_amd64.deb +################################### +# Prerequisites + +# Update the list of packages +sudo apt-get update + +# Install pre-requisite packages. +sudo apt-get install -y wget + +# Download the PowerShell package file +wget https://github.com/PowerShell/PowerShell/releases/download/v7.4.0-preview.5/powershell-preview_7.4.0-preview.5-1.deb_amd64.deb + +################################### +# Install the PowerShell package +sudo dpkg -i powershell-preview_7.4.0-preview.5-1.deb_amd64.deb # Resolve missing dependencies and finish the install (if necessary) sudo apt-get install -f -``` -> [!NOTE] -> If the `dpkg -i` command fails with unmet dependencies, the next command, `apt-get install -f` -> resolves these issues then finishes configuring the PowerShell package. +# Delete the downloaded package file +rm powershell-preview_7.4.0-preview.5-1.deb_amd64.deb + +# Start PowerShell Preview +pwsh-preview +``` -## Uninstallation +## Uninstall PowerShell ```sh sudo apt-get remove powershell @@ -94,17 +121,18 @@ archive installation method of installing PowerShell that's described in ## PowerShell paths - `$PSHOME` is `/opt/microsoft/powershell/7/` -- User profiles are read from `~/.config/powershell/profile.ps1` -- Default profiles are read from `$PSHOME/profile.ps1` -- User modules are read from `~/.local/share/powershell/Modules` -- Shared modules are read from `/usr/local/share/powershell/Modules` -- Default modules are read from `$PSHOME/Modules` -- PSReadLine history is recorded to `~/.local/share/powershell/PSReadLine/ConsoleHost_history.txt` - -The profiles respect PowerShell's per-host configuration, so the default host-specific profiles -exists at `Microsoft.PowerShell_profile.ps1` in the same locations. - -PowerShell respects the [XDG Base Directory Specification][05] on Linux. +- The profiles scripts are stored in the following locations: + - AllUsersAllHosts - `$PSHOME/profile.ps1` + - AllUsersCurrentHost - `$PSHOME/Microsoft.PowerShell_profile.ps1` + - CurrentUserAllHosts - `~/.config/powershell/profile.ps1` + - CurrentUserCurrentHost - `~/.config/powershell/Microsoft.PowerShell_profile.ps1` +- Modules are stored in the following locations: + - User modules - `~/.local/share/powershell/Modules` + - Shared modules - `/usr/local/share/powershell/Modules` + - Default modules - `$PSHOME/Modules` +- PSReadLine history is recorded in `~/.local/share/powershell/PSReadLine/ConsoleHost_history.txt` + +PowerShell respects the [XDG Base Directory Specification][04] on Linux. ## Supported versions @@ -117,7 +145,8 @@ installation available from other third-party sources. While those tools and met Microsoft can't support those methods. -[03]: #supported-versions -[04]: https://aka.ms/PowerShell-Release?tag=stable -[05]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html -[07]: install-other-linux.md#binary-archives +[01]: #supported-versions +[02]: https://aka.ms/PowerShell-Release?tag=stable +[03]: https://packages.microsoft.com +[04]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html +[05]: install-other-linux.md#binary-archives diff --git a/reference/docs-conceptual/media/how-to-use-docs/search-scope.gif b/reference/docs-conceptual/media/how-to-use-docs/search-scope.gif new file mode 100644 index 000000000000..ef262afde9cc Binary files /dev/null and b/reference/docs-conceptual/media/how-to-use-docs/search-scope.gif differ diff --git a/reference/includes/ubuntu-support.md b/reference/includes/ubuntu-support.md index 709286957237..eb044e4bd78f 100644 --- a/reference/includes/ubuntu-support.md +++ b/reference/includes/ubuntu-support.md @@ -24,11 +24,11 @@ Ubuntu they're supported on. These versions remain supported until either the ve [3]: ../media/shared/cross-mark-274c.svg [4]: ../media/shared/large-yellow-circle-1f7e1.svg -| Ubuntu | 7.2 (LTS-current) | 7.3 | 7.4 (preview) | -| --------------------------- | :---------------: | :-------------: | :-------------: | -| ![Supported][1] 22.04 (LTS) | ![Supported][1] | ![Supported][1] | ![Supported][1] | -| ![Supported][1] 20.04 (LTS) | ![Supported][1] | ![Supported][1] | ![Supported][1] | -| ![Supported][1] 18.04 (LTS) | ![Supported][1] | ![Supported][1] | ![Supported][1] | +| Ubuntu | 7.2 (LTS-current) | 7.3 | 7.4 (preview) | +| -------------------------------- | :------------------: | :------------------: | :------------------: | +| ![Supported][1] 22.04 (LTS) | ![Supported][1] | ![Supported][1] | ![Supported][1] | +| ![Supported][1] 20.04 (LTS) | ![Supported][1] | ![Supported][1] | ![Supported][1] | +| ![Out of Support][4] 18.04 (LTS) | ![Out of Support][4] | ![Out of Support][4] | ![Out of Support][4] | Only the LTS releases of Ubuntu are officially supported. Microsoft does not support [interim releases][interim] or their equivalent. Interim releases are community supported. For more diff --git a/reference/module/index.md b/reference/module/index.md index 9fb017fdc8d5..fbcc8bc7d1c0 100644 --- a/reference/module/index.md +++ b/reference/module/index.md @@ -12,7 +12,7 @@ ms.manager: sewhee ms.product: powershell ms.topic: landing-page quickFilterColumn1: powershell-7.2,windowsserver2022-ps -quickFilterColumn2: azps-10.3.0,sqlserver-ps +quickFilterColumn2: azps-10.4.0,sqlserver-ps quickFilterColumn3: graph-powershell-1.0,systemcenter-ps-2022 title: PowerShell Module Browser ---