Prof. Powershell

Parameter Peeking

Tab completion and Get-Command offer two ways to discover parameters for cmdlets without resorting to reading the cmdlet help.

• By Jeffery Hicks
• 08/03/2010

One of PowerShell's greatest strengths is its ability to tell you about itself. As long as you know where to look, which I realize is not always easy, you can extract useful information.

This week let me show you how to dig into cmdlet parameters. There are times when I know there's a cmdlet parameter, but I just don't remember the name. There are a few ways to discover the name without having to resort to reading cmdlet help.

For some cmdlets like Get-Service, the syntax is pretty simple and parameters easy to identify. But in more complex cmdlets like New-ADUser from the Microsoft Active Directory module, it can be like finding the needle in the proverbial hay stack.

One solution is to take advantage of tab completion. Open a PowerShell prompt, type the cmdlet name and then start typing the parameter name. Don't forget the dash. If you know what letter the parameter starts with, so much the better. After you type dash and the first letter, press the Tab key and let PowerShell auto-complete. If it is not the parameter you seek, press Tab again. You can also type dash and then Tab to cycle through all the parameters. Pressing Shift+Tab will move backwards.

The other approach is to use Get-Command and look at the parameters:

PS C:\> get-command get-service | select -expandproperty parameters

Key               Value
---               -----
Name              System.Management.Automation.ParameterMetadata
ComputerName      System.Management.Automation.ParameterMetadata
DependentServices System.Management.Automation.ParameterMetadata
RequiredServices  System.Management.Automation.ParameterMetadata
DisplayName       System.Management.Automation.ParameterMetadata
Include           System.Management.Automation.ParameterMetadata
Exclude           System.Management.Automation.ParameterMetadata
InputObject       System.Management.Automation.ParameterMetadata
Verbose           System.Management.Automation.ParameterMetadata
Debug             System.Management.Automation.ParameterMetadata
ErrorAction       System.Management.Automation.ParameterMetadata
WarningAction     System.Management.Automation.ParameterMetadata
ErrorVariable     System.Management.Automation.ParameterMetadata
WarningVariable   System.Management.Automation.ParameterMetadata
OutVariable       System.Management.Automation.ParameterMetadata
OutBuffer         System.Management.Automation.ParameterMetadata

The last eight parameters are part of the common parameter set that all cmdlets share. But I can easily see all the other parameters for Get-Service. What you see is actually a hash table with even more information if you feel like peeking. It will be easier to save this as a variable:

PS C:\> $params=get-command get-service | select -ExpandProperty parameters

Let's look at the Name property:

PS C:\> $params.item("name")

Name            : Name
ParameterType   : System.String[]
ParameterSets   : {[Default, System.Management.
                  Automation.ParameterSetMetadata]}
IsDynamic       : False
Aliases         : {ServiceName}
Attributes      : {Default, System.Management.Automation.
                   AliasAttribute}
SwitchParameter : False

I can see that the parameter is a String and has an alias of ServiceName. The last thing I want to show you are the parameter attributes:

PS C:\> $params.item("name").attributes

Position                        : 0
ParameterSetName                : Default
Mandatory                       : False
ValueFromPipeline               : True
ValueFromPipelineByPropertyName : True
ValueFromRemainingArguments     : False
HelpMessage                     :
HelpMessageBaseName             :
HelpMessageResourceId           :
TypeId                          : System.Management.Automation.
                                  ParameterAttribute

AliasNames                      : {ServiceName}
TypeId                          : System.Management.Automation.
                                  AliasAttribute

Very cool. I can see that the parameter is not mandatory, is positional at index 0, which means I don't have to type the parameter name, just the value. I also can tell that the parameter accepts pipelined input.

When you're trying to learn a new cmdlet, the help documentation is often useful. But sometimes, when you just want to know more about a specific parameter, this technique comes in very handy.

• Code Download