Format-Table

Syntax

Format-Table
      [[-Property] <Object[]>]
      [-AutoSize]
      [-RepeatHeader]
      [-HideTableHeaders]
      [-Wrap]
      [-GroupBy <Object>]
      [-View <string>]
      [-ShowError]
      [-DisplayError]
      [-Force]
      [-Expand <string>]
      [-InputObject <psobject>]
      [<CommonParameters>]

Description

The Format-Table cmdlet formats the output of a command as a table with the selected properties of the object in each column. The object type determines the default layout and properties that are displayed in each column. You can use the Property parameter to select the properties that you want to display.

PowerShell uses default formatters to define how object types are displayed. You can use .ps1xml files to create custom views that display an output table with specified properties. After a custom view is created, use the View parameter to display the table with your custom view. For more information about views, see about_Format.ps1xml .

You can use a hash table to add calculated properties to an object before displaying it and to specify the column headings in the table. To add a calculated property, use the Property or GroupBy parameter. For more information about hash tables, see about_Hash_Tables .

Examples

Example 1: Format PowerShell host

This example displays information about the host program for PowerShell in a table.

Get-Host | Format-Table -AutoSize

The Get-Host cmdlet gets System.Management.Automation.Internal.Host.InternalHost objects that represent the host. The objects are sent down the pipeline to Format-Table and displayed in a table. The AutoSize parameter adjusts the column widths to minimize truncation.

Example 2: Format processes by BasePriority

In this example, processes are displayed in groups that have the same BasePriority property.

Get-Process | Sort-Object -Property BasePriority | Format-Table -GroupBy BasePriority -Wrap

The Get-Process cmdlet gets objects that represent each process on the computer and sends them down the pipeline to Sort-Object . The objects are sorted in the order of their BasePriority property.

The sorted objects are sent down the pipeline to Format-Table . The GroupBy parameter arranges the process data into groups based on their BasePriority property's value. The Wrap parameter ensures that data isn't truncated.

Example 3: Format processes by start date

This example displays information about the processes running on the computer. The objects are sorted and Format-Table uses a view to group the objects by their start date.

Get-Process | Sort-Object StartTime | Format-Table -View StartTime

Get-Process gets the System.Diagnostics.Process objects that represent the processes running on the computer. The objects are sent down the pipeline to Sort-Object , and are sorted based on the StartTime property.

The sorted objects are sent down the pipeline to Format-Table . The View parameter specifies the StartTime view that's defined in the PowerShell DotNetTypes.format.ps1xml file for System.Diagnostics.Process objects. The StartTime view converts each processes start time to a short date and then groups the processes by the start date.

The DotNetTypes.format.ps1xml file contains a Priority view for processes. You can create your own format.ps1xml files with customized views.

Example 4: Use a custom view for table output

In this example, a custom view displays a directory's contents. The custom view adds the CreationTime column to the table output for System.IO.DirectoryInfo and System.IO.FileInfo objects created by Get-ChildItem .

The custom view in this example was created from the view defined in PowerShell source code. For more information about views and the code used to create this example's view, see about_Format.ps1xml .

Get-ChildItem  -Path C:\Test | Format-Table -View mygciview

Directory: C:\Test

Mode                LastWriteTime              CreationTime         Length Name
----                -------------              ------------         ------ ----
d-----        11/4/2019     15:54       9/24/2019     15:54                Archives
d-----        8/27/2019     14:22       8/27/2019     14:22                Drawings
d-----       10/23/2019     09:38       2/25/2019     09:38                Files
-a----        11/7/2019     11:07       11/7/2019     11:07          11345 Alias.txt
-a----        2/27/2019     15:15       2/27/2019     15:15            258 alias_out.txt
-a----        2/27/2019     15:16       2/27/2019     15:16            258 alias_out2.txt

Get-ChildItem gets the contents of the current directory, C:\Test . The System.IO.DirectoryInfo and System.IO.FileInfo objects are sent down the pipeline. Format-Table uses the View parameter to specify the custom view mygciview that includes the CreationTime column.

The default Format-Table output for Get-ChildItem doesn't include the CreationTime column.

Example 5: Use properties for table output

This example uses the Property parameter to display all the computer's services in a two-column table that shows the properties Name and DependentServices .

Get-Service | Format-Table -Property Name, DependentServices

Get-Service gets all the services on the computer and sends the System.ServiceProcess.ServiceController objects down the pipeline. Format-Table uses the Property parameter to specify that the Name and DependentServices properties are displayed in the table.

Name and DependentServices are two of the object type's properties. To view all the properties: Get-Service | Get-Member -MemberType Properties .

Example 6: Format a process and calculate its running time

This example displays a table with the process name and total running time for the local computer's notepad processes. The total running time is calculated by subtracting the start time of each process from the current time.

Get-Process notepad |
  Format-Table ProcessName, @{Label="TotalRunningTime"; Expression={(Get-Date) - $_.StartTime}}

ProcessName TotalRunningTime
----------- ----------------
notepad     03:20:00.2751767
notepad     00:00:16.7710520

Get-Process gets all the local computer's notepad processes and sends the objects down the pipeline. Format-Table displays a table with two columns: ProcessName , a Get-Process property, and TotalRunningTime , a calculated property.

The TotalRunningTime property is specified by a hash table with two keys, Label and Expression . The Label key specifies the property name. The Expression key specifies the calculation. The expression gets the StartTime property of each process object and subtracts it from the result of a Get-Date command, which gets the current date and time.

Example 7: Format Notepad processes

This example uses Get-CimInstance to get the running time for all notepad processes on the local computer. You can use Get-CimInstance with the ComputerName parameter to get information from remote computers.

$Processes = Get-CimInstance -Class win32_process -Filter "name='notepad.exe'"
$Processes | Format-Table ProcessName, @{
    Label = "Total Running Time"
    Expression={(Get-Date) - $_.CreationDate}
}

ProcessName Total Running Time
----------- ------------------
notepad.exe 03:39:39.6260693
notepad.exe 00:19:56.1376922

Get-CimInstance gets instances of the WMI Win32_Process class that describes all the local computer's processes named notepad.exe . The process objects are stored in the $Processes variable.

The process objects in the $Processes variable are sent down the pipeline to Format-Table , which displays the ProcessName property and a new calculated property, Total Running Time .

The command assigns the name of the new calculated property, Total Running Time , to the Label key. The Expression key's script block calculates how long the process has been running by subtracting the processes creation date from the current date. The Get-Date cmdlet gets the current date. The creation date is subtracted from the current date. The result is the value of Total Running Time .

Example 8: Troubleshooting format errors

The following examples show the results of adding the DisplayError or ShowError parameters with an expression.

Get-Date | Format-Table DayOfWeek,{ $_ / $null } -DisplayError

DayOfWeek  $_ / $null
--------- ------------
Wednesday #ERR

Get-Date | Format-Table DayOfWeek,{ $_ / $null } -ShowError

DayOfWeek  $_ / $null
--------- ------------
Wednesday

InvalidArgument: Failed to evaluate expression " $_ / $null ".

Parameters

-AutoSize

-DisplayError

-Expand

-Force

-GroupBy

-HideTableHeaders

-InputObject

-Property

-RepeatHeader

-ShowError

-View

-Wrap

Inputs

PSObject

You can pipe any object to this cmdlet.

Outputs

Microsoft.PowerShell.Commands.Internal.Format

This cmdlet returns format objects that represent the table.

Notes

PowerShell includes the following aliases for Format-Table :

• All platforms:
  • ft

PowerShell 7.2 introduced new features to colorize output. The colors can be managed using the $PSStyle automatic variable. The $PSStyle.Formatting.TableHeader property defines the color used for the header of the table displayed by Format-Table . For more information about this setting, see about_ANSI_Terminals .

If you want to use Format-Table with the Property parameter, you need to include the Force parameter under any of the following conditions:

• The input objects are normally formatted out-of-band using the ToString() method. This applies to [string] and .NET primitive types, which are a superset of the built-in numeric types such as [int] , [long] , and others.

• The input objects have no public properties.

• The input objects are instances of the wrapper types PowerShell uses for output streams other than the Success output stream. This applies only when these wrapper types are sent to the Success output stream that requires either having captured them via common parameters such as ErrorVariable first or using a redirection such as *>&1 .

  • The wrapper types include:

    • System.Management.Automation.ErrorRecord
    • System.Management.Automation.WarningRecord
    • System.Management.Automation.VerboseRecord
    • System.Management.Automation.DebugRecord
    • System.Management.Automation.InformationRecord

Related Links

• about_Calculated_Properties
• about_Format.ps1xml
• about_Hash_Tables
• Export-FormatData
• Format-Custom
• Format-Hex
• Format-List
• Format-Wide
• Get-FormatData
• Get-Member
• Get-CimInstance
• Update-FormatData