Navigating the Nuances of PowerShell Syntax with Get-Help and Get-Command

calendar Nov 2, 2023 · PowerShell  ·
Share on: linkedin copy

When working with PowerShell, it's essential to understand the tools available for exploring cmdlets and their syntax. Both Get-Help and Get-Command are invaluable resources for discovering and understanding cmdlet syntax in PowerShell. While both provide syntax information, they display the details differently for parameters that accept enumerated values. In this article, we'll explore the subtle but significant differences between these two cmdlets and how they can assist in your PowerShell scripting efforts.

The basics

Before exploring the nuances, let's review the purpose of Get-Help and Get-Command.

  • Get-Help is primarily used for retrieving detailed information about cmdlets, functions, or modules. It provides extensive documentation, including descriptions, examples, and parameter details.

  • Get-Command is used for discovering and exploring the available commands on your system. It lists commands matching specific criteria, including the command's name, module, and syntax.

Enumerated values for parameters

In PowerShell, many parameters can accept enumerated values. Enumerated values are predefined sets of values that a parameter can accept. For example, a parameter might accept values like Enabled or Disabled, and these are often defined as enums.

Now, let's explore how Get-Help and Get-Command handle enumerated values when displaying the parameters for cmdlet syntax.

Get-Help

When using Get-Help to retrieve information about a cmdlet, it provides comprehensive details about each parameter, including its data type, description, and, if applicable, the enumerated values it accepts.

The SYNTAX section of Get-Help expands the enumerated values for parameters. It displays the actual values you can use, making it easier to understand the available options.

Here's an example of how the SYNTAX section of Get-Help displays information about a parameter that accepts enumerated values.

1(Get-Help -Name Get-ExecutionPolicy).Syntax

In this example, Get-Help lists the acceptable values as {CurrentUser | LocalMachine | MachinePolicy | Process | UserPolicy} for the Scope parameter of Get-ExecutionPolicy.

1Get-ExecutionPolicy [[-Scope] {CurrentUser | LocalMachine | MachinePolicy | Process | UserPolicy}]
2[-List] [<CommonParameters>]

Get-Command

Using Get-Command with its Syntax parameter is more concise, focused primarily on displaying the syntax of a cmdlet. While it provides the parameter names and data types, it doesn't include information about enumerated values.

Here's how Get-Command displays the syntax information.

1Get-Command -Name Get-ExecutionPolicy -Syntax

In this output, you can see the parameter names and their data types, but there's no mention of the specific allowable enumerated values for the Scope parameter.

1Get-ExecutionPolicy [[-Scope] <ExecutionPolicyScope>] [-List] [<CommonParameters>]

Choosing the best tool

Now that you understand the differences between Get-Help and Get-Command regarding enumerated values for parameters of cmdlet syntax, it's essential to choose the best tool for your specific needs.

  • Use Get-Help for detailed information about a cmdlet, including parameter descriptions, examples, and acceptable enumerated values. It's an excellent choice for in-depth exploration and learning.

  • Use Get-Command with its Syntax parameter when you want a quick reference to understand the basic syntax of a cmdlet, especially when you're already familiar with the cmdlet and need a reminder of its parameter names and data types.

Summary

Both Get-Help and Get-Command are valuable tools for PowerShell scripters. By understanding their differences, you can effectively leverage them to streamline your scripting tasks and make the most of PowerShell's powerful features.

References

Acknowledgments

Thanks to Sean Wheeler for pointing out the differences between Get-Help and Get-Command when displaying enumerated values for parameters while reviewing chapter 2 of my PowerShell 101 book.