Jeffrey Snover describes the differences between using Cmdlets and APIs. He concludes with "Cmdlets are designed for Admins at keyboards while APIs are not. Cmdlets are the very heart and soul of PowerShell."
Cmdlets are created by inheriting from the Cmdlet or PSCmdlet base class. Both are implemented by overriding the BeginProcessing, ProcessRecord, and EndProcessing virtual functions.
These classes differ by the amount of PowerShell infrastructure they expose. While Cmdlet is lightweight and can be called from other Cmdlets, PSCmdlet offers access to the PowerShell runtime including environmental variables and session state.
Jeffrey Snover makes his case for Cmdlets by pointing out how they have much better support under PowerShell. Some highlights from his list include:
- Naming. Cmdlet naming is specific and constrained to allow Admins to successfully make a set of guesses about the world. Cmdlets follow a VERB-NOUN pattern with strong guidelines about the use of Verbs. Guidelines for parameters are also provided. APIs are much less predictable than cmdlets.
- Tab-Completion. PowerShell provides tab-completion for cmdlets and parameters but not for APIs.
- Help. Cmdlets provide admin-oriented man-style help. APIs provide developer oriented help.
- Discoverability. PowerShell provides a number of Admin-friendly ways to discover Cmdlets including Get-Command, Get-Help (both of which support wildcards), See-Also section of HELP.
- APIs just throw errors whereas Cmdlets draw the distinction between terminating and non-terminating errors. Non-terminating errors support bulk operations better but allowing operations to continue while gathering up all those elements that had issues and making them available as a collection.
Pipelines. Cmdlets can be written to support PIPELINE input. APIs require the user to do programming to achieve a similar result.
Jeffery also mentions that "In V2 – the gap between Cmdlets and APIs is going to grow MUCH larger. There will be important functions that will only be available to Cmdlets."