From 598733bb14ff406efa919b92591db9fe61e21749 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Mon, 15 Nov 2021 09:34:51 -0600 Subject: [PATCH 1/3] Document module metadata for experimental features --- .../About/about_Experimental_Features.md | 26 +++++++++++++++++- .../About/about_Experimental_Features.md | 27 +++++++++++++++++-- .../About/about_Experimental_Features.md | 27 +++++++++++++++++-- 3 files changed, 75 insertions(+), 5 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..e071cb604a77 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 @@ -73,6 +73,30 @@ function Enable-SSHRemoting { } ``` +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 a hashtable 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 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..21042a1cbd8f 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 @@ -73,6 +73,30 @@ function Enable-SSHRemoting { } ``` +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 a hashtable 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 @@ -170,4 +194,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..d592ef1b74f5 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 @@ -73,6 +73,30 @@ function Enable-SSHRemoting { } ``` +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 a hashtable 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 @@ -170,4 +194,3 @@ if ([ExperimentalFeature]::IsEnabled("MyModule.MyExperimentalFeature")) [Disable-ExperimentalFeature](xref:Microsoft.PowerShell.Core.Disable-ExperimentalFeature) [Get-ExperimentalFeature](xref:Microsoft.PowerShell.Core.Get-ExperimentalFeature) - From 2715c961eed014435e6640b7b53acb66aa4c9309 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Mon, 15 Nov 2021 09:44:31 -0600 Subject: [PATCH 2/3] Change H3 to H2 for better nav experience --- .../About/about_Experimental_Features.md | 8 ++++---- .../About/about_Experimental_Features.md | 8 ++++---- .../About/about_Experimental_Features.md | 8 ++++---- 3 files changed, 12 insertions(+), 12 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 e071cb604a77..c91d74617cd6 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 @@ -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: @@ -97,7 +97,7 @@ PrivateData = @{ } ``` -### Mutually Exclusive Experimental Features +## 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. @@ -132,7 +132,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 21042a1cbd8f..cf4d36f83503 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 @@ -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: @@ -97,7 +97,7 @@ PrivateData = @{ } ``` -### Mutually Exclusive Experimental Features +## 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. @@ -132,7 +132,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.2/Microsoft.PowerShell.Core/About/about_Experimental_Features.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Experimental_Features.md index d592ef1b74f5..64df89a38d6a 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 @@ -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: @@ -97,7 +97,7 @@ PrivateData = @{ } ``` -### Mutually Exclusive Experimental Features +## 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. @@ -132,7 +132,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 From 7aa850a58c0eca0eeae0f25c6f82e9965b22dd0a Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Mon, 15 Nov 2021 09:59:06 -0600 Subject: [PATCH 3/3] fix formatting --- .../About/about_Experimental_Features.md | 27 ++++++++++--------- .../About/about_Experimental_Features.md | 27 ++++++++++--------- .../About/about_Experimental_Features.md | 27 ++++++++++--------- 3 files changed, 42 insertions(+), 39 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 c91d74617cd6..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 @@ -76,24 +76,25 @@ function Enable-SSHRemoting { 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 a hashtable containing the name and description of the feature. +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" - } - ) - } + PSData = @{ + ExperimentalFeatures = @( + @{ + Name = "PSWebCmdletV2" + Description = "Rewrite the web cmdlets for better performance" + }, + @{ + Name = "PSRestCmdletV2" + Description = "Rewrite the REST API cmdlets for better performance" + } + ) + } } ``` 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 cf4d36f83503..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 @@ -76,24 +76,25 @@ function Enable-SSHRemoting { 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 a hashtable containing the name and description of the feature. +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" - } - ) - } + PSData = @{ + ExperimentalFeatures = @( + @{ + Name = "PSWebCmdletV2" + Description = "Rewrite the web cmdlets for better performance" + }, + @{ + Name = "PSRestCmdletV2" + Description = "Rewrite the REST API cmdlets for better performance" + } + ) + } } ``` 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 64df89a38d6a..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 @@ -76,24 +76,25 @@ function Enable-SSHRemoting { 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 a hashtable containing the name and description of the feature. +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" - } - ) - } + PSData = @{ + ExperimentalFeatures = @( + @{ + Name = "PSWebCmdletV2" + Description = "Rewrite the web cmdlets for better performance" + }, + @{ + Name = "PSRestCmdletV2" + Description = "Rewrite the REST API cmdlets for better performance" + } + ) + } } ```