How do I configure help and usage statements in a powershell script?

Suppose I have the powershell script foo.ps1:

<# test foo.ps1 #>
param(
  [CmdletBinding()]
  [Switch]$foo,
  [Switch]$bar
)

Which has a few automatic parameters like -Debug and -Verbose in addition to the custom parameters -foo and -bar.

I should be able to see all of these parameters when I do something like .\foo.ps1 --help, or I should be able to configure that somehow.

What is the core way to do this in powershell?

Get-Command will return you the full list of parameters, including common parameters:

$myScript = Get-Command .\foo.ps1

# this is a dictionary containing all the parameters
$myScript.Parameters 

# we can index into it like any other dictionary to inspect the parameter metadata for a given parameter
$myScript.Parameters['bar']

With regards to Get-Help, that part is already taken care of for you - when you do Get-Help .\foo.ps1 or .\foo -? after adding a CmdletBinding, PowerShell will automatically add [<CommonParameters>] to the command syntax string to indicate that common parameters are accepted:

Without [CmdletBinding()] decorator:

f [-foo] [-bar]

With [CmdletBinding()] decorator (or any parameter attribute decorators) specified:

f [-foo] [-bar]  [<CommonParameters>]

If you want richer help content displayed, then you'll need to provide it

To complement Mathias' helpful answer:

• The conceptual about_Command_Syntax help topic discusses PowerShell's syntax diagrams, which is PowerShell's notation for documenting a command's supported parameters, their data types, whether they are mandatory, and whether they can be bound positionally.

• The common parameters (such as -Debug and -Verbose) that are implicitly supported by compiled cmdlets and advanced functions and scripts^[1] are documented in the conceptual about_CommonParameters help topic.

• Common parameters are never shown individually in syntax diagrams, only with the collective placeholder [<CommonParameters>], as shown in Mathias' answer.

• Due to a bug, present up to at least PowerShell (Core) 7.3.6, this placeholder is mistakenly also shown for non-advanced functions and scripts, if they happen to define comment-based help, as documented in the conceptual about_Comment_Based_Help help topic; here's a minimal example:

  # !! Output mistakenly suggests that Get-Foo supports common parameters.
  function Get-Foo { <#.SYNOPSIS #> }; Get-Foo -?
  

  • The relevant bug report is GitHub issue #17312

• Syntax diagrams can be shown with parameter -? (for cmdlets and advanced functions and scripts as well as functions and scripts with comment-based help, even if non-advanced), Get-Help (for any command except external programs), and, in isolation, with Get-Command -Syntax, which takes its information directly from the command's definition, whereas Get-Help may take its information from an external help file, if present; since a help file may get out of sync with the actual implementation, Get-Command -Syntax is a more reliable source.

• That syntax diagrams never show enumerate the common parameters individually is somewhat unfortunate:

  • The following two common parameters aren't supported by all cmdlets / advanced functions and scripts, as they require opt-in via the ShouldProcess property of the [CmdletBinding()] attribute:

    • -WhatIf

    • -Confirm

    • As a rule of thumb, only cmdlets that have side effects, notably potentially destructive ones support these parameters, such as Remove-Item

    • Tab-completion can tell you for a given command whether these common parameters are supported or not.

  • As Mathias notes, (Get-Command ...).Parameters allows you to enumerate all parameters of a given command - but you cannot programmatically tell which of those are common parameters - you'll have to recognize them by their names.

    • As an approximation of listing only a command's common parameters - which will also tell you whether -WhatIf and -Confirm is supported, you can use the following, but note that it can yield false positives (using Remove-Item as a sample command):

      # List all common parameters supported by Remove-Item.
      (Get-Command Remove-Item).Parameters.Values |
        Where { $_.Aliases[0] -like '??' -or $_.Name -eq 'InformationAction' } | 
        ForEach-Object Name
      

      • The above takes advantage of the fact that all common parameters have two-letter aliases, such as -wi for -WhatIf - the only exception being InformationAction, whose alias is -infa.

^{[1] In short: It is the use of a [CmdletBinding()] attribute and/or of at least one parameter-individual [Parameter()] attribute that makes a function or script and advanced one.}