Formatting Cmdlet Output

Windows PowerShell provides several ways to specify how the objects returned by a cmdlet are displayed at the command line. You can use cmdlets to specify the display format within a command, you can call APIs from within your cmdlets to specify a specific display, and you can define formatting files that Windows PowerShell will use each time a specific .NET Framework object is returned.

rs of the object and You can use cmdlets to uses XML-based files to define how the output objects of cmdlets are displayed. Objects can be displayed as a table or a list. You can use the default formatting files provided by Windows PowerShell or you can create your own formatting files. Creating your own formatting files allow you to change the default display of existing objects or define how new objects are displayed.

Note:
Formatting files define only how objects are displayed, they do not define the object itself. For more information about extending an existing object programmatically, see Extending Objects Used by Cmdlets. For more information about extending an existing objects at the command line, see the Add-Member object.

Formatting files use the following naming convention: MyFile.Format.psm1xml.

Windows PowerShell Formatting Cmdlets

The following cmdlets can accept an object from another cmdlet and display that object in a specific format.

Format-List

Format-Table

Format-Wide

Format-Custom

Out-GridView

Default Formatting Files

The following formatting files are provided by Windows PowerShell, and can be found in the Windows PowerShell installation folder. You must never change these file, as that can interfere with the correct operation of the product.

Certificate.Format.ps1xml: Defines the display of the objects in the Certificate store, such as objects for X.509 certificates and certificate stores.

DotNetTypes.Format.ps1xml: Defines the display of .NET Framework types, such as CultureInfo, FileVersionInfo, and EventLogEntry objects.

FileSystem.Format.ps1xml: Defines the display of file system objects, such as objects for files and directories.

Help.Format.ps1xml: Defines the views used to display the command line Help topics for Cmdlets, such as displaying the detailed or full views of the Import-Module cmdlet.

PowerShellCore.format.ps1xml: Defines the display of the objects generated by the Windows PowerShell core cmdlets, such as the output objects of the Get-Command and Get-History cmdlets.

PowerShellTrace.format.ps1xml: Defines the display of trace objects, such as the output object of the Trace-Command cmdlet.

Registry.format.ps1xml: Defines the display of registry objects, such as objects for registry keys and entries.

Custom Formatting Files

This section describes what you need to know to create a custom formatting file, such as defining different views of an object and where you should install your formatting file. As stated previously, custom formatting files allow you to change the default display of existing objects or define how new objects are displayed. To look at a sample format file, see Table View Example.

Object Views

A formatting file can define four different views of each object: table, list, wide, and complex. For example, the Format-List cmdlet uses the list view defined in the FileSystem.format.ps1xml formatting file to determine how to display the file and folder objects as a list.

In a formatting file, a view is defined by a set of XML tags that describe the name of the view, the type of object to which the view can be applied, the column headers that are displayed, and the properties that are displayed in the body of the view. The format in the formatting file is applied to the object just before the data is presented to the user.

Formatting File Locations

As stated previously, the formatting files provided by Windows PowerShell can be found in the Windows PowerShell installation folder. You can add your own formatting files there if you are using snap-ins to register your cmdlets and providers, or you can place them in a module folder if you are using a module manifest to import your cmdlets and providers. The recommender solution for adding cmdlets and providers, as well as other resources, is through the use of a module manifest.

Prepare a Formatting File

The first thing you need to do is to create a formatting file.

Create a YourProductName.Format.ps1xml file in the same directory as your types file.
Open the file and create the root Configuration node, using the <Configuration></Configuration>delimiters.
Create a ViewDefinitions node using the using the <ViewDefinitions></ViewDefinitions>delimiters.
Customize the ViewDefinitions node as required, adding a View node for each object. The term "display view" refers to how the data of an object is displayed.

Define the Display View Basics

The View node defines how the object data is displayed by the host application (the default hosting application is powershell.exe).

In the Name node, specify a name for the display view, using the <Name></Name> delimiters.
In the ViewSelectedBy node, reference the .NET objects to which this display view applies.
In the GroupBy node, specify how you want Windows PowerShell to group the objects. For example, a directory listing is grouped by its parent. Each grouping needs a header, as defined by a control node, such as a TableControl node. The header is most relevant when the user performs a recursive directory listing.

Define the Columns of the Display View

The TableControl node defines the columns of the display view. You must define the headers that the column will use and the type of data that is displayed in the rows.

In the TableControl node, specify a TableHeaders and TableRowEntries node using the using the <TableHeaders></TableHeaders> and <TableRowEntries></TableRowsEntries> delimiters.

The follow example defines two columns for the view.
```
<TableControl>
  <TableHeaders>
    ...
  </TableHeaders>
  <TableRowEntries>
    ...
  </TableRowEntries>
</TableControl>
```
In the TableHeaders node, specify a TableColumnHeader node for each column using the <TableColumnHeader></TableColumnHeader> delimiters.

In each TableColumnHeader node, specify a label, width, and alignment setting for the column. Use the <Label></Label>, <Width></Width>, and <Alignment></Alignment> delimiters for these values.

The follow example defines two columns for the view.
```
<TableHeaders>
  <TableColumnHeader>
    <Label>Column 1</Label>
    <Width>10</Width>
    <Alignment>Left</Alignment>
  </TableColumnHeader>
  <TableColumnHeader>
    <Label>Column 2</Label>
    <Width>10</Width>
    <Alignment>Left</Alignment>
  </TableColumnHeader>
</TableHeaders>
```
In the TableRowEntries node, specify a TableRowEntry node for each column using the <TableRowEntry></TableRowEntry> delimiters. Row entries refer either to a direct property of the object, or to a ScriptBlock node. The ScriptBlock node references the current pipeline object using the "$_" automatic variable.

The following example defines an object property for the first column of the view and a script block for the second column of the view.
```
<TableRowEntries>
  <TableRowEntry>
    <TableColumnItems>
      <TableColumnItem>
        <PropertyName>ObjectPropertyName</PropertyName>
      </TableColumnItem>
      <TableColumnItem>
           <ScriptBlock>
             [int]($_.NonpagedSystemMemorySize /1024)
           </ScriptBlock>
      </TableColumnItem>
    </TableColumnItems>
  </TableRowEntry>
</TableRowEntries>
```

Load and Test the New Formatting

When Windows PowerShell loads its formatting data, the first file to define a view is loaded first. To allow your new object formatting to load, enter the following on the command line.

$formatFile = "$(parse-path $profile)\YourProductName.Format.ps1xml"
update-FormatData -prependpath $formatFile

To verify your object formatting, try several command-line entries as a test. Here is an example testing the sample format file described in Table View Example.

PS> get-process | select-object -first 5
Handles  NPM(K)    PM(K)      WS(K) VS(M)   CPU(s)     Id ProcessName
-------  ------    -----      ----- -----   ------     -- -----------
    271       6     1244       3700    33     0.05   2212 alg
     58       2      420       1904    18     0.17    744 ati2evxx
     69       2      476       2072    19     0.78   3152 ati2evxx
     50       3     2208       4256    42     0.09    440 BTTray
     38       2      420       1600    17     0.02   1744 btwdins