about_Format.ps1xml

Άρθρο
12/13/2022

Short description

Beginning in PowerShell 6, the default views for objects are defined in PowerShell source code.

You can create your own Format.ps1xml files to change the display of objects or to define default displays for new object types that you create in PowerShell.

Long description

Beginning in PowerShell 6, the default views are defined in PowerShell source code. The Format.ps1xml files from PowerShell 5.1 and earlier versions don't exist in PowerShell 6 and later versions.

The PowerShell source code defines the default display of objects in the PowerShell console. You can create your own Format.ps1xml files to change the display of objects or to define default displays for new object types that you create in PowerShell.

When PowerShell displays an object, it uses the data in structured formatting files to determine the default display of the object. The data in the formatting files determines whether the object is rendered in a table or in a list, and it determines which properties are displayed by default.

The formatting affects the display only. It doesn't affect which object properties are passed down the pipeline or how they're passed. Format.ps1xml files can't be used to customize the output format for hash tables.

A .ps1xml formatting file can define four different views of each object:

Table
List
Wide
Custom

For example, when the output of a Get-ChildItem command is piped to a Format-List command, Format-List uses the list view defined in the source code to determine how to display the file and folder objects as a list.

When a formatting file includes more than one view of an object, PowerShell applies the first view that it finds.

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

Creating new Format.ps1xml files

To change the display format of an existing object view, or to add views for new objects, create your own Format.ps1xml files, and then add them to your PowerShell session.

To create a Format.ps1xml file to define a custom view, use the Get-FormatData and Export-FormatData cmdlets. Use a text editor to edit the file. The file can be saved to any directory that PowerShell can access, such as a subdirectory of $HOME.

To change the formatting of a current view, locate the view in the formatting file, and then use the tags to change the view. To create a view for a new object type, create a new view, or use an existing view as a model. The tags are described in the next section. You can then delete all the other views in the file so that the changes are obvious to anyone examining the file.

After you save the changes, use the Update-FormatData to add the new file to your PowerShell session. If you want your view to take precedence over a view defined in the built-in files, use the PrependPath parameter. Update-FormatData affects only the current session. To make the change to all future sessions, add the Update-FormatData command to your PowerShell profile.

Example: Add calendar data to culture objects

This example shows how to change the formatting of the culture objects System.Globalization.CultureInfo generated by the Get-Culture cmdlet in the current PowerShell session. The commands in the example add the Calendar property to the default table view display of culture objects.

To begin, get the format data from the source code file and create a Format.ps1xml file that contains the current view of the culture objects.

Get-FormatData -TypeName System.Globalization.CultureInfo |
  Export-FormatData -Path $HOME\Format\CultureInfo.Format.ps1xml

Open the CultureInfo.Format.ps1xml file in any XML or text editor, such as Visual Studio Code. The following XML defines the views of the CultureInfo object.

The CultureInfo.Format.ps1xml file should look like the following sample:

<?xml version="1.0" encoding="utf-8"?>
<Configuration>
  <ViewDefinitions>
    <View>
      <Name>System.Globalization.CultureInfo</Name>
      <ViewSelectedBy>
        <TypeName>System.Globalization.CultureInfo</TypeName>
      </ViewSelectedBy>
      <TableControl>
        <TableHeaders>
          <TableColumnHeader>
            <Width>16</Width>
          </TableColumnHeader>
          <TableColumnHeader>
            <Width>16</Width>
          </TableColumnHeader>
          <TableColumnHeader />
        </TableHeaders>
        <TableRowEntries>
          <TableRowEntry>
            <TableColumnItems>
              <TableColumnItem>
                <PropertyName>LCID</PropertyName>
              </TableColumnItem>
              <TableColumnItem>
                <PropertyName>Name</PropertyName>
              </TableColumnItem>
              <TableColumnItem>
                <PropertyName>DisplayName</PropertyName>
              </TableColumnItem>
            </TableColumnItems>
          </TableRowEntry>
        </TableRowEntries>
      </TableControl>
    </View>
  </ViewDefinitions>
</Configuration>

Create a new column for the Calendar property by adding a new set of <TableColumnHeader> tags. The value of the Calendar property can be long, so specify a value of 45 characters as the <Width>.

<TableHeaders>
  <TableColumnHeader>
    <Width>16</Width>
  </TableColumnHeader>
  <TableColumnHeader>
    <Width>16</Width>
  </TableColumnHeader>
  <TableColumnHeader>
    <Width>45</Width>
  </TableColumnHeader>
  <TableColumnHeader/>
</TableHeaders>

Add a new column item for Calendar in the table rows using the <TableColumnItem> and <PropertyName tags:

<TableRowEntries>
  <TableRowEntry>
    <TableColumnItems>
      <TableColumnItem>
        <PropertyName>LCID</PropertyName>
      </TableColumnItem>
      <TableColumnItem>
        <PropertyName>Name</PropertyName>
      </TableColumnItem>
      <TableColumnItem>
        <PropertyName>Calendar</PropertyName>
      </TableColumnItem>
      <TableColumnItem>
        <PropertyName>DisplayName</PropertyName>
      </TableColumnItem>
    </TableColumnItems>
  </TableRowEntry>
</TableRowEntries>

Save and close the file. Use Update-FormatData to add the new format file to the current PowerShell session.

This example uses the PrependPath parameter to place the new file in a higher precedence order than the original file. For more information, see Update-FormatData.

Update-FormatData -PrependPath $HOME\Format\CultureInfo.Format.ps1xml

To test the change, type Get-Culture and review the output that includes the Calendar property.

Get-Culture

LCID  Name   Calendar                                DisplayName
----  ----   --------                                -----------
1033  en-US  System.Globalization.GregorianCalendar  English (United States)

The XML in Format.ps1xml files

The full schema definition can be found in Format.xsd in the PowerShell source code repository on GitHub.

The ViewDefinitions section of each Format.ps1xml file contains the <View> tags that define each view. A typical <View> tag includes the following tags:

<Name> identifies the name of the view.
<ViewSelectedBy> specifies the object type or types to which the view applies.
<GroupBy> specifies how items in the view will be combined in groups.
<TableControl>, <ListControl>, <WideControl>, and <CustomControl> contain the tags that specify how each item will be displayed.

ViewSelectedBy tag

The <ViewSelectedBy> tag can contain a <TypeName> tag for each object type to which the view applies. Or, it can contain a <SelectionSetName> tag that references a selection set that is defined elsewhere by using a <SelectionSet> tag.

GroupBy tag

The <GroupBy> tag contains a <PropertyName> tag that specifies the object property by which items are to be grouped. It also contains either a <Label> tag that specifies a string to be used as a label for each group or a <CustomControlName> tag that references a custom control defined elsewhere using a <Control> tag. The <Control> tag contains a <Name> tag and a <CustomControl> tag.

TableControlTag

The <TableControl> tag typically contains <TableHeaders> and <TableRowEntries> tags that define the formatting for the table's heads and rows. The <TableHeaders> tag typically contains <TableColumnHeader> tags that contain <Label>, <Width>, and <Alignment> tags. The <TableRowEntries> tag contains <TableRowEntry> tags for each row in the table. The <TableRowEntry> tag contains a <TableColumnItems> tag that contains a <TableColumnItem> tag for each column in the row. Typically, the <TableColumnItem> tag contains either a <PropertyName> tag that identifies the object property to be displayed in the defined location, or a <ScriptBlock> tag that contains script code that calculates a result that is to be displayed in the location.

Note

Script blocks can also be used elsewhere in locations where calculated results can be useful.

The <TableColumnItem> tag can also contain a <FormatString> tag that specifies how the property or the calculated results will be displayed.

ListControl tag

The <ListControl> tag typically contains a <ListEntries> tag. The <ListEntries> tag contains a <ListEntry> tag. The <ListEntry> tag contains a <ListItems> tag. The <ListItems> tag contains <ListItem> tags, which contain <PropertyName> tags. The <PropertyName> tags specify the object property to be displayed at the specified location in the list. If the view selection is defined using a selection set, the <ListControl> and <ListEntry> tags can also contain an <EntrySelectedBy> tag that contains one or more <TypeName> tags. These <TypeName> tags specify the object type that the <ListControl> tag is intended to display.

WideControl tag

The <WideControl> tag typically contains a <WideEntries> tag. The <WideEntries> tag contains one or more <WideEntry> tags. A <WideEntry> tag contains one <WideItem> tag.

A <WideItem> tag must include either a <PropertyName> tag or a <ScriptBlock> tag. A <PropertyName> tag specifies the property to display at the specified location in the view. A <ScriptBlock> tag specifies a script to evaluate and display at the specified location in the view.

A <WideItem> tag can contain a <FormatString> tag that specifies how to display the property.

CustomControl tag

The <CustomControl> tag lets you use a script block to define a format. A <CustomControl> tag typically contains a <CustomEntries> tag that contains multiple <CustomEntry> tags. Each <CustomEntry> tag contains a <CustomItem> tag that can contain a variety of tags that specify contents and formatting of the specified location in the view, including <Text>, <Indentation>, <ExpressionBinding>, and <NewLine> tags.

Tracing Format.ps1xml file use

To detect errors in the loading or application of Format.ps1xml files, use the Trace-Command cmdlet with any of the following format components as the value of the Name parameter:

FormatFileLoading
FormatViewBinding

For more information, see Trace-Command and Get-TraceSource.

Signing a Format.ps1xml file

To protect the users of your Format.ps1xml file, sign the file using a digital signature. For more information, see about_Signing.

Sample XML for a Format-Table custom view

The following XML sample creates a Format-Table custom view for the System.IO.DirectoryInfo and System.IO.FileInfo objects created by Get-ChildItem. The custom view is named mygciview and adds the CreationTime column to the table.

To create the custom view, use the Get-FormatData and Export-FormatData cmdlets to generate a .ps1xml file. Then, edit your .ps1xml file to create the code for your custom view. The .ps1xml file can be stored in any directory that PowerShell can access. For example, a subdirectory of $HOME.

After the .ps1xml file is created, use the Update-FormatData cmdlet to include the view in the current PowerShell session. Or, add the update command to your PowerShell profile if you need the view available in all PowerShell sessions.

For this example, the custom view must use the table format, otherwise, Format-Table fails.

Use Format-Table with the View parameter to specify the custom view's name, mygciview, and format the table's output with the CreationTime column. For an example of how the command is run, see Format-Table.