Cmdlet Overview - PowerShell (2024)

Article
09/17/2021

A cmdlet is a lightweight command that is used in the PowerShell environment. The PowerShell runtimeinvokes these cmdlets within the context of automation scripts that are provided at the commandline. The PowerShell runtime also invokes them programmatically through PowerShell APIs.

Cmdlets

Cmdlets perform an action and typically return a Microsoft .NET object to the next command in thepipeline. A cmdlet is a single command that participates in the pipeline semantics of PowerShell.This includes binary (C#) cmdlets, advanced script functions, CDXML, and Workflows.

This SDK documentation describes how to create binary cmdlets written in C#. For information aboutscript-based cmdlets, see:

about_Functions_Advanced
about_Functions_CmdletBindingAttribute
about_Functions_Advanced_Methods

To create a binary cmdlet, you must implement a cmdlet class that derives from one of twospecialized 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 ascmdlet 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 theImport-Module cmdlet, or you cancreate a host application that loads the assembly by using theSystem.Management.Automation.Runspaces.InitialsessionstateAPI. Both methods provide programmatic and command-line access to the functionality of the cmdlet.

Cmdlet Terms

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

Cmdlet attribute

A .NET attribute that is used to declare a cmdlet class as a cmdlet. Although PowerShell usesseveral other attributes that are optional, the Cmdlet attribute is required. For more informationabout this attribute, see Cmdlet Attribute Declaration.

Cmdlet parameter

The public properties that define the parameters that are available to the user or to theapplication that is running the cmdlet. Cmdlets can have required, named, positional, and switchparameters. Switch parameters allow you to define parameters that are evaluated only if theparameters 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 cmdletcan have multiple parameter sets, but each parameter set must have at least one parameter that isunique. 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 tothe cmdlet when another parameter is set to a specific value. For more information about dynamicparameters, see Cmdlet Dynamic Parameters.

Input processing methods

The System.Management.Automation.Cmdlet classprovides the following virtual methods that are used to process records. All the derived cmdletclasses 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. TheSystem.Management.Automation.Cmdlet.ProcessRecordmethod 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 pressingCTRL+C).

For more information about these methods, seeCmdlet Input Processing Methods.

When you implement a cmdlet, you must override at least one of these input processing methods.Typically, the ProcessRecord() is the method that you override because it is called for everyrecord that the cmdlet processes. In contrast, the BeginProcessing() method and theEndProcessing() method are called one time to perform pre-processing or post-processing of therecords. For more information about these methods, seeInput Processing Methods.

ShouldProcess feature

PowerShell allows you to create cmdlets that prompt the user for feedback before the cmdlet makes achange to the system. To use this feature, the cmdlet must declare that it supports theShouldProcess feature when you declare the Cmdlet attribute, and the cmdlet must call theSystem.Management.Automation.Cmdlet.ShouldProcessandSystem.Management.Automation.Cmdlet.ShouldContinuemethods from within an input processing method. For more information about how to support theShouldProcess functionality, seeRequesting Confirmation.

Transaction

A logical group of commands that are treated as a single task. The task automatically fails if anycommand in the group fails, and the user has the choice to accept or reject the actions performedwithin the transaction. To participate in a transaction, the cmdlet must declare that it supportstransactions when the Cmdlet attribute is declared. Support for transactions was introduced inWindows PowerShell 2.0. For more information about transactions, seeHow to Support Transactions.

How Cmdlets Differ from Commands

Cmdlets differ from commands in other command-shell environments in the following ways:

Cmdlets are instances of .NET 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 PowerShell runtime.
Cmdlets process input objects from the pipeline rather than from streams of text, and cmdletstypically 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 classes that derive from theSystem.Management.Automation.Cmdlet base class.Deriving from this class allows a cmdlet to use the minimum set of dependencies on the WindowsPowerShell runtime. This has two benefits. The first benefit is that the cmdlet objects aresmaller, and you are less likely to be affected by changes to the PowerShell runtime. The secondbenefit is that, if you have to, you can directly create an instance of the cmdlet object and theninvoke it directly instead of invoking it through the PowerShell runtime.
The more-complex cmdlets are based on .NET classes that derive from theSystem.Management.Automation.PSCmdlet baseclass. Deriving from this class gives you much more access to the PowerShell runtime. This accessallows 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 ismore tightly coupled to the current version of the PowerShell runtime.

In general, unless you need the extended access to the PowerShell runtime, you should derive fromthe System.Management.Automation.Cmdlet class.However, the PowerShell runtime has extensive logging capabilities for the execution of cmdlets. Ifyour auditing model depends on this logging, you can prevent the execution of your cmdlet fromwithin another cmdlet by deriving from theSystem.Management.Automation.PSCmdlet class.

Cmdlet Attributes

PowerShell defines several .NET attributes that are used to manage cmdlets and to specify commonfunctionality that is provided by 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, andto request the validation of input so that cmdlet developers do not have to implement thatfunctionality in their cmdlet code. For more information about attributes, seePowerShell Attributes.

Cmdlet Names

PowerShell uses a verb-and-noun name pair to name cmdlets. For example, the Get-Command cmdletincluded in PowerShell is used to get all the cmdlets that are registered in the command shell. Theverb identifies the action that the cmdlet performs, and the noun identifies the resource on whichthe cmdlet performs its action.

These names are specified when the .NET class is declared as a cmdlet. For moreinformation about how to declare a .NET class as a cmdlet, seeCmdlet Attribute Declaration.

Writing Cmdlet Code

This document provides two ways to discover how cmdlet code is written. If you prefer to see thecode without much explanation, see Examples of Cmdlet Code. If youprefer more explanation about the code, see the GetProc Tutorial,StopProc Tutorial, or SelectStr Tutorialtopics.

For more information about the guidelines for writing cmdlets, seeCmdlet Development Guidelines.