about_Experimental_Features

  • 项目

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

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

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

启用后的实验性功能在 $PSHOME 中的 powershell.config.json 文件中面向所有用户列出，或者在特定于用户的配置文件中面向特定用户列出。

注意

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

Experimental 属性

可以使用 Experimental 属性将某些代码声明为实验性代码。

请使用以下语法声明 Experimental 属性，并提供实验性功能的名称以及启用了此实验性功能时要执行的操作：

[Experimental(NameOfExperimentalFeature, ExperimentAction)]

对于模块，NameOfExperimentalFeature 必须采用 <modulename>.<experimentname> 形式。 必须指定 ExperimentAction 参数，并且其有效值只有：

  • Show 表示如果启用了此功能，则显示此实验性功能
  • Hide 表示如果启用了此功能，则隐藏此实验性功能

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

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

[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
}

另请参阅