From 5b95ee37c8f06a7fcba050efc429757044c1b3d7 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Mon, 15 Nov 2021 10:21:58 -0600 Subject: [PATCH 1/4] Fixes #8351 - Document module metadata for experimental features (#8353) * Document module metadata for experimental features * Change H3 to H2 for better nav experience * fix formatting --- .../About/about_Experimental_Features.md | 35 +++++++++++++++--- .../About/about_Experimental_Features.md | 36 +++++++++++++++---- .../About/about_Experimental_Features.md | 36 +++++++++++++++---- 3 files changed, 90 insertions(+), 17 deletions(-) diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Experimental_Features.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Experimental_Features.md index ea00d1d8a136..a12799eb00a7 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Experimental_Features.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Experimental_Features.md @@ -1,7 +1,7 @@ --- description: The Experimental Features support in PowerShell provides a mechanism for experimental features to coexist with existing stable features in PowerShell or PowerShell modules. Locale: en-US -ms.date: 03/13/2020 +ms.date: 11/15/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_experimental_features?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Experimental Features @@ -48,7 +48,7 @@ specified and the only valid values are: - `Show` means to show this experimental feature if the feature is enabled - `Hide` means to hide this experimental feature if the feature is enabled -### Declaring Experimental Features in Modules Written in C\# +## Declaring Experimental Features in Modules Written in C\# Module authors who want to use the Experimental Feature flags can declare a cmdlet as experimental by using the `Experimental` attribute. @@ -59,7 +59,7 @@ cmdlet as experimental by using the `Experimental` attribute. public class InvokeWebRequestCommandV2 : WebCmdletBaseV2 { ... } ``` -### Declaring Experimental Features in Modules written in PowerShell +## Declaring Experimental Features in Modules written in PowerShell Module written in PowerShell can also use the `Experimental` attribute to declare experimental cmdlets: @@ -73,7 +73,32 @@ function Enable-SSHRemoting { } ``` -### Mutually Exclusive Experimental Features +Metadata about an experimental feature is kept in the module manifest. Use the +`PrivateData.PSData.ExperimentalFeatures` property of a module manifest to +expose the experimental features from the module. The `ExperimentalFeatures` +property is an array of hashtables containing the name and description of the +feature. + +For example: + +```powershell +PrivateData = @{ + PSData = @{ + ExperimentalFeatures = @( + @{ + Name = "PSWebCmdletV2" + Description = "Rewrite the web cmdlets for better performance" + }, + @{ + Name = "PSRestCmdletV2" + Description = "Rewrite the REST API cmdlets for better performance" + } + ) + } +} +``` + +## Mutually Exclusive Experimental Features There are cases where an experimental feature cannot co-exist side-by-side with an existing feature or another experimental feature. @@ -108,7 +133,7 @@ When the `MyWebCmdlets.PSWebCmdletV2` experimental feature is enabled, the exist This allows users to try out the new cmdlet and provide feedback then revert to the non-experimental version when needed. -### Experimental Parameters in Cmdlets +## Experimental Parameters in Cmdlets The `Experimental` attribute can also be applied to individual parameters. This allows you to create an experimental set of parameters for an existing cmdlet diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Experimental_Features.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Experimental_Features.md index 73a4d0a33505..1df2b07adf14 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Experimental_Features.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Experimental_Features.md @@ -1,7 +1,7 @@ --- description: The Experimental Features support in PowerShell provides a mechanism for experimental features to coexist with existing stable features in PowerShell or PowerShell modules. Locale: en-US -ms.date: 03/13/2020 +ms.date: 11/15/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_experimental_features?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Experimental Features @@ -48,7 +48,7 @@ specified and the only valid values are: - `Show` means to show this experimental feature if the feature is enabled - `Hide` means to hide this experimental feature if the feature is enabled -### Declaring Experimental Features in Modules Written in C\# +## Declaring Experimental Features in Modules Written in C\# Module authors who want to use the Experimental Feature flags can declare a cmdlet as experimental by using the `Experimental` attribute. @@ -59,7 +59,7 @@ cmdlet as experimental by using the `Experimental` attribute. public class InvokeWebRequestCommandV2 : WebCmdletBaseV2 { ... } ``` -### Declaring Experimental Features in Modules written in PowerShell +## Declaring Experimental Features in Modules written in PowerShell Module written in PowerShell can also use the `Experimental` attribute to declare experimental cmdlets: @@ -73,7 +73,32 @@ function Enable-SSHRemoting { } ``` -### Mutually Exclusive Experimental Features +Metadata about an experimental feature is kept in the module manifest. Use the +`PrivateData.PSData.ExperimentalFeatures` property of a module manifest to +expose the experimental features from the module. The `ExperimentalFeatures` +property is an array of hashtables containing the name and description of the +feature. + +For example: + +```powershell +PrivateData = @{ + PSData = @{ + ExperimentalFeatures = @( + @{ + Name = "PSWebCmdletV2" + Description = "Rewrite the web cmdlets for better performance" + }, + @{ + Name = "PSRestCmdletV2" + Description = "Rewrite the REST API cmdlets for better performance" + } + ) + } +} +``` + +## Mutually Exclusive Experimental Features There are cases where an experimental feature cannot co-exist side-by-side with an existing feature or another experimental feature. @@ -108,7 +133,7 @@ When the `MyWebCmdlets.PSWebCmdletV2` experimental feature is enabled, the exist This allows users to try out the new cmdlet and provide feedback then revert to the non-experimental version when needed. -### Experimental Parameters in Cmdlets +## Experimental Parameters in Cmdlets The `Experimental` attribute can also be applied to individual parameters. This allows you to create an experimental set of parameters for an existing cmdlet @@ -170,4 +195,3 @@ if ([ExperimentalFeature]::IsEnabled("MyModule.MyExperimentalFeature")) [Disable-ExperimentalFeature](xref:Microsoft.PowerShell.Core.Disable-ExperimentalFeature) [Get-ExperimentalFeature](xref:Microsoft.PowerShell.Core.Get-ExperimentalFeature) - diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Experimental_Features.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Experimental_Features.md index 339eb8d75cc2..a557a7aa4ccf 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Experimental_Features.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Experimental_Features.md @@ -1,7 +1,7 @@ --- description: The Experimental Features support in PowerShell provides a mechanism for experimental features to coexist with existing stable features in PowerShell or PowerShell modules. Locale: en-US -ms.date: 03/13/2020 +ms.date: 11/15/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_experimental_features?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Experimental Features @@ -48,7 +48,7 @@ specified and the only valid values are: - `Show` means to show this experimental feature if the feature is enabled - `Hide` means to hide this experimental feature if the feature is enabled -### Declaring Experimental Features in Modules Written in C\# +## Declaring Experimental Features in Modules Written in C\# Module authors who want to use the Experimental Feature flags can declare a cmdlet as experimental by using the `Experimental` attribute. @@ -59,7 +59,7 @@ cmdlet as experimental by using the `Experimental` attribute. public class InvokeWebRequestCommandV2 : WebCmdletBaseV2 { ... } ``` -### Declaring Experimental Features in Modules written in PowerShell +## Declaring Experimental Features in Modules written in PowerShell Module written in PowerShell can also use the `Experimental` attribute to declare experimental cmdlets: @@ -73,7 +73,32 @@ function Enable-SSHRemoting { } ``` -### Mutually Exclusive Experimental Features +Metadata about an experimental feature is kept in the module manifest. Use the +`PrivateData.PSData.ExperimentalFeatures` property of a module manifest to +expose the experimental features from the module. The `ExperimentalFeatures` +property is an array of hashtables containing the name and description of the +feature. + +For example: + +```powershell +PrivateData = @{ + PSData = @{ + ExperimentalFeatures = @( + @{ + Name = "PSWebCmdletV2" + Description = "Rewrite the web cmdlets for better performance" + }, + @{ + Name = "PSRestCmdletV2" + Description = "Rewrite the REST API cmdlets for better performance" + } + ) + } +} +``` + +## Mutually Exclusive Experimental Features There are cases where an experimental feature cannot co-exist side-by-side with an existing feature or another experimental feature. @@ -108,7 +133,7 @@ When the `MyWebCmdlets.PSWebCmdletV2` experimental feature is enabled, the exist This allows users to try out the new cmdlet and provide feedback then revert to the non-experimental version when needed. -### Experimental Parameters in Cmdlets +## Experimental Parameters in Cmdlets The `Experimental` attribute can also be applied to individual parameters. This allows you to create an experimental set of parameters for an existing cmdlet @@ -170,4 +195,3 @@ if ([ExperimentalFeature]::IsEnabled("MyModule.MyExperimentalFeature")) [Disable-ExperimentalFeature](xref:Microsoft.PowerShell.Core.Disable-ExperimentalFeature) [Get-ExperimentalFeature](xref:Microsoft.PowerShell.Core.Get-ExperimentalFeature) - From 5497393dc071decb663c6c2b1446a7dea91b4b62 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Mon, 15 Nov 2021 11:04:12 -0600 Subject: [PATCH 2/4] Fixes #8347 - Update MS Store appx limitations (#8354) * Update MS Store appx limitations * Move MU section under MSI --- .../Installing-PowerShell-on-Windows.md | 81 +++++++++++-------- 1 file changed, 49 insertions(+), 32 deletions(-) diff --git a/reference/docs-conceptual/install/Installing-PowerShell-on-Windows.md b/reference/docs-conceptual/install/Installing-PowerShell-on-Windows.md index 3ff66fd974a5..26d3e2c1d8dc 100644 --- a/reference/docs-conceptual/install/Installing-PowerShell-on-Windows.md +++ b/reference/docs-conceptual/install/Installing-PowerShell-on-Windows.md @@ -1,6 +1,6 @@ --- description: Information about installing PowerShell on Windows -ms.date: 11/08/2021 +ms.date: 11/15/2021 title: Installing PowerShell on Windows --- # Installing PowerShell on Windows @@ -56,6 +56,28 @@ The installer creates a shortcut in the Windows Start Menu. > If you need to run PowerShell 7.2 side-by-side with other versions, use the [ZIP install](#zip) > method to install the other version to a different folder. +### Support for Microsoft Update in PowerShell 7.2 + +PowerShell 7.2 has support for Microsoft Update. When you enable this feature, you'll get +the latest PowerShell 7 updates in your traditional Microsoft Update (MU) management flow, whether +that's with Windows Update for Business, WSUS, SCCM, or the interactive MU dialog in Settings. + +The PowerShell 7.2 MSI package includes following command-line options: + +- `USE_MU` - This property has two possible values: + - `1` (default) - Opts into updating through Microsoft Update, WSUS, or SCCM + - `0` - Do not opt into updating through Microsoft Update, WSUS, or SCCM +- `ENABLE_MU` + - `1` (default) - Opts into using Microsoft Update for Automatic Updates + - `0` - Do not opt into using Microsoft Update + +> [!NOTE] +> Enabling updates may have been set in a previous installation or manual configuration. Using +> `ENABLE_MU=0` does not remove the existing settings. Also, this setting can be overruled by Group +> Policy settings controlled by your administrator. + +For more information, see the [PowerShell Microsoft Update FAQ](microsoft-update-faq.yml). + ### Administrative install from the command line MSI packages can be installed from the command line allowing administrators to deploy packages @@ -74,7 +96,7 @@ installation options: The following example shows how to silently install PowerShell with all the install options enabled. ```powershell -msiexec.exe /package PowerShell-7.2.0-win-x64.msi /quiet ADD_EXPLORER_CONTEXT_MENU_OPENPOWERSHELL=1 ENABLE_PSREMOTING=1 REGISTER_MANIFEST=1 +msiexec.exe /package PowerShell-7.2.0-win-x64.msi /quiet ADD_EXPLORER_CONTEXT_MENU_OPENPOWERSHELL=1 ENABLE_PSREMOTING=1 REGISTER_MANIFEST=1 USE_MU=1 ENABLE_MU=1 ``` For a full list of command-line options for `Msiexec.exe`, see @@ -146,7 +168,7 @@ winget install --id Microsoft.Powershell.Preview --source winget ## Installing from the Microsoft Store -PowerShell 7.2 has been published to the Microsoft Store. You can find the PowerShell release in the +PowerShell 7.2 can be installed from the Microsoft Store. You can find the PowerShell release in the [Microsoft Store][store-app] site or in the Store application in Windows. Benefits of the Microsoft Store package: @@ -156,18 +178,35 @@ Benefits of the Microsoft Store package: ### Known limitations -Windows Store packages run in an application sandbox that virtualizes access to some filesystem and -registry locations. +By default, Windows Store packages run in an application sandbox that virtualizes access to some +filesystem and registry locations. Changes to virtualized file and registry locations do not persist +outside of the application sandbox. -- All registry changes under HKEY_CURRENT_USER are copied on write to a private, per-user, per-app - location. Therefore, those values are not available to other applications. -- Any system-level configuration settings stored in `$PSHOME` cannot be modified. This includes the - WSMAN configuration. This prevents remote sessions from connecting to Store-based installs of - PowerShell. User-level configurations and SSH remoting are supported. +This sandbox all blocks any changes to the application's root folder. Any system-level configuration +settings stored in `$PSHOME` cannot be modified. This includes the WSMAN configuration. This +prevents remote sessions from connecting to Store-based installs of PowerShell. User-level +configurations and SSH remoting are supported. + +The following commands need write to `$PSHOME`. These commands are not supported in a Microsoft +Store instance of PowerShell. + +- `Register-PSSessionConfiguration` +- `Update-Help -Scope AllUsers` +- `Enable-ExperimentalFeature -Scope AllUsers` +- `Set-ExecutionPolicy -Scope LocalMachine` For more information, see [Understanding how packaged desktop apps run on Windows](/windows/msix/desktop/desktop-to-uwp-behind-the-scenes). +### Changes for PowerShell 7.2 + +Beginning in PowerShell 7.2, the PowerShell package is now exempt from file and registry +virtualization. Changes to virtualized file and registry locations now persist outside of the +application sandbox. However, changes to the application's root folder are still blocked. + +> [!IMPORTANT] +> You must be running on Windows build 1903 or higher for this exemption to work. + ## Installing a preview version