From ac10c23a966989e46d11a4751112f14929d30a68 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Fri, 29 Sep 2023 14:45:33 -0500 Subject: [PATCH 1/3] Updates for 7.4-p6 release --- .../About/about_Redirection.md | 94 ++++++++----- .../About/about_Preference_Variables.md | 46 ++++--- .../About/about_Redirection.md | 94 ++++++++----- .../About/about_Preference_Variables.md | 37 +++-- .../About/about_Redirection.md | 94 ++++++++----- .../About/about_ANSI_Terminals.md | 10 +- .../About/about_Preference_Variables.md | 50 +++---- .../About/about_Redirection.md | 130 +++++++++++++----- .../learn/experimental-features.md | 27 +++- .../learn/security-features.md | 24 +++- .../whats-new/What-s-New-in-PowerShell-74.md | 39 +++--- 11 files changed, 410 insertions(+), 235 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Redirection.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Redirection.md index 4baee8f008fb..012cd23dd309 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Redirection.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Redirection.md @@ -1,7 +1,7 @@ --- description: Explains how to redirect output from PowerShell to text files. Locale: en-US -ms.date: 05/04/2021 +ms.date: 09/29/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_redirection?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Redirection @@ -30,8 +30,7 @@ You can use the following methods to redirect output: a file target is functionally equivalent to piping to `Out-File` with no extra parameters. -For more information about streams, see -[about_Output_Streams](about_Output_Streams.md). +For more information about streams, see [about_Output_Streams][04]. ### Redirectable output streams @@ -47,12 +46,12 @@ PowerShell supports redirection of the following output streams. | 6 | **Information** Stream | PowerShell 5.0 | `Write-Information`, `Write-Host` | | * | All Streams | PowerShell 3.0 | | -There is also a **Progress** stream in PowerShell, but it does not support +There is also a **Progress** stream in PowerShell, but it doesn't support redirection. > [!IMPORTANT] > The **Success** and **Error** streams are similar to the stdout and stderr -> streams of other shells. However, stdin is not connected to the PowerShell +> streams of other shells. However, stdin isn't connected to the PowerShell > pipeline for input. ### PowerShell redirection operators @@ -75,10 +74,10 @@ is specified. ### Example 1: Redirect errors and output to a file -This example runs `dir` on one item that will succeed, and one that will error. +This example runs `dir` on one item that succeeds, and one that fails. ```powershell -dir 'C:\', 'fakepath' 2>&1 > .\dir.log +dir C:\, fakepath 2>&1 > .\dir.log ``` It uses `2>&1` to redirect the **Error** stream to the **Success** stream, and @@ -109,12 +108,12 @@ desired result. - `2>&1` redirects the **Error** stream to the **Success** stream (which also now includes all **Warning** stream data) - `>` redirects the **Success** stream (which now contains both **Warning** - and **Error** streams) to a file called `C:\temp\redirection.log`) + and **Error** streams) to a file called `C:\temp\redirection.log`. ### Example 4: Redirect all streams to a file This example sends all streams output from a script called `script.ps1` to a -file called `script.log` +file called `script.log`. ```powershell .\script.ps1 *> script.log @@ -124,8 +123,8 @@ file called `script.log` This example suppresses all information stream data. To read more about **Information** stream cmdlets, see -[Write-Host](xref:Microsoft.PowerShell.Utility.Write-Host) and -[Write-Information](xref:Microsoft.PowerShell.Utility.Write-Information) +[Write-Host][11] and +[Write-Information][12] ```powershell &{ @@ -175,7 +174,7 @@ When we run this script we get prompted when `$ErrorActionPreference` is set to PS C:\temp> .\test.ps1 Confirm -Cannot find path 'C:\not-here' because it does not exist. +Can't find path 'C:\not-here' because it doesn't exist. [Y] Yes [A] Yes to All [H] Halt Command [S] Suspend [?] Help (default is "Y"): H Get-Item: C:\temp\test.ps1:23 Line | @@ -186,7 +185,7 @@ Line | When we examine the log file we see the following: -``` +```powershell PS C:\temp> Get-Content .\log.txt Continue @@ -194,7 +193,7 @@ Get-Item: C:\temp\test.ps1:3 Line | 3 | get-item /not-here 2>&1 >> log.txt | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - | Cannot find path 'C:\not-here' because it does not exist. + | Can't find path 'C:\not-here' because it doesn't exist. SilentlyContinue Stop @@ -205,11 +204,11 @@ Inquire ## Notes -The redirection operators that do not append data (`>` and `n>`) overwrite the +The redirection operators that don't append data (`>` and `n>`) overwrite the current contents of the specified file without warning. However, if the file is a read-only, hidden, or system file, the redirection -**fails**. The append redirection operators (`>>` and `n>>`) do not write to a +**fails**. The append redirection operators (`>>` and `n>>`) don't write to a read-only file, but they append content to a system or hidden file. To force the redirection of content to a read-only, hidden, or system file, @@ -224,7 +223,7 @@ formatted correctly. To write to files with a different encoding, use the When you are writing to a file using either `Out-File` or the redirection operators, PowerShell formats table output to the file based on the width of -the console it is running within. For instance, when logging table output +the console it's running within. For instance, when logging table output to file using a command like `Get-ChildItem Env:\Path > path.log` on a system where the console width is set to 80 columns, the output in the file is truncated to 80 characters: @@ -267,16 +266,21 @@ Get-Service | Format-Table -AutoSize > services.log ``` For more information about `$PSDefaultParameterValues`, see -[about_Preference_Variables](about_preference_variables.md#psdefaultparametervalues). +[about_Preference_Variables][06]. + +### Redirecting binary data + +PowerShell does not support the redirection of binary data. If you redirect +byte-stream data, PowerShell treats the data as strings. This redirection +results in corrupted data. ### Potential confusion with comparison operators -The `>` operator is not to be confused with the -[Greater-than](about_Comparison_Operators.md#-gt--ge--lt-and--le) comparison +The `>` operator isn't to be confused with the [Greater-than][02] comparison operator (often denoted as `>` in other programming languages). Depending on the objects being compared, the output using `>` can appear to be -correct (because 36 is not greater than 42). +correct (because 36 isn't greater than 42). ```powershell PS> if (36 > 42) { "true" } else { "false" } @@ -311,21 +315,39 @@ The '<' operator is reserved for future use. If numeric comparison is the required operation, `-lt` and `-gt` should be used. For more information, see the `-gt` operator in -[about_Comparison_Operators](about_Comparison_Operators.md#-gt--ge--lt-and--le). +[about_Comparison_Operators][02]. ## See also -- [about_Command_Syntax](about_Command_Syntax.md) -- [about_Operators](about_Operators.md) -- [about_Output_Streams](about_Output_Streams.md) -- [about_Path_Syntax](about_Path_Syntax.md) -- [Out-File](xref:Microsoft.PowerShell.Utility.Out-File) -- [Tee-Object](xref:Microsoft.PowerShell.Utility.Tee-Object) -- [Write-Debug](xref:Microsoft.PowerShell.Utility.Write-Debug) -- [Write-Error](xref:Microsoft.PowerShell.Utility.Write-Error) -- [Write-Host](xref:Microsoft.PowerShell.Utility.Write-Host) -- [Write-Information](xref:Microsoft.PowerShell.Utility.Write-Information) -- [Write-Output](xref:Microsoft.PowerShell.Utility.Write-Output) -- [Write-Progress](xref:Microsoft.PowerShell.Utility.Write-Progress) -- [Write-Verbose](xref:Microsoft.PowerShell.Utility.Write-Verbose) -- [Write-Warning](xref:Microsoft.PowerShell.Utility.Write-Warning) +- [about_Command_Syntax][01] +- [about_Operators][03] +- [about_Output_Streams][04] +- [about_Path_Syntax][05] +- [Out-File][07] +- [Tee-Object][08] +- [Write-Debug][09] +- [Write-Error][10] +- [Write-Host][11] +- [Write-Information][12] +- [Write-Output][13] +- [Write-Progress][14] +- [Write-Verbose][15] +- [Write-Warning][16] + + +[01]: about_Command_Syntax.md +[02]: about_Comparison_Operators.md#-gt--ge--lt-and--le +[03]: about_Operators.md +[04]: about_Output_Streams.md +[05]: about_Path_Syntax.md +[06]: about_preference_variables.md#psdefaultparametervalues +[07]: xref:Microsoft.PowerShell.Utility.Out-File +[08]: xref:Microsoft.PowerShell.Utility.Tee-Object +[09]: xref:Microsoft.PowerShell.Utility.Write-Debug +[10]: xref:Microsoft.PowerShell.Utility.Write-Error +[11]: xref:Microsoft.PowerShell.Utility.Write-Host +[12]: xref:Microsoft.PowerShell.Utility.Write-Information +[13]: xref:Microsoft.PowerShell.Utility.Write-Output +[14]: xref:Microsoft.PowerShell.Utility.Write-Progress +[15]: xref:Microsoft.PowerShell.Utility.Write-Verbose +[16]: xref:Microsoft.PowerShell.Utility.Write-Warning diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Preference_Variables.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Preference_Variables.md index 0e7d7942d691..a5827aaa3185 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Preference_Variables.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Preference_Variables.md @@ -1,7 +1,7 @@ --- description: Variables that customize the behavior of PowerShell. Locale: en-US -ms.date: 01/30/2023 +ms.date: 09/29/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Preference Variables @@ -19,8 +19,8 @@ behavior. These preference variables work like the options in GUI-based systems. The preference variables affect the PowerShell operating environment and all -commands run in the environment. In many cases, the cmdlets have parameters -that you can use to override the preference behavior for a specific command. +commands run in the environment. Some cmdlets have parameters that allow you to +override the preference behavior for a specific command. The following table lists the preference variables and their default values. @@ -1007,36 +1007,44 @@ line is parsed for native commands. The new `$PSNativeCommandArgumentPassing` preference variable controls this behavior. > [!CAUTION] -> The new behavior is a **breaking change** from the current behavior. This may -> break scripts and automation that work around the various issues when -> invoking native applications. Historically, quotes must be escaped and it's -> not possible to provide empty arguments to a native application. +> The new behavior is a **breaking change** from the previous behavior. This +> may break scripts and automation that work around the various issues when +> invoking native applications. The automatic variable `$PSNativeCommandArgumentPassing` allows you to select the behavior at runtime. The valid values are `Legacy`, `Standard`, and -`Windows`. The default behavior is platform specific. On Windows platforms, the -default setting is `Windows` and non-Windows platforms default to `Standard`. +`Windows`. `Legacy` is the historic behavior. -`Legacy` is the historic behavior. The behavior of `Windows` and `Standard` -mode are the same except, in `Windows` mode, invocations of the following files -automatically use the `Legacy` style argument passing. +The `$PSNativeCommandArgumentPassing` variable is defined by default but the +value is platform specific. + +- On Windows, the preference is set to `Windows`. +- On non-Windows platforms, the preference is set to `Standard`. +- If you have removed the `$PSNativeCommandArgumentPassing` variable, + PowerShell uses the `Standard` behavior. + +The behavior of `Windows` and `Standard` mode are the same except, in `Windows` +mode, PowerShell uses the `Legacy` behavior of argument passing when you run +the following files. - `cmd.exe` - `cscript.exe` +- `find.exe` +- `sqlcmd.exe` - `wscript.exe` -- ending with `.bat` -- ending with `.cmd` -- ending with `.js` -- ending with `.vbs` -- ending with `.wsf` +- Files ending with: + - `.bat` + - `.cmd` + - `.js` + - `.vbs` + - `.wsf` If the `$PSNativeCommandArgumentPassing` is set to either `Legacy` or `Standard`, the parser doesn't check for these files. For examples of the new behavior, see [about_Parsing][33]. This experimental feature also added the ability to trace parameter binding for -native commands. For more information, see -[Trace-Command][47]. +native commands. For more information, see [Trace-Command][47]. ## $PSSessionApplicationName diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Redirection.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Redirection.md index 5859e01ca093..cfaa1ce7f320 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Redirection.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Redirection.md @@ -1,7 +1,7 @@ --- description: Explains how to redirect output from PowerShell to text files. Locale: en-US -ms.date: 05/04/2021 +ms.date: 09/29/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_redirection?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Redirection @@ -30,8 +30,7 @@ You can use the following methods to redirect output: a file target is functionally equivalent to piping to `Out-File` with no extra parameters. -For more information about streams, see -[about_Output_Streams](about_Output_Streams.md). +For more information about streams, see [about_Output_Streams][04]. ### Redirectable output streams @@ -47,12 +46,12 @@ PowerShell supports redirection of the following output streams. | 6 | **Information** Stream | PowerShell 5.0 | `Write-Information`, `Write-Host` | | * | All Streams | PowerShell 3.0 | | -There is also a **Progress** stream in PowerShell, but it does not support +There is also a **Progress** stream in PowerShell, but it doesn't support redirection. > [!IMPORTANT] > The **Success** and **Error** streams are similar to the stdout and stderr -> streams of other shells. However, stdin is not connected to the PowerShell +> streams of other shells. However, stdin isn't connected to the PowerShell > pipeline for input. ### PowerShell redirection operators @@ -75,10 +74,10 @@ is specified. ### Example 1: Redirect errors and output to a file -This example runs `dir` on one item that will succeed, and one that will error. +This example runs `dir` on one item that succeeds, and one that fails. ```powershell -dir 'C:\', 'fakepath' 2>&1 > .\dir.log +dir C:\, fakepath 2>&1 > .\dir.log ``` It uses `2>&1` to redirect the **Error** stream to the **Success** stream, and @@ -109,12 +108,12 @@ desired result. - `2>&1` redirects the **Error** stream to the **Success** stream (which also now includes all **Warning** stream data) - `>` redirects the **Success** stream (which now contains both **Warning** - and **Error** streams) to a file called `C:\temp\redirection.log`) + and **Error** streams) to a file called `C:\temp\redirection.log`. ### Example 4: Redirect all streams to a file This example sends all streams output from a script called `script.ps1` to a -file called `script.log` +file called `script.log`. ```powershell .\script.ps1 *> script.log @@ -124,8 +123,8 @@ file called `script.log` This example suppresses all information stream data. To read more about **Information** stream cmdlets, see -[Write-Host](xref:Microsoft.PowerShell.Utility.Write-Host) and -[Write-Information](xref:Microsoft.PowerShell.Utility.Write-Information) +[Write-Host][11] and +[Write-Information][12] ```powershell &{ @@ -175,7 +174,7 @@ When we run this script we get prompted when `$ErrorActionPreference` is set to PS C:\temp> .\test.ps1 Confirm -Cannot find path 'C:\not-here' because it does not exist. +Can't find path 'C:\not-here' because it doesn't exist. [Y] Yes [A] Yes to All [H] Halt Command [S] Suspend [?] Help (default is "Y"): H Get-Item: C:\temp\test.ps1:23 Line | @@ -186,7 +185,7 @@ Line | When we examine the log file we see the following: -``` +```powershell PS C:\temp> Get-Content .\log.txt Continue @@ -194,7 +193,7 @@ Get-Item: C:\temp\test.ps1:3 Line | 3 | get-item /not-here 2>&1 >> log.txt | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - | Cannot find path 'C:\not-here' because it does not exist. + | Can't find path 'C:\not-here' because it doesn't exist. SilentlyContinue Stop @@ -205,11 +204,11 @@ Inquire ## Notes -The redirection operators that do not append data (`>` and `n>`) overwrite the +The redirection operators that don't append data (`>` and `n>`) overwrite the current contents of the specified file without warning. However, if the file is a read-only, hidden, or system file, the redirection -**fails**. The append redirection operators (`>>` and `n>>`) do not write to a +**fails**. The append redirection operators (`>>` and `n>>`) don't write to a read-only file, but they append content to a system or hidden file. To force the redirection of content to a read-only, hidden, or system file, @@ -224,7 +223,7 @@ formatted correctly. To write to files with a different encoding, use the When you are writing to a file using either `Out-File` or the redirection operators, PowerShell formats table output to the file based on the width of -the console it is running within. For instance, when logging table output +the console it's running within. For instance, when logging table output to file using a command like `Get-ChildItem Env:\Path > path.log` on a system where the console width is set to 80 columns, the output in the file is truncated to 80 characters: @@ -267,16 +266,21 @@ Get-Service | Format-Table -AutoSize > services.log ``` For more information about `$PSDefaultParameterValues`, see -[about_Preference_Variables](about_preference_variables.md#psdefaultparametervalues). +[about_Preference_Variables][06]. + +### Redirecting binary data + +PowerShell does not support the redirection of binary data. If you redirect +byte-stream data, PowerShell treats the data as strings. This redirection +results in corrupted data. ### Potential confusion with comparison operators -The `>` operator is not to be confused with the -[Greater-than](about_Comparison_Operators.md#-gt--ge--lt-and--le) comparison +The `>` operator isn't to be confused with the [Greater-than][02] comparison operator (often denoted as `>` in other programming languages). Depending on the objects being compared, the output using `>` can appear to be -correct (because 36 is not greater than 42). +correct (because 36 isn't greater than 42). ```powershell PS> if (36 > 42) { "true" } else { "false" } @@ -310,21 +314,39 @@ Line | If numeric comparison is the required operation, `-lt` and `-gt` should be used. For more information, see the `-gt` operator in -[about_Comparison_Operators](about_Comparison_Operators.md#-gt--ge--lt-and--le). +[about_Comparison_Operators][02]. ## See also -- [about_Command_Syntax](about_Command_Syntax.md) -- [about_Operators](about_Operators.md) -- [about_Output_Streams](about_Output_Streams.md) -- [about_Path_Syntax](about_Path_Syntax.md) -- [Out-File](xref:Microsoft.PowerShell.Utility.Out-File) -- [Tee-Object](xref:Microsoft.PowerShell.Utility.Tee-Object) -- [Write-Debug](xref:Microsoft.PowerShell.Utility.Write-Debug) -- [Write-Error](xref:Microsoft.PowerShell.Utility.Write-Error) -- [Write-Host](xref:Microsoft.PowerShell.Utility.Write-Host) -- [Write-Information](xref:Microsoft.PowerShell.Utility.Write-Information) -- [Write-Output](xref:Microsoft.PowerShell.Utility.Write-Output) -- [Write-Progress](xref:Microsoft.PowerShell.Utility.Write-Progress) -- [Write-Verbose](xref:Microsoft.PowerShell.Utility.Write-Verbose) -- [Write-Warning](xref:Microsoft.PowerShell.Utility.Write-Warning) +- [about_Command_Syntax][01] +- [about_Operators][03] +- [about_Output_Streams][04] +- [about_Path_Syntax][05] +- [Out-File][07] +- [Tee-Object][08] +- [Write-Debug][09] +- [Write-Error][10] +- [Write-Host][11] +- [Write-Information][12] +- [Write-Output][13] +- [Write-Progress][14] +- [Write-Verbose][15] +- [Write-Warning][16] + + +[01]: about_Command_Syntax.md +[02]: about_Comparison_Operators.md#-gt--ge--lt-and--le +[03]: about_Operators.md +[04]: about_Output_Streams.md +[05]: about_Path_Syntax.md +[06]: about_preference_variables.md#psdefaultparametervalues +[07]: xref:Microsoft.PowerShell.Utility.Out-File +[08]: xref:Microsoft.PowerShell.Utility.Tee-Object +[09]: xref:Microsoft.PowerShell.Utility.Write-Debug +[10]: xref:Microsoft.PowerShell.Utility.Write-Error +[11]: xref:Microsoft.PowerShell.Utility.Write-Host +[12]: xref:Microsoft.PowerShell.Utility.Write-Information +[13]: xref:Microsoft.PowerShell.Utility.Write-Output +[14]: xref:Microsoft.PowerShell.Utility.Write-Progress +[15]: xref:Microsoft.PowerShell.Utility.Write-Verbose +[16]: xref:Microsoft.PowerShell.Utility.Write-Warning diff --git a/reference/7.3/Microsoft.PowerShell.Core/About/about_Preference_Variables.md b/reference/7.3/Microsoft.PowerShell.Core/About/about_Preference_Variables.md index 069a58068d86..43a9f0d3b7c3 100644 --- a/reference/7.3/Microsoft.PowerShell.Core/About/about_Preference_Variables.md +++ b/reference/7.3/Microsoft.PowerShell.Core/About/about_Preference_Variables.md @@ -1,7 +1,7 @@ --- description: Variables that customize the behavior of PowerShell. Locale: en-US -ms.date: 03/02/2023 +ms.date: 09/29/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Preference Variables @@ -1003,7 +1003,7 @@ For more information about automatic importing of modules, see ## $PSNativeCommandArgumentPassing -PowerShell 7.3 changed the way the command line is parsed for native commands. +PowerShell 7.3 changed the way it parses the command line for native commands. The new `$PSNativeCommandArgumentPassing` preference variable controls this behavior. @@ -1014,29 +1014,38 @@ behavior. The automatic variable `$PSNativeCommandArgumentPassing` allows you to select the behavior at runtime. The valid values are `Legacy`, `Standard`, and -`Windows`. The default behavior is platform specific. On Windows platforms, the -default setting is `Windows` and non-Windows platforms default to `Standard`. +`Windows`. `Legacy` is the historic behavior. -`Legacy` is the historic behavior. The behavior of `Windows` and `Standard` -mode are the same except, in `Windows` mode, invocations of the following files -automatically use the `Legacy` style argument passing. +The `$PSNativeCommandArgumentPassing` variable is defined by default but the +value is platform specific. + +- On Windows, the preference is set to `Windows`. +- On non-Windows platforms, the preference is set to `Standard`. +- If you have removed the `$PSNativeCommandArgumentPassing` variable, + PowerShell uses the `Standard` behavior. + +The behavior of `Windows` and `Standard` mode are the same except, in `Windows` +mode, PowerShell uses the `Legacy` behavior of argument passing when you run +the following files. - `cmd.exe` - `cscript.exe` +- `find.exe` +- `sqlcmd.exe` - `wscript.exe` -- ending with `.bat` -- ending with `.cmd` -- ending with `.js` -- ending with `.vbs` -- ending with `.wsf` +- Files ending with: + - `.bat` + - `.cmd` + - `.js` + - `.vbs` + - `.wsf` If the `$PSNativeCommandArgumentPassing` is set to either `Legacy` or `Standard`, the parser doesn't check for these files. For examples of the new behavior, see [about_Parsing][36]. PowerShell 7.3 also added the ability to trace parameter binding for native -commands. For more information, see -[Trace-Command][50]. +commands. For more information, see [Trace-Command][50]. ## $PSNativeCommandUseErrorActionPreference diff --git a/reference/7.3/Microsoft.PowerShell.Core/About/about_Redirection.md b/reference/7.3/Microsoft.PowerShell.Core/About/about_Redirection.md index 5fd6217f5c36..bab575135d98 100644 --- a/reference/7.3/Microsoft.PowerShell.Core/About/about_Redirection.md +++ b/reference/7.3/Microsoft.PowerShell.Core/About/about_Redirection.md @@ -1,7 +1,7 @@ --- description: Explains how to redirect output from PowerShell to text files. Locale: en-US -ms.date: 05/04/2021 +ms.date: 09/29/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_redirection?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Redirection @@ -30,8 +30,7 @@ You can use the following methods to redirect output: a file target is functionally equivalent to piping to `Out-File` with no extra parameters. -For more information about streams, see -[about_Output_Streams](about_Output_Streams.md). +For more information about streams, see [about_Output_Streams][04]. ### Redirectable output streams @@ -47,12 +46,12 @@ PowerShell supports redirection of the following output streams. | 6 | **Information** Stream | PowerShell 5.0 | `Write-Information`, `Write-Host` | | * | All Streams | PowerShell 3.0 | | -There is also a **Progress** stream in PowerShell, but it does not support +There is also a **Progress** stream in PowerShell, but it doesn't support redirection. > [!IMPORTANT] > The **Success** and **Error** streams are similar to the stdout and stderr -> streams of other shells. However, stdin is not connected to the PowerShell +> streams of other shells. However, stdin isn't connected to the PowerShell > pipeline for input. ### PowerShell redirection operators @@ -75,10 +74,10 @@ is specified. ### Example 1: Redirect errors and output to a file -This example runs `dir` on one item that will succeed, and one that will error. +This example runs `dir` on one item that succeeds, and one that fails. ```powershell -dir 'C:\', 'fakepath' 2>&1 > .\dir.log +dir C:\, fakepath 2>&1 > .\dir.log ``` It uses `2>&1` to redirect the **Error** stream to the **Success** stream, and @@ -109,12 +108,12 @@ desired result. - `2>&1` redirects the **Error** stream to the **Success** stream (which also now includes all **Warning** stream data) - `>` redirects the **Success** stream (which now contains both **Warning** - and **Error** streams) to a file called `C:\temp\redirection.log`) + and **Error** streams) to a file called `C:\temp\redirection.log`. ### Example 4: Redirect all streams to a file This example sends all streams output from a script called `script.ps1` to a -file called `script.log` +file called `script.log`. ```powershell .\script.ps1 *> script.log @@ -124,8 +123,8 @@ file called `script.log` This example suppresses all information stream data. To read more about **Information** stream cmdlets, see -[Write-Host](xref:Microsoft.PowerShell.Utility.Write-Host) and -[Write-Information](xref:Microsoft.PowerShell.Utility.Write-Information) +[Write-Host][11] and +[Write-Information][12] ```powershell &{ @@ -175,7 +174,7 @@ When we run this script we get prompted when `$ErrorActionPreference` is set to PS C:\temp> .\test.ps1 Confirm -Cannot find path 'C:\not-here' because it does not exist. +Can't find path 'C:\not-here' because it doesn't exist. [Y] Yes [A] Yes to All [H] Halt Command [S] Suspend [?] Help (default is "Y"): H Get-Item: C:\temp\test.ps1:23 Line | @@ -186,7 +185,7 @@ Line | When we examine the log file we see the following: -``` +```powershell PS C:\temp> Get-Content .\log.txt Continue @@ -194,7 +193,7 @@ Get-Item: C:\temp\test.ps1:3 Line | 3 | get-item /not-here 2>&1 >> log.txt | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - | Cannot find path 'C:\not-here' because it does not exist. + | Can't find path 'C:\not-here' because it doesn't exist. SilentlyContinue Stop @@ -205,11 +204,11 @@ Inquire ## Notes -The redirection operators that do not append data (`>` and `n>`) overwrite the +The redirection operators that don't append data (`>` and `n>`) overwrite the current contents of the specified file without warning. However, if the file is a read-only, hidden, or system file, the redirection -**fails**. The append redirection operators (`>>` and `n>>`) do not write to a +**fails**. The append redirection operators (`>>` and `n>>`) don't write to a read-only file, but they append content to a system or hidden file. To force the redirection of content to a read-only, hidden, or system file, @@ -224,7 +223,7 @@ formatted correctly. To write to files with a different encoding, use the When you are writing to a file using either `Out-File` or the redirection operators, PowerShell formats table output to the file based on the width of -the console it is running within. For instance, when logging table output +the console it's running within. For instance, when logging table output to file using a command like `Get-ChildItem Env:\Path > path.log` on a system where the console width is set to 80 columns, the output in the file is truncated to 80 characters: @@ -267,16 +266,21 @@ Get-Service | Format-Table -AutoSize > services.log ``` For more information about `$PSDefaultParameterValues`, see -[about_Preference_Variables](about_preference_variables.md#psdefaultparametervalues). +[about_Preference_Variables][06]. + +### Redirecting binary data + +PowerShell does not support the redirection of binary data. If you redirect +byte-stream data, PowerShell treats the data as strings. This redirection +results in corrupted data. ### Potential confusion with comparison operators -The `>` operator is not to be confused with the -[Greater-than](about_Comparison_Operators.md#-gt--ge--lt-and--le) comparison +The `>` operator isn't to be confused with the [Greater-than][02] comparison operator (often denoted as `>` in other programming languages). Depending on the objects being compared, the output using `>` can appear to be -correct (because 36 is not greater than 42). +correct (because 36 isn't greater than 42). ```powershell PS> if (36 > 42) { "true" } else { "false" } @@ -310,21 +314,39 @@ Line | If numeric comparison is the required operation, `-lt` and `-gt` should be used. For more information, see the `-gt` operator in -[about_Comparison_Operators](about_Comparison_Operators.md#-gt--ge--lt-and--le). +[about_Comparison_Operators][02]. ## See also -- [about_Command_Syntax](about_Command_Syntax.md) -- [about_Operators](about_Operators.md) -- [about_Output_Streams](about_Output_Streams.md) -- [about_Path_Syntax](about_Path_Syntax.md) -- [Out-File](xref:Microsoft.PowerShell.Utility.Out-File) -- [Tee-Object](xref:Microsoft.PowerShell.Utility.Tee-Object) -- [Write-Debug](xref:Microsoft.PowerShell.Utility.Write-Debug) -- [Write-Error](xref:Microsoft.PowerShell.Utility.Write-Error) -- [Write-Host](xref:Microsoft.PowerShell.Utility.Write-Host) -- [Write-Information](xref:Microsoft.PowerShell.Utility.Write-Information) -- [Write-Output](xref:Microsoft.PowerShell.Utility.Write-Output) -- [Write-Progress](xref:Microsoft.PowerShell.Utility.Write-Progress) -- [Write-Verbose](xref:Microsoft.PowerShell.Utility.Write-Verbose) -- [Write-Warning](xref:Microsoft.PowerShell.Utility.Write-Warning) +- [about_Command_Syntax][01] +- [about_Operators][03] +- [about_Output_Streams][04] +- [about_Path_Syntax][05] +- [Out-File][07] +- [Tee-Object][08] +- [Write-Debug][09] +- [Write-Error][10] +- [Write-Host][11] +- [Write-Information][12] +- [Write-Output][13] +- [Write-Progress][14] +- [Write-Verbose][15] +- [Write-Warning][16] + + +[01]: about_Command_Syntax.md +[02]: about_Comparison_Operators.md#-gt--ge--lt-and--le +[03]: about_Operators.md +[04]: about_Output_Streams.md +[05]: about_Path_Syntax.md +[06]: about_preference_variables.md#psdefaultparametervalues +[07]: xref:Microsoft.PowerShell.Utility.Out-File +[08]: xref:Microsoft.PowerShell.Utility.Tee-Object +[09]: xref:Microsoft.PowerShell.Utility.Write-Debug +[10]: xref:Microsoft.PowerShell.Utility.Write-Error +[11]: xref:Microsoft.PowerShell.Utility.Write-Host +[12]: xref:Microsoft.PowerShell.Utility.Write-Information +[13]: xref:Microsoft.PowerShell.Utility.Write-Output +[14]: xref:Microsoft.PowerShell.Utility.Write-Progress +[15]: xref:Microsoft.PowerShell.Utility.Write-Verbose +[16]: xref:Microsoft.PowerShell.Utility.Write-Warning 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 1113135067e6..fd0a3f429059 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: 09/26/2023 +ms.date: 09/29/2023 schema: 2.0.0 title: about ANSI terminals --- @@ -145,11 +145,13 @@ The following members control how or when ANSI formatting is used: - **Debug** - formatting for debug messages - **TableHeader** - formatting for table headers - **CustomTableHeaderLabel** - formatting for table headers that are - calculated values (added as an experimental feature in PowerShell 7.4) - - **FeedbackProvider** - formatting for the feedback provider label (added as - an experimental feature in PowerShell 7.4) + calculated values + - **FeedbackName** - formatting for the feedback provider name (added as an + experimental feature in PowerShell 7.4) - **FeedbackText** - formatting for feedback messages (added as an experimental feature in PowerShell 7.4) + - **FeedbackAction** - formatting for the feedback provider suggested actions + (added as an experimental feature in PowerShell 7.4) - `$PSStyle.Progress` allows you to control progress view bar rendering. diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Preference_Variables.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Preference_Variables.md index d9a41197bd5b..9f8bc97a7e6c 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Preference_Variables.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Preference_Variables.md @@ -1,7 +1,7 @@ --- description: Variables that customize the behavior of PowerShell. Locale: en-US -ms.date: 03/02/2023 +ms.date: 09/29/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Preference Variables @@ -60,7 +60,6 @@ PowerShell includes the following environment variables that store user preferences. For more information about these environment variables, see [about_Environment_Variables][31]. - - `env:PSExecutionPolicyPreference` - `$env:PSModulePath` @@ -1004,7 +1003,7 @@ For more information about automatic importing of modules, see ## $PSNativeCommandArgumentPassing -PowerShell 7.3 changed the way the command line is parsed for native commands. +PowerShell 7.3 changed the way it parses the command line for native commands. The new `$PSNativeCommandArgumentPassing` preference variable controls this behavior. @@ -1015,42 +1014,43 @@ behavior. The automatic variable `$PSNativeCommandArgumentPassing` allows you to select the behavior at runtime. The valid values are `Legacy`, `Standard`, and -`Windows`. The default behavior is platform specific. On Windows platforms, the -default setting is `Windows` and non-Windows platforms default to `Standard`. +`Windows`. `Legacy` is the historic behavior. + +The `$PSNativeCommandArgumentPassing` variable is defined by default but the +value is platform specific. + +- On Windows, the preference is set to `Windows`. +- On non-Windows platforms, the preference is set to `Standard`. +- If you have removed the `$PSNativeCommandArgumentPassing` variable, + PowerShell uses the `Standard` behavior. -`Legacy` is the historic behavior. The behavior of `Windows` and `Standard` -mode are the same except, in `Windows` mode, invocations of the following files -automatically use the `Legacy` style argument passing. +The behavior of `Windows` and `Standard` mode are the same except, in `Windows` +mode, PowerShell uses the `Legacy` behavior of argument passing when you run +the following files. - `cmd.exe` - `cscript.exe` +- `find.exe` +- `sqlcmd.exe` - `wscript.exe` -- ending with `.bat` -- ending with `.cmd` -- ending with `.js` -- ending with `.vbs` -- ending with `.wsf` +- Files ending with: + - `.bat` + - `.cmd` + - `.js` + - `.vbs` + - `.wsf` If the `$PSNativeCommandArgumentPassing` is set to either `Legacy` or `Standard`, the parser doesn't check for these files. For examples of the new behavior, see [about_Parsing][36]. PowerShell 7.3 also added the ability to trace parameter binding for native -commands. For more information, see -[Trace-Command][50]. +commands. For more information, see [Trace-Command][50]. ## $PSNativeCommandUseErrorActionPreference -This preference variable is available in PowerShell 7.3 and later with the -`PSNativeCommandErrorActionPreference` feature enabled. - -With this feature enabled, native commands with non-zero exit codes issue -errors according to `$ErrorActionPreference` when -`$PSNativeCommandUseErrorActionPreference` is `$true`. - -> [!NOTE] -> `PSNativeCommandUseErrorActionPreference` is an experimental feature added in -> PowerShell 7.3. For more information, see [Using experimental features][01]. +When `$PSNativeCommandUseErrorActionPreference` is `$true`, native commands +with non-zero exit codes issue errors according to `$ErrorActionPreference`. Some native commands, like [robocopy][02] use non-zero exit codes to represent information other than errors. In these cases, you can temporarily disable the diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Redirection.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Redirection.md index 7a4400d010e7..606f57e2daa1 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Redirection.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Redirection.md @@ -1,7 +1,7 @@ --- description: Explains how to redirect output from PowerShell to text files. Locale: en-US -ms.date: 05/04/2021 +ms.date: 09/29/2023 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_redirection?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Redirection @@ -30,8 +30,7 @@ You can use the following methods to redirect output: a file target is functionally equivalent to piping to `Out-File` with no extra parameters. -For more information about streams, see -[about_Output_Streams](about_Output_Streams.md). +For more information about streams, see [about_Output_Streams][04]. ### Redirectable output streams @@ -47,12 +46,12 @@ PowerShell supports redirection of the following output streams. | 6 | **Information** Stream | PowerShell 5.0 | `Write-Information`, `Write-Host` | | * | All Streams | PowerShell 3.0 | | -There is also a **Progress** stream in PowerShell, but it does not support +There is also a **Progress** stream in PowerShell, but it doesn't support redirection. > [!IMPORTANT] > The **Success** and **Error** streams are similar to the stdout and stderr -> streams of other shells. However, stdin is not connected to the PowerShell +> streams of other shells. However, stdin isn't connected to the PowerShell > pipeline for input. ### PowerShell redirection operators @@ -75,10 +74,10 @@ is specified. ### Example 1: Redirect errors and output to a file -This example runs `dir` on one item that will succeed, and one that will error. +This example runs `dir` on one item that succeeds, and one that fails. ```powershell -dir 'C:\', 'fakepath' 2>&1 > .\dir.log +dir C:\, fakepath 2>&1 > .\dir.log ``` It uses `2>&1` to redirect the **Error** stream to the **Success** stream, and @@ -109,12 +108,12 @@ desired result. - `2>&1` redirects the **Error** stream to the **Success** stream (which also now includes all **Warning** stream data) - `>` redirects the **Success** stream (which now contains both **Warning** - and **Error** streams) to a file called `C:\temp\redirection.log`) + and **Error** streams) to a file called `C:\temp\redirection.log`. ### Example 4: Redirect all streams to a file This example sends all streams output from a script called `script.ps1` to a -file called `script.log` +file called `script.log`. ```powershell .\script.ps1 *> script.log @@ -124,8 +123,8 @@ file called `script.log` This example suppresses all information stream data. To read more about **Information** stream cmdlets, see -[Write-Host](xref:Microsoft.PowerShell.Utility.Write-Host) and -[Write-Information](xref:Microsoft.PowerShell.Utility.Write-Information) +[Write-Host][11] and +[Write-Information][12] ```powershell &{ @@ -175,7 +174,7 @@ When we run this script we get prompted when `$ErrorActionPreference` is set to PS C:\temp> .\test.ps1 Confirm -Cannot find path 'C:\not-here' because it does not exist. +Can't find path 'C:\not-here' because it doesn't exist. [Y] Yes [A] Yes to All [H] Halt Command [S] Suspend [?] Help (default is "Y"): H Get-Item: C:\temp\test.ps1:23 Line | @@ -186,7 +185,7 @@ Line | When we examine the log file we see the following: -``` +```powershell PS C:\temp> Get-Content .\log.txt Continue @@ -194,7 +193,7 @@ Get-Item: C:\temp\test.ps1:3 Line | 3 | get-item /not-here 2>&1 >> log.txt | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - | Cannot find path 'C:\not-here' because it does not exist. + | Can't find path 'C:\not-here' because it doesn't exist. SilentlyContinue Stop @@ -203,13 +202,55 @@ Ignore Inquire ``` +### Example 7: Redirecting binary data from a native command + +Beginning in PowerShell 7.4, PowerShell preserves the byte-stream data when +redirecting the **stdout** stream of a native command to a file or when piping +byte-stream data to the **stdin** stream of a native command. + +For example, using the native command `curl` you can download a binary file and +save it to disk using redirection. + +```powershell +$uri = 'https://github.com/PowerShell/PowerShell/releases/download/v7.3.7/powershell-7.3.7-linux-arm64.tar.gz' + +# native command redirected to a file +curl -s -L $uri > powershell.tar.gz +``` + +You can also pipe the byte-stream data to the **stdin** stream of another +native command. The following example downloads a zipped TAR file using `curl`. +The downloaded file data is streamed to the `tar` command to extract the +contents of the archive. + +```powershell +# native command output piped to a native command +curl -s -L $uri | tar -xzvf - -C . +``` + +You can also pipe the byte-stream output of a PowerShell command to the input +of native command. The following examples use `Invoke-WebRequest` to download +the same TAR file as the previous example. + +```powershell +# byte stream piped to a native command +(Invoke-WebRequest $uri).Content | tar -xzvf - -C . + +# bytes piped to a native command (all at once as byte[]) +,(Invoke-WebRequest $uri).Content | tar -xzvf - -C . +``` + +This feature doesn't support byte-stream data when redirecting **stderr** +output to **stdout**. When you combine the **stderr** and **stdout** streams, +the combined streams are treated as string data. + ## Notes -The redirection operators that do not append data (`>` and `n>`) overwrite the +The redirection operators that don't append data (`>` and `n>`) overwrite the current contents of the specified file without warning. However, if the file is a read-only, hidden, or system file, the redirection -**fails**. The append redirection operators (`>>` and `n>>`) do not write to a +**fails**. The append redirection operators (`>>` and `n>>`) don't write to a read-only file, but they append content to a system or hidden file. To force the redirection of content to a read-only, hidden, or system file, @@ -224,7 +265,7 @@ formatted correctly. To write to files with a different encoding, use the When you are writing to a file using either `Out-File` or the redirection operators, PowerShell formats table output to the file based on the width of -the console it is running within. For instance, when logging table output +the console it's running within. For instance, when logging table output to file using a command like `Get-ChildItem Env:\Path > path.log` on a system where the console width is set to 80 columns, the output in the file is truncated to 80 characters: @@ -267,16 +308,15 @@ Get-Service | Format-Table -AutoSize > services.log ``` For more information about `$PSDefaultParameterValues`, see -[about_Preference_Variables](about_preference_variables.md#psdefaultparametervalues). +[about_Preference_Variables][06]. ### Potential confusion with comparison operators -The `>` operator is not to be confused with the -[Greater-than](about_Comparison_Operators.md#-gt--ge--lt-and--le) comparison +The `>` operator isn't to be confused with the [Greater-than][02] comparison operator (often denoted as `>` in other programming languages). Depending on the objects being compared, the output using `>` can appear to be -correct (because 36 is not greater than 42). +correct (because 36 isn't greater than 42). ```powershell PS> if (36 > 42) { "true" } else { "false" } @@ -310,21 +350,39 @@ Line | If numeric comparison is the required operation, `-lt` and `-gt` should be used. For more information, see the `-gt` operator in -[about_Comparison_Operators](about_Comparison_Operators.md#-gt--ge--lt-and--le). +[about_Comparison_Operators][02]. ## See also -- [about_Command_Syntax](about_Command_Syntax.md) -- [about_Operators](about_Operators.md) -- [about_Output_Streams](about_Output_Streams.md) -- [about_Path_Syntax](about_Path_Syntax.md) -- [Out-File](xref:Microsoft.PowerShell.Utility.Out-File) -- [Tee-Object](xref:Microsoft.PowerShell.Utility.Tee-Object) -- [Write-Debug](xref:Microsoft.PowerShell.Utility.Write-Debug) -- [Write-Error](xref:Microsoft.PowerShell.Utility.Write-Error) -- [Write-Host](xref:Microsoft.PowerShell.Utility.Write-Host) -- [Write-Information](xref:Microsoft.PowerShell.Utility.Write-Information) -- [Write-Output](xref:Microsoft.PowerShell.Utility.Write-Output) -- [Write-Progress](xref:Microsoft.PowerShell.Utility.Write-Progress) -- [Write-Verbose](xref:Microsoft.PowerShell.Utility.Write-Verbose) -- [Write-Warning](xref:Microsoft.PowerShell.Utility.Write-Warning) +- [about_Command_Syntax][01] +- [about_Operators][03] +- [about_Output_Streams][04] +- [about_Path_Syntax][05] +- [Out-File][07] +- [Tee-Object][08] +- [Write-Debug][09] +- [Write-Error][10] +- [Write-Host][11] +- [Write-Information][12] +- [Write-Output][13] +- [Write-Progress][14] +- [Write-Verbose][15] +- [Write-Warning][16] + + +[01]: about_Command_Syntax.md +[02]: about_Comparison_Operators.md#-gt--ge--lt-and--le +[03]: about_Operators.md +[04]: about_Output_Streams.md +[05]: about_Path_Syntax.md +[06]: about_preference_variables.md#psdefaultparametervalues +[07]: xref:Microsoft.PowerShell.Utility.Out-File +[08]: xref:Microsoft.PowerShell.Utility.Tee-Object +[09]: xref:Microsoft.PowerShell.Utility.Write-Debug +[10]: xref:Microsoft.PowerShell.Utility.Write-Error +[11]: xref:Microsoft.PowerShell.Utility.Write-Host +[12]: xref:Microsoft.PowerShell.Utility.Write-Information +[13]: xref:Microsoft.PowerShell.Utility.Write-Output +[14]: xref:Microsoft.PowerShell.Utility.Write-Progress +[15]: xref:Microsoft.PowerShell.Utility.Write-Verbose +[16]: xref:Microsoft.PowerShell.Utility.Write-Warning diff --git a/reference/docs-conceptual/learn/experimental-features.md b/reference/docs-conceptual/learn/experimental-features.md index 54ad0e47a2bd..4d8256871033 100644 --- a/reference/docs-conceptual/learn/experimental-features.md +++ b/reference/docs-conceptual/learn/experimental-features.md @@ -1,6 +1,6 @@ --- description: Lists the currently available experimental features and how to use them. -ms.date: 06/22/2023 +ms.date: 09/29/2023 title: Using Experimental Features in PowerShell --- # Using Experimental Features in PowerShell @@ -42,14 +42,14 @@ Legend | PSNativeCommandArgumentPassing | ![Experimental][02] | ![Mainstream][01] | | | PSAnsiRenderingFileInfo | ![Experimental][02] | ![Mainstream][01] | | | PSLoadAssemblyFromNativeCode | ![Experimental][02] | ![Experimental][02] | ![Experimental][02] | -| PSNativeCommandErrorActionPreference | | ![Experimental][02] | ![Experimental][02] | -| PSCustomTableHeaderLabelDecoration | | | ![Experimental][02] | +| PSNativeCommandErrorActionPreference | | ![Experimental][02] | ![Mainstream][01] | +| PSCustomTableHeaderLabelDecoration | | | ![Mainstream][01] | | PSFeedbackProvider | | | ![Experimental][02] | | PSModuleAutoLoadSkipOfflineFiles | | | ![Experimental][02] | | PSCommandWithArgs | | | ![Experimental][02] | -| PSConstrainedAuditLogging | | | ![Experimental][02] | -| PSNativeCommandPreserveBytePipe | | | ![Experimental][02] | -| PSWindowsNativeCommandArgPassing | | | ![Experimental][02] | +| PSConstrainedAuditLogging | | | ![Mainstream][01] | +| PSNativeCommandPreserveBytePipe | | | ![Mainstream][01] | +| PSWindowsNativeCommandArgPassing | | | ![Mainstream][01] | ## PSAnsiRenderingFileInfo @@ -112,6 +112,9 @@ This feature was added in PowerShell 7.4-preview.2. ## PSConstrainedAuditLogging +> [!NOTE] +> This feature became mainstream in PowerShell 7.4-preview.6. + On Windows, when PowerShell runs under a Windows Defender Application Control (WDAC) policy, it changes its behavior based on the defined security policy. Under a WDAC policy, PowerShell runs trusted scripts and modules allowed by the policy in Full Language mode. All other scripts and @@ -128,6 +131,9 @@ This feature was added in PowerShell 7.4-preview.4. ## PSCustomTableHeaderLabelDecoration +> [!NOTE] +> This feature became mainstream in PowerShell 7.4-preview.6. + When you enable this feature, `$PSStyle` includes formatting differentiation for table header labels that aren't property members. For example, the default output from `Get-Process` includes the following columns: `NPM(K)`, `PM(M)`, `WS(M)`, and `CPU(s)`. @@ -271,6 +277,9 @@ information, see [Trace-Command][13]. ## PSNativeCommandErrorActionPreference +> [!NOTE] +> This feature became mainstream in PowerShell 7.4-preview.6. + Native commands usually return an exit code to the calling application that's zero for success or non-zero for failure. However, native commands currently don't participate in the PowerShell error stream. Redirected **stderr** output isn't interpreted the same as the PowerShell error stream. Many @@ -309,6 +318,9 @@ set to `$true` you get the following behavior: ## PSNativeCommandPreserveBytePipe +> [!NOTE] +> This feature became mainstream in PowerShell 7.4-preview.6. + This feature preserves the byte-stream data when redirecting the **stdout** stream of a native command to a file or when piping byte-stream data to the **stdin** stream of a native command. @@ -381,6 +393,9 @@ on the system. ## PSWindowsNativeCommandArgPassing +> [!NOTE] +> This feature became mainstream in PowerShell 7.4-preview.6. + The feature changes the default values of the `$PSNativeCommandArgumentPassing` variable. - When you enable this feature on Windows, `$PSNativeCommandArgumentPassing` is set to `Windows`. diff --git a/reference/docs-conceptual/learn/security-features.md b/reference/docs-conceptual/learn/security-features.md index b4cf2f37b987..11aef226690f 100644 --- a/reference/docs-conceptual/learn/security-features.md +++ b/reference/docs-conceptual/learn/security-features.md @@ -1,6 +1,6 @@ --- description: PowerShell has several features designed to improve the security of your scripting environment. -ms.date: 05/23/2023 +ms.date: 09/29/2023 title: PowerShell security features --- # PowerShell security features @@ -57,6 +57,24 @@ experience to help secure your PowerShell environment. For more information about how PowerShell supports AppLocker and WDAC, see [Using Windows Defender Application Control][01]. +### Changes in PowerShell 7.4 + +On Windows, when PowerShell runs under a Windows Defender Application Control (WDAC) policy, it +changes its behavior based on the defined security policy. Under a WDAC policy, PowerShell runs +trusted scripts and modules allowed by the policy in Full Language mode. All other scripts and +script blocks are untrusted and run in Constrained Language mode. PowerShell throws errors when the +untrusted scripts attempt to perform disallowed actions. It's difficult to know why a script fails +to run correctly in Constrained Language mode. + +PowerShell 7.4 now supports WDAC policies in **Audit** mode. In audit mode, PowerShell runs the +untrusted scripts in Constrained Language mode but logs messages to the event log instead of +throwing errors. The log messages describe what restrictions would apply if the policy was in +**Enforce** mode. + +### Changes in PowerShell 7.3 + +- PowerShell 7.3 now supports the ability to block or allow PowerShell script files via the WDAC API. + ### Changes in PowerShell 7.2 - There was a corner-case scenario in AppLocker where you only have **Deny** rules and constrained @@ -70,10 +88,6 @@ For more information about how PowerShell supports AppLocker and WDAC, see - PowerShell 7.2 now disallows scripts from using COM objects in AppLocker system lock down conditions. Cmdlet that use COM or DCOM internally aren't affected. -### Changes in PowerShell 7.3 - -- PowerShell 7.3 now supports the ability to block or allow PowerShell script files via the WDAC API. - ### Security Servicing Criteria PowerShell follows the [Microsoft Security Servicing Criteria for Windows][13]. The table below diff --git a/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-74.md b/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-74.md index a3d608b1fc9e..e205419009a2 100644 --- a/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-74.md +++ b/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-74.md @@ -1,12 +1,12 @@ --- title: What's New in PowerShell 7.4 (preview) description: New features and changes released in PowerShell 7.4 (preview) -ms.date: 08/22/2023 +ms.date: 09/29/2023 --- # What's New in PowerShell 7.4 (preview) -PowerShell 7.4-preview.5 includes the following features, updates, and breaking changes. PowerShell +PowerShell 7.4-preview.6 includes the following features, updates, and breaking changes. PowerShell 7.4 is now built on .NET 8.0.0-preview.7. For a complete list of changes, see the [CHANGELOG][15] in the GitHub repository. @@ -17,7 +17,7 @@ For a complete list of changes, see the [CHANGELOG][15] in the GitHub repository - Added the **ProgressAction** parameter to the Common Parameters - Update some PowerShell APIs to throw **ArgumentException** instead of **ArgumentNullException** when the argument is an empty string ([#19215][19215]) (Thanks @xtqqczze!) -- Remove code related to #requires -pssnapin ([#19320][19320]) +- Remove code related to `#requires -pssnapin` ([#19320][19320]) - `Test-Json` now uses Json.Schema.Net instead of Newtonsoft.Json.Schema. With this change, `Test-Json` no longer supports the older Draft 4 schemas. ([#18141][18141]) (Thanks @gregsdennis!) - Output from`Test-Connection` now includes more detailed information about TCP connection tests @@ -27,17 +27,17 @@ For a complete list of changes, see the [CHANGELOG][15] in the GitHub repository The Windows MSI package now provides an option to disable PowerShell telemetry during installation. For more information, see [Install the msi package from the command line][01]. -## PowerShellGet v3 +## Inclusion of PSResourceGet -As of PowerShell 7.4-preview.4, **Microsoft.PowerShell.PSResourceGet** (also known as PowerShellGet -v3) is now included in PowerShell 7.4. This module is installed side-by-side with **PowerShellGet** -v2.2.5 and **PackageManagement** v1.4.8.1. +As of PowerShell 7.4-preview.6, **Microsoft.PowerShell.PSResourceGet** v0.9.0-rc1 is now included. +This module is installed side-by-side with **PowerShellGet** v2.2.5 and **PackageManagement** +v1.4.8.1. For more information, see the documentation for [Microsoft.PowerShell.PSResourceGet][14]. ## Tab completion improvements -Many thanks to **@MartinGC94** and others for all the work on improving tab completion. +Many thanks to **@MartinGC94** and others for all their work to improve tab completion. - Fix issue when completing the first command in a script with an empty array expression ([[#18355][18355]) @@ -154,7 +154,7 @@ Updates to `$PSStyle` - Adds **Dim** and **DimOff** properties ([#18653][18653]) - Added static methods to the **PSStyle** class that map foreground and background **ConsoleColor** values to ANSI escape sequences ([#17938][17938]) -- New formatting properties added by experimental features +- Table headers for calculated fields are formatted in italics by default - Add support of respecting `$PSStyle.OutputRendering` on the remote host ([#19601][19601]) Other Engine updates @@ -175,29 +175,32 @@ Other Engine updates PowerShell 7.4 introduces the following experimental features: -- [PSCustomTableHeaderLabelDecoration][05] - Add formatting differentiation for table header labels - that aren't property members. - - This feature also adds the **CustomTableHeaderLabel** property to `$PSStyle.Formatting` that - allows you to change the formatting of the header label. - [PSFeedbackProvider][06] - Replaces the hard-coded suggestion framework with an extensible feedback provider. - - This feature also adds the **FeedbackProvider** and **FeedbackText** properties to - `$PSStyle.Formatting` that allow you to change the formatting of feedback messages. + - This feature also adds the **FeedbackName**, **FeedbackText**, and **FeedbackAction** properties + to `$PSStyle.Formatting` that allow you to change the formatting of feedback messages. - [PSModuleAutoLoadSkipOfflineFiles][07] - Module discovery now skips over files that are marked by cloud providers as not fully on disk. - [PSCommandWithArgs][04] - Add support for passing arguments to commands as a single string + +The following experimental features became mainstream: + - [PSConstrainedAuditLogging][09] - Add support for logging message about code that would not be allowed in Constrained language mode +- [PSCustomTableHeaderLabelDecoration][05] - Add formatting differentiation for table header labels + that aren't property members. + - This feature also adds the **CustomTableHeaderLabel** property to `$PSStyle.Formatting` that + allows you to change the formatting of the header label. +- [PSNativeCommandErrorActionPreference][08] - `$PSNativeCommandUseErrorActionPreference` is set to + `$true` when feature is enabled ([#18695][18695]) - [PSNativeCommandPreserveBytePipe][10] - Preserves the byte-stream data when redirecting the **stdout** stream of a native command to a file or when piping byte-stream data to the stdin stream of a native command. - [PSWindowsNativeCommandArgPassing][11] - Changes the default value of - `$PSNativeCommandArgumentPassing` on Windows + `$PSNativeCommandArgumentPassing` to `Windows` on Windows. PowerShell 7.4 changed the following experimental features: -- [PSNativeCommandErrorActionPreference][08] - `$PSNativeCommandUseErrorActionPreference` is set to - `$true` when feature is enabled ([#18695][18695]) - [PSCommandNotFoundSuggestion][03] - This feature now uses an extensible feedback provider rather than hard-coded suggestions ([#18726][18726]) From 3ff0acddfd44b542aecf2056880404f0551d3fee Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Fri, 29 Sep 2023 14:50:08 -0500 Subject: [PATCH 2/3] Update feedback config to reduce empty submissions --- .github/ISSUE_TEMPLATE/04-customer-feedback.yml | 4 ++-- reference/docfx.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/04-customer-feedback.yml b/.github/ISSUE_TEMPLATE/04-customer-feedback.yml index 3b908ebb5b36..bee8a204d61c 100644 --- a/.github/ISSUE_TEMPLATE/04-customer-feedback.yml +++ b/.github/ISSUE_TEMPLATE/04-customer-feedback.yml @@ -1,5 +1,5 @@ name: "📄 Feedback control template" -title: "[Documentation feedback] - " +title: "" description: >- ⛔ This template is intended for use by the feedback control on the bottom of every page on the live site. If you aren't using the feedback control, choose one of the other templates.⛔ @@ -25,7 +25,7 @@ body: validations: required: true - type: textarea - id: feedback + id: userfeedback validations: required: true attributes: diff --git a/reference/docfx.json b/reference/docfx.json index 8dab828c5ac4..a4b274f76eee 100644 --- a/reference/docfx.json +++ b/reference/docfx.json @@ -96,7 +96,7 @@ "feedback_product_url": "https://github.com/PowerShell/PowerShell/issues/new/choose", "feedback_system": "OpenSource", "open_source_feedback_contributorGuideUrl": "https://learn.microsoft.com/powershell/scripting/community/contributing/powershell-style-guide", - "open_source_feedback_issueTitle": "Customer feedback - ", + "open_source_feedback_issueTitle": "", "open_source_feedback_issueLabels": "needs-triage", "open_source_feedback_issueUrl": "https://github.com/MicrosoftDocs/PowerShell-Docs/issues/new?template=04-customer-feedback.yml", "open_source_feedback_productDescription": "PowerShell is an open source project. Select a link to provide feedback:", From ca42d677b9833b61f53b9d6e568a7e71d833215d Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Fri, 29 Sep 2023 14:56:27 -0500 Subject: [PATCH 3/3] Feedback edits --- .../5.1/Microsoft.PowerShell.Core/About/about_Redirection.md | 4 ++-- .../7.2/Microsoft.PowerShell.Core/About/about_Redirection.md | 4 ++-- .../7.3/Microsoft.PowerShell.Core/About/about_Redirection.md | 4 ++-- .../7.4/Microsoft.PowerShell.Core/About/about_Redirection.md | 2 +- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Redirection.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Redirection.md index 012cd23dd309..5c597ad80512 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Redirection.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Redirection.md @@ -193,7 +193,7 @@ Get-Item: C:\temp\test.ps1:3 Line | 3 | get-item /not-here 2>&1 >> log.txt | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - | Can't find path 'C:\not-here' because it doesn't exist. + | Cannot find path 'C:\not-here' because it does not exist. SilentlyContinue Stop @@ -270,7 +270,7 @@ For more information about `$PSDefaultParameterValues`, see ### Redirecting binary data -PowerShell does not support the redirection of binary data. If you redirect +PowerShell doesn't support the redirection of binary data. If you redirect byte-stream data, PowerShell treats the data as strings. This redirection results in corrupted data. diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Redirection.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Redirection.md index cfaa1ce7f320..137b922273f7 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Redirection.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Redirection.md @@ -193,7 +193,7 @@ Get-Item: C:\temp\test.ps1:3 Line | 3 | get-item /not-here 2>&1 >> log.txt | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - | Can't find path 'C:\not-here' because it doesn't exist. + | Cannot find path 'C:\not-here' because it does not exist. SilentlyContinue Stop @@ -270,7 +270,7 @@ For more information about `$PSDefaultParameterValues`, see ### Redirecting binary data -PowerShell does not support the redirection of binary data. If you redirect +PowerShell doesn't support the redirection of binary data. If you redirect byte-stream data, PowerShell treats the data as strings. This redirection results in corrupted data. diff --git a/reference/7.3/Microsoft.PowerShell.Core/About/about_Redirection.md b/reference/7.3/Microsoft.PowerShell.Core/About/about_Redirection.md index bab575135d98..8775da98b9c4 100644 --- a/reference/7.3/Microsoft.PowerShell.Core/About/about_Redirection.md +++ b/reference/7.3/Microsoft.PowerShell.Core/About/about_Redirection.md @@ -193,7 +193,7 @@ Get-Item: C:\temp\test.ps1:3 Line | 3 | get-item /not-here 2>&1 >> log.txt | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - | Can't find path 'C:\not-here' because it doesn't exist. + | Cannot find path 'C:\not-here' because it does not exist. SilentlyContinue Stop @@ -270,7 +270,7 @@ For more information about `$PSDefaultParameterValues`, see ### Redirecting binary data -PowerShell does not support the redirection of binary data. If you redirect +PowerShell doesn't support the redirection of binary data. If you redirect byte-stream data, PowerShell treats the data as strings. This redirection results in corrupted data. diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Redirection.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Redirection.md index 606f57e2daa1..38894e7649d8 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Redirection.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Redirection.md @@ -193,7 +193,7 @@ Get-Item: C:\temp\test.ps1:3 Line | 3 | get-item /not-here 2>&1 >> log.txt | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - | Can't find path 'C:\not-here' because it doesn't exist. + | Cannot find path 'C:\not-here' because it does not exist. SilentlyContinue Stop