Early on in the development of the Microsoft Lync Server implementation of Windows PowerShell, everyone was talking about a “whopping” total of 300 cmdlets, tops, and the help writers confidently assured everyone that all the cmdlets would be documented by pre-beta. And then the product started to grow. And change. And then grow and change some more. In the end we wound up with well over 500 cmdlets. But the good news is that while we didn’t quite hit the pre-beta timeline, when the product shipped every cmdlet was fully documented. Even more good news is the fact that accessing help for a Windows PowerShell cmdlet is pretty easy; for example, if you want to know more about the Get-CsUser cmdlet you can (and we emphasize the word “can”) use this command:
If you run that command you’ll get back information about Get-CsUser. So then why did we say that you “can” use that command to get help on a PowerShell cmdlet?
Here’s why. The problem is that, by default, Get-Help displays only an abbreviated form of help. If you use the preceding command you’ll get a description of Get-CsUser and you’ll get a syntax diagram for the cmdlet; what you won’t get are the cmdlet parameters (which are particularly important when it comes to the New and Set cmdlets). On top of that, you won’t get the cmdlet examples, which are often the most useful part of a PowerShell help topic. In short, you get minimal help at best.
That’ss why we recommend you run a command like this instead:
Get-Help Get-CsUser –full
The –full parameter tells PowerShell that we want to see the full help for a cmdlet rather than the abbreviated help; that means that we can see all the parameters and – perhaps even more important – all the examples.
Note. If the examples are that important shouldn’t there be a way to see just the examples for a cmdlet? Funny you should ask; try this command and see what happens:
Get-Help Get-CsUser –examples
If you’d like to view only the syntax for a cmdlet you can do that by calling Get-Command with the –Syntax parameter:
Get-Command Get-CsUser –syntax
That shows you the “syntax diagram” for the cmdlet; the syntax diagram will look something like the following, which happens to be the syntax diagram for Get-Help:
Get-Help [[-Name] <String>] [-Path <String>] [-Category <String>] [-Component <String>] [-Functionality <String>] [-Role <String>] [-Full] [-Online] [-Verbose] [-Debug] [-ErrorAction <ActionPreference>] [-WarningAction <ActionPreference>] [-ErrorVariable <String>] [-WarningVariable <String>] [-OutVariable <String>] [-OutBuffer <Int32>]
And yes, we know: that’s not the most readable thing we’ve ever seen, either. But with a little diligence you can pick out the parameters for the cmdlet:
It’s far from perfect, but it is better than nothing.
Note. Here’s a trick that you can use to get the nicely-formatted parameter list shown above. To view a list of parameters for Get-Help, type this command:
(Get-Command Get-Help –syntax) –replace("\[-","`n[-")
We won’t bother to explain how that command works. Just take it on faith that it does work.
When you read one of these syntax diagrams, anything prefaced with a hyphen is a parameter; that means that Get-Help has parameters like –Name, -Path and –Category. The values enclosed in angle brackets – like <String> – indicate the data type of the parameter; for example, we can see that –Name takes a string (<String>) value. Oh, and what about a construction like this:
The square brackets () tell us that the parameter in question accepts an array of values; in PowerShell,  in a data type indicates an array.
Note. And what if there’s no data type listed; for example, what about a parameter like -Verbose? Well, if there’s no data type listed that often means that this is an example of a PowerShell “switch parameter.” A switch parameter is sort of like an on/off switch: it’s either on (that is, you run a command in Verbose mode) or it’s off (you run a command in non-Verbose mode). There’s no data type listed because you don’t pass any value to the parameter: it’s either there or it isn’t.
Of course, there’s a good chance you knew all this already. But seeing as how we’re getting paid by the word we decided to add it to this article anyway.
Editor’s Note. Before you ask, no, we don’t really get paid by the word. In fact, come to think, we’re not sure we’re getting paid at all these days. We should probably check on that, shouldn’t we?
Incidentally, the first time you look at Windows PowerShell help you’ll probably think, “Man, I need to get new glasses.” That’s because – to be perfectly frank – PowerShell’s help engine does a terrible job of figuring out line breaks; as a matter of fact, it doesn’t even try to figure out line breaks. PowerShell doesn’t care whether it breaks a line in the middle of a word or not. For example, if this paragraph was displayed as a PowerShell help topic it would look something like this:
Incidentally, the first time you look at Windows PowerShell he
lp you’ll probably think, “Man, I need to get new glasses.” Th
at’s because – to be perfectly frank – PowerShell’s help engin
e does a terrible job of figuring out line breaks; as a matter
of fact, it doesn’t even try to figure out line breaks. PowerS
hell doesn’t care whether it breaks a line in the middle or a
word or not.
So what can you do about this? Nothing; that’s the way PowerShell displays help, and there are no plans to change this. On the bright side, in addition to the inline PowerShell help, Lync Server also ships with a .CHM file that contains the exact same help, albeit in slightly easier-to-read format. You can also access all that help online.
And if that doesn’t give you a reason to live, well ....