Formatting & Output System
Relevant source files
The following files were used as context for generating this wiki page:
- src/System.Management.Automation/FormatAndOutput/common/FormatXMLWriter.cs
- src/System.Management.Automation/FormatAndOutput/common/FormattingObjects.cs
- src/System.Management.Automation/FormatAndOutput/common/ComplexWriter.cs
- src/System.Management.Automation/FormatAndOutput/common/PSStyle.cs
- src/Microsoft.PowerShell.Commands.Utility/commands/utility/FormatAndOutput/common/GetFormatDataCommand.cs
- src/System.Management.Automation/FormatAndOutput/DefaultFormatters/PowerShellCore_format_ps1xml.cs
The Formatting & Output System is a core engine component responsible for transforming complex .NET objects into human-readable visual representations. It abstracts the rendering logic from the data, allowing PowerShell to provide consistent views (Tables, Lists, Wide, and Custom) across various hosting environments and output devices.
The system relies on a metadata-driven architecture where formatting directives are defined in XML (.ps1xml) files or programmatically via Extended Type Definitions. This separation ensures that the core logic of a cmdlet remains focused on data processing, while the display logic is handled by specialized formatting commands and outputters.
Core Architecture and Components
The system is structured around a sequence of data transformations involving metadata lookup, formatting object generation, and final rendering.
Formatting Data Management
Formatting directives are stored in a database accessed via Get-FormatData. These directives map .NET types to specific visual controls.
Sources: GetFormatDataCommand.cs:17-25, PowerShellCore_format_ps1xml.cs:12-20
Visual Control Types
The system supports four primary control types for rendering objects:
- TableControl: Displays data in a grid with aligned columns and headers.
- ListControl: Displays data as a sequence of label-value pairs.
- WideControl: Displays a single property in multiple columns across the screen.
- CustomControl: Allows for complex, nested, and frame-based formatting using a specialized formatting language.
Sources: FormatXMLWriter.cs:152, FormatXMLWriter.cs:214, FormatXMLWriter.cs:266, FormatXMLWriter.cs:313
The Formatting Protocol
Communication between formatting cmdlets (e.g., Format-Table) and output cmdlets (e.g., Out-Host) occurs through a specialized protocol of formatting objects. These objects preserve type information and formatting state even across serialization boundaries.
Sources: FormattingObjects.cs:1-30
This diagram illustrates the lifecycle of an object as it passes through the formatting system, resulting in specific formatting data packets.
Formatting Objects and Data Flow
The formatting system communicates using a hierarchy of classes derived from FormatInfoData. Every packet sent to the outputter contains a ClassId (GUID) to preserve type integrity during serialization.
Top-Level Message Packets
| Class | Description | CLSID |
|---|---|---|
FormatStartData | Sent at the beginning of a formatting sequence; contains headers and autosize info. | 033ecb2bc07a4d43b5ef94ed5a35d280 |
FormatEntryData | Contains the actual payload and specific formatting instructions for an object. | 27c87ef9bbda4f709f6b4002fa4af63c |
GroupStartData | Marks the beginning of a grouped set of objects. | 9e210fe47d09416682b841769c78b8a3 |
FormatEndData | Signifies the end of the formatting sequence. | cf522b78d86c486691226b40aa69e95c |
| Sources: FormattingObjects.cs:64-118 |
Complex Rendering Logic
The ComplexWriter handles the heavy lifting for Custom views. It manages an IndentationManager to track nested frames and performs word-wrapping based on the current culture.
Sources: ComplexWriter.cs:22-55, ComplexWriter.cs:337-345
The sequence of operations within the ComplexWriter demonstrates how nested indentations are managed during the rendering process.
Styling and ANSI Rendering
Modern PowerShell formatting incorporates ANSI escape sequences for rich text rendering, controlled by the PSStyle singleton.
PSStyle Components
PSStyle provides a centralized configuration for:
- Foreground/Background Colors: Standards and RGB values.
- Formatting Data: Accents for headers, errors, warnings, and verbose streams.
- FileInfo Formatting: Specific colors based on file extensions or attributes (e.g., directories vs. symbolic links).
Sources: PSStyle.cs:46, PSStyle.cs:222, PSStyle.cs:319
Output Rendering Modes
The system supports three rendering modes defined in the OutputRendering enum:
- Host: Renders ANSI sequences only if the host supports them.
- PlainText: Strips all ANSI escape sequences.
- Ansi: Forces ANSI sequence rendering.
Sources: PSStyle.cs:13-24
XML Formatting Definitions
Formatting is primarily persisted in ps1xml files. The FormatXmlWriter class provides the logic to serialize ExtendedTypeDefinition objects back into this XML format.
Supported XML Structures
- ViewDefinitions: The root container for all views.
- ViewSelectedBy: Defines which .NET types trigger a specific view.
- GroupBy: Logic for partitioning objects based on a property or script block.
- Control Implementation: Specific XML nodes for
TableControl,ListControl,WideControl, andCustomControl.
Sources: FormatXMLWriter.cs:100-140
This class diagram shows the inheritance hierarchy of formatting packets used to transmit rendering data.
Conclusion
The PowerShell Formatting & Output System is a sophisticated metadata-driven framework. By utilizing a packet-based communication protocol (FormatInfoData) and a flexible rendering engine (ComplexWriter), it ensures that objects are displayed optimally regardless of their underlying complexity. Integration with PSStyle further allows the system to adapt to modern terminal capabilities like Virtual Terminal/ANSI support while maintaining backward compatibility for plain-text environments.