新增處理管線輸入的參數

發行項
03/25/2025

Cmdlet 的一個輸入來源是管線上源自上游 Cmdlet 的物件。本節說明如何將參數新增至 Get-Proc Cmdlet（如建立您的第一個 Cmdlet中所述），讓 Cmdlet 可以處理管線物件。

此 Get-Proc Cmdlet 會使用接受管線物件輸入的 Name 參數、根據提供的名稱從本機計算機擷取進程資訊，然後在命令行上顯示處理程式的相關信息。

定義 Cmdlet 類別

Cmdlet 建立的第一個步驟一律是命名 Cmdlet，並宣告實作 Cmdlet 的 .NET 類別。此 Cmdlet 會擷取進程資訊，因此此處選擇的動詞名稱為「Get」。（幾乎任何能夠擷取資訊的 Cmdlet 都可以處理命令行輸入。如需已核准 Cmdlet 動詞的詳細資訊，請參閱 Cmdlet 指令動詞名稱。

以下是此 Get-Proc Cmdlet 的定義。建立您的第一個 Cmdlet中會提供此定義的詳細數據。

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

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

從管線定義輸入

本節說明如何定義 Cmdlet 管線的輸入。此 Get-Proc Cmdlet 會定義屬性，表示 Name 參數，如新增處理命令行輸入的參數中所述。（如需宣告參數的一般資訊，請參閱該主題。

不過，當 Cmdlet 需要處理管線輸入時，它必須讓其參數係結至 Windows PowerShell 運行時間的輸入值。若要這樣做，您必須新增 ValueFromPipeline 關鍵詞，或將 ValueFromPipelineByProperty 關鍵詞新增至 System.Management.Automation.ParameterAttribute 屬性宣告。如果 Cmdlet 存取完整的輸入物件，請指定 ValueFromPipeline 關鍵詞。如果 Cmdlet 只存取物件的屬性，請指定 ValueFromPipelineByProperty。

以下是接受管線輸入之這個 Get-Proc Cmdlet 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 關鍵詞的設定。

覆寫輸入處理方法

如果您的 Cmdlet 是處理管線輸入，它必須覆寫適當的輸入處理方法。建立您的第一個 Cmdlet中引進基本輸入處理方法。

此 Get-Proc Cmdlet 會覆寫 System.Management.Automation.Cmdlet.ProcessRecord 方法來處理使用者或腳本所提供的 Name 參數輸入。如果未提供任何名稱，此方法會取得每個要求的進程名稱或所有進程的進程。請注意，System.Management.Automation.Cmdlet.ProcessRecord中，呼叫 writeObject（System.Object，System.Boolean）是將輸出物件傳送至管線的輸出機制。這個呼叫的第二個參數 enumerateCollection設定為 true，以告訴 Windows PowerShell 運行時間列舉進程對象的陣列，並一次將一個進程寫入命令行。

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 物件在 Cmdlet 之間傳遞資訊。因此，Cmdlet 可能需要定義自己的類型，或 Cmdlet 可能需要擴充另一個 Cmdlet 所提供的現有類型。如需定義新類型或擴充現有類型的詳細資訊，請參閱擴充物件類型和格式。

建置 Cmdlet

實作 Cmdlet 之後，它必須透過 Windows PowerShell 嵌入式管理單元向 Windows PowerShell 註冊。如需註冊 Cmdlet 的詳細資訊，請參閱如何註冊 Cmdlet、提供者和主應用程式。

測試 Cmdlet

當您的 Cmdlet 已向 Windows PowerShell 註冊時，請在命令行上執行它來測試它。例如，測試範例 Cmdlet 的程序代碼。如需從命令行使用 Cmdlet 的詳細資訊，請參閱開始使用 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 Cmdlet（由 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