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
}