パイプライン入力を処理するパラメーターを追加する

2025-03-25

コマンドレットの入力ソースの 1 つは、アップストリームコマンドレットから生成されたパイプライン上のオブジェクトです。このセクションでは、コマンドレットがパイプラインオブジェクトを処理できるように、パラメーターを Get-Proc コマンドレットに追加する方法について説明します (最初のコマンドレットの作成を参照)。

この Get-Proc コマンドレットは、パイプラインオブジェクトからの入力を受け入れ、指定された名前に基づいてローカルコンピューターからプロセス情報を取得し、コマンドラインにプロセスに関する情報を表示する Name パラメーターを使用します。

コマンドレットクラスの定義

コマンドレットの作成の最初の手順は、常にコマンドレットに名前を付け、コマンドレットを実装する .NET クラスを宣言することです。このコマンドレットはプロセス情報を取得するため、ここで選択した動詞名は "Get" です。 (情報を取得できるほぼすべての種類のコマンドレットで、コマンドライン入力を処理できます)。承認されたコマンドレット動詞の詳細については、「コマンドレットの動詞名を参照してください。

この Get-Proc コマンドレットの定義を次に示します。この定義の詳細については、「最初のコマンドレットの作成」を参照してください。

[Cmdlet(VerbsCommon.Get, "proc")]
public class GetProcCommand : Cmdlet

<Cmdlet(VerbsCommon.Get, "Proc")> _
Public Class GetProcCommand
    Inherits Cmdlet

パイプラインからの入力の定義

このセクションでは、コマンドレットのパイプラインからの入力を定義する方法について説明します。この Get-Proc コマンドレットは、「コマンドライン入力を処理するパラメーターの追加」の説明に従って、Name パラメーターを表すプロパティを定義します。 (パラメーターの宣言に関する一般的な情報については、そのトピックを参照してください)。

ただし、コマンドレットでパイプライン入力を処理する必要がある場合は、Windows PowerShell ランタイムによってパラメーターが入力値にバインドされている必要があります。これを行うには、ValueFromPipeline キーワードを追加するか、ValueFromPipelineByProperty キーワードを System.Management.Automation.ParameterAttribute 属性宣言に追加する必要があります。コマンドレットが完全な入力オブジェクトにアクセスする場合は、ValueFromPipeline キーワードを指定します。コマンドレットがオブジェクトのプロパティにのみアクセスする場合は、ValueFromPipelineByProperty を指定します。

パイプライン入力を受け入れるこの Get-Proc コマンドレットの Name パラメーターのパラメーター宣言を次に示します。

[Parameter(
   Position = 0,
   ValueFromPipeline = true,
   ValueFromPipelineByPropertyName = true)]
[ValidateNotNullOrEmpty]
public string[] Name
{
   get { return this.processNames; }
   set { this.processNames = value; }
}

<Parameter(Position:=0, ValueFromPipeline:=True, _
ValueFromPipelineByPropertyName:=True), ValidateNotNullOrEmpty()> _
Public Property Name() As String()
    Get
        Return processNames
    End Get

    Set(ByVal value As String())
        processNames = value
    End Set

End Property

前の宣言では、ValueFromPipeline キーワードを true に設定して、オブジェクトがパラメーターと同じ型の場合、または同じ型に強制できる場合に、Windows PowerShell ランタイムがパラメーターを受信オブジェクトにバインドできるようにします。また、ValueFromPipelineByPropertyName キーワードは true に設定されているため、Windows PowerShell ランタイムは受信オブジェクトで Name プロパティをチェックします。受信オブジェクトにこのようなプロパティがある場合、ランタイムは、Name パラメーターを受信オブジェクトの Name プロパティにバインドします。

注

パラメーターの ValueFromPipeline 属性キーワードの設定は、ValueFromPipelineByPropertyName キーワードの設定よりも優先されます。

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

コマンドレットがパイプライン入力を処理する場合は、適切な入力処理メソッドをオーバーライドする必要があります。基本的な入力処理方法は、「最初のコマンドレットの作成で導入されています。

この Get-Proc コマンドレットは、System.Management.Automation.Cmdlet.ProcessRecord メソッドオーバーライドして、ユーザーまたはスクリプトによって提供される Name パラメーター入力を処理します。このメソッドは、要求された各プロセス名のプロセスを取得します。名前が指定されていない場合は、すべてのプロセスを取得します。 System.Management.Automation.Cmdlet.ProcessRecord内では、WriteObject(System.Object,System.Boolean) の呼び出しが、出力オブジェクトをパイプラインに送信するための出力メカニズムであることに注意してください。この呼び出しの 2 番目のパラメーター enumerateCollectionは、プロセスオブジェクトの配列を列挙し、コマンドラインに一度に 1 つのプロセスを書き込むよう Windows PowerShell ランタイムに指示する true に設定されます。

protected override void ProcessRecord()
{
  // If no process names are passed to the cmdlet, get all processes.
  if (processNames == null)
  {
      // Write the processes to the pipeline making them available
      // to the next cmdlet. The second argument of this call tells
      // PowerShell to enumerate the array, and send one process at a
      // time to the pipeline.
      WriteObject(Process.GetProcesses(), true);
  }
  else
  {
    // If process names are passed to the cmdlet, get and write
    // the associated processes.
    foreach (string name in processNames)
    {
      WriteObject(Process.GetProcessesByName(name), true);
    } // End foreach (string name...).
  }
}

Protected Overrides Sub ProcessRecord()
    Dim processes As Process()

    '/ If no process names are passed to the cmdlet, get all processes.
    If processNames Is Nothing Then
        processes = Process.GetProcesses()
    Else

        '/ If process names are specified, write the processes to the
        '/ pipeline to display them or make them available to the next cmdlet.
        For Each name As String In processNames
            '/ The second parameter of this call tells PowerShell to enumerate the
            '/ array, and send one process at a time to the pipeline.
            WriteObject(Process.GetProcessesByName(name), True)
        Next
    End If

End Sub 'ProcessRecord

コードサンプル

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

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

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

コマンドレットのビルド

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

コマンドレットのテスト

コマンドレットが Windows PowerShell に登録されたら、コマンドラインで実行してテストします。たとえば、サンプルコマンドレットのコードをテストします。コマンドラインからコマンドレットを使用する方法の詳細については、「Windows PowerShell の概要」を参照してください。

Windows PowerShell プロンプトで、次のコマンドを入力して、パイプラインを介してプロセス名を取得します。

PS> type ProcessNames | Get-Proc

次の出力が表示されます。

Handles  NPM(K)  PM(K)   WS(K)  VS(M)  CPU(s)    Id  ProcessName
-------  ------  -----   ----- -----   ------    --  -----------
    809      21  40856    4448    147    9.50  2288  iexplore
    737      21  26036   16348    144   22.03  3860  iexplore
     39       2   1024     388     30    0.08  3396  notepad
   3927      62  71836   26984    467  195.19  1848  OUTLOOK

次の行を入力して、"IEXPLORE" というプロセスから Name プロパティを持つプロセスオブジェクトを取得します。この例では、Get-Process コマンドレット (Windows PowerShell によって提供) をアップストリームコマンドとして使用して、"IEXPLORE" プロセスを取得します。

PS> Get-Process iexplore | Get-Proc

次の出力が表示されます。

Handles  NPM(K)  PM(K)   WS(K)  VS(M)  CPU(s)    Id  ProcessName
-------  ------  -----   ----- -----   ------    --  -----------
    801      21  40720    6544    142    9.52  2288  iexplore
    726      21  25872   16652    138   22.09  3860  iexplore
    801      21  40720    6544    142    9.52  2288  iexplore
    726      21  25872   16652    138   22.09  3860  iexplore