about_Experimental_Features

[アーティクル]
11/06/2024

PowerShell の試験的機能のサポートは、試験的機能を PowerShell または PowerShell モジュールの既存の安定した機能と共存させるためのメカニズムを提供します。

試験的機能は、設計が未完成です。この機能は、ユーザーがテストしてフィードバックを提供するために使用できます。試験的機能が完成すると、設計の変更が破壊的変更になります。試験的機能は、変更が破壊的になる可能性があるため、運用環境で使用することは想定されていません。

試験的機能は既定で無効になっており、システムのユーザーまたは管理者が明示的に有効にする必要があります。

有効な試験的機能は、すべてのユーザーの$PSHOMEのpowershell.config.json ファイル、または特定のユーザーのユーザー固有の構成ファイルに一覧表示されます。

Note

ユーザー構成ファイルで有効になっている試験的機能は、システム構成ファイルに記載されている試験的機能よりも優先されます。

試験段階の属性

Experimental属性を使用して、いくつかのコードを試験段階として宣言します。

実験用機能の名前と実験用機能が有効になっている場合に実行するアクションを指定する Experimental 属性を宣言するには、次の構文を使用します。

[Experimental(NameOfExperimentalFeature, ExperimentAction)]

モジュールの場合、 NameOfExperimentalFeature は <modulename>.<experimentname>の形式に従う必要があります。 ExperimentAction パラメーターを指定する必要があり、有効な値は次のみです。

Show は、機能が有効になっている場合にこの試験的な機能を表示することを意味します
Hide は、機能が有効になっている場合にこの試験的な機能を非表示にすることを意味します

C で記述されたモジュールでの試験的特徴の宣言#

試験的機能フラグを使用するモジュール作成者は、 Experimental 属性を使用して、コマンドレットを試験段階として宣言できます。

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

PowerShell で記述されたモジュールでの実験用機能の宣言

PowerShell で記述されたモジュールでは、 Experimental 属性を使用して実験用コマンドレットを宣言することもできます。

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

相互排他的な試験的特徴

実験用の機能が、既存の機能または別の実験用機能と共存できない場合があります。

たとえば、既存のコマンドレットをオーバーライドする実験用コマンドレットを使用できます。 2 つのバージョンを並べて共存させることはできません。 ExperimentAction.Hide設定では、2 つのコマンドレットのうち 1 つだけを一度に有効にすることができます。

この例では、新しい試験的な Invoke-WebRequest コマンドレットを作成します。 InvokeWebRequestCommand には非試験的な実装が含まれています。 InvokeWebRequestCommandV2 には、コマンドレットの実験用バージョンが含まれています。

ExperimentAction.Hideを使用すると、2 つの機能のうち 1 つだけを一度に有効にすることができます。

[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の実装を提供します。

これにより、ユーザーは新しいコマンドレットを試してフィードバックを提供し、必要に応じて非試験的なバージョンに戻すことができます。

コマンドレットの実験用パラメーター

Experimental属性は、個々のパラメーターにも適用できます。これにより、まったく新しいコマンドレットではなく、既存のコマンドレットの実験用のパラメーターセットを作成できます。

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
}

次の方法で共有