Utility Cmdlets
Relevant source files
The following files were used as context for generating this wiki page:
- src/System.Management.Automation/engine/GetCommandCommand.cs
- src/Microsoft.PowerShell.Commands.Utility/commands/utility/ConvertTo-Html.cs
- src/System.Management.Automation/engine/InitialSessionState.cs
- src/System.Management.Automation/engine/Modules/NewModuleManifestCommand.cs
- src/System.Management.Automation/help/HelpCommentsParser.cs
- src/System.Management.Automation/engine/remoting/commands/NewPSSessionConfigurationFile.cs
- src/System.Management.Automation/engine/ProxyCommand.cs
Utility cmdlets in PowerShell provide essential functionality for data manipulation, system discovery, and environmental configuration. These cmdlets facilitate the conversion of structured data into human-readable formats, the management of session states, and the dynamic discovery of commands within the engine. They serve as the bridging layer between raw object data and usable administrative output.
The architecture of utility cmdlets typically follows the PSCmdlet or Cmdlet base classes, leveraging the PowerShell engine's internal providers for navigation and state management. Key systems include command discovery engines, metadata parsers for help and manifests, and formatting engines for output rendering. Sources: README.md:6-10, src/System.Management.Automation/engine/GetCommandCommand.cs:22-25
Command Discovery and Metadata
The discovery of commands is a primary utility function handled by the Get-Command cmdlet. This system identifies aliases, functions, filters, and cmdlets available in the current session or within installed modules. It utilizes a CommandSearcher to traverse the CommandDiscovery layer, supporting advanced filtering based on nouns, verbs, and module origins.
Discovery Logic and Filtering
The discovery process supports fuzzy matching and abbreviation expansion (e.g., g-ps matching Get-Process). It also filters commands by parameter names or parameter types to help developers find specific functionality.
The diagram shows the logical flow of how Get-Command resolves command requests through session scopes and module tables. Sources: src/System.Management.Automation/engine/GetCommandCommand.cs:338-380, src/System.Management.Automation/engine/GetCommandCommand.cs:646-680
Key Discovery Parameters
| Parameter | Type | Description |
|---|---|---|
Name | string[] | Specific name or wildcard pattern of commands to retrieve. |
CommandType | CommandTypes | Filters by Alias, Function, Filter, Cmdlet, or ExternalScript. |
UseFuzzyMatching | SwitchParameter | Enables searching for similar command names using Levenshtein distance. |
UseAbbreviationExpansion | SwitchParameter | Matches uppercase characters for noun abbreviation expansion. |
Sources: src/System.Management.Automation/engine/GetCommandCommand.cs:33-145
Data Rendering and Conversion
Utility cmdlets include robust data conversion tools, such as ConvertTo-Html, which transform .NET objects into structured markup. This process involves resolving object properties through PSPropertyExpression and applying formatting metadata.
HTML Conversion Architecture
The conversion utility supports both full page generation and HTML fragments. It processes incoming InputObject values from the pipeline, resolving wildcards in property lists to build HTML tables or lists.
This sequence illustrates how object properties are resolved and converted into HTML elements during pipeline processing. Sources: src/Microsoft.PowerShell.Commands.Utility/commands/utility/ConvertTo-Html.cs:496-545
Session and Environment Management
The utility layer manages the initialization of PowerShell sessions through declarative Initial Session States (ISS). This defines the baseline of available aliases and functions that provide the "standard library" of PowerShell.
Built-in Utility Aliases
The session initialization logic maps common utility commands to short-form aliases to improve terminal productivity.
| Alias | Definition | Description |
|---|---|---|
foreach | ForEach-Object | Pipeline iteration utility. |
where | Where-Object | Pipeline filtering utility. |
select | Select-Object | Property selection and object filtering. |
cls / clear | Clear-Host | Terminal screen buffer reset. |
md | mkdir | Directory creation wrapper. |
Sources: src/System.Management.Automation/engine/InitialSessionState.cs:1754-1830
Module Manifest Authoring
The New-ModuleManifest cmdlet is a management utility that generates .psd1 files. It strictly validates paths and exports, ensuring that module metadata (GUIDs, Versions, Required Modules) is correctly serialized for the engine's module loader. Sources: src/System.Management.Automation/engine/Modules/NewModuleManifestCommand.cs:720-760
Help and Metadata Parsing
Utility systems include specialized parsers for documentation and metadata. The HelpCommentsParser converts comment-based help within scripts and functions into XML-based HelpInfo objects using MAML (Microsoft Assistance Markup Language) schemas.
The parsing logic identifies specific directives within comment tokens to reconstruct structured documentation. Sources: src/System.Management.Automation/help/HelpCommentsParser.cs:150-200, src/System.Management.Automation/help/HelpCommentsParser.cs:510-550
Proxy Command Generation
The ProxyCommand utility provides an API for dynamically constructing "wrapper" functions. This is used extensively in implicit remoting and constrained endpoints to expose cmdlets with restricted parameter sets or modified behaviors.
Implementation Details
The utility uses CommandMetadata to generate the necessary script blocks for a proxy.
- Param Block: Reconstructs the exact parameter definitions of the source command.
- Steppable Pipeline: Creates a wrapper that can forward pipeline objects to the underlying command.
- Help Comments: Extracts synopsis and description from the source command's help to populate the proxy's help.
Sources: src/System.Management.Automation/engine/ProxyCommand.cs:40-100, src/System.Management.Automation/engine/ProxyCommand.cs:336-360
Summary of Utility Components
The utility system is characterized by its ability to handle cross-cutting concerns that apply to all object types in the PowerShell ecosystem.
| Component | Functionality | Primary Source |
|---|---|---|
| Discovery | Locating and scoring command matches. | GetCommandCommand.cs |
| Conversion | Transforming objects to HTML/JSON/Text. | ConvertTo-Html.cs |
| Parsing | Turning raw comments into structured Help. | HelpCommentsParser.cs |
| State | Defining initial aliases and variables. | InitialSessionState.cs |
| Manifests | Authoring module configuration metadata. | NewModuleManifestCommand.cs |
Utility cmdlets ensure that the PowerShell environment remains introspective and that data is easily portable between different formats and administrative scopes. Sources: src/System.Management.Automation/engine/GetCommandCommand.cs:22, src/System.Management.Automation/engine/InitialSessionState.cs:88, src/Microsoft.PowerShell.Commands.Utility/commands/utility/ConvertTo-Html.cs:22