Some notes I’ve taken while learning about the parameters and syntax of a PowerShell cmdlet as I read its help module.


 

Find the Syntax and Parameter Sets for a Cmdlet

Use Get-Help for a command. In the resulting output window, the “Syntax” section shows a number of parameter sets. Below is the syntax section from the help for Get-Service:

PS_Syntax

 

There are three parameter sets for Get-Service. If you use a parameter that’s unique to one set, you’re locked into using that one set of parameters when running that one operation.

With Get-Service, if you use -InputObject, you’re locked into that third set of parameters. This means you can’t use -Name, which is only in the first set, nor can you can use –DisplayName, which is only in the second set. If you use -Name with Get-Service, you can’t use -InputObject, as it’s not listed in that first set of parameters you would be locked into.

Mandatory and Optional Parameters

The list of parameters seems pretty long, but thankfully most of them aren’t required to run the cmdlet.

Optional Parameters have square brackets surrounding the entire parameter. Mandatory Parameters have at least part of the parameter outside brackets. Let’s take the first few parameters from the Get-Service help:

PS_Syntax_Required

 

[-ComputerName <String[]>] is completely optional, since the entire parameter is surrounded by brackets. However, if you use -ComputerName, you must provide the input to specify that name.

[[-Name] <String[]>] is also optional, but there are two sets of brackets, one around the -Name part, and one around the entire parameter. -Name here is a positional parameter. You don’t have to use -Name with Get-Service, but if you do, since -Name is the first parameter after the Get-Service name, you can just type in text (or provide other string input, like a text file object) without using -Name.

In this way, Get-Service EventLog and Get-Service -Name EventLog are the same thing; using -Name isn’t necessary. It is necessary when using -ComputerName, since in that parameter, the parameter name isn’t inside its own set of brackets like -Name is.

Running With No Parameters

Also, you might notice that every parameter in Get-Service has at least some portion inside brackets. Get-Service is a cmdlet that doesn’t have any required parameters at all — you could run Get-Service by itself with no parameters. Running Get-Service by itself will return all of the services running on the local computer.

What Do All These Parameters Do?

Get-Help Get-Service -Full | more

Using the -Full parameter with Get-Help will return a lot of info, including an explanation of every single parameter.

NOTE: To display a lot of output one page at a time, pipe the output to “more”, as shown above.

PS_Full_Help

The explanation for -DisplayName shows that it’s required, but the default value is to show everything. So if you used Get-Service without specifying  service(s), all of them will be shown.

Parameter Values

-DependentServices [<SwitchParameter>]

Switches are parameters which can be run by themselves, without an input value. The full help will list what the switch does and, if a value isn’t requires, what the default value would be.

[-LogName] <String> 

Input Values of some kind are otherwise required for parameters which have an input type surrounded by angle brackets.

  • String – Letters and numbers. If you need to type more than one word, where a space is involved, the string must be surrounded by quotation marks. Single quotes are recommended by the book I’m following, although it seems doubles work fine for this too.
  • INT – Including Int32 and Int64 – mean it expects a whole number. No decimals.
  • DateTime – This is for a string written in a date format as denoted by where you live. In the USA it’s usually MM-DD-YYYY format.
[-ComputerName <String[]>] 

Arrays are denoted by square brackets right next to an input value. Valid input for these include:

  • Single values
  • Multiple values, separated by commas, which PowerShell always treats as arrays.
    NOTE: Similar to arrays, if there are spaces in any of these values, the values must be surrounded by single quotes
  • Collections or Lists of values

Next Study Session

  • The structure of commands
  • Command aliases
  • Running legacy command line commands from within the PS Console