diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Command_Precedence.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Command_Precedence.md index cc6750bdeef2..e0c9830c73d1 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Command_Precedence.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Command_Precedence.md @@ -1,7 +1,7 @@ --- description: Describes how PowerShell determines which command to run. Locale: en-US -ms.date: 02/13/2020 +ms.date: 11/15/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_command_precedence?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Command Precedence @@ -98,7 +98,8 @@ C:\temp\test\[a1].ps1 You can see from the output that `[a1].ps1` runs this time because the literal match is the only file match for that wildcard pattern. -For more information about how PowerShell uses wildcards, see [about_Wildcards](about_Wildcards.md). +For more information about how PowerShell uses wildcards, see +[about_Wildcards](about_Wildcards.md). > [!NOTE] > To limit the search to a relative path, you must prefix the script name with @@ -109,10 +110,10 @@ For more information about how PowerShell uses wildcards, see [about_Wildcards]( If you do not specify a path, PowerShell uses the following precedence order when it runs commands for all items loaded in the current session: - 1. Alias - 2. Function - 3. Cmdlet - 4. External executable files (programs and non-PowerShell scripts) +1. Alias +2. Function +3. Cmdlet +4. External executable files (programs and non-PowerShell scripts) Therefore, if you type "help", PowerShell first looks for an alias named `help`, then a function named `Help`, and finally a cmdlet named `Help`. It @@ -159,12 +160,13 @@ Also, if you type a function at the command line and then import a function with the same name, the original function is replaced and is no longer accessible. -### Finding hidden commands +## Finding hidden commands -The **All** parameter of the [Get-Command](xref:Microsoft.PowerShell.Core.Get-Command) -cmdlet gets all commands with the specified name, even if they are hidden -or replaced. Beginning in PowerShell 3.0, by default, `Get-Command` -gets only the commands that run when you type the command name. +The **All** parameter of the +[Get-Command](xref:Microsoft.PowerShell.Core.Get-Command) cmdlet gets all +commands with the specified name, even if they are hidden or replaced. +Beginning in PowerShell 3.0, by default, `Get-Command` gets only the commands +that run when you type the command name. In the following examples, the session includes a `Get-Date` function and a [Get-Date](xref:Microsoft.PowerShell.Utility.Get-Date) cmdlet. @@ -203,7 +205,7 @@ the command from other commands that might have the same name. You can use this method to run any command, but it is especially useful for running hidden commands. -#### Qualified names +### Using qualified names Using the module-qualified name of a cmdlet allows you to run commands hidden by an item with the same name. For example, you can run the `Get-Date` cmdlet @@ -249,14 +251,16 @@ Microsoft.PowerShell.Utility > [!NOTE] > You cannot qualify variables or aliases. -#### Call operator +### Using the call operator -You can also use the `Call` operator `&` to run hidden commands by combining -it with a call to [Get-ChildItem](xref:Microsoft.PowerShell.Management.Get-ChildItem) -(the alias is "dir"), `Get-Command` or +You can also use the `Call` operator `&` to run hidden commands by combining it +with a call to +[Get-ChildItem](xref:Microsoft.PowerShell.Management.Get-ChildItem) (the alias +is "dir"), `Get-Command` or [Get-Module](xref:Microsoft.PowerShell.Core.Get-Module). -The call operator executes strings and script blocks in a child scope. For more information, see [about_Operators](about_Operators.md). +The call operator executes strings and script blocks in a child scope. For more +information, see [about_Operators](about_Operators.md). For example, if you have a function named `Map` that is hidden by an alias named `Map`, use the following command to run the function. @@ -281,7 +285,7 @@ $myMap = (Get-Command -Name map -CommandType function) &($myMap) ``` -### Replaced items +## Replaced items A "replaced" item is one that you can no longer access. You can replace items by importing items of the same name from a module or snap-in. @@ -294,7 +298,7 @@ Variables and aliases cannot be hidden because you cannot use a call operator or a qualified name to run them. When you import variables and aliases from a module or snap-in, they replace variables in the session with the same name. -### Avoiding name conflicts +## Avoiding name conflicts The best way to manage command name conflicts is to prevent them. When you name your commands, use a unique name. For example, add your initials or company @@ -315,7 +319,26 @@ and `Set-Date` cmdlets that come with PowerShell when you import the Import-Module -Name DateFunctions -Prefix ZZ ``` -For more information, see `Import-Module` and `Import-PSSession` below. +## Running external executables + +PowerShell treats the file extensions listed in the `$env:PATHEXT` environment +variable as executable files. Windows executable files are files with `.COM`, +`.CPL`, or `.EXE` file extensions. Windows executables and any other files with +extensions listed in `$env:PATHEXT` are executed in the current console +session. + +Files that are not Windows executables are handed to Windows to process. Windows +looks up the file association and executes the default Windows Shell verb for +the extension. For Windows to support the execution by file extension, the +association must be registered with the system. + +You can register the executable engine for a file extension using the `ftype` +and `assoc` commands of the CMD command shell. PowerShell has no direct method +to register the file handler. For more information, see the documentation for +the [ftype](/windows-server/administration/windows-commands/ftype) command. + +For PowerShell to see a file extension as executable in the current session, +you must add the extension to the `$env:PATHEXT` environment variable. ## See also diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md index fe27289948be..17e332e47744 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md @@ -1,7 +1,7 @@ --- description: Describes how to access Windows environment variables in PowerShell. Locale: en-US -ms.date: 08/18/2021 +ms.date: 11/15/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_environment_variables?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Environment Variables @@ -323,6 +323,31 @@ The environment variables that store preferences include: For more information, see [about_PSModulePath](about_PSModulePath.md). +## Other environment variables used by PowerShell + +### Path information + +- **PATHEXT** + + The `$env:PATHEXT` variable contains a list of file extensions that Windows + considers to be executable files. When a script file with one of the listed + extensions is executed from PowerShell, the script runs in the current + console or terminal session. If the file extension is not listed, the script + runs in a new console session. + + To ensure that scripts for another scripting language run in the current + console session, add the file extension used by the scripting language. For + example, to run Python scripts in the current console, add the `.py` + extension to the environment variable. For Windows to support the `.py` + extension as an executable file you must register the file extension using + the `ftype` and `assoc` commands of the CMD command shell. PowerShell has no + direct method to register the file handler. For more information, see the + documentation for the + [ftype](/windows-server/administration/windows-commands/ftype) command. + + PowerShell scripts always start in the current console session. You do not + need to add the `.PS1` extension. + ## See also - [Environment (provider)](../About/about_Environment_Provider.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Numeric_Literals.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Numeric_Literals.md index 23ec499dad5a..e37691b158af 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Numeric_Literals.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Numeric_Literals.md @@ -1,7 +1,7 @@ --- description: Both integer and real numeric literals can have type and multiplier suffixes. Locale: en-US -ms.date: 04/09/2018 +ms.date: 11/15/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_numeric_literals?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Numeric Literals @@ -180,6 +180,17 @@ their type and value: | 482gb | Int64 | 517543559168 | | 0x1e2lgb | Int64 | 517543559168 | +### Numeric type conversion + +When strings are converted to numbers, additional hexadecimal format indicators are +supported. Those additional formats are not recognized as literals. + +```powershell +[int] '0xF' -eq 0xF +[int] '&hF' -eq 0xF +[int] '#F' -eq 0xF +``` + ### Commands that look like numeric literals Any command that looks like a numeric literal must be executed using the the diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Command_Precedence.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Command_Precedence.md index cd709f977aad..8ec55977ed64 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Command_Precedence.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Command_Precedence.md @@ -1,7 +1,7 @@ --- description: Describes how PowerShell determines which command to run. Locale: en-US -ms.date: 02/13/2020 +ms.date: 11/15/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_command_precedence?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Command Precedence @@ -98,7 +98,8 @@ C:\temp\test\[a1].ps1 You can see from the output that `[a1].ps1` runs this time because the literal match is the only file match for that wildcard pattern. -For more information about how PowerShell uses wildcards, see [about_Wildcards](about_Wildcards.md). +For more information about how PowerShell uses wildcards, see +[about_Wildcards](about_Wildcards.md). > [!NOTE] > To limit the search to a relative path, you must prefix the script name with @@ -109,10 +110,10 @@ For more information about how PowerShell uses wildcards, see [about_Wildcards]( If you do not specify a path, PowerShell uses the following precedence order when it runs commands for all items loaded in the current session: - 1. Alias - 2. Function - 3. Cmdlet - 4. External executable files (programs and non-PowerShell scripts) +1. Alias +2. Function +3. Cmdlet +4. External executable files (programs and non-PowerShell scripts) Therefore, if you type "help", PowerShell first looks for an alias named `help`, then a function named `Help`, and finally a cmdlet named `Help`. It @@ -159,12 +160,13 @@ Also, if you type a function at the command line and then import a function with the same name, the original function is replaced and is no longer accessible. -### Finding hidden commands +## Finding hidden commands -The **All** parameter of the [Get-Command](xref:Microsoft.PowerShell.Core.Get-Command) -cmdlet gets all commands with the specified name, even if they are hidden -or replaced. Beginning in PowerShell 3.0, by default, `Get-Command` -gets only the commands that run when you type the command name. +The **All** parameter of the +[Get-Command](xref:Microsoft.PowerShell.Core.Get-Command) cmdlet gets all +commands with the specified name, even if they are hidden or replaced. +Beginning in PowerShell 3.0, by default, `Get-Command` gets only the commands +that run when you type the command name. In the following examples, the session includes a `Get-Date` function and a [Get-Date](xref:Microsoft.PowerShell.Utility.Get-Date) cmdlet. @@ -203,7 +205,7 @@ the command from other commands that might have the same name. You can use this method to run any command, but it is especially useful for running hidden commands. -#### Qualified names +### Using qualified names Using the module-qualified name of a cmdlet allows you to run commands hidden by an item with the same name. For example, you can run the `Get-Date` cmdlet @@ -249,14 +251,16 @@ Microsoft.PowerShell.Utility > [!NOTE] > You cannot qualify variables or aliases. -#### Call operator +### Using the call operator -You can also use the `Call` operator `&` to run hidden commands by combining -it with a call to [Get-ChildItem](xref:Microsoft.PowerShell.Management.Get-ChildItem) -(the alias is "dir"), `Get-Command` or +You can also use the `Call` operator `&` to run hidden commands by combining it +with a call to +[Get-ChildItem](xref:Microsoft.PowerShell.Management.Get-ChildItem) (the alias +is "dir"), `Get-Command` or [Get-Module](xref:Microsoft.PowerShell.Core.Get-Module). -The call operator executes strings and script blocks in a child scope. For more information, see [about_Operators](about_Operators.md). +The call operator executes strings and script blocks in a child scope. For more +information, see [about_Operators](about_Operators.md). For example, if you have a function named `Map` that is hidden by an alias named `Map`, use the following command to run the function. @@ -281,7 +285,7 @@ $myMap = (Get-Command -Name map -CommandType function) &($myMap) ``` -### Replaced items +## Replaced items A "replaced" item is one that you can no longer access. You can replace items by importing items of the same name from a module or snap-in. @@ -294,7 +298,7 @@ Variables and aliases cannot be hidden because you cannot use a call operator or a qualified name to run them. When you import variables and aliases from a module or snap-in, they replace variables in the session with the same name. -### Avoiding name conflicts +## Avoiding name conflicts The best way to manage command name conflicts is to prevent them. When you name your commands, use a unique name. For example, add your initials or company @@ -315,7 +319,26 @@ and `Set-Date` cmdlets that come with PowerShell when you import the Import-Module -Name DateFunctions -Prefix ZZ ``` -For more information, see `Import-Module` and `Import-PSSession` below. +## Running external executables + +PowerShell treats the file extensions listed in the `$env:PATHEXT` environment +variable as executable files. Windows executable files are files with `.COM`, +`.CPL`, or `.EXE` file extensions. Windows executables and any other files with +extensions listed in `$env:PATHEXT` are executed in the current console +session. + +Files that are not Windows executables are handed to Windows to process. Windows +looks up the file association and executes the default Windows Shell verb for +the extension. For Windows to support the execution by file extension, the +association must be registered with the system. + +You can register the executable engine for a file extension using the `ftype` +and `assoc` commands of the CMD command shell. PowerShell has no direct method +to register the file handler. For more information, see the documentation for +the [ftype](/windows-server/administration/windows-commands/ftype) command. + +For PowerShell to see a file extension as executable in the current session, +you must add the extension to the `$env:PATHEXT` environment variable. ## See also diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Environment_Variables.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Environment_Variables.md index c16f52d12a93..80ccf958e865 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Environment_Variables.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Environment_Variables.md @@ -1,7 +1,7 @@ --- description: Describes how to access Windows environment variables in PowerShell. Locale: en-US -ms.date: 08/18/2021 +ms.date: 11/15/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_environment_variables?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Environment Variables @@ -274,7 +274,7 @@ The environment variables that store preferences include: hexadecimal suffix so that there is a a unique filename per installation. > [!NOTE] - > If command discovery isn't working correctly, for example Intellisense + > If command discovery isn't working correctly, for example IntelliSense > shows commands that don't exist, you can delete the cache file. The cache > is recreated the next time you start PowerShell. @@ -359,14 +359,60 @@ The environment variables that store preferences include: For more information, see [about_Telemetry](about_Telemetry.md). -## Third-party environment variables +## Other environment variables used by PowerShell -On non-Windows platforms, PowerShell uses the following XDG environment -variables as defined by the [XDG Base Directory Specification][xdg-bds]. +### Path information -- **XDG_CONFIG_HOME** -- **XDG_DATA_HOME** -- **XDG_CACHE_HOME** +- **PATHEXT** + + The `$env:PATHEXT` variable contains a list of file extensions that Windows + considers to be executable files. When a script file with one of the listed + extensions is executed from PowerShell, the script runs in the current + console or terminal session. If the file extension is not listed, the script + runs in a new console session. + + To ensure that scripts for another scripting language run in the current + console session, add the file extension used by the scripting language. For + example, to run Python scripts in the current console, add the `.py` + extension to the environment variable. For Windows to support the `.py` + extension as an executable file you must register the file extension using + the `ftype` and `assoc` commands of the CMD command shell. PowerShell has no + direct method to register the file handler. For more information, see the + documentation for the + [ftype](/windows-server/administration/windows-commands/ftype) command. + + PowerShell scripts always start in the current console session. You do not + need to add the `.PS1` extension. + +- XDG variables + + On non-Windows platforms, PowerShell uses the following XDG environment + variables as defined by the [XDG Base Directory Specification][xdg-bds]. + + - **XDG_CONFIG_HOME** + - **XDG_DATA_HOME** + - **XDG_CACHE_HOME** + +### Terminal features + +Beginning in PowerShell 7.2, the following environment variables can be used to +control the Virtual Terminal features like ANSI escape sequences that colorize +output. Support for ANSI escape sequences can be turned off using the **TERM** +or **NO_COLOR** environment variables. + +- **TERM** + + The following values of `$env:TERM` change the behavior as follows: + + - `dumb` - sets `$Host.UI.SupportsVirtualTerminal = $false` + - `xterm-mono` - sets `$PSStyle.OutputRendering = PlainText` + - `xtermm` - sets `$PSStyle.OutputRendering = PlainText` + +- **NO_COLOR** + + If `$env:NO_COLOR` exists, then `$PSStyle.OutputRendering` is set to + **PlainText**. For more information about the **NO_COLOR** environment + variable, see [https://no-color.org/](https://no-color.org/). ## See also diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Experimental_Features.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Experimental_Features.md index ea00d1d8a136..a12799eb00a7 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Experimental_Features.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Experimental_Features.md @@ -1,7 +1,7 @@ --- description: The Experimental Features support in PowerShell provides a mechanism for experimental features to coexist with existing stable features in PowerShell or PowerShell modules. Locale: en-US -ms.date: 03/13/2020 +ms.date: 11/15/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_experimental_features?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Experimental Features @@ -48,7 +48,7 @@ specified and the only valid values are: - `Show` means to show this experimental feature if the feature is enabled - `Hide` means to hide this experimental feature if the feature is enabled -### Declaring Experimental Features in Modules Written in C\# +## Declaring Experimental Features in Modules Written in C\# Module authors who want to use the Experimental Feature flags can declare a cmdlet as experimental by using the `Experimental` attribute. @@ -59,7 +59,7 @@ cmdlet as experimental by using the `Experimental` attribute. public class InvokeWebRequestCommandV2 : WebCmdletBaseV2 { ... } ``` -### Declaring Experimental Features in Modules written in PowerShell +## Declaring Experimental Features in Modules written in PowerShell Module written in PowerShell can also use the `Experimental` attribute to declare experimental cmdlets: @@ -73,7 +73,32 @@ function Enable-SSHRemoting { } ``` -### Mutually Exclusive Experimental Features +Metadata about an experimental feature is kept in the module manifest. Use the +`PrivateData.PSData.ExperimentalFeatures` property of a module manifest to +expose the experimental features from the module. The `ExperimentalFeatures` +property is an array of hashtables containing the name and description of the +feature. + +For example: + +```powershell +PrivateData = @{ + PSData = @{ + ExperimentalFeatures = @( + @{ + Name = "PSWebCmdletV2" + Description = "Rewrite the web cmdlets for better performance" + }, + @{ + Name = "PSRestCmdletV2" + Description = "Rewrite the REST API cmdlets for better performance" + } + ) + } +} +``` + +## Mutually Exclusive Experimental Features There are cases where an experimental feature cannot co-exist side-by-side with an existing feature or another experimental feature. @@ -108,7 +133,7 @@ When the `MyWebCmdlets.PSWebCmdletV2` experimental feature is enabled, the exist This allows users to try out the new cmdlet and provide feedback then revert to the non-experimental version when needed. -### Experimental Parameters in Cmdlets +## Experimental Parameters in Cmdlets The `Experimental` attribute can also be applied to individual parameters. This allows you to create an experimental set of parameters for an existing cmdlet diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Numeric_Literals.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Numeric_Literals.md index a5a91b213083..b124ee138e97 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Numeric_Literals.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Numeric_Literals.md @@ -1,7 +1,7 @@ --- description: Both integer and real numeric literals can have type and multiplier suffixes. Locale: en-US -ms.date: 04/12/2019 +ms.date: 11/15/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_numeric_literals?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Numeric Literals @@ -223,6 +223,19 @@ Sign bits are accepted for BigInteger-suffixed numerals: - BigInteger-suffixed binary accepts sign bits at 96 and 128 characters, and at every 8 characters after. +### Numeric type conversion + +When strings are converted to numbers, additional hexadecimal format indicators are +supported. Those additional formats are not recognized as literals. + +```powershell +[int] '0xF' -eq 0xF +[int] '&hF' -eq 0xF +[int] '#F' -eq 0xF +[int] '0b1111' -eq 0b1111 +[int] '0b1111' -eq 15 +``` + ### Commands that look like numeric literals Any command that looks like a valid numeric literal must be executed using the diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Command_Precedence.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Command_Precedence.md index 65f2764e8804..b8538706da9b 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Command_Precedence.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Command_Precedence.md @@ -1,7 +1,7 @@ --- description: Describes how PowerShell determines which command to run. Locale: en-US -ms.date: 02/13/2020 +ms.date: 11/15/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_command_precedence?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Command Precedence @@ -98,7 +98,8 @@ C:\temp\test\[a1].ps1 You can see from the output that `[a1].ps1` runs this time because the literal match is the only file match for that wildcard pattern. -For more information about how PowerShell uses wildcards, see [about_Wildcards](about_Wildcards.md). +For more information about how PowerShell uses wildcards, see +[about_Wildcards](about_Wildcards.md). > [!NOTE] > To limit the search to a relative path, you must prefix the script name with @@ -109,10 +110,10 @@ For more information about how PowerShell uses wildcards, see [about_Wildcards]( If you do not specify a path, PowerShell uses the following precedence order when it runs commands for all items loaded in the current session: - 1. Alias - 2. Function - 3. Cmdlet - 4. External executable files (programs and non-PowerShell scripts) +1. Alias +2. Function +3. Cmdlet +4. External executable files (programs and non-PowerShell scripts) Therefore, if you type "help", PowerShell first looks for an alias named `help`, then a function named `Help`, and finally a cmdlet named `Help`. It @@ -159,12 +160,13 @@ Also, if you type a function at the command line and then import a function with the same name, the original function is replaced and is no longer accessible. -### Finding hidden commands +## Finding hidden commands -The **All** parameter of the [Get-Command](xref:Microsoft.PowerShell.Core.Get-Command) -cmdlet gets all commands with the specified name, even if they are hidden -or replaced. Beginning in PowerShell 3.0, by default, `Get-Command` -gets only the commands that run when you type the command name. +The **All** parameter of the +[Get-Command](xref:Microsoft.PowerShell.Core.Get-Command) cmdlet gets all +commands with the specified name, even if they are hidden or replaced. +Beginning in PowerShell 3.0, by default, `Get-Command` gets only the commands +that run when you type the command name. In the following examples, the session includes a `Get-Date` function and a [Get-Date](xref:Microsoft.PowerShell.Utility.Get-Date) cmdlet. @@ -203,7 +205,7 @@ the command from other commands that might have the same name. You can use this method to run any command, but it is especially useful for running hidden commands. -#### Qualified names +### Using qualified names Using the module-qualified name of a cmdlet allows you to run commands hidden by an item with the same name. For example, you can run the `Get-Date` cmdlet @@ -249,14 +251,16 @@ Microsoft.PowerShell.Utility > [!NOTE] > You cannot qualify variables or aliases. -#### Call operator +### Using the call operator -You can also use the `Call` operator `&` to run hidden commands by combining -it with a call to [Get-ChildItem](xref:Microsoft.PowerShell.Management.Get-ChildItem) -(the alias is "dir"), `Get-Command` or +You can also use the `Call` operator `&` to run hidden commands by combining it +with a call to +[Get-ChildItem](xref:Microsoft.PowerShell.Management.Get-ChildItem) (the alias +is "dir"), `Get-Command` or [Get-Module](xref:Microsoft.PowerShell.Core.Get-Module). -The call operator executes strings and script blocks in a child scope. For more information, see [about_Operators](about_Operators.md). +The call operator executes strings and script blocks in a child scope. For more +information, see [about_Operators](about_Operators.md). For example, if you have a function named `Map` that is hidden by an alias named `Map`, use the following command to run the function. @@ -281,7 +285,7 @@ $myMap = (Get-Command -Name map -CommandType function) &($myMap) ``` -### Replaced items +## Replaced items A "replaced" item is one that you can no longer access. You can replace items by importing items of the same name from a module or snap-in. @@ -294,7 +298,7 @@ Variables and aliases cannot be hidden because you cannot use a call operator or a qualified name to run them. When you import variables and aliases from a module or snap-in, they replace variables in the session with the same name. -### Avoiding name conflicts +## Avoiding name conflicts The best way to manage command name conflicts is to prevent them. When you name your commands, use a unique name. For example, add your initials or company @@ -315,7 +319,26 @@ and `Set-Date` cmdlets that come with PowerShell when you import the Import-Module -Name DateFunctions -Prefix ZZ ``` -For more information, see `Import-Module` and `Import-PSSession` below. +## Running external executables + +PowerShell treats the file extensions listed in the `$env:PATHEXT` environment +variable as executable files. Windows executable files are files with `.COM`, +`.CPL`, or `.EXE` file extensions. Windows executables and any other files with +extensions listed in `$env:PATHEXT` are executed in the current console +session. + +Files that are not Windows executables are handed to Windows to process. Windows +looks up the file association and executes the default Windows Shell verb for +the extension. For Windows to support the execution by file extension, the +association must be registered with the system. + +You can register the executable engine for a file extension using the `ftype` +and `assoc` commands of the CMD command shell. PowerShell has no direct method +to register the file handler. For more information, see the documentation for +the [ftype](/windows-server/administration/windows-commands/ftype) command. + +For PowerShell to see a file extension as executable in the current session, +you must add the extension to the `$env:PATHEXT` environment variable. ## See also @@ -327,4 +350,3 @@ For more information, see `Import-Module` and `Import-PSSession` below. - [Get-Command](xref:Microsoft.PowerShell.Core.Get-Command) - [Import-Module](xref:Microsoft.PowerShell.Core.Import-Module) - [Import-PSSession](xref:Microsoft.PowerShell.Utility.Import-PSSession) - diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md index 726b503eb88f..dc59981986a7 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md @@ -1,7 +1,7 @@ --- description: Describes how to access Windows environment variables in PowerShell. Locale: en-US -ms.date: 08/18/2021 +ms.date: 11/15/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_environment_variables?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Environment Variables @@ -274,7 +274,7 @@ The environment variables that store preferences include: hexadecimal suffix so that there is a a unique filename per installation. > [!NOTE] - > If command discovery isn't working correctly, for example Intellisense + > If command discovery isn't working correctly, for example IntelliSense > shows commands that don't exist, you can delete the cache file. The cache > is recreated the next time you start PowerShell. @@ -359,14 +359,60 @@ The environment variables that store preferences include: For more information, see [about_Telemetry](about_Telemetry.md). -## Third-party environment variables +## Other environment variables used by PowerShell -On non-Windows platforms, PowerShell uses the following XDG environment -variables as defined by the [XDG Base Directory Specification][xdg-bds]. +### Path information -- **XDG_CONFIG_HOME** -- **XDG_DATA_HOME** -- **XDG_CACHE_HOME** +- **PATHEXT** + + The `$env:PATHEXT` variable contains a list of file extensions that Windows + considers to be executable files. When a script file with one of the listed + extensions is executed from PowerShell, the script runs in the current + console or terminal session. If the file extension is not listed, the script + runs in a new console session. + + To ensure that scripts for another scripting language run in the current + console session, add the file extension used by the scripting language. For + example, to run Python scripts in the current console, add the `.py` + extension to the environment variable. For Windows to support the `.py` + extension as an executable file you must register the file extension using + the `ftype` and `assoc` commands of the CMD command shell. PowerShell has no + direct method to register the file handler. For more information, see the + documentation for the + [ftype](/windows-server/administration/windows-commands/ftype) command. + + PowerShell scripts always start in the current console session. You do not + need to add the `.PS1` extension. + +- XDG variables + + On non-Windows platforms, PowerShell uses the following XDG environment + variables as defined by the [XDG Base Directory Specification][xdg-bds]. + + - **XDG_CONFIG_HOME** + - **XDG_DATA_HOME** + - **XDG_CACHE_HOME** + +### Terminal features + +Beginning in PowerShell 7.2, the following environment variables can be used to +control the Virtual Terminal features like ANSI escape sequences that colorize +output. Support for ANSI escape sequences can be turned off using the **TERM** +or **NO_COLOR** environment variables. + +- **TERM** + + The following values of `$env:TERM` change the behavior as follows: + + - `dumb` - sets `$Host.UI.SupportsVirtualTerminal = $false` + - `xterm-mono` - sets `$PSStyle.OutputRendering = PlainText` + - `xtermm` - sets `$PSStyle.OutputRendering = PlainText` + +- **NO_COLOR** + + If `$env:NO_COLOR` exists, then `$PSStyle.OutputRendering` is set to + **PlainText**. For more information about the **NO_COLOR** environment + variable, see [https://no-color.org/](https://no-color.org/). ## See also diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Experimental_Features.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Experimental_Features.md index 73a4d0a33505..1df2b07adf14 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Experimental_Features.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Experimental_Features.md @@ -1,7 +1,7 @@ --- description: The Experimental Features support in PowerShell provides a mechanism for experimental features to coexist with existing stable features in PowerShell or PowerShell modules. Locale: en-US -ms.date: 03/13/2020 +ms.date: 11/15/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_experimental_features?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Experimental Features @@ -48,7 +48,7 @@ specified and the only valid values are: - `Show` means to show this experimental feature if the feature is enabled - `Hide` means to hide this experimental feature if the feature is enabled -### Declaring Experimental Features in Modules Written in C\# +## Declaring Experimental Features in Modules Written in C\# Module authors who want to use the Experimental Feature flags can declare a cmdlet as experimental by using the `Experimental` attribute. @@ -59,7 +59,7 @@ cmdlet as experimental by using the `Experimental` attribute. public class InvokeWebRequestCommandV2 : WebCmdletBaseV2 { ... } ``` -### Declaring Experimental Features in Modules written in PowerShell +## Declaring Experimental Features in Modules written in PowerShell Module written in PowerShell can also use the `Experimental` attribute to declare experimental cmdlets: @@ -73,7 +73,32 @@ function Enable-SSHRemoting { } ``` -### Mutually Exclusive Experimental Features +Metadata about an experimental feature is kept in the module manifest. Use the +`PrivateData.PSData.ExperimentalFeatures` property of a module manifest to +expose the experimental features from the module. The `ExperimentalFeatures` +property is an array of hashtables containing the name and description of the +feature. + +For example: + +```powershell +PrivateData = @{ + PSData = @{ + ExperimentalFeatures = @( + @{ + Name = "PSWebCmdletV2" + Description = "Rewrite the web cmdlets for better performance" + }, + @{ + Name = "PSRestCmdletV2" + Description = "Rewrite the REST API cmdlets for better performance" + } + ) + } +} +``` + +## Mutually Exclusive Experimental Features There are cases where an experimental feature cannot co-exist side-by-side with an existing feature or another experimental feature. @@ -108,7 +133,7 @@ When the `MyWebCmdlets.PSWebCmdletV2` experimental feature is enabled, the exist This allows users to try out the new cmdlet and provide feedback then revert to the non-experimental version when needed. -### Experimental Parameters in Cmdlets +## Experimental Parameters in Cmdlets The `Experimental` attribute can also be applied to individual parameters. This allows you to create an experimental set of parameters for an existing cmdlet @@ -170,4 +195,3 @@ if ([ExperimentalFeature]::IsEnabled("MyModule.MyExperimentalFeature")) [Disable-ExperimentalFeature](xref:Microsoft.PowerShell.Core.Disable-ExperimentalFeature) [Get-ExperimentalFeature](xref:Microsoft.PowerShell.Core.Get-ExperimentalFeature) - diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Numeric_Literals.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Numeric_Literals.md index a2d7713bac4a..d19e4eb36220 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Numeric_Literals.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Numeric_Literals.md @@ -1,7 +1,7 @@ --- description: Both integer and real numeric literals can have type and multiplier suffixes. Locale: en-US -ms.date: 04/12/2019 +ms.date: 11/15/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_numeric_literals?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Numeric Literals @@ -229,6 +229,19 @@ Sign bits are accepted for BigInteger-suffixed numerals: - BigInteger-suffixed binary accepts sign bits at 96 and 128 characters, and at every 8 characters after. +### Numeric type conversion + +When strings are converted to numbers, additional hexadecimal format indicators are +supported. Those additional formats are not recognized as literals. + +```powershell +[int] '0xF' -eq 0xF +[int] '&hF' -eq 0xF +[int] '#F' -eq 0xF +[int] '0b1111' -eq 0b1111 +[int] '0b1111' -eq 15 +``` + ### Commands that look like numeric literals Any command that looks like a valid numeric literal must be executed using the diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Command_Precedence.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Command_Precedence.md index b2701fa63a50..8d299dca9f9e 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Command_Precedence.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Command_Precedence.md @@ -1,7 +1,7 @@ --- description: Describes how PowerShell determines which command to run. Locale: en-US -ms.date: 02/13/2020 +ms.date: 11/15/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_command_precedence?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Command Precedence @@ -98,7 +98,8 @@ C:\temp\test\[a1].ps1 You can see from the output that `[a1].ps1` runs this time because the literal match is the only file match for that wildcard pattern. -For more information about how PowerShell uses wildcards, see [about_Wildcards](about_Wildcards.md). +For more information about how PowerShell uses wildcards, see +[about_Wildcards](about_Wildcards.md). > [!NOTE] > To limit the search to a relative path, you must prefix the script name with @@ -109,10 +110,10 @@ For more information about how PowerShell uses wildcards, see [about_Wildcards]( If you do not specify a path, PowerShell uses the following precedence order when it runs commands for all items loaded in the current session: - 1. Alias - 2. Function - 3. Cmdlet - 4. External executable files (programs and non-PowerShell scripts) +1. Alias +2. Function +3. Cmdlet +4. External executable files (programs and non-PowerShell scripts) Therefore, if you type "help", PowerShell first looks for an alias named `help`, then a function named `Help`, and finally a cmdlet named `Help`. It @@ -159,12 +160,13 @@ Also, if you type a function at the command line and then import a function with the same name, the original function is replaced and is no longer accessible. -### Finding hidden commands +## Finding hidden commands -The **All** parameter of the [Get-Command](xref:Microsoft.PowerShell.Core.Get-Command) -cmdlet gets all commands with the specified name, even if they are hidden -or replaced. Beginning in PowerShell 3.0, by default, `Get-Command` -gets only the commands that run when you type the command name. +The **All** parameter of the +[Get-Command](xref:Microsoft.PowerShell.Core.Get-Command) cmdlet gets all +commands with the specified name, even if they are hidden or replaced. +Beginning in PowerShell 3.0, by default, `Get-Command` gets only the commands +that run when you type the command name. In the following examples, the session includes a `Get-Date` function and a [Get-Date](xref:Microsoft.PowerShell.Utility.Get-Date) cmdlet. @@ -203,7 +205,7 @@ the command from other commands that might have the same name. You can use this method to run any command, but it is especially useful for running hidden commands. -#### Qualified names +### Using qualified names Using the module-qualified name of a cmdlet allows you to run commands hidden by an item with the same name. For example, you can run the `Get-Date` cmdlet @@ -249,14 +251,16 @@ Microsoft.PowerShell.Utility > [!NOTE] > You cannot qualify variables or aliases. -#### Call operator +### Using the call operator -You can also use the `Call` operator `&` to run hidden commands by combining -it with a call to [Get-ChildItem](xref:Microsoft.PowerShell.Management.Get-ChildItem) -(the alias is "dir"), `Get-Command` or +You can also use the `Call` operator `&` to run hidden commands by combining it +with a call to +[Get-ChildItem](xref:Microsoft.PowerShell.Management.Get-ChildItem) (the alias +is "dir"), `Get-Command` or [Get-Module](xref:Microsoft.PowerShell.Core.Get-Module). -The call operator executes strings and script blocks in a child scope. For more information, see [about_Operators](about_Operators.md). +The call operator executes strings and script blocks in a child scope. For more +information, see [about_Operators](about_Operators.md). For example, if you have a function named `Map` that is hidden by an alias named `Map`, use the following command to run the function. @@ -281,7 +285,7 @@ $myMap = (Get-Command -Name map -CommandType function) &($myMap) ``` -### Replaced items +## Replaced items A "replaced" item is one that you can no longer access. You can replace items by importing items of the same name from a module or snap-in. @@ -294,7 +298,7 @@ Variables and aliases cannot be hidden because you cannot use a call operator or a qualified name to run them. When you import variables and aliases from a module or snap-in, they replace variables in the session with the same name. -### Avoiding name conflicts +## Avoiding name conflicts The best way to manage command name conflicts is to prevent them. When you name your commands, use a unique name. For example, add your initials or company @@ -315,7 +319,26 @@ and `Set-Date` cmdlets that come with PowerShell when you import the Import-Module -Name DateFunctions -Prefix ZZ ``` -For more information, see `Import-Module` and `Import-PSSession` below. +## Running external executables + +PowerShell treats the file extensions listed in the `$env:PATHEXT` environment +variable as executable files. Windows executable files are files with `.COM`, +`.CPL`, or `.EXE` file extensions. Windows executables and any other files with +extensions listed in `$env:PATHEXT` are executed in the current console +session. + +Files that are not Windows executables are handed to Windows to process. Windows +looks up the file association and executes the default Windows Shell verb for +the extension. For Windows to support the execution by file extension, the +association must be registered with the system. + +You can register the executable engine for a file extension using the `ftype` +and `assoc` commands of the CMD command shell. PowerShell has no direct method +to register the file handler. For more information, see the documentation for +the [ftype](/windows-server/administration/windows-commands/ftype) command. + +For PowerShell to see a file extension as executable in the current session, +you must add the extension to the `$env:PATHEXT` environment variable. ## See also @@ -327,4 +350,3 @@ For more information, see `Import-Module` and `Import-PSSession` below. - [Get-Command](xref:Microsoft.PowerShell.Core.Get-Command) - [Import-Module](xref:Microsoft.PowerShell.Core.Import-Module) - [Import-PSSession](xref:Microsoft.PowerShell.Utility.Import-PSSession) - diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Environment_Variables.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Environment_Variables.md index ac0f912654cb..911ffcc81563 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Environment_Variables.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Environment_Variables.md @@ -1,7 +1,7 @@ --- description: Describes how to access Windows environment variables in PowerShell. Locale: en-US -ms.date: 08/18/2021 +ms.date: 11/15/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_environment_variables?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Environment Variables @@ -274,7 +274,7 @@ The environment variables that store preferences include: hexadecimal suffix so that there is a a unique filename per installation. > [!NOTE] - > If command discovery isn't working correctly, for example Intellisense + > If command discovery isn't working correctly, for example IntelliSense > shows commands that don't exist, you can delete the cache file. The cache > is recreated the next time you start PowerShell. @@ -365,14 +365,41 @@ The environment variables that store preferences include: installer packages to record the method and source of installation for PowerShell. -## Third-party environment variables +## Other environment variables used by PowerShell -On non-Windows platforms, PowerShell uses the following XDG environment -variables as defined by the [XDG Base Directory Specification][xdg-bds]. +### Path information -- **XDG_CONFIG_HOME** -- **XDG_DATA_HOME** -- **XDG_CACHE_HOME** +- **PATHEXT** + + The `$env:PATHEXT` variable contains a list of file extensions that Windows + considers to be executable files. When a script file with one of the listed + extensions is executed from PowerShell, the script runs in the current + console or terminal session. If the file extension is not listed, the script + runs in a new console session. + + To ensure that scripts for another scripting language run in the current + console session, add the file extension used by the scripting language. For + example, to run Python scripts in the current console, add the `.py` + extension to the environment variable. For Windows to support the `.py` + extension as an executable file you must register the file extension using + the `ftype` and `assoc` commands of the CMD command shell. PowerShell has no + direct method to register the file handler. For more information, see the + documentation for the + [ftype](/windows-server/administration/windows-commands/ftype) command. + + PowerShell scripts always start in the current console session. You do not + need to add the `.PS1` extension. + +- XDG variables + + On non-Windows platforms, PowerShell uses the following XDG environment + variables as defined by the [XDG Base Directory Specification][xdg-bds]. + + - **XDG_CONFIG_HOME** + - **XDG_DATA_HOME** + - **XDG_CACHE_HOME** + +### Terminal features Beginning in PowerShell 7.2, the following environment variables can be used to control the Virtual Terminal features like ANSI escape sequences that colorize diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Experimental_Features.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Experimental_Features.md index 339eb8d75cc2..a557a7aa4ccf 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Experimental_Features.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Experimental_Features.md @@ -1,7 +1,7 @@ --- description: The Experimental Features support in PowerShell provides a mechanism for experimental features to coexist with existing stable features in PowerShell or PowerShell modules. Locale: en-US -ms.date: 03/13/2020 +ms.date: 11/15/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_experimental_features?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Experimental Features @@ -48,7 +48,7 @@ specified and the only valid values are: - `Show` means to show this experimental feature if the feature is enabled - `Hide` means to hide this experimental feature if the feature is enabled -### Declaring Experimental Features in Modules Written in C\# +## Declaring Experimental Features in Modules Written in C\# Module authors who want to use the Experimental Feature flags can declare a cmdlet as experimental by using the `Experimental` attribute. @@ -59,7 +59,7 @@ cmdlet as experimental by using the `Experimental` attribute. public class InvokeWebRequestCommandV2 : WebCmdletBaseV2 { ... } ``` -### Declaring Experimental Features in Modules written in PowerShell +## Declaring Experimental Features in Modules written in PowerShell Module written in PowerShell can also use the `Experimental` attribute to declare experimental cmdlets: @@ -73,7 +73,32 @@ function Enable-SSHRemoting { } ``` -### Mutually Exclusive Experimental Features +Metadata about an experimental feature is kept in the module manifest. Use the +`PrivateData.PSData.ExperimentalFeatures` property of a module manifest to +expose the experimental features from the module. The `ExperimentalFeatures` +property is an array of hashtables containing the name and description of the +feature. + +For example: + +```powershell +PrivateData = @{ + PSData = @{ + ExperimentalFeatures = @( + @{ + Name = "PSWebCmdletV2" + Description = "Rewrite the web cmdlets for better performance" + }, + @{ + Name = "PSRestCmdletV2" + Description = "Rewrite the REST API cmdlets for better performance" + } + ) + } +} +``` + +## Mutually Exclusive Experimental Features There are cases where an experimental feature cannot co-exist side-by-side with an existing feature or another experimental feature. @@ -108,7 +133,7 @@ When the `MyWebCmdlets.PSWebCmdletV2` experimental feature is enabled, the exist This allows users to try out the new cmdlet and provide feedback then revert to the non-experimental version when needed. -### Experimental Parameters in Cmdlets +## Experimental Parameters in Cmdlets The `Experimental` attribute can also be applied to individual parameters. This allows you to create an experimental set of parameters for an existing cmdlet @@ -170,4 +195,3 @@ if ([ExperimentalFeature]::IsEnabled("MyModule.MyExperimentalFeature")) [Disable-ExperimentalFeature](xref:Microsoft.PowerShell.Core.Disable-ExperimentalFeature) [Get-ExperimentalFeature](xref:Microsoft.PowerShell.Core.Get-ExperimentalFeature) - diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Numeric_Literals.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Numeric_Literals.md index 3611aef96331..e267a3b199fb 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Numeric_Literals.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Numeric_Literals.md @@ -1,7 +1,7 @@ --- description: Both integer and real numeric literals can have type and multiplier suffixes. Locale: en-US -ms.date: 04/12/2019 +ms.date: 11/15/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_numeric_literals?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Numeric Literals @@ -229,6 +229,19 @@ Sign bits are accepted for BigInteger-suffixed numerals: - BigInteger-suffixed binary accepts sign bits at 96 and 128 characters, and at every 8 characters after. +### Numeric type conversion + +When strings are converted to numbers, additional hexadecimal format indicators are +supported. Those additional formats are not recognized as literals. + +```powershell +[int] '0xF' -eq 0xF +[int] '&hF' -eq 0xF +[int] '#F' -eq 0xF +[int] '0b1111' -eq 0b1111 +[int] '0b1111' -eq 15 +``` + ### Commands that look like numeric literals Any command that looks like a valid numeric literal must be executed using the diff --git a/reference/docs-conceptual/install/Installing-PowerShell-on-Windows.md b/reference/docs-conceptual/install/Installing-PowerShell-on-Windows.md index 3ff66fd974a5..26d3e2c1d8dc 100644 --- a/reference/docs-conceptual/install/Installing-PowerShell-on-Windows.md +++ b/reference/docs-conceptual/install/Installing-PowerShell-on-Windows.md @@ -1,6 +1,6 @@ --- description: Information about installing PowerShell on Windows -ms.date: 11/08/2021 +ms.date: 11/15/2021 title: Installing PowerShell on Windows --- # Installing PowerShell on Windows @@ -56,6 +56,28 @@ The installer creates a shortcut in the Windows Start Menu. > If you need to run PowerShell 7.2 side-by-side with other versions, use the [ZIP install](#zip) > method to install the other version to a different folder. +### Support for Microsoft Update in PowerShell 7.2 + +PowerShell 7.2 has support for Microsoft Update. When you enable this feature, you'll get +the latest PowerShell 7 updates in your traditional Microsoft Update (MU) management flow, whether +that's with Windows Update for Business, WSUS, SCCM, or the interactive MU dialog in Settings. + +The PowerShell 7.2 MSI package includes following command-line options: + +- `USE_MU` - This property has two possible values: + - `1` (default) - Opts into updating through Microsoft Update, WSUS, or SCCM + - `0` - Do not opt into updating through Microsoft Update, WSUS, or SCCM +- `ENABLE_MU` + - `1` (default) - Opts into using Microsoft Update for Automatic Updates + - `0` - Do not opt into using Microsoft Update + +> [!NOTE] +> Enabling updates may have been set in a previous installation or manual configuration. Using +> `ENABLE_MU=0` does not remove the existing settings. Also, this setting can be overruled by Group +> Policy settings controlled by your administrator. + +For more information, see the [PowerShell Microsoft Update FAQ](microsoft-update-faq.yml). + ### Administrative install from the command line MSI packages can be installed from the command line allowing administrators to deploy packages @@ -74,7 +96,7 @@ installation options: The following example shows how to silently install PowerShell with all the install options enabled. ```powershell -msiexec.exe /package PowerShell-7.2.0-win-x64.msi /quiet ADD_EXPLORER_CONTEXT_MENU_OPENPOWERSHELL=1 ENABLE_PSREMOTING=1 REGISTER_MANIFEST=1 +msiexec.exe /package PowerShell-7.2.0-win-x64.msi /quiet ADD_EXPLORER_CONTEXT_MENU_OPENPOWERSHELL=1 ENABLE_PSREMOTING=1 REGISTER_MANIFEST=1 USE_MU=1 ENABLE_MU=1 ``` For a full list of command-line options for `Msiexec.exe`, see @@ -146,7 +168,7 @@ winget install --id Microsoft.Powershell.Preview --source winget ## Installing from the Microsoft Store -PowerShell 7.2 has been published to the Microsoft Store. You can find the PowerShell release in the +PowerShell 7.2 can be installed from the Microsoft Store. You can find the PowerShell release in the [Microsoft Store][store-app] site or in the Store application in Windows. Benefits of the Microsoft Store package: @@ -156,18 +178,35 @@ Benefits of the Microsoft Store package: ### Known limitations -Windows Store packages run in an application sandbox that virtualizes access to some filesystem and -registry locations. +By default, Windows Store packages run in an application sandbox that virtualizes access to some +filesystem and registry locations. Changes to virtualized file and registry locations do not persist +outside of the application sandbox. -- All registry changes under HKEY_CURRENT_USER are copied on write to a private, per-user, per-app - location. Therefore, those values are not available to other applications. -- Any system-level configuration settings stored in `$PSHOME` cannot be modified. This includes the - WSMAN configuration. This prevents remote sessions from connecting to Store-based installs of - PowerShell. User-level configurations and SSH remoting are supported. +This sandbox all blocks any changes to the application's root folder. Any system-level configuration +settings stored in `$PSHOME` cannot be modified. This includes the WSMAN configuration. This +prevents remote sessions from connecting to Store-based installs of PowerShell. User-level +configurations and SSH remoting are supported. + +The following commands need write to `$PSHOME`. These commands are not supported in a Microsoft +Store instance of PowerShell. + +- `Register-PSSessionConfiguration` +- `Update-Help -Scope AllUsers` +- `Enable-ExperimentalFeature -Scope AllUsers` +- `Set-ExecutionPolicy -Scope LocalMachine` For more information, see [Understanding how packaged desktop apps run on Windows](/windows/msix/desktop/desktop-to-uwp-behind-the-scenes). +### Changes for PowerShell 7.2 + +Beginning in PowerShell 7.2, the PowerShell package is now exempt from file and registry +virtualization. Changes to virtualized file and registry locations now persist outside of the +application sandbox. However, changes to the application's root folder are still blocked. + +> [!IMPORTANT] +> You must be running on Windows build 1903 or higher for this exemption to work. + ## Installing a preview version