Formatting object output in PowerShell with Format.ps1xml files

PowerShell uses Format.ps1xml files to set the default display of objects to the console, and you can create or change your own Format.ps1xml files for your own object types. This article will provide background on how PowerShell uses Format.ps1xml files and how to define your own custom format file.

PowerShell is a type-based system. It assigns a type to constructs like variables, expressions, functions, or modules, which provides a set of rules. Types help display information, but a normal object doesn't know how to display itself. To resolve this, PowerShell uses something called the Extended Type System (ETS). The ETS gives the ability to add additional dynamic members to types and objects. The ETS area we're looking at in this article is formatting the displayed output.

The PowerShell install directory stores default formatting database files. PowerShell provides an automatic variable for this directory called $PSHOME. The format files have a .ps1xml extension. These formatting files only change the way of displaying the objects to the host and don't affect the object or how it works within PowerShell.

To take a look at the files included, type:

The filenames are pretty clear on areas of objects they are formatting. The format files are below with a brief description from the MSDN:

  • Format.ps1xml: Objects in the certificate store, such as X.509 certificates and other certificates
  • Format.ps1xml: Other .NET Framework types, such as CultureInfo, FileVersionInfo, and EventLogEntry objects
  • Format.ps1xml: File system objects, such as files and directories
  • Format.ps1xml: Help views, such as detailed and full views, parameters, and examples
  • format.ps1xml: Objects PowerShell core cmdlets generate, such as those from Get-Member and Get-History
  • format.ps1xml: Trace objects, such as those the Trace-Command cmdlet generates
  • format.ps1xml: Registry objects, such as keys and entries

Creating a Format.ps1xml file ^

We now have a clearer understanding on how PowerShell uses Format.ps1xml files to display objects, but let me reinforce this with an example.

Using Get-Service, add the service name BITS and view the output:

Viewing the output from Get Service

Viewing the output from Get Service

This returns three columns from the host: Status, Name, and DisplayName. Run the command again, but capture the output to a variable:

We can use a hidden member called psbase to display the "raw" object behind the object PowerShell exposes by default:

Exposing the raw object

Exposing the raw object

You can see the return exposes more objects with values. I can see a couple of useful properties I'd like to add to the default output for Get-Service, but how?

First, we need to establish the output type for Get-Service. With the type name, we can look for the default layout in the Format.ps1xml file. Get-Command is one way you can find this out:

The output type for Get Service

The output type for Get Service

Running Get-Command on Get-Service shows the output type is System.ServiceProcess.ServiceController.

I can use Select-String to find this type in the Format.ps1xml files:

Using select string to find the type

Using select string to find the type

Select-String found the System.ServiceProcess.ServiceController type in the DotNetTypes.format.ps1xml file. We are not going to edit this file but copy the XML code into a new file to load. I recommend not changing any files inside the PowerShell installation directory.

On line 773 of the DotNetTypes.format.ps1xml file, we can see the details defining the output to the host from the <view> tag down to the closing </view> tag. Copy this XML code (including both tags) into a text file.

When creating your own custom format file, you need to add some tags to the start and end of the XML. For the start of our XML file, add <?xml version="1.0" encoding="utf-8" ?>, <Configuration>, and <ViewDefinitions> tags, and to close, add </ViewDefinitions> and </Configuration> tags.

Next, we need to add our additional XML for the extra properties. Here is the part we're interested in:

In this excerpt, I have added two new TableColumnHeaders and TableColumnItems. Between the TableColumnHeader tags, you need to define the column width like so:

This time, between the TableColumnItem tags, add the property of the object you want to return inside PropertyName tags:

I'll add the fully completed XML to the bottom of the article. Save your text file with a pattern similar to the original files, in the installation directory ($PSHOME). I've called mine CustomServices.Format.ps1xml.

Loading your custom format file ^

PowerShell gives you a cmdlet to load your custom format file into the current open session. The cmdlet to use is Update-FormatData. We simply add our filename to the PrependPath parameter to load it:

To see our new Get-Service format, run the cmdlet again. I've used BITS again for brevity:

Viewing GetService after applying a custom format file

Viewing GetService after applying a custom format file

You can now see the two extra columns MachineName and StartType, now part of my default display for the System.ServiceProcess.ServiceController type. Closing the session and restarting will revert to the original default settings. If you want to have this default standard when you open a PowerShell console, you'll need to add it to your profile.

PowerShell provides all the tools to customize your console environment. Adding your own custom format can become even more useful when you're creating your own types for scripts or functions. If you have several functions with a custom format file, you can create a module with a module manifest. On loading this, the module will automatically add your custom format file to the session. This will make your automation tools look even more polished.

Join the 4sysops PowerShell group!

Your question was not answered? Ask in the forum!


Leave a reply

Your email address will not be published. Required fields are marked *


© 4sysops 2006 - 2020


Please ask IT administration questions in the forums. Any other messages are welcome.


Log in with your credentials


Forgot your details?

Create Account