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