コマンドレットにパラメーターセットを追加する

2025-03-25

パラメーターセットについて知っておくべきこと

Windows PowerShell では、パラメーターセットは、一緒に動作するパラメーターのグループとして定義されます。コマンドレットのパラメーターをグループ化することで、ユーザーが指定するパラメーターのグループに基づいて機能を変更できる 1 つのコマンドレットを作成できます。

2 つのパラメーターセットを使用して異なる機能を定義するコマンドレットの例として、Windows PowerShell によって提供される Get-EventLog コマンドレットがあります。このコマンドレットは、ユーザーが List または LogName パラメーターを指定すると、異なる情報を返します。 LogName パラメーターが指定されている場合、コマンドレットは指定されたイベントログ内のイベントに関する情報を返します。 List パラメーターを指定すると、コマンドレットはログファイル自体に関する情報を返します (含まれているイベント情報ではありません)。この場合、List パラメーターと LogName パラメーターは、2 つの個別のパラメーターセットを識別します。

パラメーターセットについて覚えておく必要がある 2 つの重要な点は、Windows PowerShell ランタイムが特定の入力に使用するパラメーターセットが 1 つだけであることと、各パラメーターセットに、そのパラメーターセットに対して一意のパラメーターが少なくとも 1 つ必要であることです。

この Stop-Proc コマンドレットは、最後のポイントを示すために、ProcessName、ProcessId、および InputObjectの 3 つのパラメーターセットを使用します。これらの各パラメーターセットには、他のパラメーターセットに含まれていない 1 つのパラメーターがあります。パラメーターセットは他のパラメーターを共有できますが、コマンドレットは一意のパラメーター ProcessName、ProcessId、および InputObject を使用して、Windows PowerShell ランタイムで使用する必要があるパラメーターのセットを識別します。

コマンドレットクラスの宣言

コマンドレットの作成の最初の手順は、常にコマンドレットに名前を付け、コマンドレットを実装する .NET クラスを宣言することです。このコマンドレットでは、コマンドレットがシステムプロセスを停止するため、ライフサイクル動詞 "Stop" が使用されます。コマンドレットはプロセスで動作するため、名詞名 "Proc" が使用されます。以下の宣言では、コマンドレットの動詞と名詞名がコマンドレットクラスの名前に反映されることに注意してください。

注

承認されたコマンドレットの動詞名の詳細については、「コマンドレット動詞名を参照してください。

次のコードは、この Stop-Proc コマンドレットのクラス定義です。

[Cmdlet(VerbsLifecycle.Stop, "Proc",
        DefaultParameterSetName = "ProcessId",
        SupportsShouldProcess = true)]
public class StopProcCommand : PSCmdlet

<Cmdlet(VerbsLifecycle.Stop, "Proc", DefaultParameterSetName:="ProcessId", _
SupportsShouldProcess:=True)> _
Public Class StopProcCommand
    Inherits PSCmdlet

コマンドレットのパラメーターの宣言

このコマンドレットは、コマンドレットへの入力として必要な 3 つのパラメーター (これらのパラメーターはパラメーターセットも定義します) と、コマンドレットの動作を管理する Force パラメーターと、コマンドレットがパイプラインを介して出力オブジェクトを送信するかどうかを決定する PassThru パラメーターを定義します。既定では、このコマンドレットはパイプラインを介してオブジェクトを渡しません。これら最後の 2 つのパラメーターの詳細については、「システムを変更するコマンドレットの作成」を参照してください。

Name パラメーターの宣言

この入力パラメーターを使用すると、ユーザーは停止するプロセスの名前を指定できます。 System.Management.Automation.ParameterAttribute 属性の ParameterSetName 属性キーワードは、このパラメーターに設定された ProcessName パラメーターを指定します。

[Parameter(
   Position = 0,
   ParameterSetName = "ProcessName",
   Mandatory = true,
   ValueFromPipeline = true,
   ValueFromPipelineByPropertyName = true,
   HelpMessage = "The name of one or more processes to stop. Wildcards are permitted."
)]
[Alias("ProcessName")]
public string[] Name
{
    get { return processNames; }
    set { processNames = value; }
}
private string[] processNames;

<Parameter(Position:=0, ParameterSetName:="ProcessName", _
Mandatory:=True, _
ValueFromPipeline:=True, ValueFromPipelineByPropertyName:=True, _
HelpMessage:="The name of one or more processes to stop. " & _
    "Wildcards are permitted."), [Alias]("ProcessName")> _
Public Property Name() As String()
    Get
        Return processNames
    End Get
    Set(ByVal value As String())
        processNames = value
    End Set
End Property

Private processNames() As String

このパラメーターにはエイリアス "ProcessName" が指定されていることにも注意してください。

ID パラメーターの宣言

この入力パラメーターを使用すると、ユーザーは停止するプロセスの識別子を指定できます。 System.Management.Automation.ParameterAttribute 属性の ParameterSetName 属性キーワードは、ProcessId パラメーターセットを指定します。

[Parameter(
           ParameterSetName = "ProcessId",
           Mandatory = true,
           ValueFromPipelineByPropertyName = true,
           ValueFromPipeline = true
)]
[Alias("ProcessId")]
public int[] Id
{
  get { return processIds; }
  set { processIds = value; }
}
private int[] processIds;

<Parameter(ParameterSetName:="ProcessId", _
Mandatory:=True, _
ValueFromPipelineByPropertyName:=True, _
ValueFromPipeline:=True), [Alias]("ProcessId")> _
Public Property Id() As Integer()
    Get
        Return processIds
    End Get
    Set(ByVal value As Integer())
        processIds = value
    End Set
End Property
Private processIds() As Integer

このパラメーターにはエイリアス "ProcessId" が指定されていることにも注意してください。

InputObject パラメーターの宣言

この入力パラメーターを使用すると、停止するプロセスに関する情報を含む入力オブジェクトをユーザーが指定できます。 System.Management.Automation.ParameterAttribute 属性の ParameterSetName 属性キーワードは、このパラメーターに設定された InputObject パラメーターを指定します。

[Parameter(
           ParameterSetName = "InputObject",
           Mandatory = true,
           ValueFromPipeline = true)]
public Process[] InputObject
{
  get { return inputObject; }
  set { inputObject = value; }
}
private Process[] inputObject;

<Parameter(ParameterSetName:="InputObject", _
Mandatory:=True, ValueFromPipeline:=True)> _
Public Property InputObject() As Process()
    Get
        Return myInputObject
    End Get
    Set(ByVal value As Process())
        myInputObject = value
    End Set
End Property
Private myInputObject() As Process

また、このパラメーターにはエイリアスがないことにも注意してください。

複数のパラメーターセットでのパラメーターの宣言

パラメーターセットごとに一意のパラメーターが必要ですが、パラメーターは複数のパラメーターセットに属することができます。このような場合は、共有パラメーターに、パラメーターが属セットごとに System.Management.Automation.ParameterAttribute 属性宣言を指定します。パラメーターがすべてのパラメーターセット内にある場合は、パラメーター属性を 1 回だけ宣言するだけで済み、パラメーターセット名を指定する必要はありません。

入力処理メソッドのオーバーライド

すべてのコマンドレットは入力処理メソッドをオーバーライドする必要があります。ほとんどの場合、これは System.Management.Automation.Cmdlet.ProcessRecord メソッドになります。このコマンドレットでは、System.Management.Automation.Cmdlet.ProcessRecord メソッドがオーバーライドされ、コマンドレットは任意の数のプロセスを処理できます。これには、ユーザーが指定したパラメーターセットに基づいて別のメソッドを呼び出す Select ステートメントが含まれています。

protected override void ProcessRecord()
{
  switch (ParameterSetName)
  {
    case "ProcessName":
         ProcessByName();
         break;

    case "ProcessId":
         ProcessById();
         break;

    case "InputObject":
         foreach (Process process in inputObject)
         {
           SafeStopProcess(process);
         }
         break;

    default:
         throw new ArgumentException("Bad ParameterSet Name");
  } // switch (ParameterSetName...
} // ProcessRecord

Protected Overrides Sub ProcessRecord()
    Select Case ParameterSetName
        Case "ProcessName"
            ProcessByName()

        Case "ProcessId"
            ProcessById()

        Case "InputObject"
            Dim process As Process
            For Each process In myInputObject
                SafeStopProcess(process)
            Next process

        Case Else
            Throw New ArgumentException("Bad ParameterSet Name")
    End Select

End Sub 'ProcessRecord ' ProcessRecord

Select ステートメントによって呼び出されるヘルパーメソッドについてはここでは説明しませんが、次のセクションの完全なコードサンプルで実装を確認できます。

コードサンプル

完全な C# サンプルコードについては、「StopProcessSample04 サンプルを参照してください。

オブジェクトの種類と書式設定の定義

Windows PowerShell は、.NET オブジェクトを使用してコマンドレット間で情報を渡します。そのため、コマンドレットは独自の型を定義する必要がある場合や、別のコマンドレットによって提供される既存の型を拡張する必要がある場合があります。新しい型の定義または既存の型の拡張の詳細については、「オブジェクト型の拡張と書式設定の」を参照してください。

コマンドレットのビルド

コマンドレットを実装したら、Windows PowerShell スナップインを使用して Windows PowerShell に登録する必要があります。コマンドレットの登録の詳細については、「コマンドレット、プロバイダー、およびホストアプリケーションを登録する方法」を参照してください。

コマンドレットのテスト

コマンドレットが Windows PowerShell に登録されたら、コマンドラインで実行してテストします。 ProcessId パラメーターと InputObject パラメーターを使用してパラメーターセットをテストしてプロセスを停止する方法を示すテストをいくつか次に示します。

Windows PowerShell を起動した後、ProcessId パラメーターを設定して Stop-Proc コマンドレットを実行し、その識別子に基づいてプロセスを停止します。この場合、コマンドレットは ProcessId パラメーターセットを使用してプロセスを停止します。
```
PS> Stop-Proc -Id 444
Confirm
Are you sure you want to perform this action?
Performing operation "Stop-Proc" on Target "notepad (444)".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): Y
```
Windows PowerShell を起動した後、InputObject パラメーターを設定して Stop-Proc コマンドレットを実行し、Get-Process コマンドによって取得されたメモ帳オブジェクトのプロセスを停止します。
```
PS> Get-Process notepad | Stop-Proc
Confirm
Are you sure you want to perform this action?
Performing operation "Stop-Proc" on Target "notepad (444)".
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): N
```

こちらもご覧ください

システムを変更するコマンドレットの作成

Windows PowerShell コマンドレットを作成する方法

オブジェクト型の拡張と書式設定の

コマンドレット、プロバイダー、およびホストアプリケーションを登録する方法

Windows PowerShell SDK の

次の方法で共有

コマンドレットにパラメーター セットを追加する

パラメーター セットについて知っておくべきこと

コマンドレット クラスの宣言