Cmdlet Overview

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

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. 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.

Cmdlet Terms

The following terms are used frequently in the Windows PowerShell cmdlet documentation:

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:

For more information about these methods, see Cmdlet Input Processing Methods.

Cmdlet Attributes

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.

Cmdlet Names

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.

See Also

Windows PowerShell Cmdlet Concepts

Writing a Windows PowerShell Cmdlet

Windows PowerShell SDK