about_Experimental_Features

[アーティクル]
03/21/2022

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

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

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

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

注意

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

実験的属性

属性を使用して、実験用として一部の 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() な機能が有効になっているかどうかを確認できます。