建立不含參數的 Cmdlet

發行項
09/27/2021

本節說明如何建立 Cmdlet，以在不使用參數的情況下，從本機電腦抓取資訊，然後將資訊寫入管線。此處所述的 Cmdlet 是 Get-Proc Cmdlet，可抓取本機電腦的處理常式資訊，然後在命令列中顯示該資訊。

注意

請注意，撰寫 Cmdlet 時，Windows PowerShell®參考元件會依預設下載到磁片 (的 C:\Program Files\Reference Assemblies\Microsoft\WindowsPowerShell\v1.0) 。它們不會安裝在全域組件快取 (GAC) 中。

命名 Cmdlet

Cmdlet 名稱是由動詞命令所組成，指出 Cmdlet 所採取的動作，以及表示 Cmdlet 所作用之專案的名詞。因為此範例 Get-Proc Cmdlet 會取出處理常式物件，所以會使用 Verbscommon 列舉所定義的動詞 "Get"，以及名詞 "Proc" 來表示此 Cmdlet 可在處理常式專案上運作。

命名 Cmdlet 時，請勿使用下列任何字元： #， () {} [] &-/\ $;： "' <> | ？ @ ` .

選擇名詞

您應該選擇特定的名詞。最好使用以產品名稱的簡短版本為開頭的單數名詞。此類型的範例 Cmdlet 名稱為 " Get-SQLServer "。

選擇動詞

您應使用來自已核准 Cmdlet 動詞名稱集合的動詞。如需已核准 Cmdlet 動詞命令的詳細資訊，請參閱 Cmdlet 動詞名稱。

定義 Cmdlet 類別

一旦您選擇了 Cmdlet 名稱，請定義 .NET 類別來執行此 Cmdlet。以下是此範例 Get-Proc Cmdlet 的類別定義：

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

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

請注意，在類別定義之前， CmdletAttribute 屬性（含語法 [Cmdlet(verb, noun, ...)] ）是用來將此類別識別為 Cmdlet。這是所有 Cmdlet 的唯一必要屬性，可讓 Windows PowerShell 執行時間正確地呼叫它們。如有必要，您可以設定屬性關鍵字以進一步宣告類別。請注意，我們範例 GetProcCommand 類別的屬性宣告只會宣告 Get-Proc Cmdlet 的名詞和動詞名稱。

注意

針對所有 Windows PowerShell 屬性類別，您可以設定的關鍵字會對應至屬性類別的屬性。

命名 Cmdlet 的類別時，在類別名稱中反映 Cmdlet 名稱是很好的作法。若要這樣做，請使用 "VerbNounCommand" 格式，並將 "Verb" 和 "名詞" 取代為 Cmdlet 名稱中使用的動詞和名詞。如先前的類別定義中所示，範例 Get-Proc Cmdlet 會定義名為 GetProcCommand 的類別，該類別衍生自 system.object 基類。

重要

如果您想要定義直接存取 Windows PowerShell 執行時間的 Cmdlet，您的 .net 類別應該衍生自PSCmdlet基類。如需此類別的詳細資訊，請參閱建立定義參數集的 Cmdlet。

注意

Cmdlet 的類別必須明確標記為公用。未標記為公用的類別會預設為內部，而且 Windows PowerShell 執行時間找不到。

Windows PowerShell 使用適用于其 Cmdlet 類別的命令命名空間。建議您將 Cmdlet 類別放在 API 命名空間的命令命名空間中，例如 xxx。

覆寫輸入處理方法

System.servicemodel 類別提供三個主要的輸入處理方法，至少其中一個 Cmdlet 必須覆寫。如需 Windows PowerShell 如何處理記錄的詳細資訊，請參閱Windows PowerShell 的運作方式。

針對所有類型的輸入，Windows PowerShell 執行時間會呼叫BeginProcessing來啟用處理。如果您的 Cmdlet 必須執行一些前置處理或設定，則可以覆寫此方法來執行這項作業。

注意

Windows PowerShell 使用「記錄」一詞來描述呼叫 Cmdlet 時所提供的一組參數值。

如果您的 Cmdlet 接受管線輸入，則它必須覆寫ProcessRecord方法，以及選擇性地覆寫 system.string 方法（選擇性）。例如，Cmdlet 可能會覆寫這兩種方法（如果它使用 ProcessRecord 收集所有輸入），然後一次以整個輸入（而不是一個元素）來操作輸入（如同 Sort-Object Cmdlet）。

如果您的 Cmdlet 未採用管線輸入，則應該覆寫system.string 方法。請注意，當 Cmdlet 一次無法在一個元素上運作時，此方法會經常用來取代 BeginProcessing ，就像是排序 Cmdlet 的情況一樣。

Because this sample Get-Proc cmdlet must receive pipeline input, it overrides the System.Management.Automation.Cmdlet.ProcessRecord method and uses the default implementations for System.Management.Automation.Cmdlet.BeginProcessing and System.Management.Automation.Cmdlet.EndProcessing. ProcessRecord覆寫會取出處理常式，並使用WriteObject方法將它們寫入命令列中的命令列。

protected override void ProcessRecord()
{
  // Get the current processes
  Process[] processes = Process.GetProcesses();

  // Write the processes to the pipeline making them available
  // to the next cmdlet. The second parameter of this call tells
  // PowerShell to enumerate the array, and send one process at a
  // time to the pipeline.
  WriteObject(processes, true);
}

Protected Overrides Sub ProcessRecord()

    '/ Get the current processes.
    Dim processes As Process()
    processes = Process.GetProcesses()

    '/ Write the processes to the pipeline making them available
    '/ to the next cmdlet. The second parameter of this call tells
    '/ PowerShell to enumerate the array, and send one process at a
    '/ time to the pipeline.
    WriteObject(processes, True)

End Sub 'ProcessRecord

輸入處理的注意事項

輸入的預設來源是明確的物件 (例如，在命令列上由使用者提供的字串) 。如需詳細資訊，請參閱建立 Cmdlet 以處理命令列輸入。
輸入處理方法也可以從管線上上游 Cmdlet 的輸出物件接收輸入。如需詳細資訊，請參閱建立 Cmdlet 來處理管線輸入。請注意，您的 Cmdlet 可以從命令列和管線來源的組合接收輸入。
下游 Cmdlet 可能不會傳回很長的時間，或根本不會傳回。基於這個理由，您 Cmdlet 中的輸入處理方法不應該在呼叫 WriteObject期間保留鎖定，尤其是範圍延伸超過 Cmdlet 實例的鎖定。

重要

Cmdlet 永遠不應呼叫 system.object * 或其對等專案。

當您的 Cmdlet 完成處理時，可能會有物件變數需要清除 (例如，如果它在 BeginProcessing 方法中開啟檔案控制代碼，並讓控制碼保持開啟以供 ProcessRecord) 使用。請務必記住，Windows PowerShell 執行時間不一定會呼叫system.string 方法，這應該會執行物件清除。

例如，如果在指令程式的中途取消，或 Cmdlet 的任何部分中發生終止錯誤，則可能不會呼叫 system.string 。因此，需要物件清除的 Cmdlet 應該會執行完整的IDisposable模式，包括完成項，如此執行時間才能在處理結束時呼叫 IDisposable 和.. 1 . a ..

程式碼範例

如需完整的 c # 範例程式碼，請參閱 >getprocesssample01 範例。

定義物件類型和格式

Windows PowerShell 使用 .net 物件在 Cmdlet 之間傳遞資訊。因此，Cmdlet 可能需要定義自己的類型，或 Cmdlet 可能需要擴充另一個 Cmdlet 所提供的現有類型。如需定義新型別或擴充現有類型的詳細資訊，請參閱擴充物件類型和格式。

建立 Cmdlet

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

測試 Cmdlet

當您的 Cmdlet 註冊 Windows PowerShell 時，您可以在命令列上執行它來進行測試。我們的範例 Get-Proc Cmdlet 的程式碼很小，但它仍會使用 Windows PowerShell 執行時間和現有的 .net 物件，這足以讓它實用。讓我們來測試它，以進一步瞭解 Get-Proc 可以做什麼，以及如何使用其輸出。如需從命令列使用 Cmdlet 的詳細資訊，請參閱Windows PowerShell 的開始使用。

啟動 Windows PowerShell，並取得電腦上目前正在執行的處理常式。

get-proc

即會出現下列輸出。

Handles  NPM(K)  PM(K)  WS(K)  VS(M)  CPU(s)  Id   ProcessName
-------  ------  -----  -----  -----  ------  --   ----------
254      7       7664   12048  66     173.75  1200  QCTRAY
32       2       1372   2628   31       0.04  1860  DLG
271      6       1216   3688   33       0.03  3816  lg
27       2       560    1920   24       0.01  1768  TpScrex
...

將變數指派給 Cmdlet 的結果，以便更輕鬆地操作。
```
$p=get-proc
```
取得進程的數目。
```
$p.length
```
即會出現下列輸出。
```
63
```

取出特定的進程。

$p[6]

即會出現下列輸出。

Handles  NPM(K)  PM(K)  WS(K)  VS(M)  CPU(s)  Id    ProcessName
-------  ------  -----  -----  -----  ------  --    -----------
1033     3       2400   3336   35     0.53    1588  rundll32

取得此程式的開始時間。

$p[6].starttime

即會出現下列輸出。

Tuesday, July 26, 2005 9:34:15 AM

$p[6].starttime.dayofyear

取得控制碼計數大於500的進程，並排序結果。

$p | Where-Object {$_.HandleCount -gt 500 } | Sort-Object HandleCount

即會出現下列輸出。

Handles  NPM(K)  PM(K)  WS(K)  VS(M)  CPU(s)  Id   ProcessName
-------  ------  -----  -----  -----  ------  --   ----------
568      14      2164   4972   39     5.55    824  svchost
716       7      2080   5332   28    25.38    468  csrss
761      21      33060  56608  440  393.56    3300 WINWORD
791      71      7412   4540   59     3.31    492  winlogon
...

使用 Get-Member Cmdlet 列出每個進程可用的屬性。

$p | Get-Member -MemberType property

    TypeName: System.Diagnostics.Process

即會出現下列輸出。

Name                     MemberType Definition
----                     ---------- ----------
BasePriority             Property   System.Int32 BasePriority {get;}
Container                Property   System.ComponentModel.IContainer Conta...
EnableRaisingEvents      Property   System.Boolean EnableRaisingEvents {ge...
...