about_Experimental_Features

PowerShell 中的实验性功能支持提供了一种机制,可便于实验性功能与 PowerShell 或 PowerShell 模块中的现有稳定功能共存。

实验性功能是指设计尚未最终确定的功能。 此类功能可供用户进行测试和提供反馈。 一旦实验性功能最终确定下来,设计变更就变成了中断性变更。 实验性功能不适合在生产环境中使用,因为允许变更成为中断性变更。

默认情况下,实验性功能处于禁用状态,需要由系统的用户或管理员显式启用。

已启用的实验性功能在 文件中列出powershell.config.json$PSHOME,适用于所有用户或特定用户的特定于用户的配置文件中。

注意

用户配置文件中启用的实验性功能优先于系统配置文件中列出的实验性功能。

实验属性

Experimental使用 特性将某些代码声明为实验性代码。

使用以下语法声明 属性, Experimental 提供实验性功能的名称,以及启用实验性功能时要执行的操作:

[Experimental(NameOfExperimentalFeature, ExperimentAction)]

对于模块, NameOfExperimentalFeature 必须遵循 的形式 <modulename>.<experimentname>ExperimentAction必须指定 参数,并且唯一有效的值为:

  • Show 表示在启用此功能的情况下显示此实验性功能
  • Hide 表示在启用此功能时隐藏此实验性功能

在用 C 编写的模块中声明实验性功能#

想要使用实验性功能标志的模块作者可以使用 属性将 cmdlet 声明为实验 Experimental 性。

[Experimental("MyWebCmdlets.PSWebCmdletV2", ExperimentAction.Show)]
[Cmdlet(Verbs.Invoke, "WebRequest")]
public class InvokeWebRequestCommandV2 : WebCmdletBaseV2 { ... }

在用 PowerShell 编写的模块中声明实验性功能

在 PowerShell 中编写的模块还可以使用 Experimental 属性来声明实验性 cmdlet:

function Enable-SSHRemoting {
    [Experimental("MyRemoting.PSSSHRemoting", "Show")]
    [CmdletBinding()]
    param()
    ...
}

有关实验功能的元数据保存在模块清单中。 PrivateData.PSData.ExperimentalFeatures使用模块清单的 属性公开模块中的实验性功能。 属性 ExperimentalFeatures 是包含功能的名称和说明的哈希表数组。

例如:

PrivateData = @{
  PSData = @{
    ExperimentalFeatures = @(
      @{
          Name = "PSWebCmdletV2"
          Description = "Rewrite the web cmdlets for better performance"
      },
      @{
          Name = "PSRestCmdletV2"
          Description = "Rewrite the REST API cmdlets for better performance"
      }
    )
  }
}

互斥实验性功能

在某些情况下,实验性功能不能与现有功能或其他实验功能并存。

例如,可以有一个替代现有 cmdlet 的实验性 cmdlet。 这两个版本不能并存。 设置 ExperimentAction.Hide 一次只允许启用两个 cmdlet 中的一个。

在此示例中,我们将创建一个新的实验性 Invoke-WebRequest cmdlet。 InvokeWebRequestCommand 包含非实验性实现。 InvokeWebRequestCommandV2 包含 cmdlet 的实验版本。

使用 ExperimentAction.Hide 将一次只允许启用两个功能中的一个:

[Experimental("MyWebCmdlets.PSWebCmdletV2", ExperimentAction.Show)]
[Cmdlet(Verbs.Invoke, "WebRequest")]
public class InvokeWebRequestCommandV2 : WebCmdletBaseV2 { ... }

[Experimental("MyWebCmdlets.PSWebCmdletV2", ExperimentAction.Hide)]
[Cmdlet(Verbs.Invoke, "WebRequest")]
public class InvokeWebRequestCommand : WebCmdletBase { ... }

MyWebCmdlets.PSWebCmdletV2启用实验性功能后,现有InvokeWebRequestCommand实现将隐藏,InvokeWebRequestCommandV2并提供 的Invoke-WebRequest实现。

这允许用户试用新的 cmdlet 并提供反馈,然后在需要时还原到非实验版本。

Cmdlet 中的实验参数

属性 Experimental 也可以应用于单个参数。 这允许你为现有 cmdlet(而不是全新的 cmdlet)创建一组试验性参数。

下面是 C# 中的一个示例:

[Experimental("MyModule.PSNewAddTypeCompilation", ExperimentAction.Show)]
[Parameter(ParameterSet = "NewCompilation")]
public CompilationParameters CompileParameters { ... }

[Experimental("MyModule.PSNewAddTypeCompilation", ExperimentAction.Hide)]
[Parameter()]
public CodeDom CodeDom { ... }

下面是 PowerShell 脚本中的另一个示例:

param(
    [Experimental("MyModule.PSNewFeature", "Show")]
    [string] $NewName,

    [Experimental("MyModule.PSNewFeature", "Hide")]
    [string] $OldName
)

检查实验性功能是否已启用

在代码中,需要先检查是否启用了实验性功能,然后才能采取适当的措施。 可以使用 类上的System.Management.Automation.ExperimentalFeature静态IsEnabled()方法确定是否启用了实验性功能。

下面是 C# 中的一个示例:

if (ExperimentalFeature.IsEnabled("MyModule.MyExperimentalFeature"))
{
   // code specific to the experimental feature
}

下面是 PowerShell 脚本中的一个示例:

if ([ExperimentalFeature]::IsEnabled("MyModule.MyExperimentalFeature"))
{
  # code specific to the experimental feature
}

另请参阅