Cmdlets vs. APIs

Some people have asked the question, "Why Cmdlets?". If you already have a reasonable API, what is the value in writing Cmdlets? I'll provide a quick answer here but we should probably include a good write up of this in our documentation.

The most important thing to realize about cmdlets is that it is all about mindset and attitude. The mindset of a cmdlet designer is that there is an "Admin at the keyboard" and the attitude is "we are going to do whatever it takes to provide that person an optimal user experience". The entire PowerShell engine is designed to make it easy for people to succeed at doing just that. There are times when cmdlets are very thin wrappers on top of APIs but if that is the case, the wrapper is doing all the critical things necessary to provide an optimal experience for Admins at keyboards.

Let's get specific about the differences. Here is a quick core dump off the top of my head. There are probably more but this is a good start:

• Abstractions. APIs are, by definition, designed for developers. Cmdlets are designed for Admins at keyboards. Cmdlets are high-level task oriented abstractions.
• 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.
• Aliases. The constrained schema for Cmdlet naming makes it easy to produce and remember easy aliases for cmdlets. You cannot alias an API in PowerShell. Parameters can also be aliases which make it easier to support different conceptual models as well as to facilitate pipeline parameter binding (byPropertyname)
• Cmdlets provide a wider dynamic range of invocation styles than APIs. Cmdlets can be fully explicit will full names for the cmdlet and parameters provided which provides easy to read, self-documenting scripts. Cmdlets can also be pithy with aliases, positional parameters or abbreviated parameter names to make it easy to go fast during interactive sessions. APIs must always provide fully articulated method/property names and parameters to methods are always positional – they cannot provide the name to be self-documenting.
• 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.
• Error handling.
  • 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.
  • Cmdlet's non terminating errors are collected in a circular array $ERROR or can be set to a variable or added to a variable using the common parameter –ErrorVariable (e.g. –ErrorVariable a or –ErrorVariable +a )
  • User's can control the behavior of that happens when a non-terminating error occurs by using the –ErrorAction common parameter (values include CONTINUE, SILENTLYCONTINUE, STOP, INQUIRE)
• -Whatif –Confirm –Verbose support. Cmdlets that have a side effect on the system support the common parameters –Whatif, -Confirm and –Verbose. APIs do not.
• Pipelines. Cmdlets can be written to support PIPELINE input. APIs require the user to do programming to achieve a similar result.
• Wildcards. Cmdlets are encouraged to support wildcards even if and when the underlying APIs do not.
• Scriptblock parameters. The PowerShell engine provides scriptblock parameter support for Cmdlets but not APIs (http://blogs.msdn.com/powershell/archive/2006/06/23/643674.aspx ).

Exchange 2007 has gone as far as to make Cmdlets be their only management interface and they do not expose an API at all. This allows them to leverage PowerShell as an SDK, to provide common security model and logging services and in the future it will provide them a single common remoting service.

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.

Cmdlets are designed for Admins at keyboards while APIs are not. Cmdlets are the very heart and soul of PowerShell.

Jeffrey Snover [MSFT]
Windows Management Partner Architect
Visit the Windows PowerShell Team blog at: http://blogs.msdn.com/PowerShell
Visit the Windows PowerShell ScriptCenter at: http://www.microsoft.com/technet/scriptcenter/hubs/msh.mspx