Management Cmdlets
Relevant source files
The following files were used as context for generating this wiki page:
- src/System.Management.Automation/engine/InitialSessionState.cs
- src/System.Management.Automation/engine/GetCommandCommand.cs
- src/System.Management.Automation/engine/Modules/ModuleCmdletBase.cs
- src/System.Management.Automation/engine/CommandMetadata.cs
- src/System.Management.Automation/engine/remoting/commands/NewPSSessionConfigurationFile.cs
- src/System.Management.Automation/cimSupport/cmdletization/ScriptWriter.cs
Management Cmdlets represent a core category of PowerShell functionality responsible for managing system resources, session states, and the lifecycle of commands and modules. These cmdlets facilitate the discovery of commands, the configuration of session environments, and the administration of local or remote system components through a standardized cmdlet framework.
The management infrastructure is built upon the System.Management.Automation namespace, utilizing metadata-driven discovery and execution models. This system ensures that management tasks are performed consistently across different platforms (Windows, Linux, macOS) by abstracting low-level system calls into high-level PowerShell commands.
Command Discovery and Metadata
The discovery of management commands is handled primarily by the Get-Command cmdlet, which interfaces with the CommandDiscovery and CommandSearcher APIs. This system allows users to find cmdlets, functions, filters, and aliases based on verbs, nouns, or specific module associations.
Architecture of Get-Command
The discovery logic employs fuzzy matching, abbreviation expansion, and wildcard pattern matching to locate commands within the current session or available modules on the system path.
The architecture leverages CommandInfo objects (like CmdletInfo or FunctionInfo) to return structured metadata about the discovered commands.
Sources: src/System.Management.Automation/engine/GetCommandCommand.cs:17-45, src/System.Management.Automation/engine/GetCommandCommand.cs:510-530
Command Metadata Structure
Management cmdlets are defined by metadata that specifies their behavior, such as support for ShouldProcess, impact levels, and parameter sets.
| Metadata Property | Description |
|---|---|
SupportsShouldProcess | Indicates if the cmdlet supports -WhatIf and -Confirm. |
ConfirmImpact | Defines the destructiveness (Low, Medium, High). |
DefaultParameterSetName | The parameter set used when no specific set is identified. |
RemotingCapability | Specifies if the command supports ambient or explicit remoting. |
Sources: src/System.Management.Automation/engine/CommandMetadata.cs:255-290
Session and State Management
Management of the PowerShell environment is centered around the InitialSessionState class. This defines the set of variables, aliases, functions, and modules available when a runspace is created.
InitialSessionState Components
The management framework uses a collection-based model to populate the session environment.
This hierarchy allows the management system to enforce restricted sessions for security purposes, such as in Just Enough Administration (JEA) scenarios.
Sources: src/System.Management.Automation/engine/InitialSessionState.cs:88-120, src/System.Management.Automation/engine/InitialSessionState.cs:1130-1160
Restricted Session Creation
The management infrastructure can create restricted sessions that expose only a minimal subset of commands required for proxying or remote management.
Module Lifecycle Management
Management cmdlets such as Import-Module and Remove-Module are derived from ModuleCmdletBase. This base class provides the logic for path resolution, version checking, and manifest processing.
Module Loading Logic
The system searches for modules using the PSModulePath and handles various file extensions, including .psd1 (Manifest), .psm1 (Script), and .dll (Binary).
- Manifest Processing: Validates members like
RootModule,ModuleVersion, andRequiredModules. - Side-by-Side Support: Allows loading specific versions of a module from versioned subfolders.
- Windows Compatibility: Uses the
WinPSCompatSessionto load modules that require Windows PowerShell in a background process.
Sources: src/System.Management.Automation/engine/Modules/ModuleCmdletBase.cs:200-240, src/System.Management.Automation/engine/Modules/ModuleCmdletBase.cs:1570-1600
Module Manifest Fields
The following table describes key management fields found in module manifests (.psd1):
| Field | Purpose |
|---|---|
RootModule | The main implementation file (script or binary). |
NestedModules | Modules or scripts to load into the module's session state. |
RequiredModules | External modules that must be loaded prior to this module. |
FunctionsToExport | Specifies which functions are visible to the user. |
CompatiblePSEditions | Restricts loading to specific editions (e.g., Desktop, Core). |
Sources: src/System.Management.Automation/engine/Modules/ModuleCmdletBase.cs:135-165
Cmdletization and C# Code Generation
A specialized management feature allows generating PowerShell modules from XML definitions, often used for CIM (Common Information Model) or REST wrappers. This is handled by the ScriptWriter class.
Logic Flow for Cmdlet Generation
The ScriptWriter reads metadata from a CDXML file and produces a .psm1 file containing proxy functions that map to an underlying object model.
Remoting and Session Configuration
The management of remote sessions involves creating configuration files (.pssc) and role capability files (.psrc). These files define the environment of a PSSession.
Session Configuration Keys
The New-PSSessionConfigurationFile cmdlet allows administrators to define the boundaries of a remote endpoint.
| Key | Description |
|---|---|
SessionType | Defines if the session is Restricted, Default, or Empty. |
TranscriptDirectory | Path where all session activities are logged. |
RoleDefinitions | Maps users/groups to specific Role Capability files. |
RunAsVirtualAccount | Specifies if the session runs under a temporary local admin account. |
Sources: src/System.Management.Automation/engine/remoting/commands/NewPSSessionConfigurationFile.cs:400-450
Summary
Management Cmdlets provide the essential tools for discovering, configuring, and maintaining the PowerShell ecosystem. Through classes like ModuleCmdletBase and InitialSessionState, the system ensures a consistent administrative experience while providing the necessary hooks for security restrictions and cross-platform compatibility. The integration of metadata-driven command discovery and automated script generation for CIM/REST allows for a highly extensible management platform.