A cmdlet is a lightweight command that is used in the Windows PowerShell environment. The Windows PowerShell runtime invokes these cmdlets within the context of automation scripts that are provided at the command line. The Windows PowerShell runtime also invokes them programmatically through Windows PowerShell APIs.
Cmdlets perform an action and typically return a Microsoft .NET Framework object to the next command in the pipeline. To write a cmdlet, you must implement a cmdlet class that derives from one of two specialized cmdlet base classes. The derived class must:
Declare an attribute that identifies the derived class as a 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.
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. Both methods provide programmatic and command-line access to the functionality of the cmdlet.
The following terms are used frequently in the Windows PowerShell cmdlet documentation:
Cmdlet attribute: A .NET Framework attribute that is used to declare a cmdlet class as a cmdlet. Although Windows PowerShell uses several other attributes that are optional, the Cmdlet attribute is required. For more information about this attribute, see Cmdlet Attribute Declaration.
Cmdlet parameter: The public properties that define the parameters that are available to the user or to the application that is running the 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. 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. A cmdlet can have multiple parameter sets, but each parameter set must have at least one parameter that is unique. Good cmdlet design strongly suggests that the unique parameter also be a required parameter. For more information about parameter sets, see Cmdlet Parameter Sets.
Dynamic parameter: A parameter that is added to the cmdlet at runtime. Typically, the dynamic parameters are added to the cmdlet when another parameter is set to a specific value. For more information about dynamic parameters, see Cmdlet Dynamic Parameters.
Input processing method: A method that a cmdlet can use to process the records it receives as input. The input processing methods include the System.Management.Automation.Cmdlet.Beginprocessing* method, the System.Management.Automation.Cmdlet.Processrecord* method, the System.Management.Automation.Cmdlet.Endprocessing* method, and the System.Management.Automation.Cmdlet.Stopprocessing* method. When you implement a cmdlet, you must override at least one of the System.Management.Automation.Cmdlet.Beginprocessing*, System.Management.Automation.Cmdlet.Processrecord*, and System.Management.Automation.Cmdlet.Endprocessing* methods. Typically, the System.Management.Automation.Cmdlet.Processrecord* method is the method that you override because it is called for every record that the cmdlet processes. In contrast, the System.Management.Automation.Cmdlet.Beginprocessing* method and the System.Management.Automation.Cmdlet.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 feature: Windows PowerShell allows you to create cmdlets that prompt the user for feedback before the cmdlet makes a change to the system. 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. 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. To participate in a transaction, the cmdlet must declare that it supports transactions when the Cmdlet attribute is declared. Support for transactions was introduced in Windows PowerShell 2.0. For more information about transactions, see Windows PowerShell Transactions.
How Cmdlets Differ from Commands
Cmdlets differ from commands in other command-shell environments in the following ways:
Cmdlets are instances of .NET Framework classes; they are not stand-alone executables.
Cmdlets can be created from as few as a dozen lines of code.
Cmdlets do not generally do their own parsing, error presentation, or output formatting. Parsing, error presentation, and output formatting are handled by the Windows PowerShell runtime.
Cmdlets process input objects from the pipeline rather than from streams of text, and cmdlets typically deliver objects as output to the pipeline.
Cmdlets are record-oriented because they process a single object at a time.
Cmdlet Base Classes
Windows PowerShell supports cmdlets that are derived from the following two base classes.
Most cmdlets are based on .NET Framework classes that derive from the System.Management.Automation.Cmdlet base class. Deriving from this class allows a cmdlet to use the minimum set of dependencies on the Windows PowerShell runtime. This has two benefits. The first benefit is that the cmdlet objects are smaller, and you are less likely to be affected by changes to the Windows PowerShell runtime. 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 Windows PowerShell runtime.
The more-complex cmdlets are based on .NET Framework classes that derive from the System.Management.Automation.Pscmdlet base class. Deriving from this class gives you much more access to the Windows PowerShell runtime. This access allows your cmdlet to call scripts, to access providers, and to access the current session state. (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 Windows PowerShell runtime.
In general, unless you need the extended access to the Windows PowerShell runtime, you should derive from the System.Management.Automation.Cmdlet class. However, the Windows PowerShell runtime has extensive logging capabilities for the execution of cmdlets. 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.
Input Processing Methods
The System.Management.Automation.Cmdlet class provides the following virtual methods that are used to process records. All the derived cmdlet classes must override one or more of the first three methods:
System.Management.Automation.Cmdlet.Beginprocessing*: Used to provide optional one-time, pre-processing functionality for the cmdlet.
System.Management.Automation.Cmdlet.Processrecord*: Used to provide record-by-record processing functionality for the cmdlet. The System.Management.Automation.Cmdlet.Processrecord* method might be called any number of times, or not at all, depending on the input of the cmdlet.
System.Management.Automation.Cmdlet.Endprocessing*: Used to provide optional one-time, post-processing functionality for the cmdlet.
System.Management.Automation.Cmdlet.Stopprocessing*: Used to stop processing when the user stops the cmdlet asynchronously (for example, by pressing CTRL+C).
For more information about these methods, see Cmdlet Input Processing Methods.
Windows PowerShell defines several .NET Framework attributes that are used to manage cmdlets and to specify common functionality that is provided by Windows PowerShell and that might be required by the 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. For more information about attributes, see Windows PowerShell Attributes.
Windows PowerShell uses a verb-and-noun name pair to name cmdlets. For example, the
Get-Command cmdlet included in Windows PowerShell is used to get all the cmdlets that are registered in the command shell. The verb identifies the action that the cmdlet performs, and the noun identifies the resource on which the cmdlet performs its action.
These names are specified when the .NET Framework class is declared as a cmdlet. For more information about how to declare a .NET Framework class as a cmdlet, see Cmdlet Attribute Declaration.
Writing Cmdlet Code
This document provides two ways to discover how cmdlet code is written. If you prefer to see the code without much explanation, see Examples of Cmdlet Code. If you prefer more explanation about the code, see the GetProc Tutorial, StopProc Tutorial, or SelectStr Tutorial topics.
For more information about the guidelines for writing cmdlets, see Cmdlet Development Guidelines.
We'd love to hear your thoughts. Choose the type you'd like to provide:
Our feedback system is built on GitHub Issues. Read more on our blog.