Cmdlet 概觀Cmdlet Overview

Cmdlet 是在 PowerShell 環境中使用的輕量命令。A cmdlet is a lightweight command that is used in the PowerShell environment. PowerShell 執行時間會在命令列提供的自動化腳本內容中叫用這些 Cmdlet。The PowerShell runtime invokes these cmdlets within the context of automation scripts that are provided at the command line. PowerShell 執行時間也會透過 PowerShell Api 以程式設計方式叫用它們。The PowerShell runtime also invokes them programmatically through PowerShell APIs.

指令程式Cmdlets

Cmdlet 會執行動作,而且通常會將 Microsoft .NET 物件傳回給管線中的下一個命令。Cmdlets perform an action and typically return a Microsoft .NET object to the next command in the pipeline. Cmdlet 是參與 PowerShell 管線語義的單一命令。A cmdlet is a single command that participates in the pipeline semantics of PowerShell. 這包括 binary (c #) Cmdlet、advanced script 函數、CDXML 和工作流程。This includes binary (C#) cmdlets, advanced script functions, CDXML, and Workflows.

此 SDK 檔描述如何建立以 c # 撰寫的二進位 Cmdlet。This SDK documentation describes how to create binary cmdlets written in C#. 如需以腳本為基礎的 Cmdlet 的詳細資訊,請參閱:For information about script-based cmdlets, see:

若要建立二元 Cmdlet,您必須執行一個衍生自兩個特製化 Cmdlet 基類之一的 Cmdlet 類別。To create a binary cmdlet, you must implement a cmdlet class that derives from one of two specialized cmdlet base classes. 衍生的類別必須:The derived class must:

  • 宣告會將衍生類別識別為 Cmdlet 的屬性。Declare an attribute that identifies the derived class as a cmdlet.
  • 定義使用屬性裝飾的公用屬性,以將公用屬性識別為 Cmdlet 參數。Define public properties that are decorated with attributes that identify the public properties as cmdlet parameters.
  • 覆寫一或多個輸入處理方法來處理記錄。Override one or more of the input processing methods to process records.

您可以使用import-module Cmdlet 直接載入包含類別的元件,也可以使用System.Management.Automation.Runspaces.Initialsessionstate API 來建立裝載該元件的主應用程式。You can load the assembly that contains the class directly by using the Import-Module cmdlet, or you can create a host application that loads the assembly by using the System.Management.Automation.Runspaces.Initialsessionstate API. 這兩種方法都可讓您以程式設計方式和命令列存取 Cmdlet 的功能。Both methods provide programmatic and command-line access to the functionality of the cmdlet.

Cmdlet 詞彙Cmdlet Terms

以下是 PowerShell Cmdlet 檔中經常使用的詞彙:The following terms are used frequently in the PowerShell cmdlet documentation:

Cmdlet 屬性Cmdlet attribute

用來將 Cmdlet 類別宣告為 Cmdlet 的 .NET 屬性。A .NET attribute that is used to declare a cmdlet class as a cmdlet. 雖然 PowerShell 使用其他幾個選擇性的屬性,但 Cmdlet 屬性是必要的。Although PowerShell uses several other attributes that are optional, the Cmdlet attribute is required. 如需此屬性的詳細資訊,請參閱Cmdlet 屬性宣告。For more information about this attribute, see Cmdlet Attribute Declaration.

Cmdlet 參數Cmdlet parameter

公用屬性,定義可供使用者或執行 Cmdlet 之應用程式使用的參數。The public properties that define the parameters that are available to the user or to the application that is running the cmdlet. Cmdlet 可以有必要、命名、位置和切換參數。Cmdlets can have required, named, positional, and switch parameters. 切換參數可讓您定義只有在呼叫中指定參數時才會評估的參數。Switch parameters allow you to define parameters that are evaluated only if the parameters are specified in the call. 如需不同類型參數的詳細資訊,請參閱Cmdlet 參數For more information about the different types of parameters, see Cmdlet Parameters.

參數集Parameter set

可在相同命令中用來執行特定動作的一組參數。A group of parameters that can be used in the same command to perform a specific action. 一個 Cmdlet 可以有多個參數集,但每個參數集必須至少有一個唯一的參數。A cmdlet can have multiple parameter sets, but each parameter set must have at least one parameter that is unique. 良好的 Cmdlet 設計強烈建議,unique 參數也是必要參數。Good cmdlet design strongly suggests that the unique parameter also be a required parameter. 如需參數集的詳細資訊,請參閱Cmdlet 參數集For more information about parameter sets, see Cmdlet Parameter Sets.

動態參數Dynamic parameter

在執行時間新增至 Cmdlet 的參數。A parameter that is added to the cmdlet at runtime. 一般而言,當另一個參數設定為特定值時,會將動態參數新增至 Cmdlet。Typically, the dynamic parameters are added to the cmdlet when another parameter is set to a specific value. 如需動態參數的詳細資訊,請參閱Cmdlet 動態參數For more information about dynamic parameters, see Cmdlet Dynamic Parameters.

輸入處理方法Input processing methods

System.web類別提供了下列用來處理記錄的虛擬方法。The System.Management.Automation.Cmdlet class provides the following virtual methods that are used to process records. 所有衍生的 Cmdlet 類別都必須覆寫前三個方法的其中一個或多個:All the derived cmdlet classes must override one or more of the first three methods:

如需這些方法的詳細資訊,請參閱Cmdlet 輸入處理方法For more information about these methods, see Cmdlet Input Processing Methods.

當您執行 Cmdlet 時,您必須至少覆寫其中一個輸入處理方法。When you implement a cmdlet, you must override at least one of these input processing methods. 一般來說, ProcessRecord () 是您覆寫的方法,因為它會針對 Cmdlet 所處理的每一筆記錄呼叫。Typically, the ProcessRecord() is the method that you override because it is called for every record that the cmdlet processes. 相反地, BeginProcessing () 方法和EndProcessing () 方法會呼叫一次來執行記錄的前置處理或後置處理。In contrast, the BeginProcessing() method and the EndProcessing() method are called one time to perform pre-processing or post-processing of the records. 如需這些方法的詳細資訊,請參閱輸入處理方法For more information about these methods, see Input Processing Methods.

ShouldProcess 功能ShouldProcess feature

PowerShell 可讓您建立 Cmdlet,在 Cmdlet 對系統進行變更之前提示使用者提供意見反應。PowerShell allows you to create cmdlets that prompt the user for feedback before the cmdlet makes a change to the system. 若要使用這項功能,Cmdlet 必須在宣告 ShouldProcess Cmdlet 屬性時宣告其支援功能,而此 Cmdlet 必須從輸入處理方法中呼叫ShouldProcessShouldContinue方法,而此指令程式必須是。To use this feature, the cmdlet must declare that it supports the ShouldProcess feature when you declare the Cmdlet attribute, and the cmdlet must call the System.Management.Automation.Cmdlet.ShouldProcess and System.Management.Automation.Cmdlet.ShouldContinue methods from within an input processing method. 如需如何支援功能的詳細資訊 ShouldProcess ,請參閱要求確認For more information about how to support the ShouldProcess functionality, see Requesting Confirmation.

交易Transaction

視為單一工作的命令邏輯群組。A logical group of commands that are treated as a single task. 如果群組中有任何命令失敗,此工作會自動失敗,而且使用者可以選擇接受或拒絕在交易內執行的動作。The task automatically fails if any command in the group fails, and the user has the choice to accept or reject the actions performed within the transaction. 若要參與交易,Cmdlet 必須在宣告 Cmdlet 屬性時宣告它支援交易。To participate in a transaction, the cmdlet must declare that it supports transactions when the Cmdlet attribute is declared. 對交易的支援是在 Windows PowerShell 2.0 中引進。Support for transactions was introduced in Windows PowerShell 2.0. 如需交易的詳細資訊,請參閱如何支援交易For more information about transactions, see How to Support Transactions.

Cmdlet 與命令有何不同How Cmdlets Differ from Commands

Cmdlet 與其他命令 shell 環境中的命令不同,有下列幾種方式:Cmdlets differ from commands in other command-shell environments in the following ways:

  • Cmdlet 是 .NET 類別的實例;它們不是獨立的可執行檔。Cmdlets are instances of .NET classes; they are not stand-alone executables.
  • 您可以從短短幾行程式碼建立 Cmdlet。Cmdlets can be created from as few as a dozen lines of code.
  • Cmdlet 通常不會執行自己的剖析、錯誤簡報或輸出格式。Cmdlets do not generally do their own parsing, error presentation, or output formatting. 剖析、錯誤簡報和輸出格式是由 PowerShell 執行時間處理。Parsing, error presentation, and output formatting are handled by the PowerShell runtime.
  • Cmdlet 會處理來自管線的輸入物件,而不是從文字的資料流程,而 Cmdlet 通常會將物件當做輸出傳遞至管線。Cmdlets process input objects from the pipeline rather than from streams of text, and cmdlets typically deliver objects as output to the pipeline.
  • Cmdlet 是記錄導向的,因為它們會一次處理一個物件。Cmdlets are record-oriented because they process a single object at a time.

Cmdlet 基類Cmdlet Base Classes

Windows PowerShell 支援衍生自下列兩個基類的 Cmdlet。Windows PowerShell supports cmdlets that are derived from the following two base classes.

  • 大部分的 Cmdlet 都是以衍生自system.object基類的 .net 類別為基礎。Most cmdlets are based on .NET classes that derive from the System.Management.Automation.Cmdlet base class. 衍生自這個類別可讓 Cmdlet 使用 Windows PowerShell 執行時間上的最小相依性集合。Deriving from this class allows a cmdlet to use the minimum set of dependencies on the Windows PowerShell runtime. 這樣有兩個優點。This has two benefits. 第一個優點是 Cmdlet 物件較小,而且您較不可能受到 PowerShell 執行時間變更的影響。The first benefit is that the cmdlet objects are smaller, and you are less likely to be affected by changes to the PowerShell runtime. 第二個優點是,如果您需要,可以直接建立 Cmdlet 物件的實例,然後直接叫用它,而不是透過 PowerShell 執行時間叫用它。The second benefit is that, if you have to, you can directly create an instance of the cmdlet object and then invoke it directly instead of invoking it through the PowerShell runtime.

  • 較複雜的 Cmdlet 是以衍生自PSCmdlet基類的 .net 類別為基礎。The more-complex cmdlets are based on .NET classes that derive from the System.Management.Automation.PSCmdlet base class. 衍生自這個類別可讓您更容易存取 PowerShell 執行時間。Deriving from this class gives you much more access to the PowerShell runtime. 此存取可讓您的 Cmdlet 呼叫腳本、存取提供者,以及存取目前的會話狀態。This access allows your cmdlet to call scripts, to access providers, and to access the current session state. (若要存取目前的會話狀態,您可以取得並設定會話變數和喜好設定)。不過,衍生自這個類別會增加 Cmdlet 物件的大小,這表示您的 Cmdlet 會與目前的 PowerShell 執行時間版本緊密結合。(To access the current session state, you get and set session variables and preferences.) However, deriving from this class increases the size of the cmdlet object, and it means that your cmdlet is more tightly coupled to the current version of the PowerShell runtime.

一般而言,除非您需要 PowerShell 執行時間的延伸存取權,否則您應該衍生自system.object類別。In general, unless you need the extended access to the PowerShell runtime, you should derive from the System.Management.Automation.Cmdlet class. 不過,PowerShell 執行時間具有廣泛的記錄功能,可執行 Cmdlet。However, the PowerShell runtime has extensive logging capabilities for the execution of cmdlets. 如果您的審核模型相依于此記錄,您可以藉由衍生自PSCmdlet類別,防止從另一個 Cmdlet 中執行 Cmdlet。If your auditing model depends on this logging, you can prevent the execution of your cmdlet from within another cmdlet by deriving from the System.Management.Automation.PSCmdlet class.

Cmdlet 屬性Cmdlet Attributes

PowerShell 定義數個用來管理 Cmdlet 的 .NET 屬性,並指定 PowerShell 提供的一般功能,以及 Cmdlet 可能需要的功能。PowerShell defines several .NET attributes that are used to manage cmdlets and to specify common functionality that is provided by PowerShell and that might be required by the cmdlet. 例如,屬性是用來指定類別做為 Cmdlet、指定 Cmdlet 的參數,以及要求輸入的驗證,讓 Cmdlet 開發人員不需要在其 Cmdlet 程式碼中執行該功能。For example, attributes are used to designate a class as a cmdlet, to specify the parameters of the cmdlet, and to request the validation of input so that cmdlet developers do not have to implement that functionality in their cmdlet code. 如需有關屬性的詳細資訊,請參閱PowerShell 屬性For more information about attributes, see PowerShell Attributes.

Cmdlet 名稱Cmdlet Names

PowerShell 會使用動詞和名詞名稱配對來命名 Cmdlet。PowerShell uses a verb-and-noun name pair to name cmdlets. 例如, Get-Command PowerShell 中包含的 Cmdlet 會用來取得在命令 shell 中註冊的所有 Cmdlet。For example, the Get-Command cmdlet included in PowerShell is used to get all the cmdlets that are registered in the command shell. 動詞識別指令程式所執行的動作,名詞則識別此 Cmdlet 執行其動作的資源。The verb identifies the action that the cmdlet performs, and the noun identifies the resource on which the cmdlet performs its action.

當 .NET 類別宣告為 Cmdlet 時,會指定這些名稱。These names are specified when the .NET class is declared as a cmdlet. 如需如何將 .NET 類別宣告為 Cmdlet 的詳細資訊,請參閱Cmdlet 屬性宣告。For more information about how to declare a .NET class as a cmdlet, see Cmdlet Attribute Declaration.

撰寫 Cmdlet 程式碼Writing Cmdlet Code

本檔提供兩種方式來探索 Cmdlet 程式碼的撰寫方式。This document provides two ways to discover how cmdlet code is written. 如果您想要查看程式碼而不會有太多說明,請參閱Cmdlet 程式碼的範例If you prefer to see the code without much explanation, see Examples of Cmdlet Code. 如果您想要更多有關程式碼的說明,請參閱GetProc 教學課程、 StopProc 教學課程或SelectStr 教學課程主題。If you prefer more explanation about the code, see the GetProc Tutorial, StopProc Tutorial, or SelectStr Tutorial topics.

如需撰寫 Cmdlet 之指導方針的詳細資訊,請參閱Cmdlet 開發指導方針For more information about the guidelines for writing cmdlets, see Cmdlet Development Guidelines.

另請參閱See Also

PowerShell Cmdlet 概念PowerShell Cmdlet Concepts

撰寫 PowerShell CmdletWriting a PowerShell Cmdlet

PowerShell SDKPowerShell SDK