Parameter Naming Conventions
Relevant source files
The following files were used as context for generating this wiki page:
- .github/instructions/powershell-parameter-naming.instructions.md
- src/System.Management.Automation/help/HelpCommentsParser.cs
- src/System.Management.Automation/engine/GetCommandCommand.cs
- src/System.Management.Automation/cimSupport/cmdletization/ScriptWriter.cs
- src/System.Management.Automation/engine/InitialSessionState.cs
- src/Microsoft.PowerShell.Commands.Utility/commands/utility/ConvertTo-Html.cs
Parameter naming in PowerShell is a standardized process designed to ensure consistency across cmdlets, functions, and scripts. This system relies on a combination of metadata-driven naming, aliases, and specific naming patterns for common tasks like filtering, conversion, and CIM (Common Information Model) operations.
The scope of these conventions covers static parameters defined in C# classes, dynamic parameters generated at runtime, and script-based parameters defined in PowerShell modules. By following these conventions, the project ensures that command discovery and help systems can accurately parse and display parameter information to the user.
Core Parameter Metadata and Discovery
PowerShell's engine uses reflection and metadata to identify bindable parameters. The Get-Command cmdlet and the HelpCommentsParser class are central to discovering these parameters and their associated descriptions.
Parameter Metadata Structure
The engine tracks parameters through specialized metadata classes. This allows the system to distinguish between common parameters (like -Verbose or -ErrorAction) and command-specific parameters.
The internal structure allows for merging parameters from different sources, such as those inherited from base classes or those defined dynamically.
Sources: src/System.Management.Automation/help/HelpCommentsParser.cs:81-98, src/System.Management.Automation/engine/GetCommandCommand.cs:1134-1185
Help-Based Parameter Naming
For script functions, parameters can be named and documented using comment-based help. The parser identifies the .PARAMETER directive followed by the parameter name to associate documentation with the code.
| Directive | Description | Case Sensitivity |
|---|---|---|
.PARAMETER <Name> | Associates the following text block with the named parameter. | Invariant Case (Parsed as Upper) |
Sources: src/System.Management.Automation/help/HelpCommentsParser.cs:407-420, src/System.Management.Automation/help/HelpCommentsParser.cs:100-106
Standard Parameter Names for Common Tasks
Certain parameter names are reserved or strongly encouraged for specific functionalities to maintain a uniform user experience.
Input and Property Handling
Cmdlets that process data typically use InputObject for pipeline input and Property for selecting specific data members.
- InputObject: Used for accepting objects from the pipeline. Often typed as
PSObjector a specific class type. - Property: Used for selecting specific properties of an object, often allowing wildcards.
Sources: src/Microsoft.PowerShell.Commands.Utility/commands/utility/ConvertTo-Html.cs:33-72, src/System.Management.Automation/engine/GetCommandCommand.cs:64-106
Standard Filtering Parameters
Cmdlets that perform searches or lookups, such as Get-Command or Get-Help, use a consistent set of filtering parameters:
| Parameter | Purpose | Type |
|---|---|---|
Name | Primary identifier or search pattern. | string[] |
Verb | Filter by cmdlet verb (e.g., Get, Set). | string[] |
Noun | Filter by cmdlet noun. | string[] |
Module | Filter by the source module or PSSnapin. | string[] |
Category | Filter by help category (Alias, Cmdlet, etc.). | string[] |
Sources: src/System.Management.Automation/engine/GetCommandCommand.cs:64-142, src/System.Management.Automation/help/HelpCommands.cs:51-85
Cmdletization and CIM Parameter Mapping
When generating PowerShell wrappers for CIM (Common Information Model) objects, the ScriptWriter component maps CIM properties to PowerShell parameters using specific logic to handle naming conflicts and positional requirements.
Mapping Logic
The system attempts to use the original property name but allows for overrides via PSName metadata.
Parameter Set Suffixes
In complex generated cmdlets (CDXML), parameter sets are often generated by combining names to ensure uniqueness.
- InputObjectQueryParameterSetName: Used when filtering is applied directly to an input object.
- SingleQueryParameterSetName: Used for standard query-based operations.
Sources: src/System.Management.Automation/cimSupport/cmdletization/ScriptWriter.cs:412-421, src/System.Management.Automation/cimSupport/cmdletization/ScriptWriter.cs:916-917
Parameter Aliasing and Attributes
PowerShell allows parameters to have one or more aliases, which are often shorter versions of the name or names that maintain backward compatibility.
Alias Implementation
Aliases are defined using the [Alias()] attribute in C# or discovered via AliasAttribute metadata in assemblies.
[Parameter(ParameterSetName = "Page")]
[Alias("cu", "uri")]
public Uri CssUri { get; set; }
Sources: src/Microsoft.PowerShell.Commands.Utility/commands/utility/ConvertTo-Html.cs:157-172, src/System.Management.Automation/engine/InitialSessionState.cs:1754-1780
Validation and Transformation Attributes
Parameter naming is often accompanied by attributes that define how the parameter behaves:
- AllowNull / AllowEmptyString: Permits null or empty values despite type constraints.
- ValidateNotNullOrEmpty: Ensures the parameter name is not passed with an empty value.
- SupportsWildcards: Indicates the parameter name can accept globbing patterns (e.g.,
*,?).
Sources: src/System.Management.Automation/help/HelpCommentsParser.cs:228-235, src/System.Management.Automation/cimSupport/cmdletization/ScriptWriter.cs:530-580
Internal and Special Variables
The system pre-defines "Built-In" variables and aliases in the InitialSessionState. These follow a specific naming scheme often prefixed with PS for engine-controlled values.
- Special Variables:
PSStyle,OutputEncoding,ErrorActionPreference,ConfirmPreference. - System Aliases: Shorthand for common cmdlets like
foreach(forForEach-Object) and?(forWhere-Object).
Sources: src/System.Management.Automation/engine/InitialSessionState.cs:1226-1300, src/System.Management.Automation/engine/InitialSessionState.cs:1410-1430
Conclusion
Parameter naming conventions in PowerShell are enforced through a robust metadata architecture. Whether defined in C#, PowerShell scripts, or generated from CIM schemas, the use of standard names like InputObject, consistent aliasing, and validation attributes ensures that the shell remains predictable and discoverable for users and developers alike.