about_Experimental_Features

發行項
12/14/2023

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
}