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])