Cmdlets vs. APIs

  • Comments 11

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

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:
Visit the Windows PowerShell ScriptCenter at:

Leave a Comment
  • Please add 1 and 4 and type the answer here:
  • Post
  • Thanks for an interesting, informative post.  I have one complaint though, I think you're selling yourself short when you start talking about "Admin at the keyboard".  I view PowerShell as the command line interface to Windows.  It's for admins, it's for developers, it's for users, it's for everyone!

    Every piece of software that runs on Windows would be better if it had PowerShell cmdlets and/or providers.  Excel, Word, Money, Visual Studio - everything.

    I look forward to that day.

  • "Exchange 2007 has gone as far as to make Cmdlets be their only management interface"

    Without knowing details about remote managementability and existing schema wrappers, this sounds to me like a stab in the back of WMI/WBEM as well as other approaches to get to standards-based management infrastructures.

  • In reply to stabbing WMI/WBEM in the back, all I can say personally is, "Make it slow, Megaweapon! Make it slow."

  • Yes, this is off topic - but are you guys getting the Visual Studio guys to include syntax highlighting (at least) and intellisense (if possible) for *.ps1 files?  I know there are other PS editors out there (I'm a fan of Powershell Analyzer) but that would be sweet if we could just drop a ps1 onto visual studio and go to town.

    Just curious if you've already worked something like that out with the VS guys.

  • Well, let's see:

    MS Office Toolbar: popular in the extreme for end users - gone.

    Office 97, Office 2000, Office 2003 Interface: learned, used by millions of end users - gone.

    Graphical Interface Server Admin Tools - NT, Server 2000, Server 2003 - going.

    There is nothing wrong with providing a powerful shell - many Linux users swear by it. When the shell replaces the GUI for admin purposes altogether - which has clearly become the goal of you all, you may assure the development of a caste that will deal with the command line.

    But what happens to those who do not love the shell?

    At a launch event for Vista and Office 2007 for admins, I was among 300 attendees. As we watched the Aero interface and saw what had been done to Office - with no way back - the room got quieter and quieter. When the announcement of the new importance of the shell was made - the room fell deadly silent. The presenter plaintively wondered aloud why there were no smiles, nods and expressions of delight.

    Why indeed?

    Can you all be so far off base that you are only talking to each other?

    Down here on the ground where I, and others like me, must use what you turn out, these are serious issues.

  • Chorney:

    Have you used the new interface -- I mean uninstall-every-scrap-of-old-Office used it?  Frankly, I've found it much easier, and I've gotten that response from others as well.  Same with Aero.

    Don't confuse familiarity with usability.  Yes, there are learning curves, but there is quite a lot of effort that goes into actual, real-people usability studies, both internal and external.  They're fascinating to watch, actually.

  • Rant/PS needs some love

    Task manager shows the full command line of the processes running. I have no idea how to copy paste that however.

    Oh but, I have powershell installed!


    get-help ps..

    .. Ok that's useless

    tasklist -?

    What.. No command line there either??

    The unix command is simply:

    ps -auxw

    Given that I'm 100% windows user now and last used *nix years ago, it's funny that there's still many things I know that can be easily done in there but can't be done in Windows without bringing up Visual Studio and writing some code.

  • I agree with John Vottero, powershell is for anyone!  I am a developer and an admin.  I tend to use clr languages only when i am forced to.  i'd rather user pshell!!!

  • I would think that anyone with some ?NIX experience but works on MSFT products would love pshell immediately!

  • To check the commands related to process, do get-command *process* or ask get-help process or ask get-help ps

  • Già da un pò utilizzavo la Windows PowerShell 2.0 Community Technology Preview . Adesso e` possibile scaricare la CTP2.

    Il cuore della powershell sono le cmdlets, un'interfaccia di alto livello orientata al task e pensata per amministratori, molto fle

Page 1 of 1 (11 items)

Cmdlets vs. APIs