From cf4611e25674dfa647a82570cc7d7217415edcc9 Mon Sep 17 00:00:00 2001 From: "Michael T Lombardi (He/Him)" Date: Fri, 1 Apr 2022 14:04:25 -0500 Subject: [PATCH 01/31] (GH-8706) Clarify `about_Environment_Variables` (#8710) Prior to this commit, the `about_Environment_Variables` topic included misleading examples that would error if run in sequence. Additionally, the organization and content of the document hid some useful information in later sections, was difficult to follow, and lacked output examples. This commit is a rewrite and restructuring of the document. The documents new flow explains, in order: 1. The most important information about environment variables in the long description 2. How to use/change environment variables 3. How to persist changes to environment variables 4. What environment variables PowerShell adds and uses --- .../About/about_Environment_Variables.md | 319 ++++++++++------- .../About/about_Environment_Variables.md | 338 ++++++++++-------- .../About/about_Environment_Variables.md | 338 ++++++++++-------- .../About/about_Environment_Variables.md | 317 +++++++++------- .../About/about_Environment_Variables.md | 317 +++++++++------- 5 files changed, 918 insertions(+), 711 deletions(-) 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 cb77f8778025..edb4837a7488 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. +description: Describes how to access and manage environment variables in PowerShell. Locale: en-US -ms.date: 11/15/2021 +ms.date: 03/31/2022 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 @@ -9,31 +9,25 @@ title: about Environment Variables # about_Environment_Variables ## Short description -Describes how to access Windows environment variables in PowerShell. +Describes how to access and manage environment variables in PowerShell. ## Long description -Environment variables store information about the operating system -environment. This information includes details such as the operating system -path, the number of processors used by the operating system, and the location -of temporary folders. - -The environment variables store data that is used by the operating system and +Environment variables store data that is used by the operating system and other programs. For example, the `WINDIR` environment variable contains the location of the Windows installation directory. Programs can query the value of this variable to determine where Windows operating system files are located. PowerShell can access and manage environment variables in any of the supported -operating system platforms. The PowerShell environment provider simplifies this -process by making it easy to view and change environment variables. +operating system platforms. The PowerShell environment provider lets you get, +add, change, clear, and delete environment variables in the current console. -Environment variables, unlike other types of variables in PowerShell, are +Environment variables, unlike other types of variables in PowerShell, are always +stored as a string and can't be empty. Also unlike other variables, they are inherited by child processes, such as local background jobs and the sessions in which module members run. This makes environment variables well suited to storing values that are needed in both parent and child processes. -## Using and changing environment variables - On Windows, environment variables can be defined in three scopes: - Machine (or System) scope @@ -45,193 +39,250 @@ process, or PowerShell session. This list of variables is inherited from the parent process and is constructed from the variables in the _Machine_ and _User_ scopes. -You can display and change the values of environment variables without using a -cmdlet by using a variable syntax with the environment provider. To display the -value of an environment variable, use the following syntax: +When you change environment variables in PowerShell, the change affects only +the current session. This behavior resembles the behavior of the `Set` command +in the Windows Command Shell and the `Setenv` command in UNIX-based +environments. To change values in the Machine or User scopes, you must use the +methods of the **System.Environment** class. + +To make changes to Machine-scoped variables, you must also have permission. If +you try to change a value without sufficient permission, the command fails and +PowerShell displays an error. + +PowerShell provides several different methods for using and managing environment +variables. + +- The variable syntax +- The Environment provider and Item cmdlets +- The .NET **System.Environment** class + +## Using the variable syntax + +You can display and change the values of environment variables with the +following syntax: ``` $Env: ``` -For example, to display the value of the `WINDIR` environment variable, type -the following command at the PowerShell command prompt: +For example, to display the value of the `WINDIR` environment variable: ```powershell $Env:windir ``` +```Output +C:\Windows +``` + In this syntax, the dollar sign (`$`) indicates a variable, and the drive name (`Env:`) indicates an environment variable followed by the variable name (`windir`). -When you change environment variables in PowerShell, the change affects only -the current session. This behavior resembles the behavior of the `Set` command -in the Windows Command Shell and the `Setenv` command in UNIX-based -environments. To change values in the Machine or User scopes, you must use the -methods of the **System.Environment** class. - -To make changes to Machine-scoped variables, you must also have permission. If -you try to change a value without sufficient permission, the command fails and -PowerShell displays an error. - -You can change the values of variables without using a cmdlet using the -following syntax: +You can create and update the value of environment variables with the following +syntax: ```powershell $Env: = "" ``` -For example, to append `;c:\temp` to the value of the `Path` environment -variable, use the following syntax: +For example, to create the `Foo` environment variable: ```powershell -$Env:Path += ";c:\temp" +$Env:Foo = 'An example' ``` -You can also use the Item cmdlets, such as `Set-Item`, `Remove-Item`, and -`Copy-Item` to change the values of environment variables. For example, to use -the `Set-Item` cmdlet to append `;c:\temp` to the value of the `Path` -environment variable, use the following syntax: +Because environment variables are always strings, you can use them like any +other variable containing a string. For example: ```powershell -Remove-Item -Path Env:Path +"The 'Foo' environment variable is set to: $Env:Foo" +$Env:Foo += '!' +$Env:Foo +``` + +```Output +The 'Foo' environment variable is set to: An example + +An example! ``` -In this command, the variable is cleared. Note that the environment -variable is referenced as an Item path and `$` is not used. +Because an environment variable can't be an empty string, setting one to `$null` +or an empty string removes it. For example: ```powershell -Set-Item -Path Env:Path -Value ($Env:Path + ";C:\Temp") +$Env:Foo = '' +$Env:Foo | Get-Member -MemberType Properties ``` -In this command, the value is enclosed in parentheses so that it is -interpreted as a unit. +```Output +Get-Member : You must specify an object for the Get-Member cmdlet. +At line:1 char:12 ++ $env:foo | Get-Member ++ ~~~~~~~~~~ + + CategoryInfo : CloseError: (:) [Get-Member], InvalidOperationException + + FullyQualifiedErrorId : NoObjectInGetMember,Microsoft.PowerShell.Commands.GetMemberCommand +``` -## Managing environment variables +`Get-Member` returned an error because the environment variable was removed. You +can see that it does not return an error when you use it on an empty string: -PowerShell provides several different methods for managing environment -variables. +```powershell +'' | Get-Member -MemberType Properties +``` -- The Environment provider drive -- The Item cmdlets -- The .NET **System.Environment** class -- On Windows, the System Control Panel +```Output + TypeName: System.String -### Using the Environment provider +Name MemberType Definition +---- ---------- ---------- +Length Property int Length {get;} +``` -Each environment variable is represented by an instance of the -**System.Collections.DictionaryEntry** class. In each **DictionaryEntry** -object, the name of the environment variable is the dictionary key. The value -of the variable is the dictionary value. +For more information about variables in PowerShell, see +[about_Variables](about_variables.md). -To display the properties and methods of the object that represents an -environment variable in PowerShell, use the `Get-Member` cmdlet. For example, -to display the methods and properties of all the objects in the `Env:` drive, -type: +## Using the Environment provider and Item cmdlets -```powershell -Get-Item -Path Env:* | Get-Member -``` +PowerShell's **Environment** provider gives you an interface for interacting +with environment variables in a format that resembles a file system drive. It +lets you get, add, change, clear, and delete environment variables and values in +PowerShell. -The PowerShell Environment provider lets you access environment variables in a -PowerShell drive (the `Env:` drive). This drive looks much like a file system -drive. To go to the `Env:` drive, type: +For example, to create the `Foo` environment variable with a value of `Bar`: ```powershell -Set-Location Env: +New-Item -Path Env:\Foo -Value 'Bar' ``` -Use the Content cmdlets to get or set the values of an environment variable. +```Output +Name Value +---- ----- +Foo Bar +``` + +You can also copy the environment variable with `Copy-Item`, set the value of an +environment variable with `Set-Item`, list environment variables with +`Get-Item`, and delete the environment variable with `Remove-Item`. ```powershell -PS Env:\> Set-Content -Path Test -Value 'Test value' -PS Env:\> Get-Content -Path Test -Test value +Copy-Item -Path Env:\Foo -Destination Env:\Foo2 -PassThru +Set-Item -Path Env:\Foo2 -Value 'BAR' +Get-Item -Path Env:\Foo* +Remove-Item -Path Env:\Foo* -Verbose ``` -You can view the environment variables in the `Env:` drive from any other -PowerShell drive, and you can go into the `Env:` drive to view and change the -environment variables. +```Output +Name Value +---- ----- +Foo2 Bar -### Using Item cmdlets +Name Value +---- ----- +Foo2 BAR +Foo Bar -When you refer to an environment variable, type the `Env:` drive name followed -by the name of the variable. For example, to display the value of the -`COMPUTERNAME` environment variable, type: - -```powershell -Get-ChildItem Env:Computername +VERBOSE: Performing the operation "Remove Item" on target "Item: Foo2". +VERBOSE: Performing the operation "Remove Item" on target "Item: Foo". ``` -To display the values of all the environment variables, type: +For more information on using the **Environment** provider to manage environment +variables, see [about_Environment_Provider](about_Environment_Provider.md). -```powershell -Get-ChildItem Env: -``` +## Using the System.Environment methods -Because environment variables do not have child items, the output of `Get-Item` -and `Get-ChildItem` is the same. +The **System.Environment** class provides the **GetEnvironmentVariable** and +**SetEnvironmentVariable** methods to get and modify environment variables. -By default, PowerShell displays the environment variables in the order in which -it retrieves them. To sort the list of environment variables by variable name, -pipe the output of a `Get-ChildItem` command to the `Sort-Object` cmdlet. For -example, from any PowerShell drive, type: +The following example creates a new environment variable, `Foo`, with a value of +`Bar` and then returns its value. ```powershell -Get-ChildItem Env: | Sort Name +[Environment]::SetEnvironmentVariable('Foo','Bar') +[Environment]::GetEnvironmentVariable('Foo') +``` + +```Output +Bar ``` -You can also go into the `Env:` drive by using the `Set-Location` cmdlet: +You can remove an environment variable with the **SetEnvironmentVariable** +method by specifying an empty string for the variable's value. For example, +to remove the `Foo` environment variable: ```powershell -Set-Location Env: +[Environment]::SetEnvironmentVariable('Foo','') +[Environment]::GetEnvironmentVariable('Foo') ``` -When you are in the `Env:` drive, you can omit the `Env:` drive name from the -path. For example, to display all the environment variables, type: +```Output -```powershell -PS Env:\> Get-ChildItem ``` -To display the value of the `COMPUTERNAME` variable from within the `Env:` -drive, type: +For more information about the methods of the **System.Environment** class, see +[Environment Methods](/dotnet/api/system.environment). + +## Saving changes to environment variables + +On Windows, there are three methods for making a persistent change to an +environment variable: setting them in your profile, using the +**SetEnvironmentVariable** method, and using the System Control Panel. + +### Saving environment variables in your profile + +Any environment variable you add or change in your PowerShell profile is +available in any session that loads your profile. This method works for any +version of PowerShell on any supported platform. + +For example, to create the `CompanyUri` environment variable and update the +`Path` environment variable to include the `C:\Tools` folder, add the following +lines to your PowerShell profile: ```powershell -PS Env:\> Get-ChildItem ComputerName +$Env:CompanyUri = 'https://internal.contoso.com' +$Env:Path += ';C:\Tools' ``` -### Saving changes to environment variables +You can get the path to your PowerShell profile with the `$PROFILE` automatic +variable. For more information on profiles, see +[about_Profiles](about_profiles.md). -To make a persistent change to an environment variable on Windows, use the -System Control Panel. Select **Advanced System Settings**. On the **Advanced** -tab, click **Environment Variable...**. You can add or edit existing -environment variables in the **User** and **System** (Machine) scopes. Windows -writes these values to the Registry so that they persist across sessions and -system restarts. +### Saving environment variables with SetEnvironmentVariable -Alternately, you can add or change environment variables in your PowerShell -profile. This method works for any version of PowerShell on any supported -platform. +On Windows, you can specify a scope for the **SetEnvironmentVariable** method as +the third parameter to set the environment variable in that scope. The machine +and user scopes both persist outside of the current process, allowing you to +save a new or changed environment variable. -### Using System.Environment methods +For example, to save a new environment variable `Foo` with the value `Bar`to the +machine scope: -The **System.Environment** class provides **GetEnvironmentVariable** and -**SetEnvironmentVariable** methods that allow you to specify the scope of the -variable. +```powershell +[Environment]::SetEnvironmentVariable('Foo', 'Bar', 'Machine') +``` -The following example uses the **GetEnvironmentVariable** method to get the -machine setting of `PSModulePath` and the **SetEnvironmentVariable** method -to add the `C:\Program Files\Fabrikam\Modules` path to the value. +You can delete an environment variable from the user or machine scope by setting +the variable's value to an empty string. ```powershell -$path = [Environment]::GetEnvironmentVariable('PSModulePath', 'Machine') -$newpath = $path + ';C:\Program Files\Fabrikam\Modules' -[Environment]::SetEnvironmentVariable("PSModulePath", $newpath, 'Machine') +[Environment]::SetEnvironmentVariable('Foo', '', 'Machine') ``` -For more information about the methods of the **System.Environment** class, see -[Environment Methods](/dotnet/api/system.environment). +### Saving environment variables with the System Control Panel + +In the System Control Panel, you can add or edit existing environment variables +in the **User** and **System** (Machine) scopes. Windows writes these values to +the Registry so that they persist across sessions and system restarts. + +To make a persistent change to an environment variable on Windows using the +System Control Panel: + +1. Open the System Control Panel. +1. Select **System**. +1. Select **Advanced System Settings**. +1. Go to the **Advanced** tab. +1. Select **Environment Variables...**. +1. Make your changes. ## PowerShell's environment variables @@ -263,23 +314,23 @@ The environment variables that store preferences include: command and is written on a background thread sometime after a module is imported. - Default location of the cache is: + The default location of the cache is: - `$env:LOCALAPPDATA\Microsoft\Windows\PowerShell` - The default filename for the cache is `ModuleAnalysisCache`. To change the - default location of the cache, set the environment variable before starting - PowerShell. Changes to this environment variable only affect child processes. - The value should name a full path (including filename) that PowerShell has - permission to create and write files. + The default filename for the cache is `ModuleAnalysisCache`. > [!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. - To disable the file cache, set this value to an invalid location, for - example: + To change the default location of the cache, set the environment variable + before starting PowerShell. Changes to this environment variable only affect + child processes. The value should name a full path (including filename) that + PowerShell has permission to create and write files. + + To disable the file cache, set this value to an invalid location, for example: ```powershell # `NUL` here is a special device on Windows that cannot be written to @@ -358,4 +409,6 @@ The environment variables that store preferences include: ## See also - [about_Environment_Provider](about_Environment_Provider.md) -- [about_Modules](about_Modules.md) +- [about_Profiles](about_profiles.md) +- [about_Variables](about_variables.md) +- [Environment Methods](/dotnet/api/system.environment) 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 df5d3ee3b967..cab8be95f1ac 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. +description: Describes how to access and manage environment variables in PowerShell. Locale: en-US -ms.date: 11/15/2021 +ms.date: 03/31/2022 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 @@ -9,31 +9,25 @@ title: about Environment Variables # about_Environment_Variables ## Short description -Describes how to access Windows environment variables in PowerShell. +Describes how to access and manage environment variables in PowerShell. ## Long description -Environment variables store information about the operating system -environment. This information includes details such as the operating system -path, the number of processors used by the operating system, and the location -of temporary folders. - -The environment variables store data that is used by the operating system and +Environment variables store data that is used by the operating system and other programs. For example, the `WINDIR` environment variable contains the location of the Windows installation directory. Programs can query the value of this variable to determine where Windows operating system files are located. PowerShell can access and manage environment variables in any of the supported -operating system platforms. The PowerShell environment provider simplifies this -process by making it easy to view and change environment variables. +operating system platforms. The PowerShell environment provider lets you get, +add, change, clear, and delete environment variables in the current console. -Environment variables, unlike other types of variables in PowerShell, are +Environment variables, unlike other types of variables in PowerShell, are always +stored as a string and can't be empty. Also unlike other variables, they are inherited by child processes, such as local background jobs and the sessions in which module members run. This makes environment variables well suited to storing values that are needed in both parent and child processes. -## Using and changing environment variables - On Windows, environment variables can be defined in three scopes: - Machine (or System) scope @@ -43,202 +37,256 @@ On Windows, environment variables can be defined in three scopes: The _Process_ scope contains the environment variables available in the current process, or PowerShell session. This list of variables is inherited from the parent process and is constructed from the variables in the _Machine_ and -_User_ scopes. Unix-based platforms only have the _Process_ scope. +_User_ scopes. + +When you change environment variables in PowerShell, the change affects only +the current session. This behavior resembles the behavior of the `Set` command +in the Windows Command Shell and the `Setenv` command in UNIX-based +environments. To change values in the Machine or User scopes, you must use the +methods of the **System.Environment** class. + +To make changes to Machine-scoped variables, you must also have permission. If +you try to change a value without sufficient permission, the command fails and +PowerShell displays an error. + +PowerShell provides several different methods for using and managing environment +variables. -You can display and change the values of environment variables without using a -cmdlet by using a variable syntax with the environment provider. To display the -value of an environment variable, use the following syntax: +- The variable syntax +- The Environment provider and Item cmdlets +- The .NET **System.Environment** class + +## Using the variable syntax + +You can display and change the values of environment variables with the +following syntax: ``` $Env: ``` -For example, to display the value of the `WINDIR` environment variable, type -the following command at the PowerShell command prompt: +For example, to display the value of the `WINDIR` environment variable: ```powershell $Env:windir ``` +```Output +C:\Windows +``` + In this syntax, the dollar sign (`$`) indicates a variable, and the drive name (`Env:`) indicates an environment variable followed by the variable name (`windir`). -When you change environment variables in PowerShell, the change affects only -the current session. This behavior resembles the behavior of the `Set` command -in the Windows Command Shell and the `Setenv` command in UNIX-based -environments. To change values in the Machine or User scopes, you must use the -methods of the **System.Environment** class. - -To make changes to Machine-scoped variables, you must also have permission. If -you try to change a value without sufficient permission, the command fails and -PowerShell displays an error. - -You can change the values of variables without using a cmdlet using the -following syntax: +You can create and update the value of environment variables with the following +syntax: ```powershell $Env: = "" ``` -For example, to append `;c:\temp` to the value of the `Path` environment -variable, use the following syntax: +For example, to create the `Foo` environment variable: ```powershell -$Env:Path += ";c:\temp" +$Env:Foo = 'An example' ``` -On Linux or macOS, the colon (`:`) in the command separates the new path from -the path that precedes it in the list. +Because environment variables are always strings, you can use them like any +other variable containing a string. For example: ```powershell -$Env:PATH += ":/usr/local/temp" +"The 'Foo' environment variable is set to: $Env:Foo" +$Env:Foo += '!' +$Env:Foo ``` -You can also use the Item cmdlets, such as `Set-Item`, `Remove-Item`, and -`Copy-Item` to change the values of environment variables. For example, to use -the `Set-Item` cmdlet to append `;c:\temp` to the value of the `Path` -environment variable, use the following syntax: +```Output +The 'Foo' environment variable is set to: An example -```powershell -Remove-Item -Path Env:Path +An example! ``` -In this command, the variable is cleared. Note that the environment -variable is referenced as an Item path and `$` is not used. +Because an environment variable can't be an empty string, setting one to `$null` +or an empty string removes it. For example: ```powershell -Set-Item -Path Env:Path -Value ($Env:Path + ";C:\Temp") +$Env:Foo = '' +$Env:Foo | Get-Member -MemberType Properties ``` -In this command, the value is enclosed in parentheses so that it is -interpreted as a unit. +```Output +Get-Member : You must specify an object for the Get-Member cmdlet. +At line:1 char:12 ++ $env:foo | Get-Member ++ ~~~~~~~~~~ + + CategoryInfo : CloseError: (:) [Get-Member], InvalidOperationException + + FullyQualifiedErrorId : NoObjectInGetMember,Microsoft.PowerShell.Commands.GetMemberCommand +``` -## Managing environment variables +`Get-Member` returned an error because the environment variable was removed. You +can see that it does not return an error when you use it on an empty string: -PowerShell provides several different methods for managing environment -variables. +```powershell +'' | Get-Member -MemberType Properties +``` -- The Environment provider drive -- The Item cmdlets -- The .NET **System.Environment** class -- On Windows, the System Control Panel +```Output + TypeName: System.String -### Using the Environment provider +Name MemberType Definition +---- ---------- ---------- +Length Property int Length {get;} +``` -Each environment variable is represented by an instance of the -**System.Collections.DictionaryEntry** class. In each **DictionaryEntry** -object, the name of the environment variable is the dictionary key. The value -of the variable is the dictionary value. +For more information about variables in PowerShell, see +[about_Variables](about_variables.md). -To display the properties and methods of the object that represents an -environment variable in PowerShell, use the `Get-Member` cmdlet. For example, -to display the methods and properties of all the objects in the `Env:` drive, -type: +## Using the Environment provider and Item cmdlets -```powershell -Get-Item -Path Env:* | Get-Member -``` +PowerShell's **Environment** provider gives you an interface for interacting +with environment variables in a format that resembles a file system drive. It +lets you get, add, change, clear, and delete environment variables and values in +PowerShell. -The PowerShell Environment provider lets you access environment variables in a -PowerShell drive (the `Env:` drive). This drive looks much like a file system -drive. To go to the `Env:` drive, type: +For example, to create the `Foo` environment variable with a value of `Bar`: ```powershell -Set-Location Env: +New-Item -Path Env:\Foo -Value 'Bar' ``` -Use the Content cmdlets to get or set the values of an environment variable. +```Output +Name Value +---- ----- +Foo Bar +``` + +You can also copy the environment variable with `Copy-Item`, set the value of an +environment variable with `Set-Item`, list environment variables with +`Get-Item`, and delete the environment variable with `Remove-Item`. ```powershell -PS Env:\> Set-Content -Path Test -Value 'Test value' -PS Env:\> Get-Content -Path Test -Test value +Copy-Item -Path Env:\Foo -Destination Env:\Foo2 -PassThru +Set-Item -Path Env:\Foo2 -Value 'BAR' +Get-Item -Path Env:\Foo* +Remove-Item -Path Env:\Foo* -Verbose ``` -You can view the environment variables in the `Env:` drive from any other -PowerShell drive, and you can go into the `Env:` drive to view and change the -environment variables. - -### Using Item cmdlets +```Output +Name Value +---- ----- +Foo2 Bar -When you refer to an environment variable, type the `Env:` drive name followed -by the name of the variable. For example, to display the value of the -`COMPUTERNAME` environment variable, type: +Name Value +---- ----- +Foo2 BAR +Foo Bar -```powershell -Get-ChildItem Env:Computername +VERBOSE: Performing the operation "Remove Item" on target "Item: Foo2". +VERBOSE: Performing the operation "Remove Item" on target "Item: Foo". ``` -To display the values of all the environment variables, type: +For more information on using the **Environment** provider to manage environment +variables, see [about_Environment_Provider](about_Environment_Provider.md). -```powershell -Get-ChildItem Env: -``` +## Using the System.Environment methods -Because environment variables do not have child items, the output of `Get-Item` -and `Get-ChildItem` is the same. +The **System.Environment** class provides the **GetEnvironmentVariable** and +**SetEnvironmentVariable** methods to get and modify environment variables. -By default, PowerShell displays the environment variables in the order in which -it retrieves them. To sort the list of environment variables by variable name, -pipe the output of a `Get-ChildItem` command to the `Sort-Object` cmdlet. For -example, from any PowerShell drive, type: +The following example creates a new environment variable, `Foo`, with a value of +`Bar` and then returns its value. ```powershell -Get-ChildItem Env: | Sort Name +[Environment]::SetEnvironmentVariable('Foo','Bar') +[Environment]::GetEnvironmentVariable('Foo') +``` + +```Output +Bar ``` -You can also go into the `Env:` drive by using the `Set-Location` cmdlet: +You can remove an environment variable with the **SetEnvironmentVariable** +method by specifying an empty string for the variable's value. For example, +to remove the `Foo` environment variable: ```powershell -Set-Location Env: +[Environment]::SetEnvironmentVariable('Foo','') +[Environment]::GetEnvironmentVariable('Foo') ``` -When you are in the `Env:` drive, you can omit the `Env:` drive name from the -path. For example, to display all the environment variables, type: +```Output -```powershell -PS Env:\> Get-ChildItem ``` -To display the value of the `COMPUTERNAME` variable from within the `Env:` -drive, type: +For more information about the methods of the **System.Environment** class, see +[Environment Methods](/dotnet/api/system.environment). + +## Saving changes to environment variables + +On Windows, there are three methods for making a persistent change to an +environment variable: setting them in your profile, using the +**SetEnvironmentVariable** method, and using the System Control Panel. + +### Saving environment variables in your profile + +Any environment variable you add or change in your PowerShell profile is +available in any session that loads your profile. This method works for any +version of PowerShell on any supported platform. + +For example, to create the `CompanyUri` environment variable and update the +`Path` environment variable to include the `C:\Tools` folder, add the following +lines to your PowerShell profile: ```powershell -PS Env:\> Get-ChildItem ComputerName +$Env:CompanyUri = 'https://internal.contoso.com' +$Env:Path += ';C:\Tools' ``` -### Saving changes to environment variables +> [!NOTE] +> On Linux or macOS, the colon (`:`) is used instead of a semi-colon(`;`) to +> separate a new path from the path that precedes it in the list. + +You can get the path to your PowerShell profile with the `$PROFILE` automatic +variable. For more information on profiles, see +[about_Profiles](about_profiles.md). -To make a persistent change to an environment variable on Windows, use the -System Control Panel. Select **Advanced System Settings**. On the **Advanced** -tab, click **Environment Variable...**. You can add or edit existing -environment variables in the **User** and **System** (Machine) scopes. Windows -writes these values to the Registry so that they persist across sessions and -system restarts. +### Saving environment variables with SetEnvironmentVariable -Alternately, you can add or change environment variables in your PowerShell -profile. This method works for any version of PowerShell on any supported -platform. +On Windows, you can specify a scope for the **SetEnvironmentVariable** method as +the third parameter to set the environment variable in that scope. The machine +and user scopes both persist outside of the current process, allowing you to +save a new or changed environment variable. -### Using System.Environment methods +For example, to save a new environment variable `Foo` with the value `Bar`to the +machine scope: -The **System.Environment** class provides **GetEnvironmentVariable** and -**SetEnvironmentVariable** methods that allow you to specify the scope of the -variable. +```powershell +[Environment]::SetEnvironmentVariable('Foo', 'Bar', 'Machine') +``` -The following example uses the **GetEnvironmentVariable** method to get the -machine setting of `PSModulePath` and the **SetEnvironmentVariable** method -to add the `C:\Program Files\Fabrikam\Modules` path to the value. +You can delete an environment variable from the user or machine scope by setting +the variable's value to an empty string. ```powershell -$path = [Environment]::GetEnvironmentVariable('PSModulePath', 'Machine') -$newpath = $path + ';C:\Program Files\Fabrikam\Modules' -[Environment]::SetEnvironmentVariable("PSModulePath", $newpath, 'Machine') +[Environment]::SetEnvironmentVariable('Foo', '', 'Machine') ``` -For more information about the methods of the **System.Environment** class, see -[Environment Methods](/dotnet/api/system.environment). +### Saving environment variables with the System Control Panel + +In the System Control Panel, you can add or edit existing environment variables +in the **User** and **System** (Machine) scopes. Windows writes these values to +the Registry so that they persist across sessions and system restarts. + +To make a persistent change to an environment variable on Windows using the +System Control Panel: + +1. Open the System Control Panel. +1. Select **System**. +1. Select **Advanced System Settings**. +1. Go to the **Advanced** tab. +1. Select **Environment Variables...**. +1. Make your changes. ## PowerShell's environment variables @@ -270,7 +318,7 @@ The environment variables that store preferences include: command and is written on a background thread sometime after a module is imported. - Default location of the cache is: + The default location of the cache is: - Windows PowerShell 5.1: `$env:LOCALAPPDATA\Microsoft\Windows\PowerShell` - PowerShell 6.0 and higher: `$env:LOCALAPPDATA\Microsoft\PowerShell` @@ -287,11 +335,10 @@ The environment variables that store preferences include: To change the default location of the cache, set the environment variable before starting PowerShell. Changes to this environment variable only affect - child processes. The value should name a full path (including filename) - that PowerShell has permission to create and write files. + child processes. The value should name a full path (including filename) that + PowerShell has permission to create and write files. - To disable the file cache, set this value to an invalid location, for - example: + To disable the file cache, set this value to an invalid location, for example: ```powershell # `NUL` here is a special device on Windows that cannot be written to, @@ -400,30 +447,11 @@ The environment variables that store preferences include: - **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 - [about_Environment_Provider](about_Environment_Provider.md) -- [about_Modules](about_Modules.md) +- [about_Profiles](about_profiles.md) +- [about_Variables](about_variables.md) +- [Environment Methods](/dotnet/api/system.environment) [xdg-bds]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html 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 040498ecbd39..5771042bb5f0 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. +description: Describes how to access and manage environment variables in PowerShell. Locale: en-US -ms.date: 11/15/2021 +ms.date: 03/31/2022 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 @@ -9,31 +9,25 @@ title: about Environment Variables # about_Environment_Variables ## Short description -Describes how to access Windows environment variables in PowerShell. +Describes how to access and manage environment variables in PowerShell. ## Long description -Environment variables store information about the operating system -environment. This information includes details such as the operating system -path, the number of processors used by the operating system, and the location -of temporary folders. - -The environment variables store data that is used by the operating system and +Environment variables store data that is used by the operating system and other programs. For example, the `WINDIR` environment variable contains the location of the Windows installation directory. Programs can query the value of this variable to determine where Windows operating system files are located. PowerShell can access and manage environment variables in any of the supported -operating system platforms. The PowerShell environment provider simplifies this -process by making it easy to view and change environment variables. +operating system platforms. The PowerShell environment provider lets you get, +add, change, clear, and delete environment variables in the current console. -Environment variables, unlike other types of variables in PowerShell, are +Environment variables, unlike other types of variables in PowerShell, are always +stored as a string and can't be empty. Also unlike other variables, they are inherited by child processes, such as local background jobs and the sessions in which module members run. This makes environment variables well suited to storing values that are needed in both parent and child processes. -## Using and changing environment variables - On Windows, environment variables can be defined in three scopes: - Machine (or System) scope @@ -43,202 +37,256 @@ On Windows, environment variables can be defined in three scopes: The _Process_ scope contains the environment variables available in the current process, or PowerShell session. This list of variables is inherited from the parent process and is constructed from the variables in the _Machine_ and -_User_ scopes. Unix-based platforms only have the _Process_ scope. +_User_ scopes. + +When you change environment variables in PowerShell, the change affects only +the current session. This behavior resembles the behavior of the `Set` command +in the Windows Command Shell and the `Setenv` command in UNIX-based +environments. To change values in the Machine or User scopes, you must use the +methods of the **System.Environment** class. + +To make changes to Machine-scoped variables, you must also have permission. If +you try to change a value without sufficient permission, the command fails and +PowerShell displays an error. + +PowerShell provides several different methods for using and managing environment +variables. -You can display and change the values of environment variables without using a -cmdlet by using a variable syntax with the environment provider. To display the -value of an environment variable, use the following syntax: +- The variable syntax +- The Environment provider and Item cmdlets +- The .NET **System.Environment** class + +## Using the variable syntax + +You can display and change the values of environment variables with the +following syntax: ``` $Env: ``` -For example, to display the value of the `WINDIR` environment variable, type -the following command at the PowerShell command prompt: +For example, to display the value of the `WINDIR` environment variable: ```powershell $Env:windir ``` +```Output +C:\Windows +``` + In this syntax, the dollar sign (`$`) indicates a variable, and the drive name (`Env:`) indicates an environment variable followed by the variable name (`windir`). -When you change environment variables in PowerShell, the change affects only -the current session. This behavior resembles the behavior of the `Set` command -in the Windows Command Shell and the `Setenv` command in UNIX-based -environments. To change values in the Machine or User scopes, you must use the -methods of the **System.Environment** class. - -To make changes to Machine-scoped variables, you must also have permission. If -you try to change a value without sufficient permission, the command fails and -PowerShell displays an error. - -You can change the values of variables without using a cmdlet using the -following syntax: +You can create and update the value of environment variables with the following +syntax: ```powershell $Env: = "" ``` -For example, to append `;c:\temp` to the value of the `Path` environment -variable, use the following syntax: +For example, to create the `Foo` environment variable: ```powershell -$Env:Path += ";c:\temp" +$Env:Foo = 'An example' ``` -On Linux or macOS, the colon (`:`) in the command separates the new path from -the path that precedes it in the list. +Because environment variables are always strings, you can use them like any +other variable containing a string. For example: ```powershell -$Env:PATH += ":/usr/local/temp" +"The 'Foo' environment variable is set to: $Env:Foo" +$Env:Foo += '!' +$Env:Foo ``` -You can also use the Item cmdlets, such as `Set-Item`, `Remove-Item`, and -`Copy-Item` to change the values of environment variables. For example, to use -the `Set-Item` cmdlet to append `;c:\temp` to the value of the `Path` -environment variable, use the following syntax: +```Output +The 'Foo' environment variable is set to: An example -```powershell -Remove-Item -Path Env:Path +An example! ``` -In this command, the variable is cleared. Note that the environment -variable is referenced as an Item path and `$` is not used. +Because an environment variable can't be an empty string, setting one to `$null` +or an empty string removes it. For example: ```powershell -Set-Item -Path Env:Path -Value ($Env:Path + ";C:\Temp") +$Env:Foo = '' +$Env:Foo | Get-Member -MemberType Properties ``` -In this command, the value is enclosed in parentheses so that it is -interpreted as a unit. +```Output +Get-Member : You must specify an object for the Get-Member cmdlet. +At line:1 char:12 ++ $env:foo | Get-Member ++ ~~~~~~~~~~ + + CategoryInfo : CloseError: (:) [Get-Member], InvalidOperationException + + FullyQualifiedErrorId : NoObjectInGetMember,Microsoft.PowerShell.Commands.GetMemberCommand +``` -## Managing environment variables +`Get-Member` returned an error because the environment variable was removed. You +can see that it does not return an error when you use it on an empty string: -PowerShell provides several different methods for managing environment -variables. +```powershell +'' | Get-Member -MemberType Properties +``` -- The Environment provider drive -- The Item cmdlets -- The .NET **System.Environment** class -- On Windows, the System Control Panel +```Output + TypeName: System.String -### Using the Environment provider +Name MemberType Definition +---- ---------- ---------- +Length Property int Length {get;} +``` -Each environment variable is represented by an instance of the -**System.Collections.DictionaryEntry** class. In each **DictionaryEntry** -object, the name of the environment variable is the dictionary key. The value -of the variable is the dictionary value. +For more information about variables in PowerShell, see +[about_Variables](about_variables.md). -To display the properties and methods of the object that represents an -environment variable in PowerShell, use the `Get-Member` cmdlet. For example, -to display the methods and properties of all the objects in the `Env:` drive, -type: +## Using the Environment provider and Item cmdlets -```powershell -Get-Item -Path Env:* | Get-Member -``` +PowerShell's **Environment** provider gives you an interface for interacting +with environment variables in a format that resembles a file system drive. It +lets you get, add, change, clear, and delete environment variables and values in +PowerShell. -The PowerShell Environment provider lets you access environment variables in a -PowerShell drive (the `Env:` drive). This drive looks much like a file system -drive. To go to the `Env:` drive, type: +For example, to create the `Foo` environment variable with a value of `Bar`: ```powershell -Set-Location Env: +New-Item -Path Env:\Foo -Value 'Bar' ``` -Use the Content cmdlets to get or set the values of an environment variable. +```Output +Name Value +---- ----- +Foo Bar +``` + +You can also copy the environment variable with `Copy-Item`, set the value of an +environment variable with `Set-Item`, list environment variables with +`Get-Item`, and delete the environment variable with `Remove-Item`. ```powershell -PS Env:\> Set-Content -Path Test -Value 'Test value' -PS Env:\> Get-Content -Path Test -Test value +Copy-Item -Path Env:\Foo -Destination Env:\Foo2 -PassThru +Set-Item -Path Env:\Foo2 -Value 'BAR' +Get-Item -Path Env:\Foo* +Remove-Item -Path Env:\Foo* -Verbose ``` -You can view the environment variables in the `Env:` drive from any other -PowerShell drive, and you can go into the `Env:` drive to view and change the -environment variables. - -### Using Item cmdlets +```Output +Name Value +---- ----- +Foo2 Bar -When you refer to an environment variable, type the `Env:` drive name followed -by the name of the variable. For example, to display the value of the -`COMPUTERNAME` environment variable, type: +Name Value +---- ----- +Foo2 BAR +Foo Bar -```powershell -Get-ChildItem Env:Computername +VERBOSE: Performing the operation "Remove Item" on target "Item: Foo2". +VERBOSE: Performing the operation "Remove Item" on target "Item: Foo". ``` -To display the values of all the environment variables, type: +For more information on using the **Environment** provider to manage environment +variables, see [about_Environment_Provider](about_Environment_Provider.md). -```powershell -Get-ChildItem Env: -``` +## Using the System.Environment methods -Because environment variables do not have child items, the output of `Get-Item` -and `Get-ChildItem` is the same. +The **System.Environment** class provides the **GetEnvironmentVariable** and +**SetEnvironmentVariable** methods to get and modify environment variables. -By default, PowerShell displays the environment variables in the order in which -it retrieves them. To sort the list of environment variables by variable name, -pipe the output of a `Get-ChildItem` command to the `Sort-Object` cmdlet. For -example, from any PowerShell drive, type: +The following example creates a new environment variable, `Foo`, with a value of +`Bar` and then returns its value. ```powershell -Get-ChildItem Env: | Sort Name +[Environment]::SetEnvironmentVariable('Foo','Bar') +[Environment]::GetEnvironmentVariable('Foo') +``` + +```Output +Bar ``` -You can also go into the `Env:` drive by using the `Set-Location` cmdlet: +You can remove an environment variable with the **SetEnvironmentVariable** +method by specifying an empty string for the variable's value. For example, +to remove the `Foo` environment variable: ```powershell -Set-Location Env: +[Environment]::SetEnvironmentVariable('Foo','') +[Environment]::GetEnvironmentVariable('Foo') ``` -When you are in the `Env:` drive, you can omit the `Env:` drive name from the -path. For example, to display all the environment variables, type: +```Output -```powershell -PS Env:\> Get-ChildItem ``` -To display the value of the `COMPUTERNAME` variable from within the `Env:` -drive, type: +For more information about the methods of the **System.Environment** class, see +[Environment Methods](/dotnet/api/system.environment). + +## Saving changes to environment variables + +On Windows, there are three methods for making a persistent change to an +environment variable: setting them in your profile, using the +**SetEnvironmentVariable** method, and using the System Control Panel. + +### Saving environment variables in your profile + +Any environment variable you add or change in your PowerShell profile is +available in any session that loads your profile. This method works for any +version of PowerShell on any supported platform. + +For example, to create the `CompanyUri` environment variable and update the +`Path` environment variable to include the `C:\Tools` folder, add the following +lines to your PowerShell profile: ```powershell -PS Env:\> Get-ChildItem ComputerName +$Env:CompanyUri = 'https://internal.contoso.com' +$Env:Path += ';C:\Tools' ``` -### Saving changes to environment variables +> [!NOTE] +> On Linux or macOS, the colon (`:`) is used instead of a semi-colon(`;`) to +> separate a new path from the path that precedes it in the list. + +You can get the path to your PowerShell profile with the `$PROFILE` automatic +variable. For more information on profiles, see +[about_Profiles](about_profiles.md). -To make a persistent change to an environment variable on Windows, use the -System Control Panel. Select **Advanced System Settings**. On the **Advanced** -tab, click **Environment Variable...**. You can add or edit existing -environment variables in the **User** and **System** (Machine) scopes. Windows -writes these values to the Registry so that they persist across sessions and -system restarts. +### Saving environment variables with SetEnvironmentVariable -Alternately, you can add or change environment variables in your PowerShell -profile. This method works for any version of PowerShell on any supported -platform. +On Windows, you can specify a scope for the **SetEnvironmentVariable** method as +the third parameter to set the environment variable in that scope. The machine +and user scopes both persist outside of the current process, allowing you to +save a new or changed environment variable. -### Using System.Environment methods +For example, to save a new environment variable `Foo` with the value `Bar`to the +machine scope: -The **System.Environment** class provides **GetEnvironmentVariable** and -**SetEnvironmentVariable** methods that allow you to specify the scope of the -variable. +```powershell +[Environment]::SetEnvironmentVariable('Foo', 'Bar', 'Machine') +``` -The following example uses the **GetEnvironmentVariable** method to get the -machine setting of `PSModulePath` and the **SetEnvironmentVariable** method -to add the `C:\Program Files\Fabrikam\Modules` path to the value. +You can delete an environment variable from the user or machine scope by setting +the variable's value to an empty string. ```powershell -$path = [Environment]::GetEnvironmentVariable('PSModulePath', 'Machine') -$newpath = $path + ';C:\Program Files\Fabrikam\Modules' -[Environment]::SetEnvironmentVariable("PSModulePath", $newpath, 'Machine') +[Environment]::SetEnvironmentVariable('Foo', '', 'Machine') ``` -For more information about the methods of the **System.Environment** class, see -[Environment Methods](/dotnet/api/system.environment). +### Saving environment variables with the System Control Panel + +In the System Control Panel, you can add or edit existing environment variables +in the **User** and **System** (Machine) scopes. Windows writes these values to +the Registry so that they persist across sessions and system restarts. + +To make a persistent change to an environment variable on Windows using the +System Control Panel: + +1. Open the System Control Panel. +1. Select **System**. +1. Select **Advanced System Settings**. +1. Go to the **Advanced** tab. +1. Select **Environment Variables...**. +1. Make your changes. ## PowerShell's environment variables @@ -270,7 +318,7 @@ The environment variables that store preferences include: command and is written on a background thread sometime after a module is imported. - Default location of the cache is: + The default location of the cache is: - Windows PowerShell 5.1: `$env:LOCALAPPDATA\Microsoft\Windows\PowerShell` - PowerShell 6.0 and higher: `$env:LOCALAPPDATA\Microsoft\PowerShell` @@ -287,11 +335,10 @@ The environment variables that store preferences include: To change the default location of the cache, set the environment variable before starting PowerShell. Changes to this environment variable only affect - child processes. The value should name a full path (including filename) - that PowerShell has permission to create and write files. + child processes. The value should name a full path (including filename) that + PowerShell has permission to create and write files. - To disable the file cache, set this value to an invalid location, for - example: + To disable the file cache, set this value to an invalid location, for example: ```powershell # `NUL` here is a special device on Windows that cannot be written to, @@ -400,30 +447,11 @@ The environment variables that store preferences include: - **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 - [about_Environment_Provider](about_Environment_Provider.md) -- [about_Modules](about_Modules.md) +- [about_Profiles](about_profiles.md) +- [about_Variables](about_variables.md) +- [Environment Methods](/dotnet/api/system.environment) [xdg-bds]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html 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 551e1653e131..04c3316973d8 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. +description: Describes how to access and manage environment variables in PowerShell. Locale: en-US -ms.date: 11/15/2021 +ms.date: 03/31/2022 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 @@ -9,31 +9,25 @@ title: about Environment Variables # about_Environment_Variables ## Short description -Describes how to access Windows environment variables in PowerShell. +Describes how to access and manage environment variables in PowerShell. ## Long description -Environment variables store information about the operating system -environment. This information includes details such as the operating system -path, the number of processors used by the operating system, and the location -of temporary folders. - -The environment variables store data that is used by the operating system and +Environment variables store data that is used by the operating system and other programs. For example, the `WINDIR` environment variable contains the location of the Windows installation directory. Programs can query the value of this variable to determine where Windows operating system files are located. PowerShell can access and manage environment variables in any of the supported -operating system platforms. The PowerShell environment provider simplifies this -process by making it easy to view and change environment variables. +operating system platforms. The PowerShell environment provider lets you get, +add, change, clear, and delete environment variables in the current console. -Environment variables, unlike other types of variables in PowerShell, are +Environment variables, unlike other types of variables in PowerShell, are always +stored as a string and can't be empty. Also unlike other variables, they are inherited by child processes, such as local background jobs and the sessions in which module members run. This makes environment variables well suited to storing values that are needed in both parent and child processes. -## Using and changing environment variables - On Windows, environment variables can be defined in three scopes: - Machine (or System) scope @@ -43,202 +37,256 @@ On Windows, environment variables can be defined in three scopes: The _Process_ scope contains the environment variables available in the current process, or PowerShell session. This list of variables is inherited from the parent process and is constructed from the variables in the _Machine_ and -_User_ scopes. Unix-based platforms only have the _Process_ scope. +_User_ scopes. + +When you change environment variables in PowerShell, the change affects only +the current session. This behavior resembles the behavior of the `Set` command +in the Windows Command Shell and the `Setenv` command in UNIX-based +environments. To change values in the Machine or User scopes, you must use the +methods of the **System.Environment** class. + +To make changes to Machine-scoped variables, you must also have permission. If +you try to change a value without sufficient permission, the command fails and +PowerShell displays an error. + +PowerShell provides several different methods for using and managing environment +variables. + +- The variable syntax +- The Environment provider and Item cmdlets +- The .NET **System.Environment** class -You can display and change the values of environment variables without using a -cmdlet by using a variable syntax with the environment provider. To display the -value of an environment variable, use the following syntax: +## Using the variable syntax + +You can display and change the values of environment variables with the +following syntax: ``` $Env: ``` -For example, to display the value of the `WINDIR` environment variable, type -the following command at the PowerShell command prompt: +For example, to display the value of the `WINDIR` environment variable: ```powershell $Env:windir ``` +```Output +C:\Windows +``` + In this syntax, the dollar sign (`$`) indicates a variable, and the drive name (`Env:`) indicates an environment variable followed by the variable name (`windir`). -When you change environment variables in PowerShell, the change affects only -the current session. This behavior resembles the behavior of the `Set` command -in the Windows Command Shell and the `Setenv` command in UNIX-based -environments. To change values in the Machine or User scopes, you must use the -methods of the **System.Environment** class. - -To make changes to Machine-scoped variables, you must also have permission. If -you try to change a value without sufficient permission, the command fails and -PowerShell displays an error. - -You can change the values of variables without using a cmdlet using the -following syntax: +You can create and update the value of environment variables with the following +syntax: ```powershell $Env: = "" ``` -For example, to append `;c:\temp` to the value of the `Path` environment -variable, use the following syntax: +For example, to create the `Foo` environment variable: ```powershell -$Env:Path += ";c:\temp" +$Env:Foo = 'An example' ``` -On Linux or macOS, the colon (`:`) in the command separates the new path from -the path that precedes it in the list. +Because environment variables are always strings, you can use them like any +other variable containing a string. For example: ```powershell -$Env:PATH += ":/usr/local/temp" +"The 'Foo' environment variable is set to: $Env:Foo" +$Env:Foo += '!' +$Env:Foo ``` -You can also use the Item cmdlets, such as `Set-Item`, `Remove-Item`, and -`Copy-Item` to change the values of environment variables. For example, to use -the `Set-Item` cmdlet to append `;c:\temp` to the value of the `Path` -environment variable, use the following syntax: +```Output +The 'Foo' environment variable is set to: An example -```powershell -Remove-Item -Path Env:Path +An example! ``` -In this command, the variable is cleared. Note that the environment -variable is referenced as an Item path and `$` is not used. +Because an environment variable can't be an empty string, setting one to `$null` +or an empty string removes it. For example: ```powershell -Set-Item -Path Env:Path -Value ($Env:Path + ";C:\Temp") +$Env:Foo = '' +$Env:Foo | Get-Member -MemberType Properties ``` -In this command, the value is enclosed in parentheses so that it is -interpreted as a unit. +```Output +Get-Member : You must specify an object for the Get-Member cmdlet. +At line:1 char:12 ++ $env:foo | Get-Member ++ ~~~~~~~~~~ + + CategoryInfo : CloseError: (:) [Get-Member], InvalidOperationException + + FullyQualifiedErrorId : NoObjectInGetMember,Microsoft.PowerShell.Commands.GetMemberCommand +``` -## Managing environment variables +`Get-Member` returned an error because the environment variable was removed. You +can see that it does not return an error when you use it on an empty string: -PowerShell provides several different methods for managing environment -variables. +```powershell +'' | Get-Member -MemberType Properties +``` -- The Environment provider drive -- The Item cmdlets -- The .NET **System.Environment** class -- On Windows, the System Control Panel +```Output + TypeName: System.String -### Using the Environment provider +Name MemberType Definition +---- ---------- ---------- +Length Property int Length {get;} +``` -Each environment variable is represented by an instance of the -**System.Collections.DictionaryEntry** class. In each **DictionaryEntry** -object, the name of the environment variable is the dictionary key. The value -of the variable is the dictionary value. +For more information about variables in PowerShell, see +[about_Variables](about_variables.md). -To display the properties and methods of the object that represents an -environment variable in PowerShell, use the `Get-Member` cmdlet. For example, -to display the methods and properties of all the objects in the `Env:` drive, -type: +## Using the Environment provider and Item cmdlets -```powershell -Get-Item -Path Env:* | Get-Member -``` +PowerShell's **Environment** provider gives you an interface for interacting +with environment variables in a format that resembles a file system drive. It +lets you get, add, change, clear, and delete environment variables and values in +PowerShell. -The PowerShell Environment provider lets you access environment variables in a -PowerShell drive (the `Env:` drive). This drive looks much like a file system -drive. To go to the `Env:` drive, type: +For example, to create the `Foo` environment variable with a value of `Bar`: ```powershell -Set-Location Env: +New-Item -Path Env:\Foo -Value 'Bar' ``` -Use the Content cmdlets to get or set the values of an environment variable. +```Output +Name Value +---- ----- +Foo Bar +``` + +You can also copy the environment variable with `Copy-Item`, set the value of an +environment variable with `Set-Item`, list environment variables with +`Get-Item`, and delete the environment variable with `Remove-Item`. ```powershell -PS Env:\> Set-Content -Path Test -Value 'Test value' -PS Env:\> Get-Content -Path Test -Test value +Copy-Item -Path Env:\Foo -Destination Env:\Foo2 -PassThru +Set-Item -Path Env:\Foo2 -Value 'BAR' +Get-Item -Path Env:\Foo* +Remove-Item -Path Env:\Foo* -Verbose ``` -You can view the environment variables in the `Env:` drive from any other -PowerShell drive, and you can go into the `Env:` drive to view and change the -environment variables. +```Output +Name Value +---- ----- +Foo2 Bar -### Using Item cmdlets +Name Value +---- ----- +Foo2 BAR +Foo Bar -When you refer to an environment variable, type the `Env:` drive name followed -by the name of the variable. For example, to display the value of the -`COMPUTERNAME` environment variable, type: - -```powershell -Get-ChildItem Env:Computername +VERBOSE: Performing the operation "Remove Item" on target "Item: Foo2". +VERBOSE: Performing the operation "Remove Item" on target "Item: Foo". ``` -To display the values of all the environment variables, type: +For more information on using the **Environment** provider to manage environment +variables, see [about_Environment_Provider](about_Environment_Provider.md). -```powershell -Get-ChildItem Env: -``` +## Using the System.Environment methods -Because environment variables do not have child items, the output of `Get-Item` -and `Get-ChildItem` is the same. +The **System.Environment** class provides the **GetEnvironmentVariable** and +**SetEnvironmentVariable** methods to get and modify environment variables. -By default, PowerShell displays the environment variables in the order in which -it retrieves them. To sort the list of environment variables by variable name, -pipe the output of a `Get-ChildItem` command to the `Sort-Object` cmdlet. For -example, from any PowerShell drive, type: +The following example creates a new environment variable, `Foo`, with a value of +`Bar` and then returns its value. ```powershell -Get-ChildItem Env: | Sort Name +[Environment]::SetEnvironmentVariable('Foo','Bar') +[Environment]::GetEnvironmentVariable('Foo') +``` + +```Output +Bar ``` -You can also go into the `Env:` drive by using the `Set-Location` cmdlet: +You can remove an environment variable with the **SetEnvironmentVariable** +method by specifying an empty string for the variable's value. For example, +to remove the `Foo` environment variable: ```powershell -Set-Location Env: +[Environment]::SetEnvironmentVariable('Foo','') +[Environment]::GetEnvironmentVariable('Foo') ``` -When you are in the `Env:` drive, you can omit the `Env:` drive name from the -path. For example, to display all the environment variables, type: +```Output -```powershell -PS Env:\> Get-ChildItem ``` -To display the value of the `COMPUTERNAME` variable from within the `Env:` -drive, type: +For more information about the methods of the **System.Environment** class, see +[Environment Methods](/dotnet/api/system.environment). + +## Saving changes to environment variables + +On Windows, there are three methods for making a persistent change to an +environment variable: setting them in your profile, using the +**SetEnvironmentVariable** method, and using the System Control Panel. + +### Saving environment variables in your profile + +Any environment variable you add or change in your PowerShell profile is +available in any session that loads your profile. This method works for any +version of PowerShell on any supported platform. + +For example, to create the `CompanyUri` environment variable and update the +`Path` environment variable to include the `C:\Tools` folder, add the following +lines to your PowerShell profile: ```powershell -PS Env:\> Get-ChildItem ComputerName +$Env:CompanyUri = 'https://internal.contoso.com' +$Env:Path += ';C:\Tools' ``` -### Saving changes to environment variables +> [!NOTE] +> On Linux or macOS, the colon (`:`) is used instead of a semi-colon(`;`) to +> separate a new path from the path that precedes it in the list. -To make a persistent change to an environment variable on Windows, use the -System Control Panel. Select **Advanced System Settings**. On the **Advanced** -tab, click **Environment Variable...**. You can add or edit existing -environment variables in the **User** and **System** (Machine) scopes. Windows -writes these values to the Registry so that they persist across sessions and -system restarts. +You can get the path to your PowerShell profile with the `$PROFILE` automatic +variable. For more information on profiles, see +[about_Profiles](about_profiles.md). -Alternately, you can add or change environment variables in your PowerShell -profile. This method works for any version of PowerShell on any supported -platform. +### Saving environment variables with SetEnvironmentVariable -### Using System.Environment methods +On Windows, you can specify a scope for the **SetEnvironmentVariable** method as +the third parameter to set the environment variable in that scope. The machine +and user scopes both persist outside of the current process, allowing you to +save a new or changed environment variable. -The **System.Environment** class provides **GetEnvironmentVariable** and -**SetEnvironmentVariable** methods that allow you to specify the scope of the -variable. +For example, to save a new environment variable `Foo` with the value `Bar`to the +machine scope: -The following example uses the **GetEnvironmentVariable** method to get the -machine setting of `PSModulePath` and the **SetEnvironmentVariable** method -to add the `C:\Program Files\Fabrikam\Modules` path to the value. +```powershell +[Environment]::SetEnvironmentVariable('Foo', 'Bar', 'Machine') +``` + +You can delete an environment variable from the user or machine scope by setting +the variable's value to an empty string. ```powershell -$path = [Environment]::GetEnvironmentVariable('PSModulePath', 'Machine') -$newpath = $path + ';C:\Program Files\Fabrikam\Modules' -[Environment]::SetEnvironmentVariable("PSModulePath", $newpath, 'Machine') +[Environment]::SetEnvironmentVariable('Foo', '', 'Machine') ``` -For more information about the methods of the **System.Environment** class, see -[Environment Methods](/dotnet/api/system.environment). +### Saving environment variables with the System Control Panel + +In the System Control Panel, you can add or edit existing environment variables +in the **User** and **System** (Machine) scopes. Windows writes these values to +the Registry so that they persist across sessions and system restarts. + +To make a persistent change to an environment variable on Windows using the +System Control Panel: + +1. Open the System Control Panel. +1. Select **System**. +1. Select **Advanced System Settings**. +1. Go to the **Advanced** tab. +1. Select **Environment Variables...**. +1. Make your changes. ## PowerShell's environment variables @@ -270,7 +318,7 @@ The environment variables that store preferences include: command and is written on a background thread sometime after a module is imported. - Default location of the cache is: + The default location of the cache is: - Windows PowerShell 5.1: `$env:LOCALAPPDATA\Microsoft\Windows\PowerShell` - PowerShell 6.0 and higher: `$env:LOCALAPPDATA\Microsoft\PowerShell` @@ -287,11 +335,10 @@ The environment variables that store preferences include: To change the default location of the cache, set the environment variable before starting PowerShell. Changes to this environment variable only affect - child processes. The value should name a full path (including filename) - that PowerShell has permission to create and write files. + child processes. The value should name a full path (including filename) that + PowerShell has permission to create and write files. - To disable the file cache, set this value to an invalid location, for - example: + To disable the file cache, set this value to an invalid location, for example: ```powershell # `NUL` here is a special device on Windows that cannot be written to, @@ -430,6 +477,8 @@ or **NO_COLOR** environment variables. ## See also - [about_Environment_Provider](about_Environment_Provider.md) -- [about_Modules](about_Modules.md) +- [about_Profiles](about_profiles.md) +- [about_Variables](about_variables.md) +- [Environment Methods](/dotnet/api/system.environment) [xdg-bds]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html diff --git a/reference/7.3/Microsoft.PowerShell.Core/About/about_Environment_Variables.md b/reference/7.3/Microsoft.PowerShell.Core/About/about_Environment_Variables.md index 9f5b266902d8..243cc9667be1 100644 --- a/reference/7.3/Microsoft.PowerShell.Core/About/about_Environment_Variables.md +++ b/reference/7.3/Microsoft.PowerShell.Core/About/about_Environment_Variables.md @@ -1,7 +1,7 @@ --- -description: Describes how to access Windows environment variables in PowerShell. +description: Describes how to access and manage environment variables in PowerShell. Locale: en-US -ms.date: 11/15/2021 +ms.date: 03/31/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_environment_variables?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Environment Variables @@ -9,31 +9,25 @@ title: about Environment Variables # about_Environment_Variables ## Short description -Describes how to access Windows environment variables in PowerShell. +Describes how to access and manage environment variables in PowerShell. ## Long description -Environment variables store information about the operating system -environment. This information includes details such as the operating system -path, the number of processors used by the operating system, and the location -of temporary folders. - -The environment variables store data that is used by the operating system and +Environment variables store data that is used by the operating system and other programs. For example, the `WINDIR` environment variable contains the location of the Windows installation directory. Programs can query the value of this variable to determine where Windows operating system files are located. PowerShell can access and manage environment variables in any of the supported -operating system platforms. The PowerShell environment provider simplifies this -process by making it easy to view and change environment variables. +operating system platforms. The PowerShell environment provider lets you get, +add, change, clear, and delete environment variables in the current console. -Environment variables, unlike other types of variables in PowerShell, are +Environment variables, unlike other types of variables in PowerShell, are always +stored as a string and can't be empty. Also unlike other variables, they are inherited by child processes, such as local background jobs and the sessions in which module members run. This makes environment variables well suited to storing values that are needed in both parent and child processes. -## Using and changing environment variables - On Windows, environment variables can be defined in three scopes: - Machine (or System) scope @@ -43,202 +37,256 @@ On Windows, environment variables can be defined in three scopes: The _Process_ scope contains the environment variables available in the current process, or PowerShell session. This list of variables is inherited from the parent process and is constructed from the variables in the _Machine_ and -_User_ scopes. Unix-based platforms only have the _Process_ scope. +_User_ scopes. + +When you change environment variables in PowerShell, the change affects only +the current session. This behavior resembles the behavior of the `Set` command +in the Windows Command Shell and the `Setenv` command in UNIX-based +environments. To change values in the Machine or User scopes, you must use the +methods of the **System.Environment** class. + +To make changes to Machine-scoped variables, you must also have permission. If +you try to change a value without sufficient permission, the command fails and +PowerShell displays an error. + +PowerShell provides several different methods for using and managing environment +variables. + +- The variable syntax +- The Environment provider and Item cmdlets +- The .NET **System.Environment** class -You can display and change the values of environment variables without using a -cmdlet by using a variable syntax with the environment provider. To display the -value of an environment variable, use the following syntax: +## Using the variable syntax + +You can display and change the values of environment variables with the +following syntax: ``` $Env: ``` -For example, to display the value of the `WINDIR` environment variable, type -the following command at the PowerShell command prompt: +For example, to display the value of the `WINDIR` environment variable: ```powershell $Env:windir ``` +```Output +C:\Windows +``` + In this syntax, the dollar sign (`$`) indicates a variable, and the drive name (`Env:`) indicates an environment variable followed by the variable name (`windir`). -When you change environment variables in PowerShell, the change affects only -the current session. This behavior resembles the behavior of the `Set` command -in the Windows Command Shell and the `Setenv` command in UNIX-based -environments. To change values in the Machine or User scopes, you must use the -methods of the **System.Environment** class. - -To make changes to Machine-scoped variables, you must also have permission. If -you try to change a value without sufficient permission, the command fails and -PowerShell displays an error. - -You can change the values of variables without using a cmdlet using the -following syntax: +You can create and update the value of environment variables with the following +syntax: ```powershell $Env: = "" ``` -For example, to append `;c:\temp` to the value of the `Path` environment -variable, use the following syntax: +For example, to create the `Foo` environment variable: ```powershell -$Env:Path += ";c:\temp" +$Env:Foo = 'An example' ``` -On Linux or macOS, the colon (`:`) in the command separates the new path from -the path that precedes it in the list. +Because environment variables are always strings, you can use them like any +other variable containing a string. For example: ```powershell -$Env:PATH += ":/usr/local/temp" +"The 'Foo' environment variable is set to: $Env:Foo" +$Env:Foo += '!' +$Env:Foo ``` -You can also use the Item cmdlets, such as `Set-Item`, `Remove-Item`, and -`Copy-Item` to change the values of environment variables. For example, to use -the `Set-Item` cmdlet to append `;c:\temp` to the value of the `Path` -environment variable, use the following syntax: +```Output +The 'Foo' environment variable is set to: An example -```powershell -Remove-Item -Path Env:Path +An example! ``` -In this command, the variable is cleared. Note that the environment -variable is referenced as an Item path and `$` is not used. +Because an environment variable can't be an empty string, setting one to `$null` +or an empty string removes it. For example: ```powershell -Set-Item -Path Env:Path -Value ($Env:Path + ";C:\Temp") +$Env:Foo = '' +$Env:Foo | Get-Member -MemberType Properties ``` -In this command, the value is enclosed in parentheses so that it is -interpreted as a unit. +```Output +Get-Member : You must specify an object for the Get-Member cmdlet. +At line:1 char:12 ++ $env:foo | Get-Member ++ ~~~~~~~~~~ + + CategoryInfo : CloseError: (:) [Get-Member], InvalidOperationException + + FullyQualifiedErrorId : NoObjectInGetMember,Microsoft.PowerShell.Commands.GetMemberCommand +``` -## Managing environment variables +`Get-Member` returned an error because the environment variable was removed. You +can see that it does not return an error when you use it on an empty string: -PowerShell provides several different methods for managing environment -variables. +```powershell +'' | Get-Member -MemberType Properties +``` -- The Environment provider drive -- The Item cmdlets -- The .NET **System.Environment** class -- On Windows, the System Control Panel +```Output + TypeName: System.String -### Using the Environment provider +Name MemberType Definition +---- ---------- ---------- +Length Property int Length {get;} +``` -Each environment variable is represented by an instance of the -**System.Collections.DictionaryEntry** class. In each **DictionaryEntry** -object, the name of the environment variable is the dictionary key. The value -of the variable is the dictionary value. +For more information about variables in PowerShell, see +[about_Variables](about_variables.md). -To display the properties and methods of the object that represents an -environment variable in PowerShell, use the `Get-Member` cmdlet. For example, -to display the methods and properties of all the objects in the `Env:` drive, -type: +## Using the Environment provider and Item cmdlets -```powershell -Get-Item -Path Env:* | Get-Member -``` +PowerShell's **Environment** provider gives you an interface for interacting +with environment variables in a format that resembles a file system drive. It +lets you get, add, change, clear, and delete environment variables and values in +PowerShell. -The PowerShell Environment provider lets you access environment variables in a -PowerShell drive (the `Env:` drive). This drive looks much like a file system -drive. To go to the `Env:` drive, type: +For example, to create the `Foo` environment variable with a value of `Bar`: ```powershell -Set-Location Env: +New-Item -Path Env:\Foo -Value 'Bar' ``` -Use the Content cmdlets to get or set the values of an environment variable. +```Output +Name Value +---- ----- +Foo Bar +``` + +You can also copy the environment variable with `Copy-Item`, set the value of an +environment variable with `Set-Item`, list environment variables with +`Get-Item`, and delete the environment variable with `Remove-Item`. ```powershell -PS Env:\> Set-Content -Path Test -Value 'Test value' -PS Env:\> Get-Content -Path Test -Test value +Copy-Item -Path Env:\Foo -Destination Env:\Foo2 -PassThru +Set-Item -Path Env:\Foo2 -Value 'BAR' +Get-Item -Path Env:\Foo* +Remove-Item -Path Env:\Foo* -Verbose ``` -You can view the environment variables in the `Env:` drive from any other -PowerShell drive, and you can go into the `Env:` drive to view and change the -environment variables. +```Output +Name Value +---- ----- +Foo2 Bar -### Using Item cmdlets +Name Value +---- ----- +Foo2 BAR +Foo Bar -When you refer to an environment variable, type the `Env:` drive name followed -by the name of the variable. For example, to display the value of the -`COMPUTERNAME` environment variable, type: - -```powershell -Get-ChildItem Env:Computername +VERBOSE: Performing the operation "Remove Item" on target "Item: Foo2". +VERBOSE: Performing the operation "Remove Item" on target "Item: Foo". ``` -To display the values of all the environment variables, type: +For more information on using the **Environment** provider to manage environment +variables, see [about_Environment_Provider](about_Environment_Provider.md). -```powershell -Get-ChildItem Env: -``` +## Using the System.Environment methods -Because environment variables do not have child items, the output of `Get-Item` -and `Get-ChildItem` is the same. +The **System.Environment** class provides the **GetEnvironmentVariable** and +**SetEnvironmentVariable** methods to get and modify environment variables. -By default, PowerShell displays the environment variables in the order in which -it retrieves them. To sort the list of environment variables by variable name, -pipe the output of a `Get-ChildItem` command to the `Sort-Object` cmdlet. For -example, from any PowerShell drive, type: +The following example creates a new environment variable, `Foo`, with a value of +`Bar` and then returns its value. ```powershell -Get-ChildItem Env: | Sort Name +[Environment]::SetEnvironmentVariable('Foo','Bar') +[Environment]::GetEnvironmentVariable('Foo') +``` + +```Output +Bar ``` -You can also go into the `Env:` drive by using the `Set-Location` cmdlet: +You can remove an environment variable with the **SetEnvironmentVariable** +method by specifying an empty string for the variable's value. For example, +to remove the `Foo` environment variable: ```powershell -Set-Location Env: +[Environment]::SetEnvironmentVariable('Foo','') +[Environment]::GetEnvironmentVariable('Foo') ``` -When you are in the `Env:` drive, you can omit the `Env:` drive name from the -path. For example, to display all the environment variables, type: +```Output -```powershell -PS Env:\> Get-ChildItem ``` -To display the value of the `COMPUTERNAME` variable from within the `Env:` -drive, type: +For more information about the methods of the **System.Environment** class, see +[Environment Methods](/dotnet/api/system.environment). + +## Saving changes to environment variables + +On Windows, there are three methods for making a persistent change to an +environment variable: setting them in your profile, using the +**SetEnvironmentVariable** method, and using the System Control Panel. + +### Saving environment variables in your profile + +Any environment variable you add or change in your PowerShell profile is +available in any session that loads your profile. This method works for any +version of PowerShell on any supported platform. + +For example, to create the `CompanyUri` environment variable and update the +`Path` environment variable to include the `C:\Tools` folder, add the following +lines to your PowerShell profile: ```powershell -PS Env:\> Get-ChildItem ComputerName +$Env:CompanyUri = 'https://internal.contoso.com' +$Env:Path += ';C:\Tools' ``` -### Saving changes to environment variables +> [!NOTE] +> On Linux or macOS, the colon (`:`) is used instead of a semi-colon(`;`) to +> separate a new path from the path that precedes it in the list. -To make a persistent change to an environment variable on Windows, use the -System Control Panel. Select **Advanced System Settings**. On the **Advanced** -tab, click **Environment Variable...**. You can add or edit existing -environment variables in the **User** and **System** (Machine) scopes. Windows -writes these values to the Registry so that they persist across sessions and -system restarts. +You can get the path to your PowerShell profile with the `$PROFILE` automatic +variable. For more information on profiles, see +[about_Profiles](about_profiles.md). -Alternately, you can add or change environment variables in your PowerShell -profile. This method works for any version of PowerShell on any supported -platform. +### Saving environment variables with SetEnvironmentVariable -### Using System.Environment methods +On Windows, you can specify a scope for the **SetEnvironmentVariable** method as +the third parameter to set the environment variable in that scope. The machine +and user scopes both persist outside of the current process, allowing you to +save a new or changed environment variable. -The **System.Environment** class provides **GetEnvironmentVariable** and -**SetEnvironmentVariable** methods that allow you to specify the scope of the -variable. +For example, to save a new environment variable `Foo` with the value `Bar`to the +machine scope: -The following example uses the **GetEnvironmentVariable** method to get the -machine setting of `PSModulePath` and the **SetEnvironmentVariable** method -to add the `C:\Program Files\Fabrikam\Modules` path to the value. +```powershell +[Environment]::SetEnvironmentVariable('Foo', 'Bar', 'Machine') +``` + +You can delete an environment variable from the user or machine scope by setting +the variable's value to an empty string. ```powershell -$path = [Environment]::GetEnvironmentVariable('PSModulePath', 'Machine') -$newpath = $path + ';C:\Program Files\Fabrikam\Modules' -[Environment]::SetEnvironmentVariable("PSModulePath", $newpath, 'Machine') +[Environment]::SetEnvironmentVariable('Foo', '', 'Machine') ``` -For more information about the methods of the **System.Environment** class, see -[Environment Methods](/dotnet/api/system.environment). +### Saving environment variables with the System Control Panel + +In the System Control Panel, you can add or edit existing environment variables +in the **User** and **System** (Machine) scopes. Windows writes these values to +the Registry so that they persist across sessions and system restarts. + +To make a persistent change to an environment variable on Windows using the +System Control Panel: + +1. Open the System Control Panel. +1. Select **System**. +1. Select **Advanced System Settings**. +1. Go to the **Advanced** tab. +1. Select **Environment Variables...**. +1. Make your changes. ## PowerShell's environment variables @@ -270,7 +318,7 @@ The environment variables that store preferences include: command and is written on a background thread sometime after a module is imported. - Default location of the cache is: + The default location of the cache is: - Windows PowerShell 5.1: `$env:LOCALAPPDATA\Microsoft\Windows\PowerShell` - PowerShell 6.0 and higher: `$env:LOCALAPPDATA\Microsoft\PowerShell` @@ -287,11 +335,10 @@ The environment variables that store preferences include: To change the default location of the cache, set the environment variable before starting PowerShell. Changes to this environment variable only affect - child processes. The value should name a full path (including filename) - that PowerShell has permission to create and write files. + child processes. The value should name a full path (including filename) that + PowerShell has permission to create and write files. - To disable the file cache, set this value to an invalid location, for - example: + To disable the file cache, set this value to an invalid location, for example: ```powershell # `NUL` here is a special device on Windows that cannot be written to, @@ -430,6 +477,8 @@ or **NO_COLOR** environment variables. ## See also - [about_Environment_Provider](about_Environment_Provider.md) -- [about_Modules](about_Modules.md) +- [about_Profiles](about_profiles.md) +- [about_Variables](about_variables.md) +- [Environment Methods](/dotnet/api/system.environment) [xdg-bds]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html From f65cd6857b4c8f7062f94c82e4fb146736f31b64 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Fri, 1 Apr 2022 14:36:47 -0500 Subject: [PATCH 02/31] - Update monthly stats and What's New - Added end-of-file markers to release notes (#8711) * - Update monthly stats and What's New - Added end-of-file markers to release notes * Apply suggestions from code review Co-authored-by: Michael T Lombardi (He/Him) Co-authored-by: Michael T Lombardi (He/Him) --- .../docs-conceptual/community/2022-updates.md | 68 ++++++++++++++++++- .../docs-conceptual/community/hall-of-fame.md | 46 +++++++------ .../whats-new/What-s-New-in-PowerShell-70.md | 2 + .../whats-new/What-s-New-in-PowerShell-71.md | 2 + .../whats-new/What-s-New-in-PowerShell-72.md | 1 + .../whats-new/What-s-New-in-PowerShell-73.md | 1 + .../What-s-New-in-Windows-PowerShell-50.md | 1 + 7 files changed, 97 insertions(+), 24 deletions(-) diff --git a/reference/docs-conceptual/community/2022-updates.md b/reference/docs-conceptual/community/2022-updates.md index 662de3b2cd93..0d96959d7b7f 100644 --- a/reference/docs-conceptual/community/2022-updates.md +++ b/reference/docs-conceptual/community/2022-updates.md @@ -1,6 +1,6 @@ --- description: List of changes to the PowerShell documentation for 2022 -ms.date: 03/02/2022 +ms.date: 04/01/2022 title: What's New in PowerShell-Docs for 2022 --- # What's new in PowerShell Docs for 2022 @@ -11,11 +11,75 @@ contributions from the community. Help us make the documentation better for you. Read the [Contributor's Guide][contrib] to learn how to get started. +## 2022-March + +New Content + +- New PowerShell docs + - [about_Member-Access_Enumeration](/powershell/module/microsoft.powershell.core/about/about_member-access_enumeration) + - [about_Module_Manifests](/powershell/module/microsoft.powershell.core/about/about_module_manifests) + - [How to create a command-line predictor](/powershell/scripting/dev-cross-plat/create-cmdline-predictor) +- Utility modules updates + - New docs for Crescendo release + - [Install Crescendo](/powershell/utility-modules/crescendo/get-started/install-crescendo) + - [Choose a command-line tool](/powershell/utility-modules/crescendo/get-started/choose-command-line-tool) + - [Decide which features to amplify](/powershell/utility-modules/crescendo/get-started/research-tool) + - [Create a Crescendo cmdlet](/powershell/utility-modules/crescendo/get-started/create-new-cmdlet) + - [Generate and test a Crescendo module](/powershell/utility-modules/crescendo/get-started/generate-module) + - We have plans for at least two more documents + - Moved PlatyPS article from PowerShell docs to the PlatyPS documentation + - [Moved PlatyPS article](/powershell/utility-modules/platyps/create-help-using-platyps) + - Migrated more PSScriptAnalyzer documentation from the source code repository + - [Using PSScriptAnalyzer](/powershell/utility-modules/psscriptanalyzer/using-scriptanalyzer) + - [Rules and recommendations](/powershell/utility-modules/psscriptanalyzer/rules-recommendations) + - [Creating custom rules](/powershell/utility-modules/psscriptanalyzer/create-custom-rule) + +Content updates + +- Bulk cleanup of related links in About_ topics +- Added issue and PR templates to all docs repos +- Updates for 7.3 preview content + - New tab completions + - Support for SSH options on remoting cmdlets + - New experimental feature `PSAMSIMethodInvocationLogging` + +Other projects + +- Created a prototype cmdlet `Get-WhatsNew` based on the + [draft RFC](https://github.com/PowerShell/PowerShell-RFC/pull/317) + - Check out the RFC and provide feedback + +New team member + +- Welcome [Mikey Lombardi](https://github.com/michaeltlombardi) to the docs team + +### Top Community Contributors + +GitHub stats + +- 49 PRs merged (8 from Community) +- 26 issues opened (14 from Community) +- 33 issues closed (18 Community issues closed) + +The following people have contributed to PowerShell docs by submitting pull requests or filing +issues. Thank you! + +| GitHub Id | PRs merged | Issues opened | +| -------------- | :--------: | :-----------: | +| AspenForester | 1 | | +| codaamok | 1 | | +| DianaKuzmenko | 1 | | +| MikeyBronowski | 1 | | +| poshdude | 1 | | +| robcmo | 1 | | +| sertdfyguhi | 1 | | +| stampycode | 1 | | + ## 2022-February New Content -- [about_Calling_Generic_Methods](/powershell/module/microsoft.powershell.core/about/about_calling_generic_methods?view=powershell-7.3&preserve-view=true) +- [about_Calling_Generic_Methods](/powershell/module/microsoft.powershell.core/about/about_calling_generic_methods&preserve-view=true) Content updates diff --git a/reference/docs-conceptual/community/hall-of-fame.md b/reference/docs-conceptual/community/hall-of-fame.md index 8be6c810934a..8e9c2dc79e13 100644 --- a/reference/docs-conceptual/community/hall-of-fame.md +++ b/reference/docs-conceptual/community/hall-of-fame.md @@ -1,6 +1,6 @@ --- description: List of the GitHub users that have the most contributions to the PowerShell-Doc project. -ms.date: 03/02/2022 +ms.date: 04/01/2022 title: Community contributor Hall of Fame --- # Community Contributor Hall of Fame @@ -9,15 +9,15 @@ The PowerShell Community is a vibrant and collaborative group. We greatly apprec and support we get from the community. Learn how you can contribute by reading the [Contributor's Guide][contrib]. -As of the end of February 2022, these GitHub users are the All-Time Top Community Contributors. +As of the end of March 2022, these GitHub users are the All-Time Top Community Contributors. -## Pull Requests opened +## Pull Requests merged Pull Requests help us fix those issues and make the documentation better for everyone. -| Docs PRs Merged | 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | Grand Total | +| PRs Merged | 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | Grand Total | | --------------- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ----------: | -| Community | 3 | 194 | 446 | 464 | 318 | 161 | 100 | 13 | 1699 | +| Community | 3 | 194 | 446 | 464 | 318 | 161 | 100 | 21 | 1707 | | matt9ucci | | | 157 | 80 | 30 | 1 | 6 | | 274 | | nschonni | | | | 14 | 138 | 10 | | | 162 | | kiazhi | | 25 | 79 | 12 | | | | | 116 | @@ -34,28 +34,30 @@ Pull Requests help us fix those issues and make the documentation better for eve | skycommand | | | 1 | 3 | 3 | 6 | | | 13 | | purdo17 | | | | 13 | | | | | 13 | | k-takai | | | | 5 | 1 | 7 | | | 13 | -| PlagueHO | | 10 | | | 1 | | | | 11 | | exchange12rocks | | | 7 | 3 | | | 1 | | 11 | +| PlagueHO | | 10 | | | 1 | | | | 11 | + ## GitHub issues opened GitHub issues help us identify errors and gaps in our documentation. -| Docs Issues Opened | 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | Grand Total | -| ------------------ | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ----------: | -| Community | 3 | 54 | 95 | 212 | 559 | 561 | 333 | 12 | 1829 | -| mklement0 | | | 19 | 60 | 56 | 61 | 27 | | 223 | -| iSazonov | | | 1 | 4 | 10 | 8 | 3 | | 26 | -| jszabo98 | | | | 2 | 15 | 6 | 1 | | 24 | -| juvtib | | | | | | 15 | 7 | | 22 | -| doctordns | | | 5 | 3 | 5 | 6 | 1 | | 20 | -| vexx32 | | | | 3 | 11 | | | 1 | 15 | -| alexandair | | 9 | 4 | 2 | | | | | 15 | -| clamb123 | | | | | | | 14 | | 14 | -| KirkMunro | | | | 7 | 5 | 1 | | | 13 | -| trollyanov | | | | | | | 11 | | 11 | -| JustinGrote | | | | 1 | 3 | 6 | 1 | | 11 | -| vors | 1 | 6 | 2 | 1 | | | | | 10 | -| rkeithhill | | | 1 | 2 | 2 | 2 | 3 | | 10 | +| Issues Opened | 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | Grand Total | +| ------------- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ----------: | +| Community | 3 | 54 | 95 | 212 | 566 | 563 | 368 | 59 | 1920 | +| mklement0 | | | 19 | 60 | 56 | 61 | 28 | | 224 | +| iSazonov | | | 1 | 4 | 10 | 8 | 4 | | 27 | +| jszabo98 | | | | 2 | 15 | 6 | 1 | | 24 | +| juvtib | | | | | | 15 | 7 | | 22 | +| doctordns | | | 5 | 3 | 5 | 7 | 1 | | 21 | +| vexx32 | | | | 3 | 11 | | | 1 | 15 | +| KirkMunro | | | | 7 | 7 | 1 | | | 15 | +| alexandair | | 9 | 4 | 2 | | | | | 15 | +| clamb123 | | | | | | | 14 | | 14 | +| trollyanov | | | | | | | 11 | | 11 | +| rkeithhill | | | 1 | 2 | 2 | 2 | 3 | 1 | 11 | +| JustinGrote | | | | 1 | 3 | 6 | 1 | | 11 | +| vors | 1 | 6 | 2 | 1 | | | | | 10 | +| UberKluger | | | | | | 1 | 7 | 2 | 10 | [contrib]: contributing/overview.md diff --git a/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-70.md b/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-70.md index 32d7b562c1f7..d33fe54209ff 100644 --- a/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-70.md +++ b/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-70.md @@ -726,3 +726,5 @@ For more information about - Fix a typo in README.md (#10465) (Thanks @vedhasp!) - Add a reference to PSKoans module to Learning Resources documentation (#10369) (Thanks @vexx32!) - Update README.md and metadata.json for 7.0.0-preview.3 (#10393) + + diff --git a/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-71.md b/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-71.md index 7a3c8ab4c2d1..3a8067227106 100644 --- a/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-71.md +++ b/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-71.md @@ -214,3 +214,5 @@ The following experimental features were added in this release: work with in C# code. After this change, the returned object is the underlying object. + + diff --git a/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-72.md b/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-72.md index 085b372b51e8..4a13136db916 100644 --- a/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-72.md +++ b/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-72.md @@ -146,6 +146,7 @@ Install-Module -Name PSDesiredStateConfiguration -Repository PSGallery -MaximumV - Change `FileSystemInfo.Target` from a **CodeProperty** to an **AliasProperty** that points to `FileSystemInfo.LinkTarget` (#16165) + [announced]: https://devblogs.microsoft.com/powershell/announcing-powershell-7-2/ diff --git a/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-73.md b/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-73.md index fad25f209dac..4aa23393292b 100644 --- a/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-73.md +++ b/reference/docs-conceptual/whats-new/What-s-New-in-PowerShell-73.md @@ -81,6 +81,7 @@ For more information about the Experimental Features, see [Using Experimental Fe resource cleanup (#15177) - Change default for `$PSStyle.OutputRendering` to **Ansi** + [CHANGELOG]: https://github.com/PowerShell/PowerShell/releases/tag/v7.3.0-preview.2 diff --git a/reference/docs-conceptual/windows-powershell/whats-new/What-s-New-in-Windows-PowerShell-50.md b/reference/docs-conceptual/windows-powershell/whats-new/What-s-New-in-Windows-PowerShell-50.md index ccca8352fd21..a374e3e00f6c 100644 --- a/reference/docs-conceptual/windows-powershell/whats-new/What-s-New-in-Windows-PowerShell-50.md +++ b/reference/docs-conceptual/windows-powershell/whats-new/What-s-New-in-Windows-PowerShell-50.md @@ -1060,5 +1060,6 @@ cmdlets. The parser also includes special logic to improve handling of the backt - [about_Windows_PowerShell_5.0](/previous-versions/powershell/module/microsoft.powershell.core/about/about_windows_powershell_5.0) - [Windows PowerShell](/powershell/) + [KB 3000850]: https://support.microsoft.com/topic/november-2014-update-rollup-for-windows-rt-8-1-windows-8-1-and-windows-server-2012-r2-7be5865b-adaa-dbbf-e2d4-1f819e7c9d87 From 5bda02b780b45af43ac5dca7e641f123d7e6586a Mon Sep 17 00:00:00 2001 From: "Michael T Lombardi (He/Him)" Date: Fri, 1 Apr 2022 16:02:31 -0500 Subject: [PATCH 03/31] (MAINT) Add GHA to check if author can target live (#8712) This commit adds a new GitHub Action workflow to validate that the author of a PR can target the `live` branch. It runs whenever a PR targeting the `live` branch is opened, reopened, or synchronized (new commits are pushed or the branch is forcibly updated). It checks the collaborators of the repository for the PR author to see if they have permissions as a maintainer or administrator; no other users are authorized to target changes at the `live` branch. If the author does not have the correct permissions, the check fails. With the branch protections for the repository set to require this check when targeting `live`, this will prevent unauthorized collaborators from accidentally trying to merge their changes to the live site instead of the working branch. --- .github/workflows/targeting-valid-branch.yml | 44 ++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 .github/workflows/targeting-valid-branch.yml diff --git a/.github/workflows/targeting-valid-branch.yml b/.github/workflows/targeting-valid-branch.yml new file mode 100644 index 000000000000..2c61f3840757 --- /dev/null +++ b/.github/workflows/targeting-valid-branch.yml @@ -0,0 +1,44 @@ +name: Targeting Valid Branch +on: + pull_request_target: + types: + - opened + - reopened + - synchronize +jobs: + Test: + runs-on: windows-latest + defaults: + run: + shell: pwsh + if: github.base_ref == 'live' + steps: + - name: Authorized to Target Live Branch + env: + GITHUB_TOKEN: ${{ github.token }} + run: | + $Query = @' + query author_collaborator_permission($owner: String!, $repo: String!, $actor: String!) { + repository(owner: $owner, name: $repo) { + collaborators(query: $actor) { + edges { + permission + } + } + } + } + '@ + $ApiParameters = @( + 'api', 'graphql' + '-F', "owner=${{ github.event.pull_request.base.repo.owner.login}}" + '-F', "repo=${{ github.event.pull_request.base.repo.name }}" + '-F', "actor=${{ github.event.pull_request.user.login }}" + '-f', "query=$Query" + '--jq', '.data.repository.collaborators.edges[].permission' + ) + [string[]]$Permissions = gh @ApiParameters + if ($Permissions -notcontains 'MAINTAIN' -and $Permissions -notcontains 'ADMIN') { + throw "Author does not have permissions to target ${{ github.base_ref }}" + } else { + echo "Author has permissions to target ${{ github.base_ref }}" + } From f9c269f8b80aed0ef5ba7ca347e400c7f1644874 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Mon, 4 Apr 2022 14:01:02 -0500 Subject: [PATCH 04/31] Fixes #8716 - Explain the effect of runspaces on script methods and properties (#8715) * Explain the effect of runspaces on script methods and properties * Apply suggestions from code review Co-authored-by: Michael T Lombardi (He/Him) * Feedback edits Co-authored-by: Michael T Lombardi (He/Him) --- .../ForEach-Object.md | 68 +++++++---- .../ForEach-Object.md | 72 +++++++----- .../ForEach-Object.md | 109 +++++++++++++----- .../ForEach-Object.md | 109 +++++++++++++----- 4 files changed, 254 insertions(+), 104 deletions(-) diff --git a/reference/7.0/Microsoft.PowerShell.Core/ForEach-Object.md b/reference/7.0/Microsoft.PowerShell.Core/ForEach-Object.md index 9b5464cb92a6..c92d5de1dc29 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/ForEach-Object.md +++ b/reference/7.0/Microsoft.PowerShell.Core/ForEach-Object.md @@ -2,7 +2,7 @@ external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core -ms.date: 07/27/2021 +ms.date: 04/04/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/foreach-object?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: ForEach-Object @@ -81,19 +81,7 @@ command. By default, the parallel scriptblocks use the current working directory of the caller that started the parallel tasks. - Non-terminating errors are written to the cmdlet error stream as they occur in parallel running - scriptblocks. Because parallel scriptblock execution order cannot be determined, the order in - which errors appear in the error stream is random. Likewise, messages written to other data - streams, like warning, verbose, or information are written to those data streams in an - indeterminate order. - - Terminating errors, such as exceptions, terminate the individual parallel instance of the - scriptblocks in which they occur. A terminating error in one scriptblocks may not cause the - termination of the `Foreach-Object` cmdlet. The other scriptblocks, running in parallel, continue - to run unless they also encounter a terminating error. The terminating error is written to the - error data stream as an **ErrorRecord** with a **FullyQualifiedErrorId** of `PSTaskException`. - Terminating errors can be converted to non-terminating errors using PowerShell try/catch or trap - blocks. + For more information, see the [NOTES](#notes) section of this article. ## EXAMPLES @@ -444,6 +432,10 @@ Output: 5 `Output: 3` is never written because the parallel scriptblock for that iteration was terminated. +> [!NOTE] +> [PipelineVariable](About/about_CommonParameters.md) common parameter variables are _not_ +> supported in `Foreach-Object -Parallel` scenarios even with the `$using:` keyword. + ### Example 17: Passing variables in nested parallel script ScriptBlockSet You can create a variable outside a `Foreach-Object -Parallel` scoped scriptblock and use @@ -765,17 +757,19 @@ This cmdlet returns objects that are determined by the input. ## NOTES -- The `ForEach-Object` cmdlet works much like the **Foreach** statement, except that you cannot pipe - input to a **Foreach** statement. For more information about the **Foreach** statement, see - [about_Foreach](./About/about_Foreach.md). +The `ForEach-Object` cmdlet works much like the **Foreach** statement, except that you cannot pipe +input to a **Foreach** statement. For more information about the **Foreach** statement, see +[about_Foreach](./About/about_Foreach.md). + +Starting in PowerShell 4.0, `Where` and `ForEach` methods were added for use with collections. You +can read more about these new methods here [about_arrays](./About/about_Arrays.md) -- Starting in PowerShell 4.0, `Where` and `ForEach` methods were added for use with collections. You - can read more about these new methods here [about_arrays](./About/about_Arrays.md) +Using `ForEach-Object -Parallel`: - The `ForEach-Object -Parallel` parameter set uses PowerShell's internal API to run each script - block. This is significantly more overhead than running `ForEach-Object` normally with sequential - processing. It is important to use **Parallel** where the overhead of running in parallel is small - compared to work the script block performs. For example: + block in a new runspace. This is significantly more overhead than running `ForEach-Object` + normally with sequential processing. It is important to use **Parallel** where the overhead of + running in parallel is small compared to work the script block performs. For example: - Compute intensive scripts on multi-core machines - Scripts that spend time waiting for results or doing file operations @@ -784,8 +778,34 @@ This cmdlet returns objects that are determined by the input. the parallel scripts are trivial. Experiment with **Parallel** to discover where it can be beneficial. +- When running in parallel, objects decorated with **ScriptProperties** or **ScriptMethods** cannot + be guaranteed to function correctly if they are run in a different runspace than the scripts were + originally attached to them. + + Scriptblock invocation always attempts to run in its _home_ runspace, regardless of where it's + actually invoked. However, `ForEach-Object -Parallel` creates temporary runspaces that get deleted + after use, so there's no runspace for the scripts to execute in anymore. + + This behavior can work as long as the _home_ runspace still exists. However, you may not get + the desired result if the script is dependent on external variables that are only present in the + caller's runspace and not the _home_ runspace. + +- Non-terminating errors are written to the cmdlet error stream as they occur in parallel running + scriptblocks. Because parallel scriptblock execution order is non-deterministic, the order in + which errors appear in the error stream is random. Likewise, messages written to other data + streams, like warning, verbose, or information are written to those data streams in an + indeterminate order. + + Terminating errors, such as exceptions, terminate the individual parallel instance of the + scriptblocks in which they occur. A terminating error in one scriptblocks may not cause the + termination of the `Foreach-Object` cmdlet. The other scriptblocks, running in parallel, continue + to run unless they also encounter a terminating error. The terminating error is written to the + error data stream as an **ErrorRecord** with a **FullyQualifiedErrorId** of `PSTaskException`. + Terminating errors can be converted to non-terminating errors using PowerShell try/catch or trap + blocks. + - [PipelineVariable](About/about_CommonParameters.md) common parameter variables are _not_ supported - in `Foreach-Object -Parallel` scenarios even with the `$using:` keyword. + in parallel scenarios even with the `$using:` keyword. > [!IMPORTANT] > The `ForEach-Object -Parallel` parameter set runs script blocks in parallel on separate process @@ -793,7 +813,7 @@ This cmdlet returns objects that are determined by the input. > thread to each running script block thread. Since the script blocks run in different threads, > the object variables passed by reference must be used safely. Generally it is safe to read from > referenced objects that don't change. But if the object state is being modified then you must - > used thread safe objects, such as .Net **System.Collection.Concurrent** types (See Example 11). + > used thread safe objects, such as .NET **System.Collection.Concurrent** types (See Example 11). ## RELATED LINKS diff --git a/reference/7.1/Microsoft.PowerShell.Core/ForEach-Object.md b/reference/7.1/Microsoft.PowerShell.Core/ForEach-Object.md index c944c343efdf..57b02c00b006 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/ForEach-Object.md +++ b/reference/7.1/Microsoft.PowerShell.Core/ForEach-Object.md @@ -2,7 +2,7 @@ external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core -ms.date: 07/27/2021 +ms.date: 04/04/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/foreach-object?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: ForEach-Object @@ -31,8 +31,8 @@ ForEach-Object [-InputObject ] [-MemberName] [-ArgumentList < ### ParallelParameterSet ``` -ForEach-Object -Parallel [-InputObject ] [-ThrottleLimit ] - [-UseNewRunspace] [-TimeoutSeconds ] [-AsJob] [-WhatIf] [-Confirm] [] +ForEach-Object [-InputObject ] -Parallel [-ThrottleLimit ] + [-TimeoutSeconds ] [-AsJob] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION @@ -84,19 +84,7 @@ command. By default, the parallel scriptblocks use the current working directory of the caller that started the parallel tasks. - Non-terminating errors are written to the cmdlet error stream as they occur in parallel running - scriptblocks. Because parallel scriptblock execution order cannot be determined, the order in - which errors appear in the error stream is random. Likewise, messages written to other data - streams, like warning, verbose, or information are written to those data streams in an - indeterminate order. - - Terminating errors, such as exceptions, terminate the individual parallel instance of the - scriptblocks in which they occur. A terminating error in one scriptblocks may not cause the - termination of the `Foreach-Object` cmdlet. The other scriptblocks, running in parallel, continue - to run unless they also encounter a terminating error. The terminating error is written to the - error data stream as an **ErrorRecord** with a **FullyQualifiedErrorId** of `PSTaskException`. - Terminating errors can be converted to non-terminating errors using PowerShell try/catch or trap - blocks. + For more information, see the [NOTES](#notes) section of this article. ## EXAMPLES @@ -447,6 +435,10 @@ Output: 5 `Output: 3` is never written because the parallel scriptblock for that iteration was terminated. +> [!NOTE] +> [PipelineVariable](About/about_CommonParameters.md) common parameter variables are _not_ +> supported in `Foreach-Object -Parallel` scenarios even with the `$using:` keyword. + ### Example 17: Passing variables in nested parallel script ScriptBlockSet You can create a variable outside a `Foreach-Object -Parallel` scoped scriptblock and use @@ -787,17 +779,19 @@ This cmdlet returns objects that are determined by the input. ## NOTES -- The `ForEach-Object` cmdlet works much like the **Foreach** statement, except that you cannot pipe - input to a **Foreach** statement. For more information about the **Foreach** statement, see - [about_Foreach](./About/about_Foreach.md). +The `ForEach-Object` cmdlet works much like the **Foreach** statement, except that you cannot pipe +input to a **Foreach** statement. For more information about the **Foreach** statement, see +[about_Foreach](./About/about_Foreach.md). + +Starting in PowerShell 4.0, `Where` and `ForEach` methods were added for use with collections. You +can read more about these new methods here [about_arrays](./About/about_Arrays.md) -- Starting in PowerShell 4.0, `Where` and `ForEach` methods were added for use with collections. You - can read more about these new methods here [about_arrays](./About/about_Arrays.md) +Using `ForEach-Object -Parallel`: - The `ForEach-Object -Parallel` parameter set uses PowerShell's internal API to run each script - block. This is significantly more overhead than running `ForEach-Object` normally with sequential - processing. It is important to use **Parallel** where the overhead of running in parallel is small - compared to work the script block performs. For example: + block in a new runspace. This is significantly more overhead than running `ForEach-Object` + normally with sequential processing. It is important to use **Parallel** where the overhead of + running in parallel is small compared to work the script block performs. For example: - Compute intensive scripts on multi-core machines - Scripts that spend time waiting for results or doing file operations @@ -806,8 +800,34 @@ This cmdlet returns objects that are determined by the input. the parallel scripts are trivial. Experiment with **Parallel** to discover where it can be beneficial. +- When running in parallel, objects decorated with **ScriptProperties** or **ScriptMethods** cannot + be guaranteed to function correctly if they are run in a different runspace than the scripts were + originally attached to them. + + Scriptblock invocation always attempts to run in its _home_ runspace, regardless of where it's + actually invoked. However, `ForEach-Object -Parallel` creates temporary runspaces that get deleted + after use, so there's no runspace for the scripts to execute in anymore. + + This behavior can work as long as the _home_ runspace still exists. However, you may not get + the desired result if the script is dependent on external variables that are only present in the + caller's runspace and not the _home_ runspace. + +- Non-terminating errors are written to the cmdlet error stream as they occur in parallel running + scriptblocks. Because parallel scriptblock execution order is non-deterministic, the order in + which errors appear in the error stream is random. Likewise, messages written to other data + streams, like warning, verbose, or information are written to those data streams in an + indeterminate order. + + Terminating errors, such as exceptions, terminate the individual parallel instance of the + scriptblocks in which they occur. A terminating error in one scriptblocks may not cause the + termination of the `Foreach-Object` cmdlet. The other scriptblocks, running in parallel, continue + to run unless they also encounter a terminating error. The terminating error is written to the + error data stream as an **ErrorRecord** with a **FullyQualifiedErrorId** of `PSTaskException`. + Terminating errors can be converted to non-terminating errors using PowerShell try/catch or trap + blocks. + - [PipelineVariable](About/about_CommonParameters.md) common parameter variables are _not_ supported - in `Foreach-Object -Parallel` scenarios even with the `$using:` keyword. + in parallel scenarios even with the `$using:` keyword. > [!IMPORTANT] > The `ForEach-Object -Parallel` parameter set runs script blocks in parallel on separate process @@ -815,7 +835,7 @@ This cmdlet returns objects that are determined by the input. > thread to each running script block thread. Since the script blocks run in different threads, > the object variables passed by reference must be used safely. Generally it is safe to read from > referenced objects that don't change. But if the object state is being modified then you must - > used thread safe objects, such as .Net **System.Collection.Concurrent** types (See Example 11). + > used thread safe objects, such as .NET **System.Collection.Concurrent** types (See Example 11). ## RELATED LINKS diff --git a/reference/7.2/Microsoft.PowerShell.Core/ForEach-Object.md b/reference/7.2/Microsoft.PowerShell.Core/ForEach-Object.md index 764885af9179..2d9af09053c4 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/ForEach-Object.md +++ b/reference/7.2/Microsoft.PowerShell.Core/ForEach-Object.md @@ -2,7 +2,7 @@ external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core -ms.date: 07/27/2021 +ms.date: 04/04/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/foreach-object?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: ForEach-Object @@ -31,8 +31,8 @@ ForEach-Object [-InputObject ] [-MemberName] [-ArgumentList < ### ParallelParameterSet ``` -ForEach-Object -Parallel [-InputObject ] [-ThrottleLimit ] - [-UseNewRunspace] [-TimeoutSeconds ] [-AsJob] [-WhatIf] [-Confirm] [] +ForEach-Object [-InputObject ] -Parallel [-ThrottleLimit ] + [-TimeoutSeconds ] [-AsJob] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION @@ -84,19 +84,7 @@ command. By default, the parallel scriptblocks use the current working directory of the caller that started the parallel tasks. - Non-terminating errors are written to the cmdlet error stream as they occur in parallel running - scriptblocks. Because parallel scriptblock execution order cannot be determined, the order in - which errors appear in the error stream is random. Likewise, messages written to other data - streams, like warning, verbose, or information are written to those data streams in an - indeterminate order. - - Terminating errors, such as exceptions, terminate the individual parallel instance of the - scriptblocks in which they occur. A terminating error in one scriptblocks may not cause the - termination of the `Foreach-Object` cmdlet. The other scriptblocks, running in parallel, continue - to run unless they also encounter a terminating error. The terminating error is written to the - error data stream as an **ErrorRecord** with a **FullyQualifiedErrorId** of `PSTaskException`. - Terminating errors can be converted to non-terminating errors using PowerShell try/catch or trap - blocks. + For more information, see the [NOTES](#notes) section of this article. ## EXAMPLES @@ -233,7 +221,7 @@ operator `$_`. It uses the dot syntax to specify the method and parentheses to e argument. The second command uses the **MemberName** parameter to specify the **Split** method and the -**ArgumentList** parameter to identify the dot (".") as the split delimiter. +**ArgumentList** parameter to identify the dot (`.`) as the split delimiter. The third command uses the **Foreach** alias of the `ForEach-Object` cmdlet and omits the names of the **MemberName** and **ArgumentList** parameters, which are optional. @@ -451,6 +439,45 @@ Output: 5 > [PipelineVariable](About/about_CommonParameters.md) common parameter variables are _not_ > supported in `Foreach-Object -Parallel` scenarios even with the `$using:` keyword. +### Example 17: Passing variables in nested parallel script ScriptBlockSet + +You can create a variable outside a `Foreach-Object -Parallel` scoped scriptblock and use +it inside the scriptblock with the `$using` keyword. + +```powershell +$test1 = 'TestA' +1..2 | Foreach-Object -Parallel { + $using:test1 +} +``` + +```Output +TestA +TestA +``` + +```powershell +# You CANNOT create a variable inside a scoped scriptblock +# to be used in a nested foreach parallel scriptblock. +$test1 = 'TestA' +1..2 | Foreach-Object -Parallel { + $using:test1 + $test2 = 'TestB' + 1..2 | Foreach-Object -Parallel { + $using:test2 + } +} +``` + +```Output +Line | + 2 | 1..2 | Foreach-Object -Parallel { + | ~~~~~~~~~~~~~~~~~~~~~~~~~~ + | The value of the using variable '$using:test2' cannot be retrieved because it has not been set in the local session. +``` + +The nested scriptblock can't access the `$test2` variable and an error is thrown. + ## PARAMETERS ### -ArgumentList @@ -752,17 +779,19 @@ This cmdlet returns objects that are determined by the input. ## NOTES -- The `ForEach-Object` cmdlet works much like the **Foreach** statement, except that you cannot pipe - input to a **Foreach** statement. For more information about the **Foreach** statement, see - [about_Foreach](./About/about_Foreach.md). +The `ForEach-Object` cmdlet works much like the **Foreach** statement, except that you cannot pipe +input to a **Foreach** statement. For more information about the **Foreach** statement, see +[about_Foreach](./About/about_Foreach.md). -- Starting in PowerShell 4.0, `Where` and `ForEach` methods were added for use with collections. You - can read more about these new methods here [about_arrays](./About/about_Arrays.md) +Starting in PowerShell 4.0, `Where` and `ForEach` methods were added for use with collections. You +can read more about these new methods here [about_arrays](./About/about_Arrays.md) + +Using `ForEach-Object -Parallel`: - The `ForEach-Object -Parallel` parameter set uses PowerShell's internal API to run each script - block. This is significantly more overhead than running `ForEach-Object` normally with sequential - processing. It is important to use **Parallel** where the overhead of running in parallel is small - compared to work the script block performs. For example: + block in a new runspace. This is significantly more overhead than running `ForEach-Object` + normally with sequential processing. It is important to use **Parallel** where the overhead of + running in parallel is small compared to work the script block performs. For example: - Compute intensive scripts on multi-core machines - Scripts that spend time waiting for results or doing file operations @@ -771,8 +800,34 @@ This cmdlet returns objects that are determined by the input. the parallel scripts are trivial. Experiment with **Parallel** to discover where it can be beneficial. +- When running in parallel, objects decorated with **ScriptProperties** or **ScriptMethods** cannot + be guaranteed to function correctly if they are run in a different runspace than the scripts were + originally attached to them. + + Scriptblock invocation always attempts to run in its _home_ runspace, regardless of where it's + actually invoked. However, `ForEach-Object -Parallel` creates temporary runspaces that get deleted + after use, so there's no runspace for the scripts to execute in anymore. + + This behavior can work as long as the _home_ runspace still exists. However, you may not get + the desired result if the script is dependent on external variables that are only present in the + caller's runspace and not the _home_ runspace. + +- Non-terminating errors are written to the cmdlet error stream as they occur in parallel running + scriptblocks. Because parallel scriptblock execution order is non-deterministic, the order in + which errors appear in the error stream is random. Likewise, messages written to other data + streams, like warning, verbose, or information are written to those data streams in an + indeterminate order. + + Terminating errors, such as exceptions, terminate the individual parallel instance of the + scriptblocks in which they occur. A terminating error in one scriptblocks may not cause the + termination of the `Foreach-Object` cmdlet. The other scriptblocks, running in parallel, continue + to run unless they also encounter a terminating error. The terminating error is written to the + error data stream as an **ErrorRecord** with a **FullyQualifiedErrorId** of `PSTaskException`. + Terminating errors can be converted to non-terminating errors using PowerShell try/catch or trap + blocks. + - [PipelineVariable](About/about_CommonParameters.md) common parameter variables are _not_ supported - in `Foreach-Object -Parallel` scenarios even with the `$using:` keyword. + in parallel scenarios even with the `$using:` keyword. > [!IMPORTANT] > The `ForEach-Object -Parallel` parameter set runs script blocks in parallel on separate process @@ -780,7 +835,7 @@ This cmdlet returns objects that are determined by the input. > thread to each running script block thread. Since the script blocks run in different threads, > the object variables passed by reference must be used safely. Generally it is safe to read from > referenced objects that don't change. But if the object state is being modified then you must - > used thread safe objects, such as .Net **System.Collection.Concurrent** types (See Example 11). + > used thread safe objects, such as .NET **System.Collection.Concurrent** types (See Example 11). ## RELATED LINKS diff --git a/reference/7.3/Microsoft.PowerShell.Core/ForEach-Object.md b/reference/7.3/Microsoft.PowerShell.Core/ForEach-Object.md index 4b9b95e943a5..8b7b4d5d4826 100644 --- a/reference/7.3/Microsoft.PowerShell.Core/ForEach-Object.md +++ b/reference/7.3/Microsoft.PowerShell.Core/ForEach-Object.md @@ -2,7 +2,7 @@ external help file: System.Management.Automation.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Core -ms.date: 07/27/2021 +ms.date: 04/04/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/foreach-object?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: ForEach-Object @@ -31,8 +31,8 @@ ForEach-Object [-InputObject ] [-MemberName] [-ArgumentList < ### ParallelParameterSet ``` -ForEach-Object -Parallel [-InputObject ] [-ThrottleLimit ] - [-UseNewRunspace] [-TimeoutSeconds ] [-AsJob] [-WhatIf] [-Confirm] [] +ForEach-Object [-InputObject ] -Parallel [-ThrottleLimit ] + [-TimeoutSeconds ] [-AsJob] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION @@ -84,19 +84,7 @@ command. By default, the parallel scriptblocks use the current working directory of the caller that started the parallel tasks. - Non-terminating errors are written to the cmdlet error stream as they occur in parallel running - scriptblocks. Because parallel scriptblock execution order cannot be determined, the order in - which errors appear in the error stream is random. Likewise, messages written to other data - streams, like warning, verbose, or information are written to those data streams in an - indeterminate order. - - Terminating errors, such as exceptions, terminate the individual parallel instance of the - scriptblocks in which they occur. A terminating error in one scriptblocks may not cause the - termination of the `Foreach-Object` cmdlet. The other scriptblocks, running in parallel, continue - to run unless they also encounter a terminating error. The terminating error is written to the - error data stream as an **ErrorRecord** with a **FullyQualifiedErrorId** of `PSTaskException`. - Terminating errors can be converted to non-terminating errors using PowerShell try/catch or trap - blocks. + For more information, see the [NOTES](#notes) section of this article. ## EXAMPLES @@ -233,7 +221,7 @@ operator `$_`. It uses the dot syntax to specify the method and parentheses to e argument. The second command uses the **MemberName** parameter to specify the **Split** method and the -**ArgumentList** parameter to identify the dot (".") as the split delimiter. +**ArgumentList** parameter to identify the dot (`.`) as the split delimiter. The third command uses the **Foreach** alias of the `ForEach-Object` cmdlet and omits the names of the **MemberName** and **ArgumentList** parameters, which are optional. @@ -451,6 +439,45 @@ Output: 5 > [PipelineVariable](About/about_CommonParameters.md) common parameter variables are _not_ > supported in `Foreach-Object -Parallel` scenarios even with the `$using:` keyword. +### Example 17: Passing variables in nested parallel script ScriptBlockSet + +You can create a variable outside a `Foreach-Object -Parallel` scoped scriptblock and use +it inside the scriptblock with the `$using` keyword. + +```powershell +$test1 = 'TestA' +1..2 | Foreach-Object -Parallel { + $using:test1 +} +``` + +```Output +TestA +TestA +``` + +```powershell +# You CANNOT create a variable inside a scoped scriptblock +# to be used in a nested foreach parallel scriptblock. +$test1 = 'TestA' +1..2 | Foreach-Object -Parallel { + $using:test1 + $test2 = 'TestB' + 1..2 | Foreach-Object -Parallel { + $using:test2 + } +} +``` + +```Output +Line | + 2 | 1..2 | Foreach-Object -Parallel { + | ~~~~~~~~~~~~~~~~~~~~~~~~~~ + | The value of the using variable '$using:test2' cannot be retrieved because it has not been set in the local session. +``` + +The nested scriptblock can't access the `$test2` variable and an error is thrown. + ## PARAMETERS ### -ArgumentList @@ -752,17 +779,19 @@ This cmdlet returns objects that are determined by the input. ## NOTES -- The `ForEach-Object` cmdlet works much like the **Foreach** statement, except that you cannot pipe - input to a **Foreach** statement. For more information about the **Foreach** statement, see - [about_Foreach](./About/about_Foreach.md). +The `ForEach-Object` cmdlet works much like the **Foreach** statement, except that you cannot pipe +input to a **Foreach** statement. For more information about the **Foreach** statement, see +[about_Foreach](./About/about_Foreach.md). -- Starting in PowerShell 4.0, `Where` and `ForEach` methods were added for use with collections. You - can read more about these new methods here [about_arrays](./About/about_Arrays.md) +Starting in PowerShell 4.0, `Where` and `ForEach` methods were added for use with collections. You +can read more about these new methods here [about_arrays](./About/about_Arrays.md) + +Using `ForEach-Object -Parallel`: - The `ForEach-Object -Parallel` parameter set uses PowerShell's internal API to run each script - block. This is significantly more overhead than running `ForEach-Object` normally with sequential - processing. It is important to use **Parallel** where the overhead of running in parallel is small - compared to work the script block performs. For example: + block in a new runspace. This is significantly more overhead than running `ForEach-Object` + normally with sequential processing. It is important to use **Parallel** where the overhead of + running in parallel is small compared to work the script block performs. For example: - Compute intensive scripts on multi-core machines - Scripts that spend time waiting for results or doing file operations @@ -771,8 +800,34 @@ This cmdlet returns objects that are determined by the input. the parallel scripts are trivial. Experiment with **Parallel** to discover where it can be beneficial. +- When running in parallel, objects decorated with **ScriptProperties** or **ScriptMethods** cannot + be guaranteed to function correctly if they are run in a different runspace than the scripts were + originally attached to them. + + Scriptblock invocation always attempts to run in its _home_ runspace, regardless of where it's + actually invoked. However, `ForEach-Object -Parallel` creates temporary runspaces that get deleted + after use, so there's no runspace for the scripts to execute in anymore. + + This behavior can work as long as the _home_ runspace still exists. However, you may not get + the desired result if the script is dependent on external variables that are only present in the + caller's runspace and not the _home_ runspace. + +- Non-terminating errors are written to the cmdlet error stream as they occur in parallel running + scriptblocks. Because parallel scriptblock execution order is non-deterministic, the order in + which errors appear in the error stream is random. Likewise, messages written to other data + streams, like warning, verbose, or information are written to those data streams in an + indeterminate order. + + Terminating errors, such as exceptions, terminate the individual parallel instance of the + scriptblocks in which they occur. A terminating error in one scriptblocks may not cause the + termination of the `Foreach-Object` cmdlet. The other scriptblocks, running in parallel, continue + to run unless they also encounter a terminating error. The terminating error is written to the + error data stream as an **ErrorRecord** with a **FullyQualifiedErrorId** of `PSTaskException`. + Terminating errors can be converted to non-terminating errors using PowerShell try/catch or trap + blocks. + - [PipelineVariable](About/about_CommonParameters.md) common parameter variables are _not_ supported - in `Foreach-Object -Parallel` scenarios even with the `$using:` keyword. + in parallel scenarios even with the `$using:` keyword. > [!IMPORTANT] > The `ForEach-Object -Parallel` parameter set runs script blocks in parallel on separate process @@ -780,7 +835,7 @@ This cmdlet returns objects that are determined by the input. > thread to each running script block thread. Since the script blocks run in different threads, > the object variables passed by reference must be used safely. Generally it is safe to read from > referenced objects that don't change. But if the object state is being modified then you must - > used thread safe objects, such as .Net **System.Collection.Concurrent** types (See Example 11). + > used thread safe objects, such as .NET **System.Collection.Concurrent** types (See Example 11). ## RELATED LINKS From 0902dcdaa40d7d009f934792e7fb69522b5879b7 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Tue, 5 Apr 2022 08:58:22 -0500 Subject: [PATCH 05/31] (MAINT) Add echo to live branch check This commit adds an echo to the GHA for validating that a PR author has authorization to submit a PR to the Live branch. It reports the username and discovered permissions before echoing that the author has permissions or throwing if they do not. --- .github/workflows/targeting-valid-branch.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/targeting-valid-branch.yml b/.github/workflows/targeting-valid-branch.yml index 2c61f3840757..67e5bec941cf 100644 --- a/.github/workflows/targeting-valid-branch.yml +++ b/.github/workflows/targeting-valid-branch.yml @@ -37,6 +37,7 @@ jobs: '--jq', '.data.repository.collaborators.edges[].permission' ) [string[]]$Permissions = gh @ApiParameters + echo "Author '${{ github.event.pull_request.user.login }}' has permissions: '$($Permissions -join ',')'" if ($Permissions -notcontains 'MAINTAIN' -and $Permissions -notcontains 'ADMIN') { throw "Author does not have permissions to target ${{ github.base_ref }}" } else { From 978d0b5e4664967d7ed2cc340b9a6e1931b0d6c6 Mon Sep 17 00:00:00 2001 From: "Mike F. Robbins" Date: Tue, 5 Apr 2022 15:23:28 -0500 Subject: [PATCH 06/31] Updated quick filter for azps to 7.4.0 (#8719) Co-authored-by: Mike F. Robbins --- reference/module/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/module/index.md b/reference/module/index.md index 28f765aa2829..5a2b3dfb4794 100644 --- a/reference/module/index.md +++ b/reference/module/index.md @@ -12,7 +12,7 @@ ms.manager: sewhee ms.product: powershell ms.topic: landing-page quickFilterColumn1: powershell-7.1,windowsserver2019-ps -quickFilterColumn2: azps-7.3.2,win-mdop2-ps +quickFilterColumn2: azps-7.4.0,win-mdop2-ps quickFilterColumn3: sqlserver-ps,systemcenter-ps-2019 title: PowerShell Module Browser --- From 6040e8867cb3047f3bde9cfdd51a550455e6a3c3 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 6 Apr 2022 10:25:43 -0500 Subject: [PATCH 07/31] Add note about experimental feature requirements (#8725) --- .../dev-cross-plat/create-cmdline-predictor.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/reference/docs-conceptual/dev-cross-plat/create-cmdline-predictor.md b/reference/docs-conceptual/dev-cross-plat/create-cmdline-predictor.md index 1d8c0d721731..cba00931cd38 100644 --- a/reference/docs-conceptual/dev-cross-plat/create-cmdline-predictor.md +++ b/reference/docs-conceptual/dev-cross-plat/create-cmdline-predictor.md @@ -1,6 +1,6 @@ --- description: This article describes how to create a command-line predictor to help with command completion in PowerShell. -ms.date: 03/28/2022 +ms.date: 04/06/2022 title: How to create a command-line predictor --- # How to create a command-line predictor @@ -197,10 +197,10 @@ Create a new PowerShell module project by following these steps: } ``` - The following example code returns the string "HELLO WORLD" for the prediction result for all user - input. Since the sample predictor doesn't process any feedback, the code does not implement the - feedback methods from the interface. Change the prediction and feedback code to meet the needs of - your predictor. + The following example code returns the string "HELLO WORLD" for the prediction result for all + user input. Since the sample predictor doesn't process any feedback, the code does not implement + the feedback methods from the interface. Change the prediction and feedback code to meet the + needs of your predictor. 1. Run `dotnet build` to produce the assembly. You can find the compiled assembly in the `bin/Debug/net6.0` location of your project folder. @@ -232,3 +232,8 @@ Kind SubsystemType IsRegistered Implementations ---- ------------- ------------ --------------- CommandPredictor ICommandPredictor True {SamplePredictor} ``` + +> [!NOTE] +> `Get-PSSubsystem` is an experimental cmdlet that was introduced in PowerShell 7.1 You must enable +> the `PSSubsystemPluginModel` experimental feature to use this cmdlet. For more information, see +> [Using Experimental Features](../learn/experimental-features.md#pssubsystempluginmodel). From 5043b621795e0da9fb91ec4e8b23236218aeedb3 Mon Sep 17 00:00:00 2001 From: "Michael T Lombardi (He/Him)" Date: Wed, 6 Apr 2022 13:36:38 -0500 Subject: [PATCH 08/31] (MAINT) Reimplement GHA for branch auth checking (#8726) This commit reimplements the GitHub Action workflow for verifying that a pull request to the live branch has been submitted by a user who is authorized to do so. It replaces the default GitHub Action token with a repository secret, `VALID_BRANCH_TOKEN`, which is a PAT with the minimum permissions needed to retrieve the permissions of repository collaborators: - `repo:public_repo` - `read:org` It refactors the logic of the check itself to: 1. Replace the graphql query with a simpler endpoint query, passing the owner of the repository, the repository name, and the login of the pull request author to retrieve that user's permissions for the repo. 2. Adds an error handling check, throwing an error (and all output from the api call) if the query's exit code is non-zero. 3. Adds a null response check, throwing an error if the query does not return the permissions needed for further verification. 4. Converts the previous array membership check into simpler check on the new data form returned by the API. 5. Echoes the pull request author's current permissions for the repo into the run log to aid with debugging. --- .github/workflows/targeting-valid-branch.yml | 50 ++++++++++---------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/.github/workflows/targeting-valid-branch.yml b/.github/workflows/targeting-valid-branch.yml index 67e5bec941cf..a5890a82d847 100644 --- a/.github/workflows/targeting-valid-branch.yml +++ b/.github/workflows/targeting-valid-branch.yml @@ -13,33 +13,33 @@ jobs: shell: pwsh if: github.base_ref == 'live' steps: - - name: Authorized to Target Live Branch + - name: Authorized to Target Live Branch? env: - GITHUB_TOKEN: ${{ github.token }} + GITHUB_TOKEN: ${{ secrets.VALID_BRANCH_TOKEN }} run: | - $Query = @' - query author_collaborator_permission($owner: String!, $repo: String!, $actor: String!) { - repository(owner: $owner, name: $repo) { - collaborators(query: $actor) { - edges { - permission - } - } - } + $Owner = '${{ github.event.pull_request.base.repo.owner.login}}' + $Repo = '${{ github.event.pull_request.base.repo.name }}' + $Actor = '${{ github.event.pull_request.user.login }}' + + $ResultString = gh api repos/$Owner/$Repo/collaborators/$Actor/permission + $ExitCode = $LASTEXITCODE + if ($ExitCode -ne 0) { + throw "GitHub API call failed with exit code ${ExitCode}:`n$ResultString" } - '@ - $ApiParameters = @( - 'api', 'graphql' - '-F', "owner=${{ github.event.pull_request.base.repo.owner.login}}" - '-F', "repo=${{ github.event.pull_request.base.repo.name }}" - '-F', "actor=${{ github.event.pull_request.user.login }}" - '-f', "query=$Query" - '--jq', '.data.repository.collaborators.edges[].permission' - ) - [string[]]$Permissions = gh @ApiParameters - echo "Author '${{ github.event.pull_request.user.login }}' has permissions: '$($Permissions -join ',')'" - if ($Permissions -notcontains 'MAINTAIN' -and $Permissions -notcontains 'ADMIN') { - throw "Author does not have permissions to target ${{ github.base_ref }}" - } else { + + $Permissions = $ResultString + | ConvertFrom-Json + | Select-Object -Property @{ Name = 'Permissions' ; Expression = { $_.user.permissions } } + | Select-Object -ExpandProperty Permissions + + if ($null -eq $Permissions) { + throw "Unable to retrieve permissions for author '$Actor':`n$ResultString" + } + + echo "Author '$Actor' has permissions:`n$($Permissions | Format-List | Out-String)" + + if ($Permissions.admin -or $Permissions.maintain) { echo "Author has permissions to target ${{ github.base_ref }}" + } else { + throw "Author does not have permissions to target ${{ github.base_ref }}" } From fb40c3c45502bae707c07f9a0d861244fd76bdb8 Mon Sep 17 00:00:00 2001 From: kevinholtkamp <32170328+kevinholtkamp@users.noreply.github.com> Date: Mon, 11 Apr 2022 15:31:47 +0200 Subject: [PATCH 09/31] Formatting fix in Wait-Job.md (#8730) * Formatting fix in Wait-Job.md in 7.1 * Formatting fix in Wait-Job.md 7.0 * Formatting fix in Wait-Job.md 5.1 * Formatting fix in Wait-Job.md 7.2 * Formatting fix in Wait-Job.md 7.3 --- reference/5.1/Microsoft.PowerShell.Core/Wait-Job.md | 5 +++-- reference/7.0/Microsoft.PowerShell.Core/Wait-Job.md | 5 +++-- reference/7.1/Microsoft.PowerShell.Core/Wait-Job.md | 5 +++-- reference/7.2/Microsoft.PowerShell.Core/Wait-Job.md | 5 +++-- reference/7.3/Microsoft.PowerShell.Core/Wait-Job.md | 5 +++-- 5 files changed, 15 insertions(+), 10 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/Wait-Job.md b/reference/5.1/Microsoft.PowerShell.Core/Wait-Job.md index 6ecf42121128..72b7358fcd8f 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/Wait-Job.md +++ b/reference/5.1/Microsoft.PowerShell.Core/Wait-Job.md @@ -498,8 +498,9 @@ By default, `Wait-Job` returns, or ends the wait, when jobs are in one of the fo - Failed - Stopped - Suspended -- Disconnected To direct `Wait-Job` to continue to wait for Suspended and Disconnected jobs, use the - **Force** parameter. +- Disconnected + +To direct `Wait-Job` to continue to wait for Suspended and Disconnected jobs, use the **Force** parameter. ## RELATED LINKS diff --git a/reference/7.0/Microsoft.PowerShell.Core/Wait-Job.md b/reference/7.0/Microsoft.PowerShell.Core/Wait-Job.md index d9180f90fd50..9a6334583e75 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/Wait-Job.md +++ b/reference/7.0/Microsoft.PowerShell.Core/Wait-Job.md @@ -498,8 +498,9 @@ By default, `Wait-Job` returns, or ends the wait, when jobs are in one of the fo - Failed - Stopped - Suspended -- Disconnected To direct `Wait-Job` to continue to wait for Suspended and Disconnected jobs, use the - **Force** parameter. +- Disconnected + +To direct `Wait-Job` to continue to wait for Suspended and Disconnected jobs, use the **Force** parameter. ## RELATED LINKS diff --git a/reference/7.1/Microsoft.PowerShell.Core/Wait-Job.md b/reference/7.1/Microsoft.PowerShell.Core/Wait-Job.md index 28cc216b8343..3650bd3cf2ff 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/Wait-Job.md +++ b/reference/7.1/Microsoft.PowerShell.Core/Wait-Job.md @@ -498,8 +498,9 @@ By default, `Wait-Job` returns, or ends the wait, when jobs are in one of the fo - Failed - Stopped - Suspended -- Disconnected To direct `Wait-Job` to continue to wait for Suspended and Disconnected jobs, use the - **Force** parameter. +- Disconnected + +To direct `Wait-Job` to continue to wait for Suspended and Disconnected jobs, use the**Force** parameter. ## RELATED LINKS diff --git a/reference/7.2/Microsoft.PowerShell.Core/Wait-Job.md b/reference/7.2/Microsoft.PowerShell.Core/Wait-Job.md index c8521b0b17e2..ca58d1fb311d 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/Wait-Job.md +++ b/reference/7.2/Microsoft.PowerShell.Core/Wait-Job.md @@ -498,8 +498,9 @@ By default, `Wait-Job` returns, or ends the wait, when jobs are in one of the fo - Failed - Stopped - Suspended -- Disconnected To direct `Wait-Job` to continue to wait for Suspended and Disconnected jobs, use the - **Force** parameter. +- Disconnected + +To direct `Wait-Job` to continue to wait for Suspended and Disconnected jobs, use the **Force** parameter. ## RELATED LINKS diff --git a/reference/7.3/Microsoft.PowerShell.Core/Wait-Job.md b/reference/7.3/Microsoft.PowerShell.Core/Wait-Job.md index 9dc4e1c012b2..2849e2b208ab 100644 --- a/reference/7.3/Microsoft.PowerShell.Core/Wait-Job.md +++ b/reference/7.3/Microsoft.PowerShell.Core/Wait-Job.md @@ -498,8 +498,9 @@ By default, `Wait-Job` returns, or ends the wait, when jobs are in one of the fo - Failed - Stopped - Suspended -- Disconnected To direct `Wait-Job` to continue to wait for Suspended and Disconnected jobs, use the - **Force** parameter. +- Disconnected + +To direct `Wait-Job` to continue to wait for Suspended and Disconnected jobs, use the **Force** parameter. ## RELATED LINKS From 5e6f6c150913d52f4bb7995a434610a76e860270 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 12 Apr 2022 10:01:43 -0500 Subject: [PATCH 10/31] Refactor compatibility article (#8732) --- .../whats-new/module-compatibility.md | 263 +++++------------- 1 file changed, 66 insertions(+), 197 deletions(-) diff --git a/reference/docs-conceptual/whats-new/module-compatibility.md b/reference/docs-conceptual/whats-new/module-compatibility.md index e2f0c3476517..1f962f17bb03 100644 --- a/reference/docs-conceptual/whats-new/module-compatibility.md +++ b/reference/docs-conceptual/whats-new/module-compatibility.md @@ -1,206 +1,75 @@ --- -description: This article lists the status of PowerShell 7 with Powershell modules published for other Microsoft products. -ms.date: 10/04/2021 +description: This article lists the compatibility status of modules published for other Microsoft products with PowerShell 7. +ms.date: 04/12/2022 title: PowerShell 7 module compatibility --- # PowerShell 7 module compatibility -This article contains a list of PowerShell modules published by Microsoft. These modules provide -management and support for various Microsoft products and services. They have been updated -to work natively with PowerShell 7, or tested for compatibility with PowerShell 7. This list will be -updated with new information as more modules are identified and tested. +This article contains a partial list of PowerShell modules published by Microsoft. -If you have information to share or issues with specific modules, please file an issue in the -[WindowsCompatibility repo](https://github.com/PowerShell/WindowsCompatibility). +The PowerShell team is working with the various feature teams that create PowerShell modules to help +them produce modules that work in PowerShell 7. These modules are not owned by the PowerShell team. + +The following modules are known to support PowerShell 7. + +## Azure PowerShell + +The Az PowerShell module is a set of cmdlets for managing Azure resources directly from PowerShell. +PowerShell 7.0.6 LTS or higher is the recommended version of PowerShell for use with the Azure Az +PowerShell module on all platforms. + +For more information, see +[Introducing the Azure Az PowerShell module](/powershell/azure/new-azureps-module-az). + +## MSGraph PowerShell SDK + +The Microsoft Graph SDKs are designed to simplify building high-quality, efficient, and resilient +applications that access Microsoft Graph. PowerShell 7 and later is the recommended PowerShell +version for use with the Microsoft Graph PowerShell SDK. + +For more information, see +[Install the Microsoft Graph PowerShell SDK](/graph/powershell/installation#supported-powershell-versions). ## Windows management modules -The Windows management modules are installed in different ways, dependent on the Edition of Windows, -and how the module was packaged for that Edition. - -On Windows Server, use the feature name with the -[Install-WindowsFeature](/powershell/module/servermanager/install-windowsfeature) cmdlet as an -Administrator. For example: - -```powershell -Install-WindowsFeature -Name ActiveDirectory -``` - -On Windows 10, the Windows management modules are made available as **Windows Optional Features** or -**Windows Capabilities**. The following commands must be run from an elevated session using **Run as -administrator**. - -- For Windows Optional Features - - To get a list of Optional Features, run the following command: - - ```powershell - Get-WindowsOptionalFeature -Online - ``` - - To install the feature: - - ```powershell - Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V-Management-PowerShell - ``` - - For more information see: - - - [Get-WindowsOptionalFeature](/powershell/module/dism/get-windowsoptionalfeature) - - [Enable-WindowsOptionalFeature](/powershell/module/dism/enable-windowsoptionalfeature) - -- For Windows Capabilities - - To get a list of Windows Capabilities, run the following command: - - ```powershell - Get-WindowsCapability -online - ``` - - Notice that the name of the capability package ends with `~~~~0.0.1.0`. You must use the full name - to install the capability: - - ```powershell - Add-WindowsCapability -Online -Name Rsat.ServerManager.Tools~~~~0.0.1.0 - ``` - - For more information see: - - - [Get-WindowsCapability](/powershell/module/dism/get-windowscapability) - - [Add-WindowsCapability](/powershell/module/dism/add-windowscapability) - -### Module list - -| Module name | Status | Supported OS | -| ---------------------------------- | ------------------------------------ | ---------------------------------- | -| ActiveDirectory | Natively Compatible | Windows Server 1809+ with RSAT-AD-PowerShell
Windows 10 1809+ with Rsat.ActiveDirectory.DS-LDS.Tools | -| ADDSDeployment | Works with Compatibility Layer | Windows Server 2019 1809+ | -| ADFS | Untested with Compatibility Layer | | -| AppBackgroundTask | Natively Compatible | Windows 10 1903+ | -| AppLocker | Untested with Compatibility Layer | | -| AppvClient | Untested with Compatibility Layer | | -| Appx | Natively Compatible** | Windows Server 1809+
Windows 10 1809+
**Must use Compatibility Layer with PowerShell 7.1 | -| AssignedAccess | Natively Compatible | Windows 10 1809+ | -| BestPractices | Not Supported by Compatibility Layer | | -| BitLocker | Natively Compatible | Windows Server 1809+ with BitLocker
Windows 10 1809+ | -| BitsTransfer | Natively Compatible | Windows Server 20H1
Windows 10 20H1 | -| BootEventCollector | Untested with Compatibility Layer | | -| BranchCache | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| CimCmdlets | Natively Compatible | Built into PowerShell 7 | -| ClusterAwareUpdating | Untested with Compatibility Layer | | -| ConfigCI | Untested with Compatibility Layer | | -| Defender | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| DeliveryOptimization | Natively Compatible | Windows Server 1903+
Windows 10 1903+ | -| DFSN | Natively Compatible | Windows Server 1809+ with FS-DFS-Namespace
Windows 10 1809+ with Rsat.FailoverCluster.Management.Tools | -| DFSR | Untested with Compatibility Layer | | -| DhcpServer | Untested with Compatibility Layer | | -| DirectAccessClientComponents | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| Dism | Natively Compatible | Windows Server 1903+
Windows 10 1903+ | -| DnsClient | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| DnsServer | Natively Compatible | Windows Server 1809+ with DNS or RSAT-DNS-Server
Windows 10 1809+ with Rsat.Dns.Tools | -| EventTracingManagement | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| FailoverClusters | Untested with Compatibility Layer | | -| FailoverClusterSet | Untested with Compatibility Layer | | -| FileServerResourceManager | Natively Compatible | Windows Server 1809+ with FS-Resource-Manager | -| GroupPolicy | Untested with Compatibility Layer | | -| HgsClient | Natively Compatible | Windows Server 1903+ with Hyper-V or RSAT-Shielded-VM-Tools
Windows 10 1903+ with Rsat.Shielded.VM.Tools | -| HgsDiagnostics | Natively Compatible | Windows Server 1809+ with Hyper-V or RSAT-Shielded-VM-Tools
Windows 10 1809+ with Rsat.Shielded.VM.Tools | -| Hyper-V | Natively Compatible | Windows Server 1809+ with Hyper-V-PowerShell
Windows 10 1809+ with Microsoft-Hyper-V-Management-PowerShell | -| IISAdministration | Untested with Compatibility Layer | | -| International | Natively Compatible | Windows Server 1903+
Windows 10 1903+ | -| IpamServer | Untested with Compatibility Layer | | -| iSCSI | Untested with Compatibility Layer | | -| IscsiTarget | Untested with Compatibility Layer | | -| ISE | Untested with Compatibility Layer | | -| Kds | Natively Compatible | Windows Server 20H1
Windows 10 20H1 | -| Microsoft.PowerShell.Archive | Natively Compatible | Built into PowerShell 7 | -| Microsoft.PowerShell.Diagnostics | Natively Compatible | Built into PowerShell 7 | -| Microsoft.PowerShell.Host | Natively Compatible | Built into PowerShell 7 | -| Microsoft.PowerShell.LocalAccounts | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| Microsoft.PowerShell.Management | Natively Compatible | Built into PowerShell 7 | -| Microsoft.PowerShell.ODataUtils | Untested with Compatibility Layer | | -| Microsoft.PowerShell.Security | Natively Compatible | Built into PowerShell 7 | -| Microsoft.PowerShell.Utility | Natively Compatible | Built into PowerShell 7 | -| Microsoft.WSMan.Management | Natively Compatible | Built into PowerShell 7 | -| MMAgent | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| MPIO | Natively Compatible | Windows Server 1809+ with Multipath-IO | -| MsDtc | Untested with Compatibility Layer | | -| NetAdapter | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| NetConnection | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| NetEventPacketCapture | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| NetLbfo | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| NetLldpAgent | Untested with Compatibility Layer | | -| NetNat | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| NetQos | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| NetSecurity | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| NetSwitchTeam | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| NetTCPIP | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| NetWNV | Untested with Compatibility Layer | | -| NetworkConnectivityStatus | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| NetworkController | Untested with Compatibility Layer | | -| NetworkControllerDiagnostics | Untested with Compatibility Layer | | -| NetworkLoadBalancingClusters | Untested with Compatibility Layer | | -| NetworkSwitchManager | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| NetworkTransition | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| NFS | Natively Compatible | Windows Server 1809+
Windows 10 1809+ with Rsat.ServerManager.Tools | -| PackageManagement | Natively Compatible | Built into PowerShell 7 | -| PcsvDevice | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| PersistentMemory | Untested with Compatibility Layer | | -| PKI | Untested with Compatibility Layer | | -| PnpDevice | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| PowerShellGet | Natively Compatible | Built into PowerShell 7 | -| PrintManagement | Natively Compatible | Windows Server 1903+ with Print-Services
Windows 10 1903+ | -| ProcessMitigations | Natively Compatible | Windows Server 1903+
Windows 10 1903+ | -| Provisioning | Untested with Compatibility Layer | | -| PSDesiredStateConfiguration | Partially | Built into PowerShell 7 | -| PSDiagnostics | Natively Compatible | Built into PowerShell 7 | -| PSScheduledJob | Not Supported by Compatibility Layer | Built into PowerShell 5.1 | -| PSWorkflow | Untested with Compatibility Layer | | -| PSWorkflowUtility | Untested with Compatibility Layer | | -| RemoteAccess | Untested with Compatibility Layer | | -| RemoteDesktop | Untested with Compatibility Layer | | -| ScheduledTasks | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| SecureBoot | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| ServerCore | Untested with Compatibility Layer | | -| ServerManager | Natively Compatible | Windows Server 1809+
Windows 10 1809+ with Rsat.ServerManager.Tools
_See notes below_ | -| ServerManagerTasks | Untested with Compatibility Layer | | -| ShieldedVMDataFile | Natively Compatible | Windows Server 1903+ with RSAT-Shielded-VM-Tools
Windows 10 1903+ with Rsat.Shielded.VM.Tools | -| ShieldedVMProvisioning | Natively Compatible | Windows Server 1809+ with HostGuardian
Windows 10 1809+ with HostGuardian | -| ShieldedVMTemplate | Natively Compatible | Windows Server 1809+ with RSAT-Shielded-VM-Tools
Windows 10 1809+ with Rsat.Shielded.VM.Tools | -| SmbShare | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| SmbWitness | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| SMISConfig | Natively Compatible | Windows Server 1903+ with WindowsStorageManagementService | -| SMS | Untested with Compatibility Layer | | -| SoftwareInventoryLogging | Natively Compatible | Windows Server 1809+ | -| StartLayout | Natively Compatible | Windows Server 1809+ with Desktop Experience
Windows 10 1809+ | -| Storage | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| StorageBusCache | Untested with Compatibility Layer | | -| StorageMigrationService | Untested with Compatibility Layer | | -| StorageQOS | Natively Compatible | Windows Server 1809+ with RSAT-Clustering-PowerShell
Windows 10 1809+ with Rsat.FailoverCluster.Management.Tools | -| StorageReplica | Untested with Compatibility Layer | | -| SyncShare | Natively Compatible | Windows Server 1809+ with FS-SyncShareService | -| SystemInsights | Untested with Compatibility Layer | | -| TLS | Untested with Compatibility Layer | | -| TroubleshootingPack | Natively Compatible | Windows 10 1903+ | -| TrustedPlatformModule | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| UEV | Natively Compatible | Windows Server ??Future version of Server with Desktop Experience??
Windows 10 1903+ | -| UpdateServices | Not Supported by Compatibility Layer | | -| VpnClient | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| Wdac | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| WebAdministration | Untested with Compatibility Layer | | -| WHEA | Natively Compatible | Windows Server 1903+
Windows 10 1903+ | -| WindowsDeveloperLicense | Natively Compatible | Windows Server 1809+ with Desktop Experience
Windows 10 1809+ | -| WindowsErrorReporting | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| WindowsSearch | Natively Compatible | Windows 10 1903+ | -| WindowsServerBackup | Natively Compatible | Windows Server 19H2 with Windows-Server-Backup | -| WindowsUpdate | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | -| WindowsUpdateProvider | Natively Compatible | Windows Server 1809+
Windows 10 1809+ | - -## Notes - -### ServerManager module - -This module has some minor compatibility issues with formatted output in PowerShell 7. For example, -the `Get-WindowsFeature` cmdlet returns the proper object with all properties, but the default -display formatting makes some properties appear to be empty. The actual values are available in the -object properties using `Select-Object` or by direct member access. +The Windows management modules provide management and support for various Windows features and +services. Most of these modules have been updated to work natively with PowerShell 7, or tested for +compatibility with PowerShell 7. + +These modules are installed in different ways depending on the Edition of Windows, and how the +module is packaged for that Edition. + +For more information about installation and compatibility, see +[PowerShell 7 module compatibility](/powershell/windows/module-compatibility) in the Windows +documentation. + +## Exchange Online Management 2.0 + +The Exchange Online PowerShell V2 module (EXO V2) connects to all Exchange-related PowerShell +environments in Microsoft 365: Exchange Online PowerShell, Security & Compliance PowerShell, and +standalone Exchange Online Protection (EOP) PowerShell. + +EXO v2.0.4 or later is supported in PowerShell 7.0.3 or later. + +For more information, see +[About the Exchange Online PowerShell V2 module](/powershell/exchange/exchange-online-powershell-v2). + +## PowerShell modules for SQL Server + +There are two SQL Server PowerShell modules: + +- **SqlServer**: This module includes new cmdlets to support the latest SQL features, including + updated versions of the cmdlets in SQLPS. +- **SQLPS**: The SQLPS is the module used by SQL Agent to run agent jobs in agent job steps using + the PowerShell subsystem. + +The SqlServer modules require PowerShell version 5.0 or greater. + +For more information, see +[Install the SQL Server PowerShell module](/sql/powershell/download-sql-server-ps-module). + +## Finding the status of other modules + +You can find a complete list of modules using the [PowerShell Module Browser](/powershell/module). +Using the Module Browser, you can find documentation for other PowerShell modules to determine their +PowerShell version requirements. From 79f9e2f162b1211f9744834ebb67ec4ca480b745 Mon Sep 17 00:00:00 2001 From: "Michael T Lombardi (He/Him)" Date: Thu, 14 Apr 2022 09:49:45 -0500 Subject: [PATCH 11/31] (GH-8601) Clarify Include parameter for Copy-Item (#8734) * (GH-8601) Clarify Include parameter for Copy-Item Prior to this commit, the documentation for the Include parameter of the Copy-Item cmdlet was unclear. This commit clarifies its functionality and adds a new example to show how it is used and where its behavior might be otherwise surprising. * Apply suggestions from code review * Added recurse example Co-authored-by: Sean Wheeler --- .../Copy-Item.md | 160 +++++++++++++++--- .../Copy-Item.md | 154 ++++++++++++++--- .../Copy-Item.md | 155 ++++++++++++++--- .../Copy-Item.md | 155 ++++++++++++++--- .../Copy-Item.md | 155 ++++++++++++++--- 5 files changed, 673 insertions(+), 106 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Management/Copy-Item.md b/reference/5.1/Microsoft.PowerShell.Management/Copy-Item.md index ab4594eaecda..6e448c48bd52 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Copy-Item.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Copy-Item.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 01/18/2022 +ms.date: 04/12/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/copy-item?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: Copy-Item @@ -252,6 +252,114 @@ The `Copy-Item` cmdlet has the **Container** parameter set to `$false`. This cau the source folder to be copied but does not preserve the folder structure. Notice that files with the same name are overwritten in the destination folder. +### Example 13: Using filters to copy items without recursion + +This example shows the results using the **Include** parameter to select which items should be +copied. + +This example uses the following folder structure containing the files to be copied: + +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` + +In this example, `Copy-Item` is called with a wildcard for both the **Path** and **Include** +parameters. Specifying a wildcard for the **Path** parameter ensures that it processes all of the +files and folders that match `D:\temp\tree\*`. The **Include** parameter filters the list of items +to process, limiting the operation to only those paths that begin with `ex`. + +```powershell +PS D:\temp\test\out> Copy-Item -Path D:\temp\tree\* -Include ex* +PS D:\temp\test\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example.ps1 +D:\temp\out\example.txt +``` + +The **Include** parameter is applied to the contents of `D:\temp\tree` folder to copy all items that +match `ex*`. Notice that, without recursion, the `D:\temp\out\examples` folder is copied, but none +of its contents are copied. + +### Example 15: Using filters to copy items with recursion + +This example shows the results using the **Include** parameter to select which items should be +copied. + +This example uses the following folder structure containing the files to be copied: + +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` + +In this example, `Copy-Item` is called with a wildcard for both the **Path** and **Include** +parameters. Specifying a wildcard for the **Path** parameter ensures that it processes all the files +and folders that match `D:\temp\tree\*`. The **Include** parameter filters the list of items to +process, limiting the operation to only those paths that begin with `ex`. + +```powershell +D:\temp\out> Copy-Item -Path D:\temp\tree\* -Include ex* -Recurse +D:\temp\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example.ps1 +D:\temp\out\example.txt +D:\temp\out\examples\subfolder +D:\temp\out\examples\example_1.txt +D:\temp\out\examples\example_2.txt +D:\temp\out\examples\subfolder\test.txt +``` + +The **Include** parameter is applied to the contents of `D:\temp\tree` folder to copy all items that +match `ex*`. Notice that, with recursion, the `D:\temp\out\examples` folder is copied along with all +the files and subfolders. The copy includes files that _do not_ match the include filter. When using +`Copy-Item`, the filters only apply to the top-level specified by the **Path** parameter. Then +recursion is applied to those matching items. + +> [!NOTE] +> The behavior of the **Exclude** parameter is the same as described in this example, except that +> it limits the operation to only those paths which do not match the pattern. + +### Example 15: Limit the files to recursively copy from a wildcard-specified path + +This example shows how to limit the files recursively copied from a wildcard-matching path into +another folder. Example 13 shows that, because the **Include** parameter only filters on the paths +resolved for a wildcard-specifying **Path**, the **Include** parameter can't be used to limit the +files recursively copied from a folder. Instead, you can use `Get-ChildItem` to find the items you +want to copy and pass those items to `Copy-Item`. + +This example uses the following folder structure containing the files to be copied: + +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` + +To copy all items that begin with `ex*`, use `Get-ChildItem` with the **Recurse** and **Filter** +parameters and pipe the results to `Copy-Item`. + +```powershell +D:\temp\out> Get-ChildItem -Path D:\temp\tree -Recurse -Filter ex* | Copy-Item +D:\temp\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example_1.txt +D:\temp\out\example_2.txt +D:\temp\out\example.ps1 +D:\temp\out\example.txt +``` + +Unlike the `Copy-Item`, the **Filter** parameter for `Get-ChildItem` applies to the items discovered +during recursion. This enables you to find, filter, and then copy items recursively. + ## PARAMETERS ### -Container @@ -310,11 +418,12 @@ Accept wildcard characters: False ### -Exclude -Specifies, as a string array, an item or items that this cmdlet excludes in the operation. The value -of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as -`*.txt`. Wildcard characters are permitted. The **Exclude** parameter is effective only when the -command includes the contents of an item, such as `C:\Windows\*`, where the wildcard character -specifies the contents of the `C:\Windows` directory. +Specifies one or more path elements or patterns, such as `"*.txt"`, to limit this cmdlet's +operation. The value of this parameter filters against the wildcard-matching result of the **Path** +parameter, not the final results. This parameter is only effective when the **Path** is specified +with one or more wildcards. Since this parameter only filters on the paths resolved for the **Path** +parameter, it does not filter any items discovered when recursing through child folders with the +**Recurse** parameter. ```yaml Type: System.String[] @@ -330,11 +439,13 @@ Accept wildcard characters: True ### -Filter -Specifies a filter to qualify the **Path** parameter. The [FileSystem](../Microsoft.PowerShell.Core/About/about_FileSystem_Provider.md) -provider is the only installed PowerShell provider that supports the use of filters. You can find -the syntax for the **FileSystem** filter language in [about_Wildcards](../Microsoft.PowerShell.Core/About/about_Wildcards.md). -Filters are more efficient than other parameters, because the provider applies them when the cmdlet -gets the objects rather than having PowerShell filter the objects after they're retrieved. +Specifies a filter to qualify the **Path** parameter. The +[FileSystem](../Microsoft.PowerShell.Core/About/about_FileSystem_Provider.md) provider is the only +installed PowerShell provider that supports the use of filters. You can find the syntax for the +**FileSystem** filter language in +[about_Wildcards](../Microsoft.PowerShell.Core/About/about_Wildcards.md). Filters are more efficient +than other parameters, because the provider applies them when the cmdlet gets the objects rather +than having PowerShell filter the objects after they're retrieved. ```yaml Type: System.String @@ -385,11 +496,12 @@ Accept wildcard characters: False ### -Include -Specifies, as a string array, an item or items that this cmdlet includes in the operation. The value -of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as -`"*.txt"`. Wildcard characters are permitted. The **Include** parameter is effective only when the -command includes the contents of an item, such as `C:\Windows\*`, where the wildcard character -specifies the contents of the `C:\Windows` directory. +Specifies one or more path elements or patterns, such as `"*.txt"`, to limit this cmdlet's +operation. The value of this parameter filters against the wildcard-matching result of the **Path** +parameter, not the final results. This parameter is only effective when the **Path** is specified +with one or more wildcards. Since this parameter only filters on the paths resolved for the **Path** +parameter, it does not filter any items discovered when recursing through child folders with the +**Recurse** parameter. ```yaml Type: System.String[] @@ -476,8 +588,7 @@ Accept wildcard characters: False ### -ToSession Specifies the **PSSession** object to which a remote file is being copied. When you use this -parameter, the **Destination** parameter refers to the local path on the remote -machine. +parameter, the **Destination** parameter refers to the local path on the remote machine. ```yaml Type: System.Management.Automation.Runspaces.PSSession @@ -494,7 +605,8 @@ Accept wildcard characters: False ### -UseTransaction Includes the command in the active transaction. This parameter is valid only when a transaction is -in progress. For more information, see [about_Transactions](../Microsoft.PowerShell.Core/About/about_Transactions.md). +in progress. For more information, see +[about_Transactions](../Microsoft.PowerShell.Core/About/about_Transactions.md). ```yaml Type: System.Management.Automation.SwitchParameter @@ -542,9 +654,10 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, -`-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, -`-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -562,7 +675,8 @@ item. Otherwise, this cmdlet doesn't generate any output. ## NOTES This cmdlet is designed to work with the data exposed by any provider. To list the providers -available in your session, type `Get-PSProvider`. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). +available in your session, type `Get-PSProvider`. For more information, see +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ## RELATED LINKS diff --git a/reference/7.0/Microsoft.PowerShell.Management/Copy-Item.md b/reference/7.0/Microsoft.PowerShell.Management/Copy-Item.md index 0e980d95546b..f20e84ea2bbd 100644 --- a/reference/7.0/Microsoft.PowerShell.Management/Copy-Item.md +++ b/reference/7.0/Microsoft.PowerShell.Management/Copy-Item.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 01/18/2022 +ms.date: 04/12/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/copy-item?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: Copy-Item @@ -250,6 +250,114 @@ The `Copy-Item` cmdlet has the **Container** parameter set to `$false`. This cau the source folder to be copied but does not preserve the folder structure. Notice that files with the same name are overwritten in the destination folder. +### Example 13: Using filters to copy items without recursion + +This example shows the results using the **Include** parameter to select which items should be +copied. + +This example uses the following folder structure containing the files to be copied: + +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` + +In this example, `Copy-Item` is called with a wildcard for both the **Path** and **Include** +parameters. Specifying a wildcard for the **Path** parameter ensures that it processes all of the +files and folders that match `D:\temp\tree\*`. The **Include** parameter filters the list of items +to process, limiting the operation to only those paths that begin with `ex`. + +```powershell +PS D:\temp\test\out> Copy-Item -Path D:\temp\tree\* -Include ex* +PS D:\temp\test\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example.ps1 +D:\temp\out\example.txt +``` + +The **Include** parameter is applied to the contents of `D:\temp\tree` folder to copy all items that +match `ex*`. Notice that, without recursion, the `D:\temp\out\examples` folder is copied, but none +of its contents are copied. + +### Example 15: Using filters to copy items with recursion + +This example shows the results using the **Include** parameter to select which items should be +copied. + +This example uses the following folder structure containing the files to be copied: + +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` + +In this example, `Copy-Item` is called with a wildcard for both the **Path** and **Include** +parameters. Specifying a wildcard for the **Path** parameter ensures that it processes all the files +and folders that match `D:\temp\tree\*`. The **Include** parameter filters the list of items to +process, limiting the operation to only those paths that begin with `ex`. + +```powershell +D:\temp\out> Copy-Item -Path D:\temp\tree\* -Include ex* -Recurse +D:\temp\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example.ps1 +D:\temp\out\example.txt +D:\temp\out\examples\subfolder +D:\temp\out\examples\example_1.txt +D:\temp\out\examples\example_2.txt +D:\temp\out\examples\subfolder\test.txt +``` + +The **Include** parameter is applied to the contents of `D:\temp\tree` folder to copy all items that +match `ex*`. Notice that, with recursion, the `D:\temp\out\examples` folder is copied along with all +the files and subfolders. The copy includes files that _do not_ match the include filter. When using +`Copy-Item`, the filters only apply to the top-level specified by the **Path** parameter. Then +recursion is applied to those matching items. + +> [!NOTE] +> The behavior of the **Exclude** parameter is the same as described in this example, except that +> it limits the operation to only those paths which do not match the pattern. + +### Example 15: Limit the files to recursively copy from a wildcard-specified path + +This example shows how to limit the files recursively copied from a wildcard-matching path into +another folder. Example 13 shows that, because the **Include** parameter only filters on the paths +resolved for a wildcard-specifying **Path**, the **Include** parameter can't be used to limit the +files recursively copied from a folder. Instead, you can use `Get-ChildItem` to find the items you +want to copy and pass those items to `Copy-Item`. + +This example uses the following folder structure containing the files to be copied: + +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` + +To copy all items that begin with `ex*`, use `Get-ChildItem` with the **Recurse** and **Filter** +parameters and pipe the results to `Copy-Item`. + +```powershell +D:\temp\out> Get-ChildItem -Path D:\temp\tree -Recurse -Filter ex* | Copy-Item +D:\temp\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example_1.txt +D:\temp\out\example_2.txt +D:\temp\out\example.ps1 +D:\temp\out\example.txt +``` + +Unlike the `Copy-Item`, the **Filter** parameter for `Get-ChildItem` applies to the items discovered +during recursion. This enables you to find, filter, and then copy items recursively. + ## PARAMETERS ### -Container @@ -308,11 +416,12 @@ Accept wildcard characters: False ### -Exclude -Specifies, as a string array, an item or items that this cmdlet excludes in the operation. The value -of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as -`*.txt`. Wildcard characters are permitted. The **Exclude** parameter is effective only when the -command includes the contents of an item, such as `C:\Windows\*`, where the wildcard character -specifies the contents of the `C:\Windows` directory. +Specifies one or more path elements or patterns, such as `"*.txt"`, to limit this cmdlet's +operation. The value of this parameter filters against the wildcard-matching result of the **Path** +parameter, not the final results. This parameter is only effective when the **Path** is specified +with one or more wildcards. Since this parameter only filters on the paths resolved for the **Path** +parameter, it does not filter any items discovered when recursing through child folders with the +**Recurse** parameter. ```yaml Type: System.String[] @@ -328,11 +437,13 @@ Accept wildcard characters: True ### -Filter -Specifies a filter to qualify the **Path** parameter. The [FileSystem](../Microsoft.PowerShell.Core/About/about_FileSystem_Provider.md) -provider is the only installed PowerShell provider that supports the use of filters. You can find -the syntax for the **FileSystem** filter language in [about_Wildcards](../Microsoft.PowerShell.Core/About/about_Wildcards.md). -Filters are more efficient than other parameters, because the provider applies them when the cmdlet -gets the objects rather than having PowerShell filter the objects after they're retrieved. +Specifies a filter to qualify the **Path** parameter. The +[FileSystem](../Microsoft.PowerShell.Core/About/about_FileSystem_Provider.md) provider is the only +installed PowerShell provider that supports the use of filters. You can find the syntax for the +**FileSystem** filter language in +[about_Wildcards](../Microsoft.PowerShell.Core/About/about_Wildcards.md). Filters are more efficient +than other parameters, because the provider applies them when the cmdlet gets the objects rather +than having PowerShell filter the objects after they're retrieved. ```yaml Type: System.String @@ -383,11 +494,12 @@ Accept wildcard characters: False ### -Include -Specifies, as a string array, an item or items that this cmdlet includes in the operation. The value -of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as -`"*.txt"`. Wildcard characters are permitted. The **Include** parameter is effective only when the -command includes the contents of an item, such as `C:\Windows\*`, where the wildcard character -specifies the contents of the `C:\Windows` directory. +Specifies one or more path elements or patterns, such as `"*.txt"`, to limit this cmdlet's +operation. The value of this parameter filters against the wildcard-matching result of the **Path** +parameter, not the final results. This parameter is only effective when the **Path** is specified +with one or more wildcards. Since this parameter only filters on the paths resolved for the **Path** +parameter, it does not filter any items discovered when recursing through child folders with the +**Recurse** parameter. ```yaml Type: System.String[] @@ -523,9 +635,10 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, -`-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, -`-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -543,7 +656,8 @@ item. Otherwise, this cmdlet doesn't generate any output. ## NOTES This cmdlet is designed to work with the data exposed by any provider. To list the providers -available in your session, type `Get-PSProvider`. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). +available in your session, type `Get-PSProvider`. For more information, see +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ## RELATED LINKS diff --git a/reference/7.1/Microsoft.PowerShell.Management/Copy-Item.md b/reference/7.1/Microsoft.PowerShell.Management/Copy-Item.md index e3387e65b32a..711c295f96c5 100644 --- a/reference/7.1/Microsoft.PowerShell.Management/Copy-Item.md +++ b/reference/7.1/Microsoft.PowerShell.Management/Copy-Item.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 01/18/2022 +ms.date: 04/12/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/copy-item?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: Copy-Item @@ -250,6 +250,114 @@ The `Copy-Item` cmdlet has the **Container** parameter set to `$false`. This cau the source folder to be copied but does not preserve the folder structure. Notice that files with the same name are overwritten in the destination folder. +### Example 13: Using filters to copy items without recursion + +This example shows the results using the **Include** parameter to select which items should be +copied. + +This example uses the following folder structure containing the files to be copied: + +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` + +In this example, `Copy-Item` is called with a wildcard for both the **Path** and **Include** +parameters. Specifying a wildcard for the **Path** parameter ensures that it processes all of the +files and folders that match `D:\temp\tree\*`. The **Include** parameter filters the list of items +to process, limiting the operation to only those paths that begin with `ex`. + +```powershell +PS D:\temp\test\out> Copy-Item -Path D:\temp\tree\* -Include ex* +PS D:\temp\test\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example.ps1 +D:\temp\out\example.txt +``` + +The **Include** parameter is applied to the contents of `D:\temp\tree` folder to copy all items that +match `ex*`. Notice that, without recursion, the `D:\temp\out\examples` folder is copied, but none +of its contents are copied. + +### Example 15: Using filters to copy items with recursion + +This example shows the results using the **Include** parameter to select which items should be +copied. + +This example uses the following folder structure containing the files to be copied: + +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` + +In this example, `Copy-Item` is called with a wildcard for both the **Path** and **Include** +parameters. Specifying a wildcard for the **Path** parameter ensures that it processes all the files +and folders that match `D:\temp\tree\*`. The **Include** parameter filters the list of items to +process, limiting the operation to only those paths that begin with `ex`. + +```powershell +D:\temp\out> Copy-Item -Path D:\temp\tree\* -Include ex* -Recurse +D:\temp\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example.ps1 +D:\temp\out\example.txt +D:\temp\out\examples\subfolder +D:\temp\out\examples\example_1.txt +D:\temp\out\examples\example_2.txt +D:\temp\out\examples\subfolder\test.txt +``` + +The **Include** parameter is applied to the contents of `D:\temp\tree` folder to copy all items that +match `ex*`. Notice that, with recursion, the `D:\temp\out\examples` folder is copied along with all +the files and subfolders. The copy includes files that _do not_ match the include filter. When using +`Copy-Item`, the filters only apply to the top-level specified by the **Path** parameter. Then +recursion is applied to those matching items. + +> [!NOTE] +> The behavior of the **Exclude** parameter is the same as described in this example, except that +> it limits the operation to only those paths which do not match the pattern. + +### Example 15: Limit the files to recursively copy from a wildcard-specified path + +This example shows how to limit the files recursively copied from a wildcard-matching path into +another folder. Example 13 shows that, because the **Include** parameter only filters on the paths +resolved for a wildcard-specifying **Path**, the **Include** parameter can't be used to limit the +files recursively copied from a folder. Instead, you can use `Get-ChildItem` to find the items you +want to copy and pass those items to `Copy-Item`. + +This example uses the following folder structure containing the files to be copied: + +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` + +To copy all items that begin with `ex*`, use `Get-ChildItem` with the **Recurse** and **Filter** +parameters and pipe the results to `Copy-Item`. + +```powershell +D:\temp\out> Get-ChildItem -Path D:\temp\tree -Recurse -Filter ex* | Copy-Item +D:\temp\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example_1.txt +D:\temp\out\example_2.txt +D:\temp\out\example.ps1 +D:\temp\out\example.txt +``` + +Unlike the `Copy-Item`, the **Filter** parameter for `Get-ChildItem` applies to the items discovered +during recursion. This enables you to find, filter, and then copy items recursively. + ## PARAMETERS ### -Container @@ -308,11 +416,12 @@ Accept wildcard characters: False ### -Exclude -Specifies, as a string array, an item or items that this cmdlet excludes in the operation. The value -of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as -`*.txt`. Wildcard characters are permitted. The **Exclude** parameter is effective only when the -command includes the contents of an item, such as `C:\Windows\*`, where the wildcard character -specifies the contents of the `C:\Windows` directory. +Specifies one or more path elements or patterns, such as `"*.txt"`, to limit this cmdlet's +operation. The value of this parameter filters against the wildcard-matching result of the **Path** +parameter, not the final results. This parameter is only effective when the **Path** is specified +with one or more wildcards. Since this parameter only filters on the paths resolved for the **Path** +parameter, it does not filter any items discovered when recursing through child folders with the +**Recurse** parameter. ```yaml Type: System.String[] @@ -328,11 +437,13 @@ Accept wildcard characters: True ### -Filter -Specifies a filter to qualify the **Path** parameter. The [FileSystem](../Microsoft.PowerShell.Core/About/about_FileSystem_Provider.md) -provider is the only installed PowerShell provider that supports the use of filters. You can find -the syntax for the **FileSystem** filter language in [about_Wildcards](../Microsoft.PowerShell.Core/About/about_Wildcards.md). -Filters are more efficient than other parameters, because the provider applies them when the cmdlet -gets the objects rather than having PowerShell filter the objects after they're retrieved. +Specifies a filter to qualify the **Path** parameter. The +[FileSystem](../Microsoft.PowerShell.Core/About/about_FileSystem_Provider.md) provider is the only +installed PowerShell provider that supports the use of filters. You can find the syntax for the +**FileSystem** filter language in +[about_Wildcards](../Microsoft.PowerShell.Core/About/about_Wildcards.md). Filters are more efficient +than other parameters, because the provider applies them when the cmdlet gets the objects rather +than having PowerShell filter the objects after they're retrieved. ```yaml Type: System.String @@ -383,11 +494,12 @@ Accept wildcard characters: False ### -Include -Specifies, as a string array, an item or items that this cmdlet includes in the operation. The value -of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as -`"*.txt"`. Wildcard characters are permitted. The **Include** parameter is effective only when the -command includes the contents of an item, such as `C:\Windows\*`, where the wildcard character -specifies the contents of the `C:\Windows` directory. +Specifies one or more path elements or patterns, such as `"*.txt"`, to limit this cmdlet's +operation. The value of this parameter filters against the wildcard-matching result of the **Path** +parameter, not the final results. This parameter is only effective when the **Path** is specified +with one or more wildcards. Since this parameter only filters on the paths resolved for the **Path** +parameter, it does not filter any items discovered when recursing through child folders with the +**Recurse** parameter. ```yaml Type: System.String[] @@ -523,9 +635,10 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, -`-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, -`-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -543,7 +656,8 @@ item. Otherwise, this cmdlet doesn't generate any output. ## NOTES This cmdlet is designed to work with the data exposed by any provider. To list the providers -available in your session, type `Get-PSProvider`. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). +available in your session, type `Get-PSProvider`. For more information, see +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ## RELATED LINKS @@ -566,4 +680,3 @@ available in your session, type `Get-PSProvider`. For more information, see [abo [Rename-Item](Rename-Item.md) [Set-Item](Set-Item.md) - diff --git a/reference/7.2/Microsoft.PowerShell.Management/Copy-Item.md b/reference/7.2/Microsoft.PowerShell.Management/Copy-Item.md index 14ea5e14dd4d..b8ef709fb407 100644 --- a/reference/7.2/Microsoft.PowerShell.Management/Copy-Item.md +++ b/reference/7.2/Microsoft.PowerShell.Management/Copy-Item.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 01/18/2022 +ms.date: 04/12/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/copy-item?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: Copy-Item @@ -250,6 +250,114 @@ The `Copy-Item` cmdlet has the **Container** parameter set to `$false`. This cau the source folder to be copied but does not preserve the folder structure. Notice that files with the same name are overwritten in the destination folder. +### Example 13: Using filters to copy items without recursion + +This example shows the results using the **Include** parameter to select which items should be +copied. + +This example uses the following folder structure containing the files to be copied: + +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` + +In this example, `Copy-Item` is called with a wildcard for both the **Path** and **Include** +parameters. Specifying a wildcard for the **Path** parameter ensures that it processes all of the +files and folders that match `D:\temp\tree\*`. The **Include** parameter filters the list of items +to process, limiting the operation to only those paths that begin with `ex`. + +```powershell +PS D:\temp\test\out> Copy-Item -Path D:\temp\tree\* -Include ex* +PS D:\temp\test\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example.ps1 +D:\temp\out\example.txt +``` + +The **Include** parameter is applied to the contents of `D:\temp\tree` folder to copy all items that +match `ex*`. Notice that, without recursion, the `D:\temp\out\examples` folder is copied, but none +of its contents are copied. + +### Example 15: Using filters to copy items with recursion + +This example shows the results using the **Include** parameter to select which items should be +copied. + +This example uses the following folder structure containing the files to be copied: + +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` + +In this example, `Copy-Item` is called with a wildcard for both the **Path** and **Include** +parameters. Specifying a wildcard for the **Path** parameter ensures that it processes all the files +and folders that match `D:\temp\tree\*`. The **Include** parameter filters the list of items to +process, limiting the operation to only those paths that begin with `ex`. + +```powershell +D:\temp\out> Copy-Item -Path D:\temp\tree\* -Include ex* -Recurse +D:\temp\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example.ps1 +D:\temp\out\example.txt +D:\temp\out\examples\subfolder +D:\temp\out\examples\example_1.txt +D:\temp\out\examples\example_2.txt +D:\temp\out\examples\subfolder\test.txt +``` + +The **Include** parameter is applied to the contents of `D:\temp\tree` folder to copy all items that +match `ex*`. Notice that, with recursion, the `D:\temp\out\examples` folder is copied along with all +the files and subfolders. The copy includes files that _do not_ match the include filter. When using +`Copy-Item`, the filters only apply to the top-level specified by the **Path** parameter. Then +recursion is applied to those matching items. + +> [!NOTE] +> The behavior of the **Exclude** parameter is the same as described in this example, except that +> it limits the operation to only those paths which do not match the pattern. + +### Example 15: Limit the files to recursively copy from a wildcard-specified path + +This example shows how to limit the files recursively copied from a wildcard-matching path into +another folder. Example 13 shows that, because the **Include** parameter only filters on the paths +resolved for a wildcard-specifying **Path**, the **Include** parameter can't be used to limit the +files recursively copied from a folder. Instead, you can use `Get-ChildItem` to find the items you +want to copy and pass those items to `Copy-Item`. + +This example uses the following folder structure containing the files to be copied: + +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` + +To copy all items that begin with `ex*`, use `Get-ChildItem` with the **Recurse** and **Filter** +parameters and pipe the results to `Copy-Item`. + +```powershell +D:\temp\out> Get-ChildItem -Path D:\temp\tree -Recurse -Filter ex* | Copy-Item +D:\temp\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example_1.txt +D:\temp\out\example_2.txt +D:\temp\out\example.ps1 +D:\temp\out\example.txt +``` + +Unlike the `Copy-Item`, the **Filter** parameter for `Get-ChildItem` applies to the items discovered +during recursion. This enables you to find, filter, and then copy items recursively. + ## PARAMETERS ### -Container @@ -308,11 +416,12 @@ Accept wildcard characters: False ### -Exclude -Specifies, as a string array, an item or items that this cmdlet excludes in the operation. The value -of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as -`*.txt`. Wildcard characters are permitted. The **Exclude** parameter is effective only when the -command includes the contents of an item, such as `C:\Windows\*`, where the wildcard character -specifies the contents of the `C:\Windows` directory. +Specifies one or more path elements or patterns, such as `"*.txt"`, to limit this cmdlet's +operation. The value of this parameter filters against the wildcard-matching result of the **Path** +parameter, not the final results. This parameter is only effective when the **Path** is specified +with one or more wildcards. Since this parameter only filters on the paths resolved for the **Path** +parameter, it does not filter any items discovered when recursing through child folders with the +**Recurse** parameter. ```yaml Type: System.String[] @@ -328,11 +437,13 @@ Accept wildcard characters: True ### -Filter -Specifies a filter to qualify the **Path** parameter. The [FileSystem](../Microsoft.PowerShell.Core/About/about_FileSystem_Provider.md) -provider is the only installed PowerShell provider that supports the use of filters. You can find -the syntax for the **FileSystem** filter language in [about_Wildcards](../Microsoft.PowerShell.Core/About/about_Wildcards.md). -Filters are more efficient than other parameters, because the provider applies them when the cmdlet -gets the objects rather than having PowerShell filter the objects after they're retrieved. +Specifies a filter to qualify the **Path** parameter. The +[FileSystem](../Microsoft.PowerShell.Core/About/about_FileSystem_Provider.md) provider is the only +installed PowerShell provider that supports the use of filters. You can find the syntax for the +**FileSystem** filter language in +[about_Wildcards](../Microsoft.PowerShell.Core/About/about_Wildcards.md). Filters are more efficient +than other parameters, because the provider applies them when the cmdlet gets the objects rather +than having PowerShell filter the objects after they're retrieved. ```yaml Type: System.String @@ -383,11 +494,12 @@ Accept wildcard characters: False ### -Include -Specifies, as a string array, an item or items that this cmdlet includes in the operation. The value -of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as -`"*.txt"`. Wildcard characters are permitted. The **Include** parameter is effective only when the -command includes the contents of an item, such as `C:\Windows\*`, where the wildcard character -specifies the contents of the `C:\Windows` directory. +Specifies one or more path elements or patterns, such as `"*.txt"`, to limit this cmdlet's +operation. The value of this parameter filters against the wildcard-matching result of the **Path** +parameter, not the final results. This parameter is only effective when the **Path** is specified +with one or more wildcards. Since this parameter only filters on the paths resolved for the **Path** +parameter, it does not filter any items discovered when recursing through child folders with the +**Recurse** parameter. ```yaml Type: System.String[] @@ -523,9 +635,10 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, -`-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, -`-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -543,7 +656,8 @@ item. Otherwise, this cmdlet doesn't generate any output. ## NOTES This cmdlet is designed to work with the data exposed by any provider. To list the providers -available in your session, type `Get-PSProvider`. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). +available in your session, type `Get-PSProvider`. For more information, see +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ## RELATED LINKS @@ -566,4 +680,3 @@ available in your session, type `Get-PSProvider`. For more information, see [abo [Rename-Item](Rename-Item.md) [Set-Item](Set-Item.md) - diff --git a/reference/7.3/Microsoft.PowerShell.Management/Copy-Item.md b/reference/7.3/Microsoft.PowerShell.Management/Copy-Item.md index f34c15530341..026bd20df688 100644 --- a/reference/7.3/Microsoft.PowerShell.Management/Copy-Item.md +++ b/reference/7.3/Microsoft.PowerShell.Management/Copy-Item.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 08/25/2020 +ms.date: 04/12/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/copy-item?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: Copy-Item @@ -250,6 +250,114 @@ The `Copy-Item` cmdlet has the **Container** parameter set to `$false`. This cau the source folder to be copied but does not preserve the folder structure. Notice that files with the same name are overwritten in the destination folder. +### Example 13: Using filters to copy items without recursion + +This example shows the results using the **Include** parameter to select which items should be +copied. + +This example uses the following folder structure containing the files to be copied: + +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` + +In this example, `Copy-Item` is called with a wildcard for both the **Path** and **Include** +parameters. Specifying a wildcard for the **Path** parameter ensures that it processes all of the +files and folders that match `D:\temp\tree\*`. The **Include** parameter filters the list of items +to process, limiting the operation to only those paths that begin with `ex`. + +```powershell +PS D:\temp\test\out> Copy-Item -Path D:\temp\tree\* -Include ex* +PS D:\temp\test\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example.ps1 +D:\temp\out\example.txt +``` + +The **Include** parameter is applied to the contents of `D:\temp\tree` folder to copy all items that +match `ex*`. Notice that, without recursion, the `D:\temp\out\examples` folder is copied, but none +of its contents are copied. + +### Example 15: Using filters to copy items with recursion + +This example shows the results using the **Include** parameter to select which items should be +copied. + +This example uses the following folder structure containing the files to be copied: + +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` + +In this example, `Copy-Item` is called with a wildcard for both the **Path** and **Include** +parameters. Specifying a wildcard for the **Path** parameter ensures that it processes all the files +and folders that match `D:\temp\tree\*`. The **Include** parameter filters the list of items to +process, limiting the operation to only those paths that begin with `ex`. + +```powershell +D:\temp\out> Copy-Item -Path D:\temp\tree\* -Include ex* -Recurse +D:\temp\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example.ps1 +D:\temp\out\example.txt +D:\temp\out\examples\subfolder +D:\temp\out\examples\example_1.txt +D:\temp\out\examples\example_2.txt +D:\temp\out\examples\subfolder\test.txt +``` + +The **Include** parameter is applied to the contents of `D:\temp\tree` folder to copy all items that +match `ex*`. Notice that, with recursion, the `D:\temp\out\examples` folder is copied along with all +the files and subfolders. The copy includes files that _do not_ match the include filter. When using +`Copy-Item`, the filters only apply to the top-level specified by the **Path** parameter. Then +recursion is applied to those matching items. + +> [!NOTE] +> The behavior of the **Exclude** parameter is the same as described in this example, except that +> it limits the operation to only those paths which do not match the pattern. + +### Example 15: Limit the files to recursively copy from a wildcard-specified path + +This example shows how to limit the files recursively copied from a wildcard-matching path into +another folder. Example 13 shows that, because the **Include** parameter only filters on the paths +resolved for a wildcard-specifying **Path**, the **Include** parameter can't be used to limit the +files recursively copied from a folder. Instead, you can use `Get-ChildItem` to find the items you +want to copy and pass those items to `Copy-Item`. + +This example uses the following folder structure containing the files to be copied: + +- `D:\temp\tree\example.ps1` +- `D:\temp\tree\example.txt` +- `D:\temp\tree\examples\` +- `D:\temp\tree\examples\example_1.txt` +- `D:\temp\tree\examples\example_2.txt` +- `D:\temp\tree\examples\subfolder\` +- `D:\temp\tree\examples\subfolder\test.txt` + +To copy all items that begin with `ex*`, use `Get-ChildItem` with the **Recurse** and **Filter** +parameters and pipe the results to `Copy-Item`. + +```powershell +D:\temp\out> Get-ChildItem -Path D:\temp\tree -Recurse -Filter ex* | Copy-Item +D:\temp\out> (Get-ChildItem -Recurse).FullName +D:\temp\out\examples +D:\temp\out\example_1.txt +D:\temp\out\example_2.txt +D:\temp\out\example.ps1 +D:\temp\out\example.txt +``` + +Unlike the `Copy-Item`, the **Filter** parameter for `Get-ChildItem` applies to the items discovered +during recursion. This enables you to find, filter, and then copy items recursively. + ## PARAMETERS ### -Container @@ -308,11 +416,12 @@ Accept wildcard characters: False ### -Exclude -Specifies, as a string array, an item or items that this cmdlet excludes in the operation. The value -of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as -`*.txt`. Wildcard characters are permitted. The **Exclude** parameter is effective only when the -command includes the contents of an item, such as `C:\Windows\*`, where the wildcard character -specifies the contents of the `C:\Windows` directory. +Specifies one or more path elements or patterns, such as `"*.txt"`, to limit this cmdlet's +operation. The value of this parameter filters against the wildcard-matching result of the **Path** +parameter, not the final results. This parameter is only effective when the **Path** is specified +with one or more wildcards. Since this parameter only filters on the paths resolved for the **Path** +parameter, it does not filter any items discovered when recursing through child folders with the +**Recurse** parameter. ```yaml Type: System.String[] @@ -328,11 +437,13 @@ Accept wildcard characters: True ### -Filter -Specifies a filter to qualify the **Path** parameter. The [FileSystem](../Microsoft.PowerShell.Core/About/about_FileSystem_Provider.md) -provider is the only installed PowerShell provider that supports the use of filters. You can find -the syntax for the **FileSystem** filter language in [about_Wildcards](../Microsoft.PowerShell.Core/About/about_Wildcards.md). -Filters are more efficient than other parameters, because the provider applies them when the cmdlet -gets the objects rather than having PowerShell filter the objects after they're retrieved. +Specifies a filter to qualify the **Path** parameter. The +[FileSystem](../Microsoft.PowerShell.Core/About/about_FileSystem_Provider.md) provider is the only +installed PowerShell provider that supports the use of filters. You can find the syntax for the +**FileSystem** filter language in +[about_Wildcards](../Microsoft.PowerShell.Core/About/about_Wildcards.md). Filters are more efficient +than other parameters, because the provider applies them when the cmdlet gets the objects rather +than having PowerShell filter the objects after they're retrieved. ```yaml Type: System.String @@ -383,11 +494,12 @@ Accept wildcard characters: False ### -Include -Specifies, as a string array, an item or items that this cmdlet includes in the operation. The value -of this parameter qualifies the **Path** parameter. Enter a path element or pattern, such as -`"*.txt"`. Wildcard characters are permitted. The **Include** parameter is effective only when the -command includes the contents of an item, such as `C:\Windows\*`, where the wildcard character -specifies the contents of the `C:\Windows` directory. +Specifies one or more path elements or patterns, such as `"*.txt"`, to limit this cmdlet's +operation. The value of this parameter filters against the wildcard-matching result of the **Path** +parameter, not the final results. This parameter is only effective when the **Path** is specified +with one or more wildcards. Since this parameter only filters on the paths resolved for the **Path** +parameter, it does not filter any items discovered when recursing through child folders with the +**Recurse** parameter. ```yaml Type: System.String[] @@ -523,9 +635,10 @@ Accept wildcard characters: False ### CommonParameters -This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, -`-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, -`-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -543,7 +656,8 @@ item. Otherwise, this cmdlet doesn't generate any output. ## NOTES This cmdlet is designed to work with the data exposed by any provider. To list the providers -available in your session, type `Get-PSProvider`. For more information, see [about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). +available in your session, type `Get-PSProvider`. For more information, see +[about_Providers](../Microsoft.PowerShell.Core/About/about_Providers.md). ## RELATED LINKS @@ -566,4 +680,3 @@ available in your session, type `Get-PSProvider`. For more information, see [abo [Rename-Item](Rename-Item.md) [Set-Item](Set-Item.md) - From 899a0a31bb63d1c4a4edd4d958ca0cbc27aa28cd Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 14 Apr 2022 10:15:42 -0500 Subject: [PATCH 12/31] Clarify the purpose of network hosts (#8737) --- reference/docs-conceptual/gallery/getting-started.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/reference/docs-conceptual/gallery/getting-started.md b/reference/docs-conceptual/gallery/getting-started.md index e04002bcb440..1838fa1283ab 100644 --- a/reference/docs-conceptual/gallery/getting-started.md +++ b/reference/docs-conceptual/gallery/getting-started.md @@ -129,16 +129,19 @@ your system that were installed directly from the PowerShell Gallery. ## Network access to the PowerShell Gallery -The PowerShell Gallery uses the following hostnames. +These hostnames should be added to the allow lists that control access from your network. + +Hosts required for package discovery and download: - `psg-prod-eastus.azureedge.net` - CDN hostname - `az818661.vo.msecnd.net` - CDN hostname + +Hosts required when using the PowerShell Gallery website: + - `devopsgallerystorage.blob.core.windows.net` - storage account hostname - `*.powershellgallery.com` - website - `go.microsoft.com` - redirection service -These hostnames should be added to the allow lists that control access from your network. - [!INCLUDE [TLS 1.2 Requirement](../../includes/tls-gallery.md)] [Find-DscResource]: /powershell/module/powershellget/Find-DscResource From 791b0d8bd512551fe181eec64eba416d9cd844f7 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Sat, 16 Apr 2022 08:16:56 -0500 Subject: [PATCH 13/31] Update 2022-updates.md --- reference/docs-conceptual/community/2022-updates.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/reference/docs-conceptual/community/2022-updates.md b/reference/docs-conceptual/community/2022-updates.md index 0d96959d7b7f..8450f049e70e 100644 --- a/reference/docs-conceptual/community/2022-updates.md +++ b/reference/docs-conceptual/community/2022-updates.md @@ -135,3 +135,6 @@ issues. Thank you! | julian-hansen | 1 | | | Hrxn | 1 | | | peteraritchie | 1 | | + + +[contrib]: contributing/overview.md From b5321f0ac96b693421b2282f435fe7469615bf81 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Mon, 18 Apr 2022 08:59:49 -0500 Subject: [PATCH 14/31] Update list of cmdlets that support -ComputerName (#8742) --- .../learn/remoting/powershell-remoting-faq.yml | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/reference/docs-conceptual/learn/remoting/powershell-remoting-faq.yml b/reference/docs-conceptual/learn/remoting/powershell-remoting-faq.yml index 9254e9d5dbb4..6a7aa9ccd299 100644 --- a/reference/docs-conceptual/learn/remoting/powershell-remoting-faq.yml +++ b/reference/docs-conceptual/learn/remoting/powershell-remoting-faq.yml @@ -2,7 +2,7 @@ metadata: description: Contains questions and answers about running remote commands in PowerShell. Locale: en-US - ms.date: 06/10/2021 + ms.date: 04/18/2022 online version: https schema: 2.0.0 title: PowerShell Remoting FAQ @@ -79,7 +79,7 @@ sections: - question: | Do all remote commands require PowerShell remoting? answer: | - No. Several cmdlets have a **ComputerName** parameter that lets you get objects from the + No. Some cmdlets have a **ComputerName** parameter that lets you get objects from the remote computer. These cmdlets do not use PowerShell remoting. So, you can use them on any computer that is @@ -88,11 +88,10 @@ sections: These cmdlets include the following: - - `Get-Process` - - `Get-Service` - - `Get-WinEvent` - - `Get-EventLog` - - `Test-Connection` + - `Get-Hotfix` + - `Rename-Computer` + - `Restart-Computer` + - `Stop-Computer` To find all the cmdlets with a **ComputerName** parameter, type: @@ -113,7 +112,7 @@ sections: For example: ```PowerShell - Get-Help Get-Process -Parameter ComputerName + Get-Help Get-Hotfix -Parameter ComputerName ``` For all other commands, use the `Invoke-Command` cmdlet. From c5c320dde2e43843f63730ce0c97c29ea0dff062 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 20 Apr 2022 16:46:53 -0500 Subject: [PATCH 15/31] Add hostname to allow list (#8746) --- reference/docs-conceptual/gallery/getting-started.md | 1 + 1 file changed, 1 insertion(+) diff --git a/reference/docs-conceptual/gallery/getting-started.md b/reference/docs-conceptual/gallery/getting-started.md index 1838fa1283ab..20dec19ee4fe 100644 --- a/reference/docs-conceptual/gallery/getting-started.md +++ b/reference/docs-conceptual/gallery/getting-started.md @@ -133,6 +133,7 @@ These hostnames should be added to the allow lists that control access from your Hosts required for package discovery and download: +- `onegetcdn.azureedge.net` - CDN hostname - `psg-prod-eastus.azureedge.net` - CDN hostname - `az818661.vo.msecnd.net` - CDN hostname From cd107e1d14ed26b92700a5525377c4e5b280c39d Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 21 Apr 2022 11:18:45 -0500 Subject: [PATCH 16/31] Fix filename (#8750) * Fix filename * Fix filename --- .../About/{about_Module_Manifest.md => about_Module_Manifests.md} | 0 .../About/{about_Module_Manifest.md => about_Module_Manifests.md} | 0 .../About/{about_Module_Manifest.md => about_Module_Manifests.md} | 0 .../About/{about_Module_Manifest.md => about_Module_Manifests.md} | 0 .../About/{about_Module_Manifest.md => about_Module_Manifests.md} | 0 5 files changed, 0 insertions(+), 0 deletions(-) rename reference/5.1/Microsoft.PowerShell.Core/About/{about_Module_Manifest.md => about_Module_Manifests.md} (100%) rename reference/7.0/Microsoft.PowerShell.Core/About/{about_Module_Manifest.md => about_Module_Manifests.md} (100%) rename reference/7.1/Microsoft.PowerShell.Core/About/{about_Module_Manifest.md => about_Module_Manifests.md} (100%) rename reference/7.2/Microsoft.PowerShell.Core/About/{about_Module_Manifest.md => about_Module_Manifests.md} (100%) rename reference/7.3/Microsoft.PowerShell.Core/About/{about_Module_Manifest.md => about_Module_Manifests.md} (100%) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifests.md similarity index 100% rename from reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md rename to reference/5.1/Microsoft.PowerShell.Core/About/about_Module_Manifests.md diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Module_Manifest.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Module_Manifests.md similarity index 100% rename from reference/7.0/Microsoft.PowerShell.Core/About/about_Module_Manifest.md rename to reference/7.0/Microsoft.PowerShell.Core/About/about_Module_Manifests.md diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Module_Manifests.md similarity index 100% rename from reference/7.1/Microsoft.PowerShell.Core/About/about_Module_Manifest.md rename to reference/7.1/Microsoft.PowerShell.Core/About/about_Module_Manifests.md diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Module_Manifest.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Module_Manifests.md similarity index 100% rename from reference/7.2/Microsoft.PowerShell.Core/About/about_Module_Manifest.md rename to reference/7.2/Microsoft.PowerShell.Core/About/about_Module_Manifests.md diff --git a/reference/7.3/Microsoft.PowerShell.Core/About/about_Module_Manifest.md b/reference/7.3/Microsoft.PowerShell.Core/About/about_Module_Manifests.md similarity index 100% rename from reference/7.3/Microsoft.PowerShell.Core/About/about_Module_Manifest.md rename to reference/7.3/Microsoft.PowerShell.Core/About/about_Module_Manifests.md From c88dc3ee6966c30bf76ddfb03442de41cdced334 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 21 Apr 2022 17:30:45 -0500 Subject: [PATCH 17/31] Fixes #8744 - Update PowerShellGet install documents (#8752) * Update PowerShellGet install documents * minor edits * Apply suggestions from code review Co-authored-by: Michael T Lombardi (He/Him) * Remove unused hostname Co-authored-by: Michael T Lombardi (He/Him) --- .../PackageManagement/PackageManagement.md | 7 +- reference/5.1/PowershellGet/PowerShellGet.md | 9 +- .../PackageManagement/PackageManagement.md | 7 +- reference/7.0/PowerShellGet/PowerShellGet.md | 9 +- .../PackageManagement/PackageManagement.md | 8 +- reference/7.1/PowerShellGet/PowerShellGet.md | 8 +- .../PackageManagement/PackageManagement.md | 7 +- reference/7.2/PowerShellGet/PowerShellGet.md | 8 +- .../PackageManagement/PackageManagement.md | 7 +- reference/7.3/PowerShellGet/PowerShellGet.md | 10 +- .../gallery/getting-started.md | 2 +- .../gallery/install-on-older-systems.md | 80 +++++++ .../gallery/installing-psget.md | 198 ++++++++---------- reference/docs-conceptual/gallery/overview.md | 59 +++--- reference/docs-conceptual/toc.yml | 4 +- 15 files changed, 246 insertions(+), 177 deletions(-) create mode 100644 reference/docs-conceptual/gallery/install-on-older-systems.md diff --git a/reference/5.1/PackageManagement/PackageManagement.md b/reference/5.1/PackageManagement/PackageManagement.md index 74252113542a..f35ba2bb8683 100644 --- a/reference/5.1/PackageManagement/PackageManagement.md +++ b/reference/5.1/PackageManagement/PackageManagement.md @@ -4,7 +4,7 @@ Help Version: 5.2.0.0 Locale: en-US Module Guid: 4ae9fd46-338a-459c-8186-07f910774cb8 Module Name: PackageManagement -ms.date: 06/09/2017 +ms.date: 04/21/2022 schema: 2.0.0 title: PackageManagement --- @@ -12,7 +12,8 @@ title: PackageManagement ## Description -This topic displays help topics for the Package Management Cmdlets. +This topic displays help topics for the Package Management Cmdlets. The cmdlet reference +documentation on this site documents the latest version of the module. > [!IMPORTANT] > As of April 2020, the PowerShell Gallery no longer supports Transport Layer Security (TLS) @@ -20,7 +21,7 @@ This topic displays help topics for the Package Management Cmdlets. > trying to access the PowerShell Gallery. Use the following command to ensure you are using TLS > 1.2: > -> `[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12` +> `[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12` > > For more information, see the > [announcement](https://devblogs.microsoft.com/powershell/powershell-gallery-tls-support/) in the diff --git a/reference/5.1/PowershellGet/PowerShellGet.md b/reference/5.1/PowershellGet/PowerShellGet.md index 1aad6a100d2d..78d6409b97a3 100644 --- a/reference/5.1/PowershellGet/PowerShellGet.md +++ b/reference/5.1/PowershellGet/PowerShellGet.md @@ -4,7 +4,7 @@ Help Version: 5.2.0.0 Locale: en-US Module Guid: 1d73a601-4a6c-43c5-ba3f-619b18bbb404 Module Name: PowerShellGet -ms.date: 06/09/2017 +ms.date: 04/21/2022 schema: 2.0.0 title: PowerShellGet --- @@ -15,13 +15,15 @@ title: PowerShellGet PowerShellGet is a module with commands for discovering, installing, updating and publishing PowerShell artifacts like Modules, DSC Resources, Role Capabilities, and Scripts. +The cmdlet reference documentation on this site documents the latest version of the module. + > [!IMPORTANT] > As of April 2020, the PowerShell Gallery no longer supports Transport Layer Security (TLS) > versions 1.0 and 1.1. If you are not using TLS 1.2 or higher, you will receive an error when > trying to access the PowerShell Gallery. Use the following command to ensure you are using TLS > 1.2: > -> `[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12` +> `[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12` > > For more information, see the > [announcement](https://devblogs.microsoft.com/powershell/powershell-gallery-tls-support/) in the @@ -93,8 +95,7 @@ Uninstalls a script. Unregisters a repository. ### [Update-Module](Update-Module.md) -Downloads and installs the newest version of specified modules from an online gallery to the local -computer. +Downloads and installs the newest version of specified modules from an online gallery to the local computer. ### [Update-ModuleManifest](Update-ModuleManifest.md) Updates a module manifest file. diff --git a/reference/7.0/PackageManagement/PackageManagement.md b/reference/7.0/PackageManagement/PackageManagement.md index a7c8c5c621f0..9faeb25e98bc 100644 --- a/reference/7.0/PackageManagement/PackageManagement.md +++ b/reference/7.0/PackageManagement/PackageManagement.md @@ -4,7 +4,7 @@ Help Version: 7.0.1.0 Locale: en-US Module Guid: 4ae9fd46-338a-459c-8186-07f910774cb8 Module Name: PackageManagement -ms.date: 06/09/2017 +ms.date: 04/21/2022 schema: 2.0.0 title: PackageManagement --- @@ -12,7 +12,8 @@ title: PackageManagement ## Description -This topic displays help topics for the Package Management Cmdlets. +This topic displays help topics for the Package Management Cmdlets. The cmdlet reference +documentation on this site documents the latest version of the module. > [!IMPORTANT] > As of April 2020, the PowerShell Gallery no longer supports Transport Layer Security (TLS) @@ -20,7 +21,7 @@ This topic displays help topics for the Package Management Cmdlets. > trying to access the PowerShell Gallery. Use the following command to ensure you are using TLS > 1.2: > -> `[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12` +> `[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12` > > For more information, see the > [announcement](https://devblogs.microsoft.com/powershell/powershell-gallery-tls-support/) in the diff --git a/reference/7.0/PowerShellGet/PowerShellGet.md b/reference/7.0/PowerShellGet/PowerShellGet.md index 6800ff7511c3..04a3274851d1 100644 --- a/reference/7.0/PowerShellGet/PowerShellGet.md +++ b/reference/7.0/PowerShellGet/PowerShellGet.md @@ -4,7 +4,7 @@ Help Version: 7.0.1.0 Locale: en-US Module Guid: 1d73a601-4a6c-43c5-ba3f-619b18bbb404 Module Name: PowerShellGet -ms.date: 06/09/2017 +ms.date: 04/21/2022 schema: 2.0.0 title: PowerShellGet --- @@ -15,13 +15,15 @@ title: PowerShellGet PowerShellGet is a module with commands for discovering, installing, updating and publishing PowerShell artifacts like Modules, DSC Resources, Role Capabilities, and Scripts. +The cmdlet reference documentation on this site documents the latest version of the module. + > [!IMPORTANT] > As of April 2020, the PowerShell Gallery no longer supports Transport Layer Security (TLS) > versions 1.0 and 1.1. If you are not using TLS 1.2 or higher, you will receive an error when > trying to access the PowerShell Gallery. Use the following command to ensure you are using TLS > 1.2: > -> `[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12` +> `[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12` > > For more information, see the > [announcement](https://devblogs.microsoft.com/powershell/powershell-gallery-tls-support/) in the @@ -33,7 +35,7 @@ PowerShell artifacts like Modules, DSC Resources, Role Capabilities, and Scripts Finds PowerShell commands in modules. ### [Find-DscResource](Find-DscResource.md) -Finds Desired State Configuration (DSC) resources. +Finds a DSC resource. ### [Find-Module](Find-Module.md) Finds modules in a repository that match specified criteria. @@ -103,4 +105,3 @@ Updates a script. ### [Update-ScriptFileInfo](Update-ScriptFileInfo.md) Updates information for a script. - diff --git a/reference/7.1/PackageManagement/PackageManagement.md b/reference/7.1/PackageManagement/PackageManagement.md index 896e2c1e6a03..0c6e053ca9c5 100644 --- a/reference/7.1/PackageManagement/PackageManagement.md +++ b/reference/7.1/PackageManagement/PackageManagement.md @@ -4,7 +4,7 @@ Help Version: 7.1.0.0 Locale: en-US Module Guid: 4ae9fd46-338a-459c-8186-07f910774cb8 Module Name: PackageManagement -ms.date: 06/09/2017 +ms.date: 04/21/2022 schema: 2.0.0 title: PackageManagement --- @@ -12,7 +12,8 @@ title: PackageManagement ## Description -This topic displays help topics for the Package Management Cmdlets. +This topic displays help topics for the Package Management Cmdlets. The cmdlet reference +documentation on this site documents the latest version of the module. > [!IMPORTANT] > As of April 2020, the PowerShell Gallery no longer supports Transport Layer Security (TLS) @@ -20,7 +21,7 @@ This topic displays help topics for the Package Management Cmdlets. > trying to access the PowerShell Gallery. Use the following command to ensure you are using TLS > 1.2: > -> `[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12` +> `[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12` > > For more information, see the > [announcement](https://devblogs.microsoft.com/powershell/powershell-gallery-tls-support/) in the @@ -66,4 +67,3 @@ Uninstalls one or more software packages. ### [Unregister-PackageSource](Unregister-PackageSource.md) Removes a registered package source. - diff --git a/reference/7.1/PowerShellGet/PowerShellGet.md b/reference/7.1/PowerShellGet/PowerShellGet.md index 6e2249eb2bd0..9e0a5676fb72 100644 --- a/reference/7.1/PowerShellGet/PowerShellGet.md +++ b/reference/7.1/PowerShellGet/PowerShellGet.md @@ -4,7 +4,7 @@ Help Version: 7.1.0.0 Locale: en-US Module Guid: 1d73a601-4a6c-43c5-ba3f-619b18bbb404 Module Name: PowerShellGet -ms.date: 06/09/2017 +ms.date: 04/21/2022 schema: 2.0.0 title: PowerShellGet --- @@ -15,13 +15,15 @@ title: PowerShellGet PowerShellGet is a module with commands for discovering, installing, updating and publishing PowerShell artifacts like Modules, DSC Resources, Role Capabilities, and Scripts. +The cmdlet reference documentation on this site documents the latest version of the module. + > [!IMPORTANT] > As of April 2020, the PowerShell Gallery no longer supports Transport Layer Security (TLS) > versions 1.0 and 1.1. If you are not using TLS 1.2 or higher, you will receive an error when > trying to access the PowerShell Gallery. Use the following command to ensure you are using TLS > 1.2: > -> `[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12` +> `[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12` > > For more information, see the > [announcement](https://devblogs.microsoft.com/powershell/powershell-gallery-tls-support/) in the @@ -33,7 +35,7 @@ PowerShell artifacts like Modules, DSC Resources, Role Capabilities, and Scripts Finds PowerShell commands in modules. ### [Find-DscResource](Find-DscResource.md) -Finds Desired State Configuration (DSC) resources. +Finds a DSC resource. ### [Find-Module](Find-Module.md) Finds modules in a repository that match specified criteria. diff --git a/reference/7.2/PackageManagement/PackageManagement.md b/reference/7.2/PackageManagement/PackageManagement.md index 6ef2c43412ab..e489a9608edb 100644 --- a/reference/7.2/PackageManagement/PackageManagement.md +++ b/reference/7.2/PackageManagement/PackageManagement.md @@ -4,7 +4,7 @@ Help Version: 7.2.0.0 Locale: en-US Module Guid: 4ae9fd46-338a-459c-8186-07f910774cb8 Module Name: PackageManagement -ms.date: 06/09/2017 +ms.date: 04/21/2022 schema: 2.0.0 title: PackageManagement --- @@ -12,7 +12,8 @@ title: PackageManagement ## Description -This topic displays help topics for the Package Management Cmdlets. +This topic displays help topics for the Package Management Cmdlets. The cmdlet reference +documentation on this site documents the latest version of the module. > [!IMPORTANT] > As of April 2020, the PowerShell Gallery no longer supports Transport Layer Security (TLS) @@ -20,7 +21,7 @@ This topic displays help topics for the Package Management Cmdlets. > trying to access the PowerShell Gallery. Use the following command to ensure you are using TLS > 1.2: > -> `[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12` +> `[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12` > > For more information, see the > [announcement](https://devblogs.microsoft.com/powershell/powershell-gallery-tls-support/) in the diff --git a/reference/7.2/PowerShellGet/PowerShellGet.md b/reference/7.2/PowerShellGet/PowerShellGet.md index d0b5ad00c4fe..a60d87f5f973 100644 --- a/reference/7.2/PowerShellGet/PowerShellGet.md +++ b/reference/7.2/PowerShellGet/PowerShellGet.md @@ -4,7 +4,7 @@ Help Version: 7.2.0.0 Locale: en-US Module Guid: 1d73a601-4a6c-43c5-ba3f-619b18bbb404 Module Name: PowerShellGet -ms.date: 06/09/2017 +ms.date: 04/21/2022 schema: 2.0.0 title: PowerShellGet --- @@ -15,13 +15,15 @@ title: PowerShellGet PowerShellGet is a module with commands for discovering, installing, updating and publishing PowerShell artifacts like Modules, DSC Resources, Role Capabilities, and Scripts. +The cmdlet reference documentation on this site documents the latest version of the module. + > [!IMPORTANT] > As of April 2020, the PowerShell Gallery no longer supports Transport Layer Security (TLS) > versions 1.0 and 1.1. If you are not using TLS 1.2 or higher, you will receive an error when > trying to access the PowerShell Gallery. Use the following command to ensure you are using TLS > 1.2: > -> `[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12` +> `[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12` > > For more information, see the > [announcement](https://devblogs.microsoft.com/powershell/powershell-gallery-tls-support/) in the @@ -33,7 +35,7 @@ PowerShell artifacts like Modules, DSC Resources, Role Capabilities, and Scripts Finds PowerShell commands in modules. ### [Find-DscResource](Find-DscResource.md) -Finds Desired State Configuration (DSC) resources. +Finds a DSC resource. ### [Find-Module](Find-Module.md) Finds modules in a repository that match specified criteria. diff --git a/reference/7.3/PackageManagement/PackageManagement.md b/reference/7.3/PackageManagement/PackageManagement.md index 72489eeee764..30f0c69093d3 100644 --- a/reference/7.3/PackageManagement/PackageManagement.md +++ b/reference/7.3/PackageManagement/PackageManagement.md @@ -4,7 +4,7 @@ Help Version: 7.2.0.0 Locale: en-US Module Guid: 4ae9fd46-338a-459c-8186-07f910774cb8 Module Name: PackageManagement -ms.date: 06/09/2017 +ms.date: 04/21/2022 schema: 2.0.0 title: PackageManagement --- @@ -12,7 +12,8 @@ title: PackageManagement ## Description -This topic displays help topics for the Package Management Cmdlets. +This topic displays help topics for the Package Management Cmdlets. The cmdlet reference +documentation on this site documents the latest version of the module. > [!IMPORTANT] > As of April 2020, the PowerShell Gallery no longer supports Transport Layer Security (TLS) @@ -20,7 +21,7 @@ This topic displays help topics for the Package Management Cmdlets. > trying to access the PowerShell Gallery. Use the following command to ensure you are using TLS > 1.2: > -> `[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12` +> `[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12` > > For more information, see the > [announcement](https://devblogs.microsoft.com/powershell/powershell-gallery-tls-support/) in the diff --git a/reference/7.3/PowerShellGet/PowerShellGet.md b/reference/7.3/PowerShellGet/PowerShellGet.md index d8e4a9f67f74..cb1f1e7c558b 100644 --- a/reference/7.3/PowerShellGet/PowerShellGet.md +++ b/reference/7.3/PowerShellGet/PowerShellGet.md @@ -1,10 +1,10 @@ --- Download Help Link: https://aka.ms/powershell73-help -Help Version: 7.2.0.0 +Help Version: 7.3.0.0 Locale: en-US Module Guid: 1d73a601-4a6c-43c5-ba3f-619b18bbb404 Module Name: PowerShellGet -ms.date: 06/09/2017 +ms.date: 04/21/2022 schema: 2.0.0 title: PowerShellGet --- @@ -15,13 +15,15 @@ title: PowerShellGet PowerShellGet is a module with commands for discovering, installing, updating and publishing PowerShell artifacts like Modules, DSC Resources, Role Capabilities, and Scripts. +The cmdlet reference documentation on this site documents the latest version of the module. + > [!IMPORTANT] > As of April 2020, the PowerShell Gallery no longer supports Transport Layer Security (TLS) > versions 1.0 and 1.1. If you are not using TLS 1.2 or higher, you will receive an error when > trying to access the PowerShell Gallery. Use the following command to ensure you are using TLS > 1.2: > -> `[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12` +> `[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12` > > For more information, see the > [announcement](https://devblogs.microsoft.com/powershell/powershell-gallery-tls-support/) in the @@ -33,7 +35,7 @@ PowerShell artifacts like Modules, DSC Resources, Role Capabilities, and Scripts Finds PowerShell commands in modules. ### [Find-DscResource](Find-DscResource.md) -Finds Desired State Configuration (DSC) resources. +Finds a DSC resource. ### [Find-Module](Find-Module.md) Finds modules in a repository that match specified criteria. diff --git a/reference/docs-conceptual/gallery/getting-started.md b/reference/docs-conceptual/gallery/getting-started.md index 20dec19ee4fe..8f4b124a383d 100644 --- a/reference/docs-conceptual/gallery/getting-started.md +++ b/reference/docs-conceptual/gallery/getting-started.md @@ -134,8 +134,8 @@ These hostnames should be added to the allow lists that control access from your Hosts required for package discovery and download: - `onegetcdn.azureedge.net` - CDN hostname +- `psg-prod-centralus.azureedge.net` - CDN hostname - `psg-prod-eastus.azureedge.net` - CDN hostname -- `az818661.vo.msecnd.net` - CDN hostname Hosts required when using the PowerShell Gallery website: diff --git a/reference/docs-conceptual/gallery/install-on-older-systems.md b/reference/docs-conceptual/gallery/install-on-older-systems.md new file mode 100644 index 000000000000..19fdd7516c0d --- /dev/null +++ b/reference/docs-conceptual/gallery/install-on-older-systems.md @@ -0,0 +1,80 @@ +--- +description: This article explains how to install the PowerShellGet module in older versions of PowerShell. +ms.date: 04/21/2022 +title: Installing PowerShellGet on older Windows systems +--- +# Installing PowerShellGet on older Windows systems + +Older versions of Windows shipped with different versions of PowerShell. The **PowerShellGet** +module requires **PowerShell 3.0 or newer**. + +**PowerShellGet** requires .NET Framework 4.5 or above. For more information, see +[Install the .NET Framework for developers](/dotnet/framework/install/guide-for-developers). + +[!INCLUDE [TLS 1.2 Requirements](../../includes/tls-gallery.md)] + +## For computers running PowerShell 3.0 or PowerShell 4.0 + +These instructions apply to computers that have the **PackageManagement Preview** installed or don't +have any version of **PowerShellGet** installed. + +The `Save-Module` cmdlet is used in both sets of instructions. `Save-Module` downloads and saves a +module and any dependencies from a registered repository. The module's most current version is saved +to a specified path on the local computer, but isn't installed. To install the modules in PowerShell +3.0 or 4.0, copy the saved module folders to `$env:ProgramFiles\WindowsPowerShell\Modules`. + +For more information, see [Save-Module](/powershell/module/PowershellGet/Save-Module). + +> [!NOTE] +> PowerShell 3.0 and PowerShell 4.0 only supported one version of a module. Starting in PowerShell +> 5.0, modules are installed in `\`. This allows you to install +> multiple versions side-by-side. After downloading the module using `Save-Module` you must copy the +> files from the `\` to the `` folder on the destination machine, +> as shown in the instructions below. + +### Preparatory Step on computers running PowerShell 3.0 + +The instructions in the sections below install the modules in directory +`$env:ProgramFiles\WindowsPowerShell\Modules`. In PowerShell 3.0, this directory isn't listed in +`$env:PSModulePath` by default, so you'll need to add it in order for the modules to be auto-loaded. + +Open an elevated PowerShell session and run the following command: + +```powershell +[Environment]::SetEnvironmentVariable( + 'PSModulePath', + ((([Environment]::GetEnvironmentVariable('PSModulePath', 'Machine') -split ';') + "$env:ProgramFiles\WindowsPowerShell\Modules") -join ';'), + 'Machine' +) +``` + +The updated value of `$env:PSModulePath` is not available in the current session. You must open a +new PowerShell session. + +### For computers with the PackageManagement Preview installed + +> [!NOTE] +> PackageManagement Preview was a downloadable component that made PowerShellGet available to +> PowerShell versions 3 and 4, but it is no longer available. To test if it was installed on a given +> computer, run `Get-Module -ListAvailable PowerShellGet`. + +1. From a PowerShell session, use `Save-Module` to download the current version of + **PowerShellGet**. Two folders are downloaded: **PowerShellGet** and **PackageManagement**. Each + folder contains a subfolder with a version number. + + ```powershell + Save-Module -Name PowerShellGet -Path C:\LocalFolder -Repository PSGallery + ``` + +1. Ensure that the **PowerShellGet** and **PackageManagement** modules aren't loaded in any other + processes. + +1. Reopen the PowerShell console with elevated permissions and run the following command. + + ```powershell + 'PowerShellGet', 'PackageManagement' | % { + $targetDir = "$env:ProgramFiles\WindowsPowerShell\Modules\$_" + Remove-Item $targetDir\* -Recurse -Force + Copy-Item C:\LocalFolder\$_\*\* $targetDir\ -Recurse -Force + } + ``` diff --git a/reference/docs-conceptual/gallery/installing-psget.md b/reference/docs-conceptual/gallery/installing-psget.md index 6b0ffa73c311..d9ab77585086 100644 --- a/reference/docs-conceptual/gallery/installing-psget.md +++ b/reference/docs-conceptual/gallery/installing-psget.md @@ -1,140 +1,114 @@ --- description: This article explains how to install the PowerShellGet module in various versions of PowerShell. -ms.date: 10/05/2021 +ms.date: 04/21/2022 title: Installing PowerShellGet --- -# Installing PowerShellGet +# Installing PowerShellGet on Windows -## PowerShellGet is an in-box module in the following releases +Windows PowerShell 5.1 comes with version 1.0.0.1 of **PowerShellGet** preinstalled. -- [Windows 10](https://www.microsoft.com/windows) or newer -- [Windows Server 2016](/windows-server/windows-server) or newer -- [Windows Management Framework (WMF) 5.0](https://www.microsoft.com/download/details.aspx?id=50395) - or newer -- [PowerShell 6](https://github.com/PowerShell/PowerShell/releases) +> [!IMPORTANT] +> This version of PowerShellGet has a limited features and doesn't support the updated capabilities +> of the PowerShell Gallery. To be supported, you must update to the latest version. -## Get the latest version from PowerShell Gallery +PowerShell 6.0 shipped with version 1.6.0 of **PowerShellGet**. PowerShell 7.0 shipped with version +2.2.3 of **PowerShellGet**. The current supported version of **PowerShellGet** is 2.2.5. -Before updating **PowerShellGet**, you should always install the latest **NuGet** provider. From an -elevated PowerShell session, run the following command. +If you are running PowerShell 6 or higher, you have a usable version of **PowerShellGet**. If you +are running Windows PowerShell 5.1, you must install a newer version. -```powershell -Install-PackageProvider -Name NuGet -Force -``` +For best results, you should always install the latest supported version. -[!INCLUDE [TLS 1.2 Requirements](../../includes/tls-gallery.md)] +## Updating the preinstalled version of PowerShellGet -### For systems with PowerShell 5.0 (or newer) you can install the latest PowerShellGet +The PowerShellGet module includes cmdlets to install and update modules: -To install PowerShellGet on any system with WMF 5.1 installed, run the following commands from an -elevated PowerShell session. +- `Install-Module` installs the latest (non-prerelease) version of a module. +- `Update-Module` installs the latest (non-prerelease) version of a module if it is newer than the + currently installed module. However, this cmdlet only works if the previous version was installed + using `Install-Module`. -```powershell -Install-Module -Name PowerShellGet -Force -``` +To update the preinstalled module you must use `Install-Module`. After you have installed the new +version from the PowerShell Gallery, you can use `Update-Module` to install newer releases. -Use `Update-Module` to get newer versions. +## Updating PowerShellGet for Windows PowerShell 5.1 -```powershell -Update-Module -Name PowerShellGet -Exit -``` +### System requirements -### For computers running PowerShell 3.0 or PowerShell 4.0 +- **PowerShellGet** requires .NET Framework 4.5 or above. For more information, see + [Install the .NET Framework for developers](/dotnet/framework/install/guide-for-developers). -These instructions apply to computers that have the **PackageManagement Preview** installed or don't -have any version of **PowerShellGet** installed. +- To access the PowerShell Gallery, you must use Transport Layer Security (TLS) 1.2 or higher. By + default, PowerShell is not configured to use TLS 1.2. Use the following command to enable TLS 1.2 + in your PowerShell session. -The `Save-Module` cmdlet is used in both sets of instructions. `Save-Module` downloads and saves a -module and any dependencies from a registered repository. The module's most current version is saved -to a specified path on the local computer, but isn't installed. To install the modules in PowerShell -3.0 or 4.0, copy the module saved folders to `$env:ProgramFiles\WindowsPowerShell\Modules`. + ```powershell + [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12 + ``` -For more information, see -[Save-Module](/powershell/module/PowershellGet/Save-Module). + We also recommend adding this line of code to your PowerShell profile script. For more information + about profiles, see + [about_Profiles](/powershell/module/microsoft.powershell.core/about/about_profiles). + +### Installing the latest version of PowerShellGet + +Windows PowerShell 5.1 comes with **PowerShellGet** version 1.0.0.1, which doesn't include the NuGet +provider. The provider is required by **PowerShellGet** when working with the PowerShell Gallery. > [!NOTE] -> PowerShell 3.0 and PowerShell 4.0 only supported one version of a module. Starting in PowerShell -> 5.0, modules are installed in `\`. This allows you to install -> multiple versions side-by-side. After downloading the module using `Save-Module` you must copy the -> files from the `\` to the `` folder on the destination machine, -> as shown in the instructions below. +> The following commands must be run from an elevated PowerShell session. Right-click the PowerShell +> icon and choose **Run as administrator** to start an elevated session. -#### Preparatory Step on computers running PowerShell 3.0 +There are two ways to install the NuGet provider: -The instructions in the sections below install the modules in directory -`$env:ProgramFiles\WindowsPowerShell\Modules`. In PowerShell 3.0, this directory isn't listed in -`$env:PSModulePath` by default, so you'll need to add it in order for the modules to be auto-loaded. +- Use `Install-PackageProvider` to install NuGet before installing other modules -Open an elevated PowerShell session and run the following command (which will take effect in future -sessions): + Run the following command to install the NuGet provider. -```powershell -[Environment]::SetEnvironmentVariable( - 'PSModulePath', - ((([Environment]::GetEnvironmentVariable('PSModulePath', 'Machine') -split ';') + "$env:ProgramFiles\WindowsPowerShell\Modules") -join ';'), - 'Machine' -) -``` + ```powershell + Install-PackageProvider -Name NuGet -Force + ``` + + After you have installed the provider you should be able to use any of the **PowerShellGet** + cmdlets with the PowerShell Gallery. -#### Computers with the PackageManagement Preview installed +- Let `Install-Module` prompt you to install the NuGet provider + + The following command attempts to install the updated PowerShellGet module without the NuGet + provider. + + ```powershell + Install-Module PowerShellGet -AllowClobber -Force + ``` + + `Install-Module` prompts you to install the NuGet provider. Type Y to install the + provider. + + ```Output + NuGet provider is required to continue + PowerShellGet requires NuGet provider version '2.8.5.201' or newer to interact with NuGet-based + repositories. The NuGet provider must be available in 'C:\Program Files\PackageManagement\ProviderAssemblies' + or 'C:\Users\user1\AppData\Local\PackageManagement\ProviderAssemblies'. You can also install the NuGet + provider by running 'Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force'. Do you + want PowerShellGet to install and import the NuGet provider now? + [Y] Yes [N] No [S] Suspend [?] Help (default is "Y"): Y + VERBOSE: Installing NuGet provider. + ``` > [!NOTE] -> PackageManagement Preview was a downloadable component that made PowerShellGet available to -> PowerShell versions 3 and 4, but it is no longer available. To test if it was installed on a given -> computer, run `Get-Module -ListAvailable PowerShellGet`. - -1. From a PowerShell session, use `Save-Module` to download the current version of - **PowerShellGet**. Two folders are downloaded: **PowerShellGet** and **PackageManagement**. Each - folder contains a subfolder with a version number. - - ```powershell - Save-Module -Name PowerShellGet -Path C:\LocalFolder -Repository PSGallery - ``` - -1. Ensure that the **PowerShellGet** and **PackageManagement** modules aren't loaded in any other - processes. - -1. Reopen the PowerShell console with elevated permissions and run the following command. - - ```powershell - 'PowerShellGet', 'PackageManagement' | % { - $targetDir = "$env:ProgramFiles\WindowsPowerShell\Modules\$_" - Remove-Item $targetDir\* -Recurse -Force - Copy-Item C:\LocalFolder\$_\*\* $targetDir\ -Recurse -Force - } - ``` - -#### Computers without PowerShellGet - -For computers without any version of **PowerShellGet** installed (test with -`Get-Module -ListAvailable PowerShellGet`), a computer with **PowerShellGet** installed is needed to -download the modules. - -1. From the computer that has **PowerShellGet** installed, use `Save-Module` to download the current - version of **PowerShellGet**. Two folders are downloaded: **PowerShellGet** and - **PackageManagement**. Each folder contains a subfolder with a version number. - - ```powershell - Save-Module -Name PowerShellGet -Path C:\LocalFolder -Repository PSGallery - ``` - -1. Copy the respective `` subfolder in the **PowerShellGet** and **PackageManagement** - folders to the computer that doesn't have **PowerShellGet** installed, into folders - `$env:ProgramFiles\WindowsPowerShell\Modules\PowerShellGet\` and - `$env:ProgramFiles\WindowsPowerShell\Modules\PackageManagement\` respectively, which requires an - elevated session. - -1. For instance, if you can access the download folder on the other computer, say `ws1`, from the - target computer via a UNC path, say `\\ws1\C$\LocalFolder`, open a PowerShell console with - elevated permissions and run the following command: - - ```powershell - 'PowerShellGet', 'PackageManagement' | % { - $targetDir = "$env:ProgramFiles\WindowsPowerShell\Modules\$_" - $null = New-Item -Type Directory -Force $targetDir - $fromComputer = 'ws1' # Specify the name of the other computer here. - Copy-Item \\$fromComputer\C$\LocalFolder\$_\*\* $targetDir -Recurse -Force - if (-not (Get-ChildItem $targetDir)) { Throw "Copying failed." } - } - ``` +> If you have not configured TLS 1.2, any attempts to install the NuGet provider and other +> packages will fail. + +### After installing PowerShellGet + +After you have installed the new version of **PowerShellGet**, you should open a new PowerShell +session. PowerShell automatically loads the newest version of the module when you use a +**PowerShellGet** cmdlet. + +We also recommend that you register the PowerShell Gallery as a trusted repository. Use the following command: + +```powershell +Set-PSRepository -Name PSGallery -InstallationPolicy Trusted +``` + +For more information, see [Set-PSRepository](xref:PowerShellGet.Set-PSRepository). diff --git a/reference/docs-conceptual/gallery/overview.md b/reference/docs-conceptual/gallery/overview.md index b0901526f734..7ad191a99933 100644 --- a/reference/docs-conceptual/gallery/overview.md +++ b/reference/docs-conceptual/gallery/overview.md @@ -1,54 +1,55 @@ --- description: The PowerShell Gallery is the central repository for PowerShell modules, scripts, and DSC resources. -ms.date: 10/22/2021 +ms.date: 04/21/2022 title: The PowerShell Gallery --- # The PowerShell Gallery -The PowerShell Gallery is the central repository for PowerShell content. In it, you can find useful -PowerShell modules containing PowerShell commands and Desired State Configuration (DSC) resources. -You can also find PowerShell scripts, some of which may contain PowerShell workflows, and which -outline a set of tasks and provide sequencing for those tasks. Some of these packages are authored -by Microsoft, and others are authored by the PowerShell community. +The PowerShell Gallery is the central repository for PowerShell content. In it, you can find +PowerShell scripts, modules containing PowerShell cmdlets and Desired State Configuration (DSC) +resources. Some of these packages are authored by Microsoft, and others are authored by the +PowerShell community. -## PowerShellGet Overview +## The PowerShellGet module -The PowerShellGet module contains cmdlets for discovering, installing, updating and publishing -PowerShell packages which contain artifacts such as Modules, DSC Resources, Role Capabilities and -Scripts from the [PowerShell Gallery](https://www.PowerShellGallery.com) and other private -repositories. +The **PowerShellGet** module contains cmdlets for discovering, installing, updating, and publishing +PowerShell packages from the [PowerShell Gallery](https://www.powershellgallery.com). These packages +can contain artifacts such as Modules, DSC Resources, Role Capabilities, and Scripts. -## Getting Started with the Gallery +### Version history -Installing packages from the Gallery requires the latest version of the PowerShellGet module. See -[Installing PowerShellGet](installing-psget.md) for complete instructions. +Windows PowerShell 5.1 comes with version 1.0.0.1 of **PowerShellGet** preinstalled. -Check out the [Getting Started](getting-started.md) page for more information on how to use -PowerShellGet commands with the Gallery. You can also run `Update-Help -Module PowerShellGet` to -install local help for these commands. +> [!IMPORTANT] +> This version of PowerShellGet has a limited features and doesn't support the updated capabilities +> of the PowerShell Gallery. To be supported, you must update to the latest version. + +PowerShell 6.0 shipped with version 1.6.0 of **PowerShellGet**. PowerShell 7.0 shipped with version +2.2.3 of **PowerShellGet**. The current supported version of **PowerShellGet** is 2.2.5. -## Supported Operating Systems +For best results, use the latest version of the **PowerShellGet** module. See +[Installing PowerShellGet](installing-psget.md) for complete instructions. The cmdlet reference +documentation on this site documents the latest version. -The **PowerShellGet** module requires **PowerShell 3.0 or newer**. +## Getting Started with the PowerShell Gallery -**PowerShellGet** requires .NET Framework 4.5 or above. For more information, see -[Install the .NET Framework for developers](/dotnet/framework/install/guide-for-developers). +Check out the [Getting Started](getting-started.md) page for more information on how to use +**PowerShellGet** commands with the Gallery. You can also run +`Update-Help -Module PowerShellGet -Force` to install local help for these commands. -PowerShell is cross-platform, which means it works on Windows, Linux and MacOS. That also makes +PowerShell is cross-platform, which means it works on Windows, Linux, and macOS. That also makes **PowerShellGet** available on those systems. For a full list of systems supported by PowerShell see [Installing PowerShell](/powershell/scripting/install/installing-powershell). -Many modules hosted in the gallery support different OSes and have additional requirements. -Please refer to the documentation for the modules for more information. +Modules in the PowerShell Gallery can support different operating systems and have additional +requirements. For information, see the documentation for the module. ## Got a question? Have feedback? -More information about the PowerShell Gallery and PowerShellGet can be found in the +More information about the PowerShell Gallery and **PowerShellGet** can be found in the [Getting Started](getting-started.md) page. To see the current status of the PowerShell Gallery services, see the -[PowerShell Gallery Status](https://github.com/PowerShell/PowerShellGallery/blob/master/psgallery_status.md) -page on GitHub. +[PowerShell Gallery Status](https://aka.ms/psgallery-status) page on GitHub. -Please provide feedback and report issues the -[GitHub repository](https://github.com/PowerShell/PowerShellGallery/issues). +Please provide feedback and report issues in the [GitHub repository](https://aka.ms/psgallery-issues). diff --git a/reference/docs-conceptual/toc.yml b/reference/docs-conceptual/toc.yml index 4e63ae81c490..415e0f380b4e 100644 --- a/reference/docs-conceptual/toc.yml +++ b/reference/docs-conceptual/toc.yml @@ -245,7 +245,7 @@ items: href: whats-new/unix-support.md - name: Module and cmdlet release history href: whats-new/cmdlet-versions.md - - name: Module compatibility list + - name: Module compatibility href: whats-new/module-compatibility.md - name: Windows PowerShell items: @@ -420,6 +420,8 @@ items: href: gallery/overview.md - name: Installing PowerShellGet href: gallery/installing-psget.md + - name: Installing PowerShellGet on older systems + href: gallery/install-on-older-systems.md - name: Getting Started href: gallery/getting-started.md - name: How-To From 570e2ea5b47601310f03d4fc78f9c84b045d4d54 Mon Sep 17 00:00:00 2001 From: "Michael T Lombardi (He/Him)" Date: Mon, 25 Apr 2022 11:02:37 -0500 Subject: [PATCH 18/31] (AB#1942543) Ensure PSConsoleHostReadLine is translatable (#8760) Prior to this commit, the documentation for PSConsoleHostReadLine did not correctly translate due to the casing of the H2s, which are required to be fully upcased. This commit upcases those items to ensure the documentation can be properly translated. --- .../5.1/PSReadLine/PSConsoleHostReadLine.md | 20 +++++++++--------- .../7.0/PSReadLine/PSConsoleHostReadLine.md | 20 +++++++++--------- .../7.1/PSReadLine/PSConsoleHostReadLine.md | 21 +++++++++---------- .../7.2/PSReadLine/PSConsoleHostReadLine.md | 21 +++++++++---------- .../7.3/PSReadLine/PSConsoleHostReadLine.md | 21 +++++++++---------- 5 files changed, 50 insertions(+), 53 deletions(-) diff --git a/reference/5.1/PSReadLine/PSConsoleHostReadLine.md b/reference/5.1/PSReadLine/PSConsoleHostReadLine.md index a9cecaa9a6fa..3eafede3f8f5 100644 --- a/reference/5.1/PSReadLine/PSConsoleHostReadLine.md +++ b/reference/5.1/PSReadLine/PSConsoleHostReadLine.md @@ -2,7 +2,7 @@ external help file: PSReadLine-help.xml Locale: en-US Module Name: PSReadLine -ms.date: 12/07/2018 +ms.date: 04/25/2022 online version: https://docs.microsoft.com/powershell/module/psreadline/psconsolehostreadline?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: PSConsoleHostReadLine @@ -10,16 +10,16 @@ title: PSConsoleHostReadLine # PSConsoleHostReadLine -## Synopsis +## SYNOPSIS This function is the main entry point for PSReadLine. -## Syntax +## SYNTAX ``` PSConsoleHostReadLine ``` -## Description +## DESCRIPTION `PSConsoleHostReadLine` is the main entry point for the PSReadLine module. The PowerShell console host automatically loads the PSReadLine module and calls this function. Under normal operating @@ -29,24 +29,24 @@ The extension point `PSConsoleHostReadLine` is special to the console host. The alias, function, or script with this name. PSReadLine defines this function so that it is called from the console host. -## Examples +## EXAMPLES ### Example 1 This function is not intended to be used from the command line. -## Parameters +## PARAMETERS -## Inputs +## INPUTS ### None -## Outputs +## OUTPUTS ### None -## Notes +## NOTES -## Related links +## RELATED LINKS [about_PSReadLine](./About/about_PSReadLine.md) diff --git a/reference/7.0/PSReadLine/PSConsoleHostReadLine.md b/reference/7.0/PSReadLine/PSConsoleHostReadLine.md index 7eed2da79675..25a8f09230d2 100644 --- a/reference/7.0/PSReadLine/PSConsoleHostReadLine.md +++ b/reference/7.0/PSReadLine/PSConsoleHostReadLine.md @@ -2,7 +2,7 @@ external help file: PSReadLine-help.xml Locale: en-US Module Name: PSReadLine -ms.date: 12/07/2018 +ms.date: 04/25/2022 online version: https://docs.microsoft.com/powershell/module/psreadline/psconsolehostreadline?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: PSConsoleHostReadLine @@ -10,16 +10,16 @@ title: PSConsoleHostReadLine # PSConsoleHostReadLine -## Synopsis +## SYNOPSIS This function is the main entry point for PSReadLine. -## Syntax +## SYNTAX ``` PSConsoleHostReadLine ``` -## Description +## DESCRIPTION `PSConsoleHostReadLine` is the main entry point for the PSReadLine module. The PowerShell console host automatically loads the PSReadLine module and calls this function. Under normal operating @@ -29,24 +29,24 @@ The extension point `PSConsoleHostReadLine` is special to the console host. The alias, function, or script with this name. PSReadLine defines this function so that it is called from the console host. -## Examples +## EXAMPLES ### Example 1 This function is not intended to be used from the command line. -## Parameters +## PARAMETERS -## Inputs +## INPUTS ### None -## Outputs +## OUTPUTS ### None -## Notes +## NOTES -## Related links +## RELATED LINKS [about_PSReadLine](./About/about_PSReadLine.md) diff --git a/reference/7.1/PSReadLine/PSConsoleHostReadLine.md b/reference/7.1/PSReadLine/PSConsoleHostReadLine.md index 8b9f8fd157af..7c1439eb6601 100644 --- a/reference/7.1/PSReadLine/PSConsoleHostReadLine.md +++ b/reference/7.1/PSReadLine/PSConsoleHostReadLine.md @@ -2,7 +2,7 @@ external help file: PSReadLine-help.xml Locale: en-US Module Name: PSReadLine -ms.date: 12/07/2018 +ms.date: 04/25/2022 online version: https://docs.microsoft.com/powershell/module/psreadline/psconsolehostreadline?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: PSConsoleHostReadLine @@ -10,16 +10,16 @@ title: PSConsoleHostReadLine # PSConsoleHostReadLine -## Synopsis +## SYNOPSIS This function is the main entry point for PSReadLine. -## Syntax +## SYNTAX ``` PSConsoleHostReadLine ``` -## Description +## DESCRIPTION `PSConsoleHostReadLine` is the main entry point for the PSReadLine module. The PowerShell console host automatically loads the PSReadLine module and calls this function. Under normal operating @@ -29,25 +29,24 @@ The extension point `PSConsoleHostReadLine` is special to the console host. The alias, function, or script with this name. PSReadLine defines this function so that it is called from the console host. -## Examples +## EXAMPLES ### Example 1 This function is not intended to be used from the command line. -## Parameters +## PARAMETERS -## Inputs +## INPUTS ### None -## Outputs +## OUTPUTS ### None -## Notes +## NOTES -## Related links +## RELATED LINKS [about_PSReadLine](./About/about_PSReadLine.md) - diff --git a/reference/7.2/PSReadLine/PSConsoleHostReadLine.md b/reference/7.2/PSReadLine/PSConsoleHostReadLine.md index 8800053491cf..26ba3b1c6017 100644 --- a/reference/7.2/PSReadLine/PSConsoleHostReadLine.md +++ b/reference/7.2/PSReadLine/PSConsoleHostReadLine.md @@ -2,7 +2,7 @@ external help file: PSReadLine-help.xml Locale: en-US Module Name: PSReadLine -ms.date: 12/07/2018 +ms.date: 04/25/2022 online version: https://docs.microsoft.com/powershell/module/psreadline/psconsolehostreadline?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: PSConsoleHostReadLine @@ -10,16 +10,16 @@ title: PSConsoleHostReadLine # PSConsoleHostReadLine -## Synopsis +## SYNOPSIS This function is the main entry point for PSReadLine. -## Syntax +## SYNTAX ``` PSConsoleHostReadLine ``` -## Description +## DESCRIPTION `PSConsoleHostReadLine` is the main entry point for the PSReadLine module. The PowerShell console host automatically loads the PSReadLine module and calls this function. Under normal operating @@ -29,25 +29,24 @@ The extension point `PSConsoleHostReadLine` is special to the console host. The alias, function, or script with this name. PSReadLine defines this function so that it is called from the console host. -## Examples +## EXAMPLES ### Example 1 This function is not intended to be used from the command line. -## Parameters +## PARAMETERS -## Inputs +## INPUTS ### None -## Outputs +## OUTPUTS ### None -## Notes +## NOTES -## Related links +## RELATED LINKS [about_PSReadLine](./About/about_PSReadLine.md) - diff --git a/reference/7.3/PSReadLine/PSConsoleHostReadLine.md b/reference/7.3/PSReadLine/PSConsoleHostReadLine.md index 47d5129c4691..73d0c027b1b9 100644 --- a/reference/7.3/PSReadLine/PSConsoleHostReadLine.md +++ b/reference/7.3/PSReadLine/PSConsoleHostReadLine.md @@ -2,7 +2,7 @@ external help file: PSReadLine-help.xml Locale: en-US Module Name: PSReadLine -ms.date: 12/07/2018 +ms.date: 04/25/2022 online version: https://docs.microsoft.com/powershell/module/psreadline/psconsolehostreadline?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: PSConsoleHostReadLine @@ -10,16 +10,16 @@ title: PSConsoleHostReadLine # PSConsoleHostReadLine -## Synopsis +## SYNOPSIS This function is the main entry point for PSReadLine. -## Syntax +## SYNTAX ``` PSConsoleHostReadLine ``` -## Description +## DESCRIPTION `PSConsoleHostReadLine` is the main entry point for the PSReadLine module. The PowerShell console host automatically loads the PSReadLine module and calls this function. Under normal operating @@ -29,25 +29,24 @@ The extension point `PSConsoleHostReadLine` is special to the console host. The alias, function, or script with this name. PSReadLine defines this function so that it is called from the console host. -## Examples +## EXAMPLES ### Example 1 This function is not intended to be used from the command line. -## Parameters +## PARAMETERS -## Inputs +## INPUTS ### None -## Outputs +## OUTPUTS ### None -## Notes +## NOTES -## Related links +## RELATED LINKS [about_PSReadLine](./About/about_PSReadLine.md) - From e73d1536a900470c4409371cbe2d4534617c5046 Mon Sep 17 00:00:00 2001 From: "Michael T Lombardi (He/Him)" Date: Mon, 25 Apr 2022 12:21:17 -0500 Subject: [PATCH 19/31] (GH-8759) Update WideControl in about_Format.ps1xml (#8761) Prior to this commit, the section in **about_Format.ps1xml** incorrectly explained the `` tag and did not mention the `` tag at all. This commit updates the section for clarity and documents the `` tag and its valid child tags. --- .../About/about_Format.ps1xml.md | 17 +++++++++++------ .../About/about_Format.ps1xml.md | 17 +++++++++++------ .../About/about_Format.ps1xml.md | 17 +++++++++++------ .../About/about_Format.ps1xml.md | 17 +++++++++++------ .../About/about_Format.ps1xml.md | 17 +++++++++++------ 5 files changed, 55 insertions(+), 30 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md index 23895490c2f8..d61a02871c45 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md @@ -1,7 +1,7 @@ --- description: The `Format.ps1xml` files in PowerShell define the default display of objects in the PowerShell console. You can create your own `Format.ps1xml` files to change the display of objects or to define default displays for new object types that you create in PowerShell. Locale: en-US -ms.date: 11/27/2019 +ms.date: 04/25/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_format.ps1xml?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Format.ps1xml @@ -376,11 +376,16 @@ that the `` tag is intended to display. ### WideControl tag The `` tag typically contains a `` tag. The -`` tag contains one or more `` tags. A `` -tag typically contains a `` tag that specifies the property to be -displayed at the specified location in the view. The `` tag can -contain a `` tag that specifies how the property is to be -displayed. +`` tag contains one or more `` tags. A `` tag +contains one `` tag. + +A `` tag must include either a `` tag or a +`` tag. A `` tag specifies the property to display at +the specified location in the view. A `` tag specifies a script to +evaluate and display at the specified location in the view. + +A `` tag can contain a `` tag that specifies how to +display the property. ### CustomControl tag diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md index ee6d92810d3f..a304d12ab2a0 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md @@ -1,7 +1,7 @@ --- description: Beginning in PowerShell 6, the default views for objects are defined in PowerShell source code. You can create your own `Format.ps1xml` files to change the display of objects or to define default displays for new object types that you create in PowerShell. Locale: en-US -ms.date: 11/27/2019 +ms.date: 04/25/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_format.ps1xml?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Format.ps1xml @@ -280,11 +280,16 @@ that the `` tag is intended to display. ### WideControl tag The `` tag typically contains a `` tag. The -`` tag contains one or more `` tags. A `` -tag typically contains a `` tag that specifies the property to be -displayed at the specified location in the view. The `` tag can -contain a `` tag that specifies how the property is to be -displayed. +`` tag contains one or more `` tags. A `` tag +contains one `` tag. + +A `` tag must include either a `` tag or a +`` tag. A `` tag specifies the property to display at +the specified location in the view. A `` tag specifies a script to +evaluate and display at the specified location in the view. + +A `` tag can contain a `` tag that specifies how to +display the property. ### CustomControl tag diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md index 4d93c879815d..a1f8dcef6d58 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md @@ -1,7 +1,7 @@ --- description: Beginning in PowerShell 6, the default views for objects are defined in PowerShell source code. You can create your own `Format.ps1xml` files to change the display of objects or to define default displays for new object types that you create in PowerShell. Locale: en-US -ms.date: 11/27/2019 +ms.date: 04/25/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_format.ps1xml?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Format.ps1xml @@ -280,11 +280,16 @@ that the `` tag is intended to display. ### WideControl tag The `` tag typically contains a `` tag. The -`` tag contains one or more `` tags. A `` -tag typically contains a `` tag that specifies the property to be -displayed at the specified location in the view. The `` tag can -contain a `` tag that specifies how the property is to be -displayed. +`` tag contains one or more `` tags. A `` tag +contains one `` tag. + +A `` tag must include either a `` tag or a +`` tag. A `` tag specifies the property to display at +the specified location in the view. A `` tag specifies a script to +evaluate and display at the specified location in the view. + +A `` tag can contain a `` tag that specifies how to +display the property. ### CustomControl tag diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md index 0c4ba5313419..9fcb4c3eafdd 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md @@ -1,7 +1,7 @@ --- description: Beginning in PowerShell 6, the default views for objects are defined in PowerShell source code. You can create your own `Format.ps1xml` files to change the display of objects or to define default displays for new object types that you create in PowerShell. Locale: en-US -ms.date: 11/27/2019 +ms.date: 04/25/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_format.ps1xml?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Format.ps1xml @@ -280,11 +280,16 @@ that the `` tag is intended to display. ### WideControl tag The `` tag typically contains a `` tag. The -`` tag contains one or more `` tags. A `` -tag typically contains a `` tag that specifies the property to be -displayed at the specified location in the view. The `` tag can -contain a `` tag that specifies how the property is to be -displayed. +`` tag contains one or more `` tags. A `` tag +contains one `` tag. + +A `` tag must include either a `` tag or a +`` tag. A `` tag specifies the property to display at +the specified location in the view. A `` tag specifies a script to +evaluate and display at the specified location in the view. + +A `` tag can contain a `` tag that specifies how to +display the property. ### CustomControl tag diff --git a/reference/7.3/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md b/reference/7.3/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md index 92824a2418d3..b0b1338b7778 100644 --- a/reference/7.3/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md +++ b/reference/7.3/Microsoft.PowerShell.Core/About/about_Format.ps1xml.md @@ -1,7 +1,7 @@ --- description: Beginning in PowerShell 6, the default views for objects are defined in PowerShell source code. You can create your own `Format.ps1xml` files to change the display of objects or to define default displays for new object types that you create in PowerShell. Locale: en-US -ms.date: 11/27/2019 +ms.date: 04/25/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_format.ps1xml?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Format.ps1xml @@ -280,11 +280,16 @@ that the `` tag is intended to display. ### WideControl tag The `` tag typically contains a `` tag. The -`` tag contains one or more `` tags. A `` -tag typically contains a `` tag that specifies the property to be -displayed at the specified location in the view. The `` tag can -contain a `` tag that specifies how the property is to be -displayed. +`` tag contains one or more `` tags. A `` tag +contains one `` tag. + +A `` tag must include either a `` tag or a +`` tag. A `` tag specifies the property to display at +the specified location in the view. A `` tag specifies a script to +evaluate and display at the specified location in the view. + +A `` tag can contain a `` tag that specifies how to +display the property. ### CustomControl tag From a6d911d8ae243a4da58be2c19fc70a6f3a3f7a51 Mon Sep 17 00:00:00 2001 From: "Michael T Lombardi (He/Him)" Date: Mon, 25 Apr 2022 16:10:11 -0500 Subject: [PATCH 20/31] (GH-8757) Clarify remoting in Managing Services (#8762) Prior to this commit, the Managing Services sample in the conceptual documentation included example code using the **ComputerName** parameter for `Get-Service`, but that parameter was removed from the `*-Service` cmdlets in PowerShell 6.0. This commit updates the documentation to distinguish between Windows PowerShell and PowerShell for managing remote services and clarifies how to do so. --- .../samples/Managing-Services.md | 22 +++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/reference/docs-conceptual/samples/Managing-Services.md b/reference/docs-conceptual/samples/Managing-Services.md index f599e4334274..258c1c892042 100644 --- a/reference/docs-conceptual/samples/Managing-Services.md +++ b/reference/docs-conceptual/samples/Managing-Services.md @@ -49,15 +49,28 @@ Running lanmanserver Server Stopped ServiceLayer ServiceLayer ``` -You can use the ComputerName parameter of the Get-Service cmdlet to get the services on remote -computers. The ComputerName parameter accepts multiple values and wildcard characters, so you can -get the services on multiple computers with a single command. For example, the following command -gets the services on the Server01 remote computer. +## Getting Remote Services + +With Windows PowerShell, you can use the **ComputerName** parameter of the `Get-Service` cmdlet to +get the services on remote computers. The **ComputerName** parameter accepts multiple values and +wildcard characters, so you can get the services on multiple computers with a single command. For +example, the following command gets the services on the Server01 remote computer. ```powershell Get-Service -ComputerName Server01 ``` +Starting in PowerShell 6.0, the `*-Service` cmdlets do not have the **ComputerName** parameter. You +can still get services on remote computers with PowerShell remoting. For example, the following +command gets the services on the Server02 remote computer. + +```powershell +Invoke-Command -ComputerName Server02 -ScriptBlock { Get-Service } +``` + +You can also manage services with the other `*-Service` cmdlets. For more information on PowerShell +remoting, see [about_Remote](/powershell/module/Microsoft.PowerShell.Core/about_Remote). + ## Getting Required and Dependent Services The Get-Service cmdlet has two parameters that are very useful in service administration. The @@ -177,6 +190,7 @@ For more information, see [Set-Service](/powershell/module/Microsoft.PowerShell. ## See Also +- [about_Remote](/powershell/module/Microsoft.PowerShell.Core/about_Remote) - [Get-Service](/powershell/module/Microsoft.PowerShell.Management/get-service) - [Set-Service](/powershell/module/Microsoft.PowerShell.Management/set-service) - [Restart-Service](/powershell/module/Microsoft.PowerShell.Management/restart-service) From 1fc9e56edca9f6b0b92d8e9a9496d2ec78b06060 Mon Sep 17 00:00:00 2001 From: HRXN Date: Tue, 26 Apr 2022 18:18:43 +0200 Subject: [PATCH 21/31] Improve consistency and readability of about_Quoting_Rules (#8764) --- .../Microsoft.PowerShell.Core/About/about_Quoting_Rules.md | 6 +++--- .../Microsoft.PowerShell.Core/About/about_Quoting_Rules.md | 6 +++--- .../Microsoft.PowerShell.Core/About/about_Quoting_Rules.md | 6 +++--- .../Microsoft.PowerShell.Core/About/about_Quoting_Rules.md | 6 +++--- .../Microsoft.PowerShell.Core/About/about_Quoting_Rules.md | 6 +++--- 5 files changed, 15 insertions(+), 15 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md index f870fa47555f..b7214a3ea5a7 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md @@ -1,7 +1,7 @@ --- description: Describes rules for using single and double quotation marks in PowerShell. Locale: en-US -ms.date: 12/09/2021 +ms.date: 04/26/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Quoting Rules @@ -98,7 +98,7 @@ The value of $i is 5. ## Single-quoted strings -A string enclosed in single-quotation marks is a _verbatim_ string. The string +A string enclosed in single quotation marks is a _verbatim_ string. The string is passed to the command exactly as you type it. No substitution is performed. For example: @@ -114,7 +114,7 @@ The value $i is $i. ``` Similarly, expressions in single-quoted strings are not evaluated. They are -interpreted as literals. For example: +interpreted as string literals. For example: ```powershell 'The value of $(2+3) is 5.' diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md index 59bc9c15045e..401e1e4e4ffc 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md @@ -1,7 +1,7 @@ --- description: Describes rules for using single and double quotation marks in PowerShell. Locale: en-US -ms.date: 12/09/2021 +ms.date: 04/26/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Quoting Rules @@ -98,7 +98,7 @@ The value of $i is 5. ## Single-quoted strings -A string enclosed in single-quotation marks is a _verbatim_ string. The string +A string enclosed in single quotation marks is a _verbatim_ string. The string is passed to the command exactly as you type it. No substitution is performed. For example: @@ -114,7 +114,7 @@ The value $i is $i. ``` Similarly, expressions in single-quoted strings are not evaluated. They are -interpreted as literals. For example: +interpreted as string literals. For example: ```powershell 'The value of $(2+3) is 5.' diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md index 62db451ce025..6e28b8921dca 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md @@ -1,7 +1,7 @@ --- description: Describes rules for using single and double quotation marks in PowerShell. Locale: en-US -ms.date: 12/09/2021 +ms.date: 04/26/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Quoting Rules @@ -98,7 +98,7 @@ The value of $i is 5. ## Single-quoted strings -A string enclosed in single-quotation marks is a _verbatim_ string. The string +A string enclosed in single quotation marks is a _verbatim_ string. The string is passed to the command exactly as you type it. No substitution is performed. For example: @@ -114,7 +114,7 @@ The value $i is $i. ``` Similarly, expressions in single-quoted strings are not evaluated. They are -interpreted as literals. For example: +interpreted as string literals. For example: ```powershell 'The value of $(2+3) is 5.' diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md index 55850be565c3..bbcd750a0f36 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md @@ -1,7 +1,7 @@ --- description: Describes rules for using single and double quotation marks in PowerShell. Locale: en-US -ms.date: 12/09/2021 +ms.date: 04/26/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Quoting Rules @@ -98,7 +98,7 @@ The value of $i is 5. ## Single-quoted strings -A string enclosed in single-quotation marks is a _verbatim_ string. The string +A string enclosed in single quotation marks is a _verbatim_ string. The string is passed to the command exactly as you type it. No substitution is performed. For example: @@ -114,7 +114,7 @@ The value $i is $i. ``` Similarly, expressions in single-quoted strings are not evaluated. They are -interpreted as literals. For example: +interpreted as string literals. For example: ```powershell 'The value of $(2+3) is 5.' diff --git a/reference/7.3/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/7.3/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md index 44a728c7a13f..7e569ee4212d 100644 --- a/reference/7.3/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md +++ b/reference/7.3/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md @@ -1,7 +1,7 @@ --- description: Describes rules for using single and double quotation marks in PowerShell. Locale: en-US -ms.date: 12/09/2021 +ms.date: 04/26/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Quoting Rules @@ -98,7 +98,7 @@ The value of $i is 5. ## Single-quoted strings -A string enclosed in single-quotation marks is a _verbatim_ string. The string +A string enclosed in single quotation marks is a _verbatim_ string. The string is passed to the command exactly as you type it. No substitution is performed. For example: @@ -114,7 +114,7 @@ The value $i is $i. ``` Similarly, expressions in single-quoted strings are not evaluated. They are -interpreted as literals. For example: +interpreted as string literals. For example: ```powershell 'The value of $(2+3) is 5.' From e410709c0a6a616856df22b04cd256177763b17a Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 26 Apr 2022 11:55:24 -0500 Subject: [PATCH 22/31] Update quicklink for Az PowerShell --- reference/module/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/module/index.md b/reference/module/index.md index 5a2b3dfb4794..40f6c814bac8 100644 --- a/reference/module/index.md +++ b/reference/module/index.md @@ -12,7 +12,7 @@ ms.manager: sewhee ms.product: powershell ms.topic: landing-page quickFilterColumn1: powershell-7.1,windowsserver2019-ps -quickFilterColumn2: azps-7.4.0,win-mdop2-ps +quickFilterColumn2: azps-7.5.0,win-mdop2-ps quickFilterColumn3: sqlserver-ps,systemcenter-ps-2019 title: PowerShell Module Browser --- From c0440e93c05d328fbce6d8d7aee6bb6ca173087f Mon Sep 17 00:00:00 2001 From: "Michael T Lombardi (He/Him)" Date: Wed, 27 Apr 2022 10:02:21 -0500 Subject: [PATCH 23/31] (GH-8768) Correct EOL for 7.1 & 7.2 (#8769) Prior to this commit, the EOL date for 7.1 incorrectly specified May 31, 2022. Support for PowerShell versions is tied to the version of .NET they are built on. Support for .NET 5.0, which PowerShell 7.1 is built on, ends on May 8, 2022. Additionally, the EOL date for .NET 6.0, which PowerShell 7.2 is built on, is now known to be November 8, 2024, instead of merely projected to be November 2024. This commit corrects the date for the EOL of PowerShell 7.1 and updates the EOL date of PowerShell 7.2 to ensure clarity and accuracy of the support lifecycle. --- .../install/PowerShell-Support-Lifecycle.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/reference/docs-conceptual/install/PowerShell-Support-Lifecycle.md b/reference/docs-conceptual/install/PowerShell-Support-Lifecycle.md index 718a7e387dc8..a1fca2cdbe23 100644 --- a/reference/docs-conceptual/install/PowerShell-Support-Lifecycle.md +++ b/reference/docs-conceptual/install/PowerShell-Support-Lifecycle.md @@ -1,6 +1,6 @@ --- description: Details the policies governing support for PowerShell -ms.date: 03/10/2022 +ms.date: 04/27/2022 title: PowerShell Support Lifecycle --- # PowerShell Support Lifecycle @@ -123,14 +123,14 @@ use the traditional, paid support options. Based on these lifecycle policies, the following table lists the dates when various releases are no longer be supported. -| Version | End-of-support | -| ----------------- | ------------------------- | -| 7.2 (LTS-current) | November 2024 (projected) | -| 7.1 | May 31, 2022 | -| 7.0 (LTS) | December 3, 2022 | -| 6.2 | September 4, 2020 | -| 6.1 | September 28, 2019 | -| 6.0 | February 13, 2019 | +| Version | End-of-support | +| ----------------- | ------------------ | +| 7.2 (LTS-current) | November 8, 2024 | +| 7.1 | May 8, 2022 | +| 7.0 (LTS) | December 3, 2022 | +| 6.2 | September 4, 2020 | +| 6.1 | September 28, 2019 | +| 6.0 | February 13, 2019 | Support for PowerShell on a specific platforms is based on the support policy of the version of .NET used. From b53fe5a52b25b58085a08e30d3360fd27278e1e9 Mon Sep 17 00:00:00 2001 From: Mikey Bronowski Date: Thu, 28 Apr 2022 15:26:23 +0100 Subject: [PATCH 24/31] Update Installing-PowerShell-on-Windows.md (#8771) --- .../Installing-PowerShell-on-Windows.md | 44 +++++++++---------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/reference/docs-conceptual/install/Installing-PowerShell-on-Windows.md b/reference/docs-conceptual/install/Installing-PowerShell-on-Windows.md index 12216fad3606..ae4c86084272 100644 --- a/reference/docs-conceptual/install/Installing-PowerShell-on-Windows.md +++ b/reference/docs-conceptual/install/Installing-PowerShell-on-Windows.md @@ -35,8 +35,8 @@ different scenarios and workflows. Choose the method that best suits your needs. To install PowerShell on Windows, use the following links to download the install package from GitHub. -- [PowerShell-7.2.2-win-x64.msi][x64msi] -- [PowerShell-7.2.2-win-x86.msi][x86msi] +- [PowerShell-7.2.3-win-x64.msi][x64msi] +- [PowerShell-7.2.3-win-x86.msi][x86msi] Once downloaded, double-click the installer file and follow the prompts. @@ -97,7 +97,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.2-win-x64.msi /quiet ADD_EXPLORER_CONTEXT_MENU_OPENPOWERSHELL=1 ENABLE_PSREMOTING=1 REGISTER_MANIFEST=1 USE_MU=1 ENABLE_MU=1 +msiexec.exe /package PowerShell-7.2.3-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 @@ -108,10 +108,10 @@ For a full list of command-line options for `Msiexec.exe`, see PowerShell binary ZIP archives are provided to enable advanced deployment scenarios. Download one of the following ZIP archives from the [current release][current] page. -- [PowerShell-7.2.2-win-x64.zip][x64zip] -- [PowerShell-7.2.2-win-x86.zip][x86zip] -- [PowerShell-7.2.2-win-arm64.zip][arm64zip] -- [PowerShell-7.2.2-win-arm32.zip][arm32zip] +- [PowerShell-7.2.3-win-x64.zip][x64zip] +- [PowerShell-7.2.3-win-x86.zip][x86zip] +- [PowerShell-7.2.3-win-arm64.zip][arm64zip] +- [PowerShell-7.2.3-win-arm32.zip][arm32zip] Depending on how you download the file you may need to unblock the file using the `Unblock-File` cmdlet. Unzip the contents to the location of your choice and run `pwsh.exe` from there. Unlike @@ -156,8 +156,8 @@ winget search Microsoft.PowerShell ```Output Name Id Version Source --------------------------------------------------------------- -PowerShell Microsoft.PowerShell 7.2.2.0 winget -PowerShell Preview Microsoft.PowerShell.Preview 7.3.0.2 winget +PowerShell Microsoft.PowerShell 7.2.3.0 winget +PowerShell Preview Microsoft.PowerShell.Preview 7.3.0.3 winget ``` Install Powershell or Powershell Preview using the `id` parameter @@ -234,7 +234,7 @@ Windows 10 IoT Enterprise comes with Windows PowerShell, which we can use to dep ```powershell # Replace the placeholder information for the following variables: $deviceip = ' -$zipfile = 'PowerShell-7.2.2-win-x64.zip' +$zipfile = 'PowerShell-7.2.3-win-x64.zip' # Connect to the built-in instance of Windows PowerShell $session = New-PSSession -ComputerName $ipaddr -Credential $credential # Copy the file to the Nano Server instance @@ -319,7 +319,7 @@ Copy-Item $zipfile c:\ -ToSession $session # Enter the interactive remote session Enter-PSSession $session # Extract the ZIP file -Expand-Archive -Path C:\PowerShell-7.2.2-win-x64.zip -DestinationPath 'C:\Program Files\PowerShell 7' +Expand-Archive -Path C:\PowerShell-7.2.3-win-x64.zip -DestinationPath 'C:\Program Files\PowerShell 7' ``` If you want WSMan-based remoting, follow the instructions to create a remoting endpoint using the @@ -370,10 +370,10 @@ cannot support those methods. [store-app]: https://www.microsoft.com/store/apps/9MZ1SNWT0N5D [winget]: /windows/package-manager/winget [wsman-remoting]: ../learn/remoting/WSMan-Remoting-in-PowerShell-Core.md -[arm32zip]: https://github.com/PowerShell/PowerShell/releases/download/v7.2.2/PowerShell-7.2.2-win-arm32.zip -[arm64zip]: https://github.com/PowerShell/PowerShell/releases/download/v7.2.2/PowerShell-7.2.2-win-arm64.zip -[x64msi]: https://github.com/PowerShell/PowerShell/releases/download/v7.2.2/PowerShell-7.2.2-win-x64.msi -[x64zip]: https://github.com/PowerShell/PowerShell/releases/download/v7.2.2/PowerShell-7.2.2-win-x64.zip -[x86msi]: https://github.com/PowerShell/PowerShell/releases/download/v7.2.2/PowerShell-7.2.2-win-x86.msi -[x86zip]: https://github.com/PowerShell/PowerShell/releases/download/v7.2.2/PowerShell-7.2.2-win-x86.zip -[72x64msi]: https://github.com/PowerShell/PowerShell/releases/download/v7.2.2/PowerShell-7.2.2-win-x64.msi +[arm32zip]: https://github.com/PowerShell/PowerShell/releases/download/v7.2.3/PowerShell-7.2.3-win-arm32.zip +[arm64zip]: https://github.com/PowerShell/PowerShell/releases/download/v7.2.3/PowerShell-7.2.3-win-arm64.zip +[x64msi]: https://github.com/PowerShell/PowerShell/releases/download/v7.2.3/PowerShell-7.2.3-win-x64.msi +[x64zip]: https://github.com/PowerShell/PowerShell/releases/download/v7.2.3/PowerShell-7.2.3-win-x64.zip +[x86msi]: https://github.com/PowerShell/PowerShell/releases/download/v7.2.3/PowerShell-7.2.3-win-x86.msi +[x86zip]: https://github.com/PowerShell/PowerShell/releases/download/v7.2.3/PowerShell-7.2.3-win-x86.zip +[72x64msi]: https://github.com/PowerShell/PowerShell/releases/download/v7.2.3/PowerShell-7.2.3-win-x64.msi From 0f4e7947d9f011e0a8b7f1b60aaa915624e878df Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 28 Apr 2022 15:26:46 -0500 Subject: [PATCH 25/31] Fixes #8739 - Update description of PropertyType parameter (#8773) * Update -PropertyType description * Editorial changes to sync versions * Update related articles --- .../About/about_Registry_Provider.md | 28 +++++++++---------- .../New-ItemProperty.md | 22 +++++++-------- .../Set-ItemProperty.md | 22 +++++++-------- .../About/about_Registry_Provider.md | 28 +++++++++---------- .../New-ItemProperty.md | 22 +++++++-------- .../Set-ItemProperty.md | 22 +++++++-------- .../About/about_Registry_Provider.md | 28 +++++++++---------- .../New-ItemProperty.md | 22 +++++++-------- .../Set-ItemProperty.md | 22 +++++++-------- .../About/about_Registry_Provider.md | 28 +++++++++---------- .../New-ItemProperty.md | 22 +++++++-------- .../Set-ItemProperty.md | 22 +++++++-------- .../About/about_Registry_Provider.md | 28 +++++++++---------- .../New-ItemProperty.md | 22 +++++++-------- .../Set-ItemProperty.md | 24 ++++++++-------- 15 files changed, 181 insertions(+), 181 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Registry_Provider.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Registry_Provider.md index b3c10d6e67cb..ff0deb311e05 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Registry_Provider.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Registry_Provider.md @@ -1,7 +1,7 @@ --- description: Registry Locale: en-US -ms.date: 09/28/2021 +ms.date: 04/28/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_registry_provider?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Registry Provider @@ -541,19 +541,19 @@ cmdlet. It is also available on the [Set-Item](xref:Microsoft.PowerShell.Management.Set-Item) cmdlet in the registry drives, but it has no effect. -| Value | Description | -| -------------- | ------------------------------------------------------------ | -| `String` | Specifies a null-terminated string. Equivalent to REG_SZ. | -| `ExpandString` | Specifies a null-terminated string that contains unexpanded | -| | references to environment variables that are expanded when | -| | the value is retrieved. Equivalent to REG_EXPAND_SZ. | -| `Binary` | Specifies binary data in any form. Equivalent to REG_BINARY. | -| `DWord` | Specifies a 32-bit binary number. Equivalent to REG_DWORD. | -| `MultiString` | Specifies an array of null-terminated strings terminated by | -| | two null characters. Equivalent to REG_MULTI_SZ. | -| `QWord` | Specifies a 64-bit binary number. Equivalent to REG_QWORD. | -| `Unknown` | Indicates an unsupported registry data type, such as | -| | REG_RESOURCE_LIST. | +| Value | Description | +| -------------- | -------------------------------------------------------------- | +| `String` | Specifies a null-terminated string. Used for REG_SZ values. | +| `ExpandString` | Specifies a null-terminated string that contains unexpanded | +| | references to environment variables that are expanded when | +| | the value is retrieved. Used for REG_EXPAND_SZ values. | +| `Binary` | Specifies binary data in any form. Used for REG_BINARY values. | +| `DWord` | Specifies a 32-bit binary number. Used for REG_DWORD values. | +| `MultiString` | Specifies an array of null-terminated strings terminated by | +| | two null characters. Used for REG_MULTI_SZ values. | +| `QWord` | Specifies a 64-bit binary number. Used for REG_QWORD values. | +| `Unknown` | Indicates an unsupported registry data type, such as | +| | REG_RESOURCE_LIST values. | #### Cmdlets supported diff --git a/reference/5.1/Microsoft.PowerShell.Management/New-ItemProperty.md b/reference/5.1/Microsoft.PowerShell.Management/New-ItemProperty.md index c610e352a972..0070a13780ac 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/New-ItemProperty.md +++ b/reference/5.1/Microsoft.PowerShell.Management/New-ItemProperty.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 10/18/2018 +ms.date: 04/28/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/new-itemproperty?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: New-ItemProperty @@ -280,16 +280,16 @@ Accept wildcard characters: False Specifies the type of property that this cmdlet adds. The acceptable values for this parameter are: -- **String**: Specifies a null-terminated string. Equivalent to **REG_SZ**. -- **ExpandString**: Specifies a null-terminated string that contains unexpanded references to - environment variables that are expanded when the value is retrieved. Equivalent to - **REG_EXPAND_SZ**. -- **Binary**: Specifies binary data in any form. Equivalent to **REG_BINARY**. -- **DWord**: Specifies a 32-bit binary number. Equivalent to **REG_DWORD**. -- **MultiString**: Specifies an array of null-terminated strings terminated by two null characters. - Equivalent to **REG_MULTI_SZ**. -- **Qword**: Specifies a 64-bit binary number. Equivalent to **REG_QWORD**. -- **Unknown**: Indicates an unsupported registry data type, such as **REG_RESOURCE_LIST**. +- `String`: Specifies a null-terminated string. Used for **REG_SZ** values. +- `ExpandString`: Specifies a null-terminated string that contains unexpanded references to + environment variables that are expanded when the value is retrieved. Used for **REG_EXPAND_SZ** + values. +- `Binary`: Specifies binary data in any form. Used for **REG_BINARY** values. +- `DWord`: Specifies a 32-bit binary number. Used for **REG_DWORD** values. +- `MultiString`: Specifies an array of null-terminated strings terminated by two null characters. + Used for **REG_MULTI_SZ** values. +- `Qword`: Specifies a 64-bit binary number. Used for **REG_QWORD** values. +- `Unknown`: Indicates an unsupported registry data type, such as **REG_RESOURCE_LIST** values. ```yaml Type: System.String diff --git a/reference/5.1/Microsoft.PowerShell.Management/Set-ItemProperty.md b/reference/5.1/Microsoft.PowerShell.Management/Set-ItemProperty.md index 314e8c16a040..7354621d71b8 100644 --- a/reference/5.1/Microsoft.PowerShell.Management/Set-ItemProperty.md +++ b/reference/5.1/Microsoft.PowerShell.Management/Set-ItemProperty.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 10/28/2021 +ms.date: 04/28/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/set-itemproperty?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: Set-ItemProperty @@ -336,16 +336,16 @@ This parameter only works in the registry drives. Specifies the type of property that this cmdlet adds. The acceptable values for this parameter are: -- **String**: Specifies a null-terminated string. Equivalent to **REG_SZ**. -- **ExpandString**: Specifies a null-terminated string that contains unexpanded references to - environment variables that are expanded when the value is retrieved. Equivalent to - **REG_EXPAND_SZ**. -- **Binary**: Specifies binary data in any form. Equivalent to **REG_BINARY**. -- **DWord**: Specifies a 32-bit binary number. Equivalent to **REG_DWORD**. -- **MultiString**: Specifies an array of null-terminated strings terminated by two null characters. - Equivalent to **REG_MULTI_SZ**. -- **Qword**: Specifies a 64-bit binary number. Equivalent to **REG_QWORD**. -- **Unknown**: Indicates an unsupported registry data type, such as **REG_RESOURCE_LIST**. +- `String`: Specifies a null-terminated string. Used for **REG_SZ** values. +- `ExpandString`: Specifies a null-terminated string that contains unexpanded references to + environment variables that are expanded when the value is retrieved. Used for **REG_EXPAND_SZ** + values. +- `Binary`: Specifies binary data in any form. Used for **REG_BINARY** values. +- `DWord`: Specifies a 32-bit binary number. Used for **REG_DWORD** values. +- `MultiString`: Specifies an array of null-terminated strings terminated by two null characters. + Used for **REG_MULTI_SZ** values. +- `Qword`: Specifies a 64-bit binary number. Used for **REG_QWORD** values. +- `Unknown`: Indicates an unsupported registry data type, such as **REG_RESOURCE_LIST** values. ```yaml Type: Microsoft.Win32.RegistryValueKind diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Registry_Provider.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Registry_Provider.md index ac52c97c74a0..0cc1402d27e2 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Registry_Provider.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Registry_Provider.md @@ -1,7 +1,7 @@ --- description: Registry Locale: en-US -ms.date: 03/07/2022 +ms.date: 04/28/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_registry_provider?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Registry Provider @@ -543,19 +543,19 @@ cmdlet. It is also available on the [Set-Item](xref:Microsoft.PowerShell.Management.Set-Item) cmdlet in the registry drives, but it has no effect. -| Value | Description | -| -------------- | ------------------------------------------------------------ | -| `String` | Specifies a null-terminated string. Equivalent to REG_SZ. | -| `ExpandString` | Specifies a null-terminated string that contains unexpanded | -| | references to environment variables that are expanded when | -| | the value is retrieved. Equivalent to REG_EXPAND_SZ. | -| `Binary` | Specifies binary data in any form. Equivalent to REG_BINARY. | -| `DWord` | Specifies a 32-bit binary number. Equivalent to REG_DWORD. | -| `MultiString` | Specifies an array of null-terminated strings terminated by | -| | two null characters. Equivalent to REG_MULTI_SZ. | -| `QWord` | Specifies a 64-bit binary number. Equivalent to REG_QWORD. | -| `Unknown` | Indicates an unsupported registry data type, such as | -| | REG_RESOURCE_LIST. | +| Value | Description | +| -------------- | -------------------------------------------------------------- | +| `String` | Specifies a null-terminated string. Used for REG_SZ values. | +| `ExpandString` | Specifies a null-terminated string that contains unexpanded | +| | references to environment variables that are expanded when | +| | the value is retrieved. Used for REG_EXPAND_SZ values. | +| `Binary` | Specifies binary data in any form. Used for REG_BINARY values. | +| `DWord` | Specifies a 32-bit binary number. Used for REG_DWORD values. | +| `MultiString` | Specifies an array of null-terminated strings terminated by | +| | two null characters. Used for REG_MULTI_SZ values. | +| `QWord` | Specifies a 64-bit binary number. Used for REG_QWORD values. | +| `Unknown` | Indicates an unsupported registry data type, such as | +| | REG_RESOURCE_LIST values. | #### Cmdlets supported diff --git a/reference/7.0/Microsoft.PowerShell.Management/New-ItemProperty.md b/reference/7.0/Microsoft.PowerShell.Management/New-ItemProperty.md index 6431ae819947..40ea3d9d9915 100644 --- a/reference/7.0/Microsoft.PowerShell.Management/New-ItemProperty.md +++ b/reference/7.0/Microsoft.PowerShell.Management/New-ItemProperty.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 05/14/2019 +ms.date: 04/28/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/new-itemproperty?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: New-ItemProperty @@ -277,16 +277,16 @@ Accept wildcard characters: True Specifies the type of property that this cmdlet adds. The acceptable values for this parameter are: -- **String**: Specifies a null-terminated string. Equivalent to **REG_SZ**. -- **ExpandString**: Specifies a null-terminated string that contains unexpanded references to - environment variables that are expanded when the value is retrieved. Equivalent to - **REG_EXPAND_SZ**. -- **Binary**: Specifies binary data in any form. Equivalent to **REG_BINARY**. -- **DWord**: Specifies a 32-bit binary number. Equivalent to **REG_DWORD**. -- **MultiString**: Specifies an array of null-terminated strings terminated by two null characters. - Equivalent to **REG_MULTI_SZ**. -- **Qword**: Specifies a 64-bit binary number. Equivalent to **REG_QWORD**. -- **Unknown**: Indicates an unsupported registry data type, such as **REG_RESOURCE_LIST**. +- `String`: Specifies a null-terminated string. Used for **REG_SZ** values. +- `ExpandString`: Specifies a null-terminated string that contains unexpanded references to + environment variables that are expanded when the value is retrieved. Used for **REG_EXPAND_SZ** + values. +- `Binary`: Specifies binary data in any form. Used for **REG_BINARY** values. +- `DWord`: Specifies a 32-bit binary number. Used for **REG_DWORD** values. +- `MultiString`: Specifies an array of null-terminated strings terminated by two null characters. + Used for **REG_MULTI_SZ** values. +- `Qword`: Specifies a 64-bit binary number. Used for **REG_QWORD** values. +- `Unknown`: Indicates an unsupported registry data type, such as **REG_RESOURCE_LIST** values. ```yaml Type: System.String diff --git a/reference/7.0/Microsoft.PowerShell.Management/Set-ItemProperty.md b/reference/7.0/Microsoft.PowerShell.Management/Set-ItemProperty.md index d981b517ceb2..aaeab5461e9d 100644 --- a/reference/7.0/Microsoft.PowerShell.Management/Set-ItemProperty.md +++ b/reference/7.0/Microsoft.PowerShell.Management/Set-ItemProperty.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 10/28/2021 +ms.date: 04/28/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/set-itemproperty?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: Set-ItemProperty @@ -338,16 +338,16 @@ This parameter only works in the registry drives. Specifies the type of property that this cmdlet adds. The acceptable values for this parameter are: -- **String**: Specifies a null-terminated string. Equivalent to **REG_SZ**. -- **ExpandString**: Specifies a null-terminated string that contains unexpanded references to - environment variables that are expanded when the value is retrieved. Equivalent to - **REG_EXPAND_SZ**. -- **Binary**: Specifies binary data in any form. Equivalent to **REG_BINARY**. -- **DWord**: Specifies a 32-bit binary number. Equivalent to **REG_DWORD**. -- **MultiString**: Specifies an array of null-terminated strings terminated by two null characters. - Equivalent to **REG_MULTI_SZ**. -- **Qword**: Specifies a 64-bit binary number. Equivalent to **REG_QWORD**. -- **Unknown**: Indicates an unsupported registry data type, such as **REG_RESOURCE_LIST**. +- `String`: Specifies a null-terminated string. Used for **REG_SZ** values. +- `ExpandString`: Specifies a null-terminated string that contains unexpanded references to + environment variables that are expanded when the value is retrieved. Used for **REG_EXPAND_SZ** + values. +- `Binary`: Specifies binary data in any form. Used for **REG_BINARY** values. +- `DWord`: Specifies a 32-bit binary number. Used for **REG_DWORD** values. +- `MultiString`: Specifies an array of null-terminated strings terminated by two null characters. + Used for **REG_MULTI_SZ** values. +- `Qword`: Specifies a 64-bit binary number. Used for **REG_QWORD** values. +- `Unknown`: Indicates an unsupported registry data type, such as **REG_RESOURCE_LIST** values. ```yaml Type: Microsoft.Win32.RegistryValueKind diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Registry_Provider.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Registry_Provider.md index fb7f87aa8d3b..bf67758df000 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Registry_Provider.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Registry_Provider.md @@ -1,7 +1,7 @@ --- description: Registry Locale: en-US -ms.date: 03/07/2022 +ms.date: 04/28/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_registry_provider?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Registry Provider @@ -543,19 +543,19 @@ cmdlet. It is also available on the [Set-Item](xref:Microsoft.PowerShell.Management.Set-Item) cmdlet in the registry drives, but it has no effect. -| Value | Description | -| -------------- | ------------------------------------------------------------ | -| `String` | Specifies a null-terminated string. Equivalent to REG_SZ. | -| `ExpandString` | Specifies a null-terminated string that contains unexpanded | -| | references to environment variables that are expanded when | -| | the value is retrieved. Equivalent to REG_EXPAND_SZ. | -| `Binary` | Specifies binary data in any form. Equivalent to REG_BINARY. | -| `DWord` | Specifies a 32-bit binary number. Equivalent to REG_DWORD. | -| `MultiString` | Specifies an array of null-terminated strings terminated by | -| | two null characters. Equivalent to REG_MULTI_SZ. | -| `QWord` | Specifies a 64-bit binary number. Equivalent to REG_QWORD. | -| `Unknown` | Indicates an unsupported registry data type, such as | -| | REG_RESOURCE_LIST. | +| Value | Description | +| -------------- | -------------------------------------------------------------- | +| `String` | Specifies a null-terminated string. Used for REG_SZ values. | +| `ExpandString` | Specifies a null-terminated string that contains unexpanded | +| | references to environment variables that are expanded when | +| | the value is retrieved. Used for REG_EXPAND_SZ values. | +| `Binary` | Specifies binary data in any form. Used for REG_BINARY values. | +| `DWord` | Specifies a 32-bit binary number. Used for REG_DWORD values. | +| `MultiString` | Specifies an array of null-terminated strings terminated by | +| | two null characters. Used for REG_MULTI_SZ values. | +| `QWord` | Specifies a 64-bit binary number. Used for REG_QWORD values. | +| `Unknown` | Indicates an unsupported registry data type, such as | +| | REG_RESOURCE_LIST values. | #### Cmdlets supported diff --git a/reference/7.1/Microsoft.PowerShell.Management/New-ItemProperty.md b/reference/7.1/Microsoft.PowerShell.Management/New-ItemProperty.md index e5f849bf3ddb..cc2021148028 100644 --- a/reference/7.1/Microsoft.PowerShell.Management/New-ItemProperty.md +++ b/reference/7.1/Microsoft.PowerShell.Management/New-ItemProperty.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 05/14/2019 +ms.date: 04/28/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/new-itemproperty?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: New-ItemProperty @@ -277,16 +277,16 @@ Accept wildcard characters: True Specifies the type of property that this cmdlet adds. The acceptable values for this parameter are: -- **String**: Specifies a null-terminated string. Equivalent to **REG_SZ**. -- **ExpandString**: Specifies a null-terminated string that contains unexpanded references to - environment variables that are expanded when the value is retrieved. Equivalent to - **REG_EXPAND_SZ**. -- **Binary**: Specifies binary data in any form. Equivalent to **REG_BINARY**. -- **DWord**: Specifies a 32-bit binary number. Equivalent to **REG_DWORD**. -- **MultiString**: Specifies an array of null-terminated strings terminated by two null characters. - Equivalent to **REG_MULTI_SZ**. -- **Qword**: Specifies a 64-bit binary number. Equivalent to **REG_QWORD**. -- **Unknown**: Indicates an unsupported registry data type, such as **REG_RESOURCE_LIST**. +- `String`: Specifies a null-terminated string. Used for **REG_SZ** values. +- `ExpandString`: Specifies a null-terminated string that contains unexpanded references to + environment variables that are expanded when the value is retrieved. Used for **REG_EXPAND_SZ** + values. +- `Binary`: Specifies binary data in any form. Used for **REG_BINARY** values. +- `DWord`: Specifies a 32-bit binary number. Used for **REG_DWORD** values. +- `MultiString`: Specifies an array of null-terminated strings terminated by two null characters. + Used for **REG_MULTI_SZ** values. +- `Qword`: Specifies a 64-bit binary number. Used for **REG_QWORD** values. +- `Unknown`: Indicates an unsupported registry data type, such as **REG_RESOURCE_LIST** values. ```yaml Type: System.String diff --git a/reference/7.1/Microsoft.PowerShell.Management/Set-ItemProperty.md b/reference/7.1/Microsoft.PowerShell.Management/Set-ItemProperty.md index c48f6e95ff99..311949e31eaf 100644 --- a/reference/7.1/Microsoft.PowerShell.Management/Set-ItemProperty.md +++ b/reference/7.1/Microsoft.PowerShell.Management/Set-ItemProperty.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 10/28/2021 +ms.date: 04/28/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/set-itemproperty?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: Set-ItemProperty @@ -338,16 +338,16 @@ This parameter only works in the registry drives. Specifies the type of property that this cmdlet adds. The acceptable values for this parameter are: -- **String**: Specifies a null-terminated string. Equivalent to **REG_SZ**. -- **ExpandString**: Specifies a null-terminated string that contains unexpanded references to - environment variables that are expanded when the value is retrieved. Equivalent to - **REG_EXPAND_SZ**. -- **Binary**: Specifies binary data in any form. Equivalent to **REG_BINARY**. -- **DWord**: Specifies a 32-bit binary number. Equivalent to **REG_DWORD**. -- **MultiString**: Specifies an array of null-terminated strings terminated by two null characters. - Equivalent to **REG_MULTI_SZ**. -- **Qword**: Specifies a 64-bit binary number. Equivalent to **REG_QWORD**. -- **Unknown**: Indicates an unsupported registry data type, such as **REG_RESOURCE_LIST**. +- `String`: Specifies a null-terminated string. Used for **REG_SZ** values. +- `ExpandString`: Specifies a null-terminated string that contains unexpanded references to + environment variables that are expanded when the value is retrieved. Used for **REG_EXPAND_SZ** + values. +- `Binary`: Specifies binary data in any form. Used for **REG_BINARY** values. +- `DWord`: Specifies a 32-bit binary number. Used for **REG_DWORD** values. +- `MultiString`: Specifies an array of null-terminated strings terminated by two null characters. + Used for **REG_MULTI_SZ** values. +- `Qword`: Specifies a 64-bit binary number. Used for **REG_QWORD** values. +- `Unknown`: Indicates an unsupported registry data type, such as **REG_RESOURCE_LIST** values. ```yaml Type: Microsoft.Win32.RegistryValueKind diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Registry_Provider.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Registry_Provider.md index f6170f1bbdd9..691b70ae14d3 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Registry_Provider.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Registry_Provider.md @@ -1,7 +1,7 @@ --- description: Registry Locale: en-US -ms.date: 03/07/2022 +ms.date: 04/28/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_registry_provider?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Registry Provider @@ -543,19 +543,19 @@ cmdlet. It is also available on the [Set-Item](xref:Microsoft.PowerShell.Management.Set-Item) cmdlet in the registry drives, but it has no effect. -| Value | Description | -| -------------- | ------------------------------------------------------------ | -| `String` | Specifies a null-terminated string. Equivalent to REG_SZ. | -| `ExpandString` | Specifies a null-terminated string that contains unexpanded | -| | references to environment variables that are expanded when | -| | the value is retrieved. Equivalent to REG_EXPAND_SZ. | -| `Binary` | Specifies binary data in any form. Equivalent to REG_BINARY. | -| `DWord` | Specifies a 32-bit binary number. Equivalent to REG_DWORD. | -| `MultiString` | Specifies an array of null-terminated strings terminated by | -| | two null characters. Equivalent to REG_MULTI_SZ. | -| `QWord` | Specifies a 64-bit binary number. Equivalent to REG_QWORD. | -| `Unknown` | Indicates an unsupported registry data type, such as | -| | REG_RESOURCE_LIST. | +| Value | Description | +| -------------- | -------------------------------------------------------------- | +| `String` | Specifies a null-terminated string. Used for REG_SZ values. | +| `ExpandString` | Specifies a null-terminated string that contains unexpanded | +| | references to environment variables that are expanded when | +| | the value is retrieved. Used for REG_EXPAND_SZ values. | +| `Binary` | Specifies binary data in any form. Used for REG_BINARY values. | +| `DWord` | Specifies a 32-bit binary number. Used for REG_DWORD values. | +| `MultiString` | Specifies an array of null-terminated strings terminated by | +| | two null characters. Used for REG_MULTI_SZ values. | +| `QWord` | Specifies a 64-bit binary number. Used for REG_QWORD values. | +| `Unknown` | Indicates an unsupported registry data type, such as | +| | REG_RESOURCE_LIST values. | #### Cmdlets supported diff --git a/reference/7.2/Microsoft.PowerShell.Management/New-ItemProperty.md b/reference/7.2/Microsoft.PowerShell.Management/New-ItemProperty.md index 7bb32ef1d17c..024ca2b95b79 100644 --- a/reference/7.2/Microsoft.PowerShell.Management/New-ItemProperty.md +++ b/reference/7.2/Microsoft.PowerShell.Management/New-ItemProperty.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 05/14/2019 +ms.date: 04/28/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/new-itemproperty?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: New-ItemProperty @@ -277,16 +277,16 @@ Accept wildcard characters: True Specifies the type of property that this cmdlet adds. The acceptable values for this parameter are: -- **String**: Specifies a null-terminated string. Equivalent to **REG_SZ**. -- **ExpandString**: Specifies a null-terminated string that contains unexpanded references to - environment variables that are expanded when the value is retrieved. Equivalent to - **REG_EXPAND_SZ**. -- **Binary**: Specifies binary data in any form. Equivalent to **REG_BINARY**. -- **DWord**: Specifies a 32-bit binary number. Equivalent to **REG_DWORD**. -- **MultiString**: Specifies an array of null-terminated strings terminated by two null characters. - Equivalent to **REG_MULTI_SZ**. -- **Qword**: Specifies a 64-bit binary number. Equivalent to **REG_QWORD**. -- **Unknown**: Indicates an unsupported registry data type, such as **REG_RESOURCE_LIST**. +- `String`: Specifies a null-terminated string. Used for **REG_SZ** values. +- `ExpandString`: Specifies a null-terminated string that contains unexpanded references to + environment variables that are expanded when the value is retrieved. Used for **REG_EXPAND_SZ** + values. +- `Binary`: Specifies binary data in any form. Used for **REG_BINARY** values. +- `DWord`: Specifies a 32-bit binary number. Used for **REG_DWORD** values. +- `MultiString`: Specifies an array of null-terminated strings terminated by two null characters. + Used for **REG_MULTI_SZ** values. +- `Qword`: Specifies a 64-bit binary number. Used for **REG_QWORD** values. +- `Unknown`: Indicates an unsupported registry data type, such as **REG_RESOURCE_LIST** values. ```yaml Type: System.String diff --git a/reference/7.2/Microsoft.PowerShell.Management/Set-ItemProperty.md b/reference/7.2/Microsoft.PowerShell.Management/Set-ItemProperty.md index b572b9368143..386c01f827ca 100644 --- a/reference/7.2/Microsoft.PowerShell.Management/Set-ItemProperty.md +++ b/reference/7.2/Microsoft.PowerShell.Management/Set-ItemProperty.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 10/28/2021 +ms.date: 04/28/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/set-itemproperty?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: Set-ItemProperty @@ -338,16 +338,16 @@ This parameter only works in the registry drives. Specifies the type of property that this cmdlet adds. The acceptable values for this parameter are: -- **String**: Specifies a null-terminated string. Equivalent to **REG_SZ**. -- **ExpandString**: Specifies a null-terminated string that contains unexpanded references to - environment variables that are expanded when the value is retrieved. Equivalent to - **REG_EXPAND_SZ**. -- **Binary**: Specifies binary data in any form. Equivalent to **REG_BINARY**. -- **DWord**: Specifies a 32-bit binary number. Equivalent to **REG_DWORD**. -- **MultiString**: Specifies an array of null-terminated strings terminated by two null characters. - Equivalent to **REG_MULTI_SZ**. -- **Qword**: Specifies a 64-bit binary number. Equivalent to **REG_QWORD**. -- **Unknown**: Indicates an unsupported registry data type, such as **REG_RESOURCE_LIST**. +- `String`: Specifies a null-terminated string. Used for **REG_SZ** values. +- `ExpandString`: Specifies a null-terminated string that contains unexpanded references to + environment variables that are expanded when the value is retrieved. Used for **REG_EXPAND_SZ** + values. +- `Binary`: Specifies binary data in any form. Used for **REG_BINARY** values. +- `DWord`: Specifies a 32-bit binary number. Used for **REG_DWORD** values. +- `MultiString`: Specifies an array of null-terminated strings terminated by two null characters. + Used for **REG_MULTI_SZ** values. +- `Qword`: Specifies a 64-bit binary number. Used for **REG_QWORD** values. +- `Unknown`: Indicates an unsupported registry data type, such as **REG_RESOURCE_LIST** values. ```yaml Type: Microsoft.Win32.RegistryValueKind diff --git a/reference/7.3/Microsoft.PowerShell.Core/About/about_Registry_Provider.md b/reference/7.3/Microsoft.PowerShell.Core/About/about_Registry_Provider.md index 6d250224d1c1..dc9b707e53bf 100644 --- a/reference/7.3/Microsoft.PowerShell.Core/About/about_Registry_Provider.md +++ b/reference/7.3/Microsoft.PowerShell.Core/About/about_Registry_Provider.md @@ -1,7 +1,7 @@ --- description: Registry Locale: en-US -ms.date: 03/07/2022 +ms.date: 04/28/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_registry_provider?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Registry Provider @@ -543,19 +543,19 @@ cmdlet. It is also available on the [Set-Item](xref:Microsoft.PowerShell.Management.Set-Item) cmdlet in the registry drives, but it has no effect. -| Value | Description | -| -------------- | ------------------------------------------------------------ | -| `String` | Specifies a null-terminated string. Equivalent to REG_SZ. | -| `ExpandString` | Specifies a null-terminated string that contains unexpanded | -| | references to environment variables that are expanded when | -| | the value is retrieved. Equivalent to REG_EXPAND_SZ. | -| `Binary` | Specifies binary data in any form. Equivalent to REG_BINARY. | -| `DWord` | Specifies a 32-bit binary number. Equivalent to REG_DWORD. | -| `MultiString` | Specifies an array of null-terminated strings terminated by | -| | two null characters. Equivalent to REG_MULTI_SZ. | -| `QWord` | Specifies a 64-bit binary number. Equivalent to REG_QWORD. | -| `Unknown` | Indicates an unsupported registry data type, such as | -| | REG_RESOURCE_LIST. | +| Value | Description | +| -------------- | -------------------------------------------------------------- | +| `String` | Specifies a null-terminated string. Used for REG_SZ values. | +| `ExpandString` | Specifies a null-terminated string that contains unexpanded | +| | references to environment variables that are expanded when | +| | the value is retrieved. Used for REG_EXPAND_SZ values. | +| `Binary` | Specifies binary data in any form. Used for REG_BINARY values. | +| `DWord` | Specifies a 32-bit binary number. Used for REG_DWORD values. | +| `MultiString` | Specifies an array of null-terminated strings terminated by | +| | two null characters. Used for REG_MULTI_SZ values. | +| `QWord` | Specifies a 64-bit binary number. Used for REG_QWORD values. | +| `Unknown` | Indicates an unsupported registry data type, such as | +| | REG_RESOURCE_LIST values. | #### Cmdlets supported diff --git a/reference/7.3/Microsoft.PowerShell.Management/New-ItemProperty.md b/reference/7.3/Microsoft.PowerShell.Management/New-ItemProperty.md index c1ff546122f3..6c455734cdba 100644 --- a/reference/7.3/Microsoft.PowerShell.Management/New-ItemProperty.md +++ b/reference/7.3/Microsoft.PowerShell.Management/New-ItemProperty.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 05/14/2019 +ms.date: 04/28/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/new-itemproperty?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: New-ItemProperty @@ -277,16 +277,16 @@ Accept wildcard characters: True Specifies the type of property that this cmdlet adds. The acceptable values for this parameter are: -- **String**: Specifies a null-terminated string. Equivalent to **REG_SZ**. -- **ExpandString**: Specifies a null-terminated string that contains unexpanded references to - environment variables that are expanded when the value is retrieved. Equivalent to - **REG_EXPAND_SZ**. -- **Binary**: Specifies binary data in any form. Equivalent to **REG_BINARY**. -- **DWord**: Specifies a 32-bit binary number. Equivalent to **REG_DWORD**. -- **MultiString**: Specifies an array of null-terminated strings terminated by two null characters. - Equivalent to **REG_MULTI_SZ**. -- **Qword**: Specifies a 64-bit binary number. Equivalent to **REG_QWORD**. -- **Unknown**: Indicates an unsupported registry data type, such as **REG_RESOURCE_LIST**. +- `String`: Specifies a null-terminated string. Used for **REG_SZ** values. +- `ExpandString`: Specifies a null-terminated string that contains unexpanded references to + environment variables that are expanded when the value is retrieved. Used for **REG_EXPAND_SZ** + values. +- `Binary`: Specifies binary data in any form. Used for **REG_BINARY** values. +- `DWord`: Specifies a 32-bit binary number. Used for **REG_DWORD** values. +- `MultiString`: Specifies an array of null-terminated strings terminated by two null characters. + Used for **REG_MULTI_SZ** values. +- `Qword`: Specifies a 64-bit binary number. Used for **REG_QWORD** values. +- `Unknown`: Indicates an unsupported registry data type, such as **REG_RESOURCE_LIST** values. ```yaml Type: System.String diff --git a/reference/7.3/Microsoft.PowerShell.Management/Set-ItemProperty.md b/reference/7.3/Microsoft.PowerShell.Management/Set-ItemProperty.md index b52cd15cbfc7..a968dfb56e0c 100644 --- a/reference/7.3/Microsoft.PowerShell.Management/Set-ItemProperty.md +++ b/reference/7.3/Microsoft.PowerShell.Management/Set-ItemProperty.md @@ -2,8 +2,8 @@ external help file: Microsoft.PowerShell.Commands.Management.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Management -ms.date: 10/28/2021 -online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/set-itemproperty?view=powershell-7.3&WT.mc_id=ps-gethelp +ms.date: 04/28/2022 +online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.management/set-itemproperty?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: Set-ItemProperty --- @@ -338,16 +338,16 @@ This parameter only works in the registry drives. Specifies the type of property that this cmdlet adds. The acceptable values for this parameter are: -- **String**: Specifies a null-terminated string. Equivalent to **REG_SZ**. -- **ExpandString**: Specifies a null-terminated string that contains unexpanded references to - environment variables that are expanded when the value is retrieved. Equivalent to - **REG_EXPAND_SZ**. -- **Binary**: Specifies binary data in any form. Equivalent to **REG_BINARY**. -- **DWord**: Specifies a 32-bit binary number. Equivalent to **REG_DWORD**. -- **MultiString**: Specifies an array of null-terminated strings terminated by two null characters. - Equivalent to **REG_MULTI_SZ**. -- **Qword**: Specifies a 64-bit binary number. Equivalent to **REG_QWORD**. -- **Unknown**: Indicates an unsupported registry data type, such as **REG_RESOURCE_LIST**. +- `String`: Specifies a null-terminated string. Used for **REG_SZ** values. +- `ExpandString`: Specifies a null-terminated string that contains unexpanded references to + environment variables that are expanded when the value is retrieved. Used for **REG_EXPAND_SZ** + values. +- `Binary`: Specifies binary data in any form. Used for **REG_BINARY** values. +- `DWord`: Specifies a 32-bit binary number. Used for **REG_DWORD** values. +- `MultiString`: Specifies an array of null-terminated strings terminated by two null characters. + Used for **REG_MULTI_SZ** values. +- `Qword`: Specifies a 64-bit binary number. Used for **REG_QWORD** values. +- `Unknown`: Indicates an unsupported registry data type, such as **REG_RESOURCE_LIST** values. ```yaml Type: Microsoft.Win32.RegistryValueKind From c9bed40a1a36a4ad576dc1b6f44ebb9d852ade17 Mon Sep 17 00:00:00 2001 From: "Michael T Lombardi (He/Him)" Date: Fri, 29 Apr 2022 16:02:32 -0500 Subject: [PATCH 26/31] (GH-8770) Clarify MSU support is for x64 only (#8774) This commit clarifies that support for using Microsoft Update for Powershell is limited to x64-based systems. --- reference/docs-conceptual/install/microsoft-update-faq.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/docs-conceptual/install/microsoft-update-faq.yml b/reference/docs-conceptual/install/microsoft-update-faq.yml index 31fd27654008..43f982db3fa1 100644 --- a/reference/docs-conceptual/install/microsoft-update-faq.yml +++ b/reference/docs-conceptual/install/microsoft-update-faq.yml @@ -39,7 +39,7 @@ sections: questions: - question: What version of Windows is required to support the Microsoft Update feature? answer: | - You must have Windows 10 RS3 (10.0.16299) or newer installed. + You must have Windows 10 Version 1709 (10.0.16299) or newer installed on an x64-based system. - question: Do I need to check both boxes in the setup dialog? answer: | From 8c59547aa3bd56ba4acce05bb50a5ebd34b4c31d Mon Sep 17 00:00:00 2001 From: tommymaynard Date: Tue, 3 May 2022 11:04:28 -0700 Subject: [PATCH 27/31] Update asPowerShell spacing (#8779) --- reference/5.1/Microsoft.PowerShell.Core/About/about_Parsing.md | 2 +- reference/7.0/Microsoft.PowerShell.Core/About/about_Parsing.md | 2 +- reference/7.1/Microsoft.PowerShell.Core/About/about_Parsing.md | 2 +- reference/7.2/Microsoft.PowerShell.Core/About/about_Parsing.md | 2 +- reference/7.3/Microsoft.PowerShell.Core/About/about_Parsing.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Parsing.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Parsing.md index 2d563d528507..03047a9323f1 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Parsing.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Parsing.md @@ -203,7 +203,7 @@ icacls X:\VMS /grant Dom\HVAdmin:`(CI`)`(OI`)F ### The stop-parsing token Beginning in PowerShell 3.0, you can use the stop-parsing token (`--%`) to -stop PowerShell from interpreting input asPowerShell commands or expressions. +stop PowerShell from interpreting input as PowerShell commands or expressions. > [!NOTE] > The stop-parsing token is only intended for use on Windows platforms. diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Parsing.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Parsing.md index 381fb466877b..f5f5b90640ec 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Parsing.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Parsing.md @@ -203,7 +203,7 @@ icacls X:\VMS /grant Dom\HVAdmin:`(CI`)`(OI`)F ### The stop-parsing token Beginning in PowerShell 3.0, you can use the stop-parsing token (`--%`) to -stop PowerShell from interpreting input asPowerShell commands or expressions. +stop PowerShell from interpreting input as PowerShell commands or expressions. > [!NOTE] > The stop-parsing token is only intended for use on Windows platforms. diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Parsing.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Parsing.md index edbcb3a054ea..c156f5a77be0 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Parsing.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Parsing.md @@ -203,7 +203,7 @@ icacls X:\VMS /grant Dom\HVAdmin:`(CI`)`(OI`)F ### The stop-parsing token Beginning in PowerShell 3.0, you can use the stop-parsing token (`--%`) to -stop PowerShell from interpreting input asPowerShell commands or expressions. +stop PowerShell from interpreting input as PowerShell commands or expressions. > [!NOTE] > The stop-parsing token is only intended for use on Windows platforms. diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Parsing.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Parsing.md index 5629cdee8597..2846e872be8e 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Parsing.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Parsing.md @@ -203,7 +203,7 @@ icacls X:\VMS /grant Dom\HVAdmin:`(CI`)`(OI`)F ### The stop-parsing token Beginning in PowerShell 3.0, you can use the stop-parsing token (`--%`) to -stop PowerShell from interpreting input asPowerShell commands or expressions. +stop PowerShell from interpreting input as PowerShell commands or expressions. > [!NOTE] > The stop-parsing token is only intended for use on Windows platforms. diff --git a/reference/7.3/Microsoft.PowerShell.Core/About/about_Parsing.md b/reference/7.3/Microsoft.PowerShell.Core/About/about_Parsing.md index 8005129f3af7..25b8949adc33 100644 --- a/reference/7.3/Microsoft.PowerShell.Core/About/about_Parsing.md +++ b/reference/7.3/Microsoft.PowerShell.Core/About/about_Parsing.md @@ -203,7 +203,7 @@ icacls X:\VMS /grant Dom\HVAdmin:`(CI`)`(OI`)F ### The stop-parsing token Beginning in PowerShell 3.0, you can use the stop-parsing token (`--%`) to -stop PowerShell from interpreting input asPowerShell commands or expressions. +stop PowerShell from interpreting input as PowerShell commands or expressions. > [!NOTE] > The stop-parsing token is only intended for use on Windows platforms. From 093f436b238641cbed50930ee18ab99146304e34 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 3 May 2022 13:42:39 -0500 Subject: [PATCH 28/31] Update monthly stats (#8782) --- .../docs-conceptual/community/2022-updates.md | 39 ++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/reference/docs-conceptual/community/2022-updates.md b/reference/docs-conceptual/community/2022-updates.md index 8450f049e70e..21b0f9771ebb 100644 --- a/reference/docs-conceptual/community/2022-updates.md +++ b/reference/docs-conceptual/community/2022-updates.md @@ -1,6 +1,6 @@ --- description: List of changes to the PowerShell documentation for 2022 -ms.date: 04/01/2022 +ms.date: 05/03/2022 title: What's New in PowerShell-Docs for 2022 --- # What's new in PowerShell Docs for 2022 @@ -11,6 +11,43 @@ contributions from the community. Help us make the documentation better for you. Read the [Contributor's Guide][contrib] to learn how to get started. +## 2022-April + +New content + +- No new content this month + +Content updates + +- Rewrote the install instructions for [PowerShellGet](/powershell/scripting/gallery/installing-psget) +- Created separate article for + [Installing PowerShellGet on older Windows systems](/powershell/scripting/gallery/install-on-older-systems) + +Other projects + +- PowerShell + DevOps Summit April 25-28 + - Gave presentation about contributing to Docs + - Lightning demo about argument completers + - Interview for the [PowerShell Podcast](https://powershellpodcast.podbean.com/e/contributing-to-powershell-made-easy-with-sean-wheeler/) + +### Top Community Contributors + +GitHub stats + +- 24 PRs merged (3 from Community) +- 22 issues opened (17 from Community) +- 21 issues closed (15 Community issues closed) + +The following people have contributed to PowerShell docs by submitting pull requests or filing +issues. Thank you! + +| GitHub Id | PRs merged | Issues opened | +| -------------- | :--------: | :-----------: | +| Hrxn | 1 | | +| kevinholtkamp | 1 | | +| MikeyBronowski | 1 | | +| tommymaynard | | 4 | + ## 2022-March New Content From cc80df088e373dd5aa63d59e10a9eea99dacd18a Mon Sep 17 00:00:00 2001 From: "Michael T Lombardi (He/Him)" Date: Tue, 3 May 2022 14:08:44 -0500 Subject: [PATCH 29/31] (GH-8777) Reword here-string section for clarity (#8780) * (GH-8777) Reword here-string section for clarity This commit rewords the section of About Quoting Rules for clarity by being more explicit about the opening and closing tags and their effect. * Apply suggestions from review Co-authored-by: Sean Wheeler * (GH-8777) Rework info for clarity This commit reworks the list of distinguishing factors of a here-string into an unordered list to improve readability and clarify the info. * (GH-8777) Push changes to all versions Co-authored-by: Sean Wheeler --- .../About/about_Quoting_Rules.md | 27 ++++++++++++------- .../About/about_Quoting_Rules.md | 27 ++++++++++++------- .../About/about_Quoting_Rules.md | 27 ++++++++++++------- .../About/about_Quoting_Rules.md | 27 ++++++++++++------- .../About/about_Quoting_Rules.md | 27 ++++++++++++------- 5 files changed, 85 insertions(+), 50 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md index b7214a3ea5a7..16f51da7fa97 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md @@ -1,7 +1,7 @@ --- description: Describes rules for using single and double quotation marks in PowerShell. Locale: en-US -ms.date: 04/26/2022 +ms.date: 05/03/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Quoting Rules @@ -201,10 +201,16 @@ Use a quotation mark (`") to begin a string. The quotation rules for here-strings are slightly different. -A here-string is a single-quoted or double-quoted string in which quotation -marks are interpreted literally. A here-string can span multiple lines. All the -lines in a here-string are interpreted as strings even though they are not -enclosed in quotation marks. +A here-string is a single-quoted or double-quoted string surrounded by at signs +(`@`). Quotation marks within a here-string are interpreted literally. + +A here-string: + +- spans multiple lines +- begins with the opening mark followed by a newline +- ends with a newline followed by the closing mark +- includes every line between the opening and closing marks as part of a single + string Like regular strings, variables are replaced by their values in double-quoted here-strings. In single-quoted here-strings, variables are not replaced by @@ -214,7 +220,7 @@ You can use here-strings for any text, but they are particularly useful for the following kinds of text: - Text that contains literal quotation marks -- Multiple lines of text, such as the text in an HTML or XML +- Multiple lines of text, such as the text in an HTML or XML block - The Help text for a script or function document A here-string can have either of the following formats, where `` @@ -237,11 +243,12 @@ Single-quotes: '@ ``` -In either format, the closing quotation mark must be the first character in -the line. +> [!NOTE] +> The final newline character is part of the closing mark. It is not added to +> the here-string. -A here-string contains all the text between the two hidden characters. In the -here-string, all quotation marks are interpreted literally. For example: +A here-string contains all the text between the opening and closing marks. In +the here-string, all quotation marks are interpreted literally. For example: ```powershell @" diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md index 401e1e4e4ffc..fb4d655588be 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md @@ -1,7 +1,7 @@ --- description: Describes rules for using single and double quotation marks in PowerShell. Locale: en-US -ms.date: 04/26/2022 +ms.date: 05/03/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Quoting Rules @@ -201,10 +201,16 @@ Use a quotation mark (`") to begin a string. The quotation rules for here-strings are slightly different. -A here-string is a single-quoted or double-quoted string in which quotation -marks are interpreted literally. A here-string can span multiple lines. All the -lines in a here-string are interpreted as strings even though they are not -enclosed in quotation marks. +A here-string is a single-quoted or double-quoted string surrounded by at signs +(`@`). Quotation marks within a here-string are interpreted literally. + +A here-string: + +- spans multiple lines +- begins with the opening mark followed by a newline +- ends with a newline followed by the closing mark +- includes every line between the opening and closing marks as part of a single + string Like regular strings, variables are replaced by their values in double-quoted here-strings. In single-quoted here-strings, variables are not replaced by @@ -214,7 +220,7 @@ You can use here-strings for any text, but they are particularly useful for the following kinds of text: - Text that contains literal quotation marks -- Multiple lines of text, such as the text in an HTML or XML +- Multiple lines of text, such as the text in an HTML or XML block - The Help text for a script or function document A here-string can have either of the following formats, where `` @@ -237,11 +243,12 @@ Single-quotes: '@ ``` -In either format, the closing quotation mark must be the first character in -the line. +> [!NOTE] +> The final newline character is part of the closing mark. It is not added to +> the here-string. -A here-string contains all the text between the two hidden characters. In the -here-string, all quotation marks are interpreted literally. For example: +A here-string contains all the text between the opening and closing marks. In +the here-string, all quotation marks are interpreted literally. For example: ```powershell @" diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md index 6e28b8921dca..0d33acb729e6 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md @@ -1,7 +1,7 @@ --- description: Describes rules for using single and double quotation marks in PowerShell. Locale: en-US -ms.date: 04/26/2022 +ms.date: 05/03/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Quoting Rules @@ -201,10 +201,16 @@ Use a quotation mark (`") to begin a string. The quotation rules for here-strings are slightly different. -A here-string is a single-quoted or double-quoted string in which quotation -marks are interpreted literally. A here-string can span multiple lines. All the -lines in a here-string are interpreted as strings even though they are not -enclosed in quotation marks. +A here-string is a single-quoted or double-quoted string surrounded by at signs +(`@`). Quotation marks within a here-string are interpreted literally. + +A here-string: + +- spans multiple lines +- begins with the opening mark followed by a newline +- ends with a newline followed by the closing mark +- includes every line between the opening and closing marks as part of a single + string Like regular strings, variables are replaced by their values in double-quoted here-strings. In single-quoted here-strings, variables are not replaced by @@ -214,7 +220,7 @@ You can use here-strings for any text, but they are particularly useful for the following kinds of text: - Text that contains literal quotation marks -- Multiple lines of text, such as the text in an HTML or XML +- Multiple lines of text, such as the text in an HTML or XML block - The Help text for a script or function document A here-string can have either of the following formats, where `` @@ -237,11 +243,12 @@ Single-quotes: '@ ``` -In either format, the closing quotation mark must be the first character in -the line. +> [!NOTE] +> The final newline character is part of the closing mark. It is not added to +> the here-string. -A here-string contains all the text between the two hidden characters. In the -here-string, all quotation marks are interpreted literally. For example: +A here-string contains all the text between the opening and closing marks. In +the here-string, all quotation marks are interpreted literally. For example: ```powershell @" diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md index bbcd750a0f36..8aad7e1d1642 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md @@ -1,7 +1,7 @@ --- description: Describes rules for using single and double quotation marks in PowerShell. Locale: en-US -ms.date: 04/26/2022 +ms.date: 05/03/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Quoting Rules @@ -201,10 +201,16 @@ Use a quotation mark (`") to begin a string. The quotation rules for here-strings are slightly different. -A here-string is a single-quoted or double-quoted string in which quotation -marks are interpreted literally. A here-string can span multiple lines. All the -lines in a here-string are interpreted as strings even though they are not -enclosed in quotation marks. +A here-string is a single-quoted or double-quoted string surrounded by at signs +(`@`). Quotation marks within a here-string are interpreted literally. + +A here-string: + +- spans multiple lines +- begins with the opening mark followed by a newline +- ends with a newline followed by the closing mark +- includes every line between the opening and closing marks as part of a single + string Like regular strings, variables are replaced by their values in double-quoted here-strings. In single-quoted here-strings, variables are not replaced by @@ -214,7 +220,7 @@ You can use here-strings for any text, but they are particularly useful for the following kinds of text: - Text that contains literal quotation marks -- Multiple lines of text, such as the text in an HTML or XML +- Multiple lines of text, such as the text in an HTML or XML block - The Help text for a script or function document A here-string can have either of the following formats, where `` @@ -237,11 +243,12 @@ Single-quotes: '@ ``` -In either format, the closing quotation mark must be the first character in -the line. +> [!NOTE] +> The final newline character is part of the closing mark. It is not added to +> the here-string. -A here-string contains all the text between the two hidden characters. In the -here-string, all quotation marks are interpreted literally. For example: +A here-string contains all the text between the opening and closing marks. In +the here-string, all quotation marks are interpreted literally. For example: ```powershell @" diff --git a/reference/7.3/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md b/reference/7.3/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md index 7e569ee4212d..ed56981ae422 100644 --- a/reference/7.3/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md +++ b/reference/7.3/Microsoft.PowerShell.Core/About/about_Quoting_Rules.md @@ -1,7 +1,7 @@ --- description: Describes rules for using single and double quotation marks in PowerShell. Locale: en-US -ms.date: 04/26/2022 +ms.date: 05/03/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_quoting_rules?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Quoting Rules @@ -201,10 +201,16 @@ Use a quotation mark (`") to begin a string. The quotation rules for here-strings are slightly different. -A here-string is a single-quoted or double-quoted string in which quotation -marks are interpreted literally. A here-string can span multiple lines. All the -lines in a here-string are interpreted as strings even though they are not -enclosed in quotation marks. +A here-string is a single-quoted or double-quoted string surrounded by at signs +(`@`). Quotation marks within a here-string are interpreted literally. + +A here-string: + +- spans multiple lines +- begins with the opening mark followed by a newline +- ends with a newline followed by the closing mark +- includes every line between the opening and closing marks as part of a single + string Like regular strings, variables are replaced by their values in double-quoted here-strings. In single-quoted here-strings, variables are not replaced by @@ -214,7 +220,7 @@ You can use here-strings for any text, but they are particularly useful for the following kinds of text: - Text that contains literal quotation marks -- Multiple lines of text, such as the text in an HTML or XML +- Multiple lines of text, such as the text in an HTML or XML block - The Help text for a script or function document A here-string can have either of the following formats, where `` @@ -237,11 +243,12 @@ Single-quotes: '@ ``` -In either format, the closing quotation mark must be the first character in -the line. +> [!NOTE] +> The final newline character is part of the closing mark. It is not added to +> the here-string. -A here-string contains all the text between the two hidden characters. In the -here-string, all quotation marks are interpreted literally. For example: +A here-string contains all the text between the opening and closing marks. In +the here-string, all quotation marks are interpreted literally. For example: ```powershell @" From 368727685932d4ee2a8992293451273152b20936 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 3 May 2022 16:52:37 -0500 Subject: [PATCH 30/31] Update Hall of Fame (#8783) --- reference/docs-conceptual/community/hall-of-fame.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/reference/docs-conceptual/community/hall-of-fame.md b/reference/docs-conceptual/community/hall-of-fame.md index 8e9c2dc79e13..b64c11f5d894 100644 --- a/reference/docs-conceptual/community/hall-of-fame.md +++ b/reference/docs-conceptual/community/hall-of-fame.md @@ -1,6 +1,6 @@ --- description: List of the GitHub users that have the most contributions to the PowerShell-Doc project. -ms.date: 04/01/2022 +ms.date: 05/03/2022 title: Community contributor Hall of Fame --- # Community Contributor Hall of Fame @@ -17,7 +17,7 @@ Pull Requests help us fix those issues and make the documentation better for eve | PRs Merged | 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | Grand Total | | --------------- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ----------: | -| Community | 3 | 194 | 446 | 464 | 318 | 161 | 100 | 21 | 1707 | +| Community | 3 | 194 | 446 | 464 | 318 | 161 | 100 | 24 | 1710 | | matt9ucci | | | 157 | 80 | 30 | 1 | 6 | | 274 | | nschonni | | | | 14 | 138 | 10 | | | 162 | | kiazhi | | 25 | 79 | 12 | | | | | 116 | @@ -43,7 +43,7 @@ GitHub issues help us identify errors and gaps in our documentation. | Issues Opened | 2015 | 2016 | 2017 | 2018 | 2019 | 2020 | 2021 | 2022 | Grand Total | | ------------- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ----------: | -| Community | 3 | 54 | 95 | 212 | 566 | 563 | 368 | 59 | 1920 | +| Community | 3 | 54 | 95 | 212 | 566 | 563 | 368 | 71 | 1932 | | mklement0 | | | 19 | 60 | 56 | 61 | 28 | | 224 | | iSazonov | | | 1 | 4 | 10 | 8 | 4 | | 27 | | jszabo98 | | | | 2 | 15 | 6 | 1 | | 24 | @@ -56,8 +56,8 @@ GitHub issues help us identify errors and gaps in our documentation. | trollyanov | | | | | | | 11 | | 11 | | rkeithhill | | | 1 | 2 | 2 | 2 | 3 | 1 | 11 | | JustinGrote | | | | 1 | 3 | 6 | 1 | | 11 | -| vors | 1 | 6 | 2 | 1 | | | | | 10 | | UberKluger | | | | | | 1 | 7 | 2 | 10 | +| vors | 1 | 6 | 2 | 1 | | | | | 10 | [contrib]: contributing/overview.md From 4928df299610d2d5a5635e86dc0cf8fae753f29e Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 4 May 2022 09:58:33 -0500 Subject: [PATCH 31/31] Add examples and clean up descriptions (#8785) --- .../New-WinEvent.md | 104 +++++++++++++++--- .../New-WinEvent.md | 102 ++++++++++++++--- .../New-WinEvent.md | 102 ++++++++++++++--- .../New-WinEvent.md | 102 ++++++++++++++--- .../New-WinEvent.md | 102 ++++++++++++++--- 5 files changed, 441 insertions(+), 71 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Diagnostics/New-WinEvent.md b/reference/5.1/Microsoft.PowerShell.Diagnostics/New-WinEvent.md index 45929222d11d..7ce59ffeb3ba 100644 --- a/reference/5.1/Microsoft.PowerShell.Diagnostics/New-WinEvent.md +++ b/reference/5.1/Microsoft.PowerShell.Diagnostics/New-WinEvent.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Diagnostics.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Diagnostics -ms.date: 09/28/2021 +ms.date: 05/04/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.diagnostics/new-winevent?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: New-WinEvent @@ -22,11 +22,11 @@ New-WinEvent [-ProviderName] [-Id] [-Version ] [[-Payload ## DESCRIPTION The `New-WinEvent` cmdlet creates an Event Tracing for Windows (ETW) event for an event provider. -You can use this cmdlet to add events to ETW channels from Windows PowerShell. +You can use this cmdlet to add events to ETW channels from PowerShell. ## EXAMPLES -### Example 1 +### Example 1 - Create a new event ```powershell New-WinEvent -ProviderName Microsoft-Windows-PowerShell -Id 45090 -Payload @("Workflow", "Running") @@ -35,11 +35,85 @@ New-WinEvent -ProviderName Microsoft-Windows-PowerShell -Id 45090 -Payload @("Wo This command uses the `New-WinEvent` cmdlet to create event 45090 for the Microsoft-Windows-PowerShell provider. +### Example 2 - Get the template for an event + +In this example, `Get-WinEvent` is used to get the template for event id 8007 from the Group Policy +event provider. Notice that the event has two formats. + +In version 0, the **IsMachine** field is a boolean value. In version 1, the **IsMachine** field is +an unsigned integer value. + +```powershell +(Get-WinEvent -ListProvider Microsoft-Windows-GroupPolicy).Events | Where-Object Id -eq 8007 +``` + +```Output +Id : 8007 +Version : 0 +LogLink : System.Diagnostics.Eventing.Reader.EventLogLink +Level : System.Diagnostics.Eventing.Reader.EventLevel +Opcode : System.Diagnostics.Eventing.Reader.EventOpcode +Task : System.Diagnostics.Eventing.Reader.EventTask +Keywords : {} +Template : + +Description : Completed periodic policy processing for user %3 in %1 seconds. + +Id : 8007 +Version : 1 +LogLink : System.Diagnostics.Eventing.Reader.EventLogLink +Level : System.Diagnostics.Eventing.Reader.EventLevel +Opcode : System.Diagnostics.Eventing.Reader.EventOpcode +Task : System.Diagnostics.Eventing.Reader.EventTask +Keywords : {} +Template : + +Description : Completed periodic policy processing for user %3 in %1 seconds. +``` + +The **Description** property contains the message that gets written to the event log. The `%3` and +`%1` value are placeholders for the values passed into the template. The `%3` string is replace with +the value passed to the **PrincipalSamName** field. The `%1` string is replaced withe value passed +to the **PolicyElaspedTimeInSeconds** field. + +### Example 3 - Create a new event using a versioned template + +This example shows how to create an event using a specific template version. + +```powershell +$Payload = @(300, [uint32]'0x8001011f', $env:USERNAME, 0, 1) +New-WinEvent -ProviderName Microsoft-Windows-GroupPolicy -Id 8007 -Version 1 -Payload $Payload +Get-winEvent -ProviderName Microsoft-Windows-GroupPolicy -MaxEvents 1 +``` + +```Output + ProviderName: Microsoft-Windows-GroupPolicy + +TimeCreated Id LevelDisplayName Message +----------- -- ---------------- ------- +5/4/2022 8:40:24 AM 8007 Information Completed periodic policy processing for user User1 in 300 seconds +``` + +If the values in the payload do not match the types in the template, the event is logged but the +payload contains an error. + ## PARAMETERS ### -Id -Specifies an event id that was registered through an instrumentation manifest. +Specifies an event Id that is registered in the event provider. ```yaml Type: System.Int32 @@ -55,11 +129,12 @@ Accept wildcard characters: False ### -Payload -Specifies the message for the event. When the event is written to an event log, the payload is -stored in the **Message** property of the event object. +The payload is an array of values passed as positional arguments to the event template. The values +are inserted into the template to construct the message for the event. Events can have multiple +template versions that use different formats. -When the specified payload does not match the payload in the event definition, Windows PowerShell -generates a warning, but the command still succeeds. +If the values in the payload do not match the types in the template, the event is logged but the +payload contains an error. ```yaml Type: System.Object[] @@ -93,10 +168,8 @@ Accept wildcard characters: False ### -Version -Specifies the version number of the event. Type the event number. Windows PowerShell converts the -number to the required Byte type. - -This parameter lets you specify an event when different versions of the same event are defined. +Specifies the version number of the event. PowerShell converts the number to the required Byte type. +The value specifies the version of the event when different versions of the same event are defined. ```yaml Type: System.Byte @@ -114,7 +187,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -130,8 +204,8 @@ This cmdlet does to generate any output. ## NOTES -- After the provider writes the event to an eventlog, you can use the `Get-WinEvent` cmdlet to get the - event from the event log. +After the provider writes the event to an eventlog, you can use the `Get-WinEvent` cmdlet to get the +event from the event log. ## RELATED LINKS diff --git a/reference/7.0/Microsoft.PowerShell.Diagnostics/New-WinEvent.md b/reference/7.0/Microsoft.PowerShell.Diagnostics/New-WinEvent.md index 62ceba41992e..459f1277c952 100644 --- a/reference/7.0/Microsoft.PowerShell.Diagnostics/New-WinEvent.md +++ b/reference/7.0/Microsoft.PowerShell.Diagnostics/New-WinEvent.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Diagnostics.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Diagnostics -ms.date: 09/28/2021 +ms.date: 05/04/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.diagnostics/new-winevent?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: New-WinEvent @@ -28,7 +28,7 @@ You can use this cmdlet to add events to ETW channels from PowerShell. ## EXAMPLES -### Example 1 +### Example 1 - Create a new event ```powershell New-WinEvent -ProviderName Microsoft-Windows-PowerShell -Id 45090 -Payload @("Workflow", "Running") @@ -37,11 +37,85 @@ New-WinEvent -ProviderName Microsoft-Windows-PowerShell -Id 45090 -Payload @("Wo This command uses the `New-WinEvent` cmdlet to create event 45090 for the Microsoft-Windows-PowerShell provider. +### Example 2 - Get the template for an event + +In this example, `Get-WinEvent` is used to get the template for event id 8007 from the Group Policy +event provider. Notice that the event has two formats. + +In version 0, the **IsMachine** field is a boolean value. In version 1, the **IsMachine** field is +an unsigned integer value. + +```powershell +(Get-WinEvent -ListProvider Microsoft-Windows-GroupPolicy).Events | Where-Object Id -eq 8007 +``` + +```Output +Id : 8007 +Version : 0 +LogLink : System.Diagnostics.Eventing.Reader.EventLogLink +Level : System.Diagnostics.Eventing.Reader.EventLevel +Opcode : System.Diagnostics.Eventing.Reader.EventOpcode +Task : System.Diagnostics.Eventing.Reader.EventTask +Keywords : {} +Template : + +Description : Completed periodic policy processing for user %3 in %1 seconds. + +Id : 8007 +Version : 1 +LogLink : System.Diagnostics.Eventing.Reader.EventLogLink +Level : System.Diagnostics.Eventing.Reader.EventLevel +Opcode : System.Diagnostics.Eventing.Reader.EventOpcode +Task : System.Diagnostics.Eventing.Reader.EventTask +Keywords : {} +Template : + +Description : Completed periodic policy processing for user %3 in %1 seconds. +``` + +The **Description** property contains the message that gets written to the event log. The `%3` and +`%1` value are placeholders for the values passed into the template. The `%3` string is replace with +the value passed to the **PrincipalSamName** field. The `%1` string is replaced withe value passed +to the **PolicyElaspedTimeInSeconds** field. + +### Example 3 - Create a new event using a versioned template + +This example shows how to create an event using a specific template version. + +```powershell +$Payload = @(300, [uint32]'0x8001011f', $env:USERNAME, 0, 1) +New-WinEvent -ProviderName Microsoft-Windows-GroupPolicy -Id 8007 -Version 1 -Payload $Payload +Get-winEvent -ProviderName Microsoft-Windows-GroupPolicy -MaxEvents 1 +``` + +```Output + ProviderName: Microsoft-Windows-GroupPolicy + +TimeCreated Id LevelDisplayName Message +----------- -- ---------------- ------- +5/4/2022 8:40:24 AM 8007 Information Completed periodic policy processing for user User1 in 300 seconds +``` + +If the values in the payload do not match the types in the template, the event is logged but the +payload contains an error. + ## PARAMETERS ### -Id -Specifies an event id that was registered through an instrumentation manifest. +Specifies an event Id that is registered in the event provider. ```yaml Type: System.Int32 @@ -57,11 +131,12 @@ Accept wildcard characters: False ### -Payload -Specifies the message for the event. When the event is written to an event log, the payload is -stored in the **Message** property of the event object. +The payload is an array of values passed as positional arguments to the event template. The values +are inserted into the template to construct the message for the event. Events can have multiple +template versions that use different formats. -When the specified payload does not match the payload in the event definition, PowerShell generates -a warning, but the command still succeeds. +If the values in the payload do not match the types in the template, the event is logged but the +payload contains an error. ```yaml Type: System.Object[] @@ -95,10 +170,8 @@ Accept wildcard characters: False ### -Version -Specifies the version number of the event. Type the event number. PowerShell converts the -number to the required Byte type. - -This parameter lets you specify an event when different versions of the same event are defined. +Specifies the version number of the event. PowerShell converts the number to the required Byte type. +The value specifies the version of the event when different versions of the same event are defined. ```yaml Type: System.Byte @@ -116,7 +189,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -132,8 +206,8 @@ This cmdlet does to generate any output. ## NOTES -- After the provider writes the event to an eventlog, you can use the `Get-WinEvent` cmdlet to get the - event from the event log. +After the provider writes the event to an eventlog, you can use the `Get-WinEvent` cmdlet to get the +event from the event log. ## RELATED LINKS diff --git a/reference/7.1/Microsoft.PowerShell.Diagnostics/New-WinEvent.md b/reference/7.1/Microsoft.PowerShell.Diagnostics/New-WinEvent.md index 81556d75bff2..e55f4708771b 100644 --- a/reference/7.1/Microsoft.PowerShell.Diagnostics/New-WinEvent.md +++ b/reference/7.1/Microsoft.PowerShell.Diagnostics/New-WinEvent.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Diagnostics.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Diagnostics -ms.date: 09/28/2021 +ms.date: 05/04/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.diagnostics/new-winevent?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: New-WinEvent @@ -28,7 +28,7 @@ You can use this cmdlet to add events to ETW channels from PowerShell. ## EXAMPLES -### Example 1 +### Example 1 - Create a new event ```powershell New-WinEvent -ProviderName Microsoft-Windows-PowerShell -Id 45090 -Payload @("Workflow", "Running") @@ -37,11 +37,85 @@ New-WinEvent -ProviderName Microsoft-Windows-PowerShell -Id 45090 -Payload @("Wo This command uses the `New-WinEvent` cmdlet to create event 45090 for the Microsoft-Windows-PowerShell provider. +### Example 2 - Get the template for an event + +In this example, `Get-WinEvent` is used to get the template for event id 8007 from the Group Policy +event provider. Notice that the event has two formats. + +In version 0, the **IsMachine** field is a boolean value. In version 1, the **IsMachine** field is +an unsigned integer value. + +```powershell +(Get-WinEvent -ListProvider Microsoft-Windows-GroupPolicy).Events | Where-Object Id -eq 8007 +``` + +```Output +Id : 8007 +Version : 0 +LogLink : System.Diagnostics.Eventing.Reader.EventLogLink +Level : System.Diagnostics.Eventing.Reader.EventLevel +Opcode : System.Diagnostics.Eventing.Reader.EventOpcode +Task : System.Diagnostics.Eventing.Reader.EventTask +Keywords : {} +Template : + +Description : Completed periodic policy processing for user %3 in %1 seconds. + +Id : 8007 +Version : 1 +LogLink : System.Diagnostics.Eventing.Reader.EventLogLink +Level : System.Diagnostics.Eventing.Reader.EventLevel +Opcode : System.Diagnostics.Eventing.Reader.EventOpcode +Task : System.Diagnostics.Eventing.Reader.EventTask +Keywords : {} +Template : + +Description : Completed periodic policy processing for user %3 in %1 seconds. +``` + +The **Description** property contains the message that gets written to the event log. The `%3` and +`%1` value are placeholders for the values passed into the template. The `%3` string is replace with +the value passed to the **PrincipalSamName** field. The `%1` string is replaced withe value passed +to the **PolicyElaspedTimeInSeconds** field. + +### Example 3 - Create a new event using a versioned template + +This example shows how to create an event using a specific template version. + +```powershell +$Payload = @(300, [uint32]'0x8001011f', $env:USERNAME, 0, 1) +New-WinEvent -ProviderName Microsoft-Windows-GroupPolicy -Id 8007 -Version 1 -Payload $Payload +Get-winEvent -ProviderName Microsoft-Windows-GroupPolicy -MaxEvents 1 +``` + +```Output + ProviderName: Microsoft-Windows-GroupPolicy + +TimeCreated Id LevelDisplayName Message +----------- -- ---------------- ------- +5/4/2022 8:40:24 AM 8007 Information Completed periodic policy processing for user User1 in 300 seconds +``` + +If the values in the payload do not match the types in the template, the event is logged but the +payload contains an error. + ## PARAMETERS ### -Id -Specifies an event id that was registered through an instrumentation manifest. +Specifies an event Id that is registered in the event provider. ```yaml Type: System.Int32 @@ -57,11 +131,12 @@ Accept wildcard characters: False ### -Payload -Specifies the message for the event. When the event is written to an event log, the payload is -stored in the **Message** property of the event object. +The payload is an array of values passed as positional arguments to the event template. The values +are inserted into the template to construct the message for the event. Events can have multiple +template versions that use different formats. -When the specified payload does not match the payload in the event definition, PowerShell generates -a warning, but the command still succeeds. +If the values in the payload do not match the types in the template, the event is logged but the +payload contains an error. ```yaml Type: System.Object[] @@ -95,10 +170,8 @@ Accept wildcard characters: False ### -Version -Specifies the version number of the event. Type the event number. PowerShell converts the -number to the required Byte type. - -This parameter lets you specify an event when different versions of the same event are defined. +Specifies the version number of the event. PowerShell converts the number to the required Byte type. +The value specifies the version of the event when different versions of the same event are defined. ```yaml Type: System.Byte @@ -116,7 +189,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -132,8 +206,8 @@ This cmdlet does to generate any output. ## NOTES -- After the provider writes the event to an eventlog, you can use the `Get-WinEvent` cmdlet to get the - event from the event log. +After the provider writes the event to an eventlog, you can use the `Get-WinEvent` cmdlet to get the +event from the event log. ## RELATED LINKS diff --git a/reference/7.2/Microsoft.PowerShell.Diagnostics/New-WinEvent.md b/reference/7.2/Microsoft.PowerShell.Diagnostics/New-WinEvent.md index 4f1e61fdd3b9..4f4a30ca389b 100644 --- a/reference/7.2/Microsoft.PowerShell.Diagnostics/New-WinEvent.md +++ b/reference/7.2/Microsoft.PowerShell.Diagnostics/New-WinEvent.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Diagnostics.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Diagnostics -ms.date: 09/28/2021 +ms.date: 05/04/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.diagnostics/new-winevent?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: New-WinEvent @@ -28,7 +28,7 @@ You can use this cmdlet to add events to ETW channels from PowerShell. ## EXAMPLES -### Example 1 +### Example 1 - Create a new event ```powershell New-WinEvent -ProviderName Microsoft-Windows-PowerShell -Id 45090 -Payload @("Workflow", "Running") @@ -37,11 +37,85 @@ New-WinEvent -ProviderName Microsoft-Windows-PowerShell -Id 45090 -Payload @("Wo This command uses the `New-WinEvent` cmdlet to create event 45090 for the Microsoft-Windows-PowerShell provider. +### Example 2 - Get the template for an event + +In this example, `Get-WinEvent` is used to get the template for event id 8007 from the Group Policy +event provider. Notice that the event has two formats. + +In version 0, the **IsMachine** field is a boolean value. In version 1, the **IsMachine** field is +an unsigned integer value. + +```powershell +(Get-WinEvent -ListProvider Microsoft-Windows-GroupPolicy).Events | Where-Object Id -eq 8007 +``` + +```Output +Id : 8007 +Version : 0 +LogLink : System.Diagnostics.Eventing.Reader.EventLogLink +Level : System.Diagnostics.Eventing.Reader.EventLevel +Opcode : System.Diagnostics.Eventing.Reader.EventOpcode +Task : System.Diagnostics.Eventing.Reader.EventTask +Keywords : {} +Template : + +Description : Completed periodic policy processing for user %3 in %1 seconds. + +Id : 8007 +Version : 1 +LogLink : System.Diagnostics.Eventing.Reader.EventLogLink +Level : System.Diagnostics.Eventing.Reader.EventLevel +Opcode : System.Diagnostics.Eventing.Reader.EventOpcode +Task : System.Diagnostics.Eventing.Reader.EventTask +Keywords : {} +Template : + +Description : Completed periodic policy processing for user %3 in %1 seconds. +``` + +The **Description** property contains the message that gets written to the event log. The `%3` and +`%1` value are placeholders for the values passed into the template. The `%3` string is replace with +the value passed to the **PrincipalSamName** field. The `%1` string is replaced withe value passed +to the **PolicyElaspedTimeInSeconds** field. + +### Example 3 - Create a new event using a versioned template + +This example shows how to create an event using a specific template version. + +```powershell +$Payload = @(300, [uint32]'0x8001011f', $env:USERNAME, 0, 1) +New-WinEvent -ProviderName Microsoft-Windows-GroupPolicy -Id 8007 -Version 1 -Payload $Payload +Get-winEvent -ProviderName Microsoft-Windows-GroupPolicy -MaxEvents 1 +``` + +```Output + ProviderName: Microsoft-Windows-GroupPolicy + +TimeCreated Id LevelDisplayName Message +----------- -- ---------------- ------- +5/4/2022 8:40:24 AM 8007 Information Completed periodic policy processing for user User1 in 300 seconds +``` + +If the values in the payload do not match the types in the template, the event is logged but the +payload contains an error. + ## PARAMETERS ### -Id -Specifies an event id that was registered through an instrumentation manifest. +Specifies an event Id that is registered in the event provider. ```yaml Type: System.Int32 @@ -57,11 +131,12 @@ Accept wildcard characters: False ### -Payload -Specifies the message for the event. When the event is written to an event log, the payload is -stored in the **Message** property of the event object. +The payload is an array of values passed as positional arguments to the event template. The values +are inserted into the template to construct the message for the event. Events can have multiple +template versions that use different formats. -When the specified payload does not match the payload in the event definition, PowerShell generates -a warning, but the command still succeeds. +If the values in the payload do not match the types in the template, the event is logged but the +payload contains an error. ```yaml Type: System.Object[] @@ -95,10 +170,8 @@ Accept wildcard characters: False ### -Version -Specifies the version number of the event. Type the event number. PowerShell converts the -number to the required Byte type. - -This parameter lets you specify an event when different versions of the same event are defined. +Specifies the version number of the event. PowerShell converts the number to the required Byte type. +The value specifies the version of the event when different versions of the same event are defined. ```yaml Type: System.Byte @@ -116,7 +189,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -132,8 +206,8 @@ This cmdlet does to generate any output. ## NOTES -- After the provider writes the event to an eventlog, you can use the `Get-WinEvent` cmdlet to get the - event from the event log. +After the provider writes the event to an eventlog, you can use the `Get-WinEvent` cmdlet to get the +event from the event log. ## RELATED LINKS diff --git a/reference/7.3/Microsoft.PowerShell.Diagnostics/New-WinEvent.md b/reference/7.3/Microsoft.PowerShell.Diagnostics/New-WinEvent.md index 638caa7231ae..29470f5be040 100644 --- a/reference/7.3/Microsoft.PowerShell.Diagnostics/New-WinEvent.md +++ b/reference/7.3/Microsoft.PowerShell.Diagnostics/New-WinEvent.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Diagnostics.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Diagnostics -ms.date: 09/28/2021 +ms.date: 05/04/2022 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.diagnostics/new-winevent?view=powershell-7.3&WT.mc_id=ps-gethelp schema: 2.0.0 title: New-WinEvent @@ -28,7 +28,7 @@ You can use this cmdlet to add events to ETW channels from PowerShell. ## EXAMPLES -### Example 1 +### Example 1 - Create a new event ```powershell New-WinEvent -ProviderName Microsoft-Windows-PowerShell -Id 45090 -Payload @("Workflow", "Running") @@ -37,11 +37,85 @@ New-WinEvent -ProviderName Microsoft-Windows-PowerShell -Id 45090 -Payload @("Wo This command uses the `New-WinEvent` cmdlet to create event 45090 for the Microsoft-Windows-PowerShell provider. +### Example 2 - Get the template for an event + +In this example, `Get-WinEvent` is used to get the template for event id 8007 from the Group Policy +event provider. Notice that the event has two formats. + +In version 0, the **IsMachine** field is a boolean value. In version 1, the **IsMachine** field is +an unsigned integer value. + +```powershell +(Get-WinEvent -ListProvider Microsoft-Windows-GroupPolicy).Events | Where-Object Id -eq 8007 +``` + +```Output +Id : 8007 +Version : 0 +LogLink : System.Diagnostics.Eventing.Reader.EventLogLink +Level : System.Diagnostics.Eventing.Reader.EventLevel +Opcode : System.Diagnostics.Eventing.Reader.EventOpcode +Task : System.Diagnostics.Eventing.Reader.EventTask +Keywords : {} +Template : + +Description : Completed periodic policy processing for user %3 in %1 seconds. + +Id : 8007 +Version : 1 +LogLink : System.Diagnostics.Eventing.Reader.EventLogLink +Level : System.Diagnostics.Eventing.Reader.EventLevel +Opcode : System.Diagnostics.Eventing.Reader.EventOpcode +Task : System.Diagnostics.Eventing.Reader.EventTask +Keywords : {} +Template : + +Description : Completed periodic policy processing for user %3 in %1 seconds. +``` + +The **Description** property contains the message that gets written to the event log. The `%3` and +`%1` value are placeholders for the values passed into the template. The `%3` string is replace with +the value passed to the **PrincipalSamName** field. The `%1` string is replaced withe value passed +to the **PolicyElaspedTimeInSeconds** field. + +### Example 3 - Create a new event using a versioned template + +This example shows how to create an event using a specific template version. + +```powershell +$Payload = @(300, [uint32]'0x8001011f', $env:USERNAME, 0, 1) +New-WinEvent -ProviderName Microsoft-Windows-GroupPolicy -Id 8007 -Version 1 -Payload $Payload +Get-winEvent -ProviderName Microsoft-Windows-GroupPolicy -MaxEvents 1 +``` + +```Output + ProviderName: Microsoft-Windows-GroupPolicy + +TimeCreated Id LevelDisplayName Message +----------- -- ---------------- ------- +5/4/2022 8:40:24 AM 8007 Information Completed periodic policy processing for user User1 in 300 seconds +``` + +If the values in the payload do not match the types in the template, the event is logged but the +payload contains an error. + ## PARAMETERS ### -Id -Specifies an event id that was registered through an instrumentation manifest. +Specifies an event Id that is registered in the event provider. ```yaml Type: System.Int32 @@ -57,11 +131,12 @@ Accept wildcard characters: False ### -Payload -Specifies the message for the event. When the event is written to an event log, the payload is -stored in the **Message** property of the event object. +The payload is an array of values passed as positional arguments to the event template. The values +are inserted into the template to construct the message for the event. Events can have multiple +template versions that use different formats. -When the specified payload does not match the payload in the event definition, PowerShell generates -a warning, but the command still succeeds. +If the values in the payload do not match the types in the template, the event is logged but the +payload contains an error. ```yaml Type: System.Object[] @@ -95,10 +170,8 @@ Accept wildcard characters: False ### -Version -Specifies the version number of the event. Type the event number. PowerShell converts the -number to the required Byte type. - -This parameter lets you specify an event when different versions of the same event are defined. +Specifies the version number of the event. PowerShell converts the number to the required Byte type. +The value specifies the version of the event when different versions of the same event are defined. ```yaml Type: System.Byte @@ -116,7 +189,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). ## INPUTS @@ -132,8 +206,8 @@ This cmdlet does to generate any output. ## NOTES -- After the provider writes the event to an eventlog, you can use the `Get-WinEvent` cmdlet to get the - event from the event log. +After the provider writes the event to an eventlog, you can use the `Get-WinEvent` cmdlet to get the +event from the event log. ## RELATED LINKS