Windows PowerShell -f Format Operator

Introduction to Windows PowerShell -f Format Output

My mission on this page is to explain the basics of PowerShell’s -f format operator.  We use this operator, -f, to set the column widths in the output.  Another way of looking at -f is to control the tab alignment.  It has to be said that Format-Table is the easiest method of controlling the output display; however, there are occasions where only -f can achieve the desired result.

Topics for PowerShell -f Format Operator

• Example 1: The Format Problem
• Example 2: Columns Aligned – Desired Format
• Guy’s Suck-it-And-see Explanation
• Even more control over -f formatting

 ♣

Example 1: The Format Problem

I have chosen PowerShell’s eventlog command to illustrate the formatting problem. What I would like is for the data in the three fields to align precisely in columns.

In the screenshot below, data is difficult to read (even allowing for it being out of focus).  Actually, it could be worse, the only reason there is a space between ACEEventLog and OverwriteOlder is because I added the clumsy command:  + ” “.  See code below.

Code which Produces the Format Problem (Above)

Example 2: Columns Aligned – Desired Format

PowerShell -f code for Example 2

Guy Recommends:  A Free Trial of the Network Performance Monitor (NPM) v11.5

SolarWinds’ Network Performance Monitor will help you discover what’s happening on your network.  This utility will also guide you through troubleshooting; the dashboard will indicate whether the root cause is a broken link, faulty equipment or resource overload.

What I like best is the way NPM suggests solutions to network problems.  Its also has the ability to monitor the health of individual VMware virtual machines.  If you are interested in troubleshooting, and creating network maps, then I recommend that you try NPM now.

Download a free trial of Solarwinds’ Network Performance Monitor

Guy’s Suck-it-And-see Explanation

What I would like to do here is explain how the -f format output operator works.  I will give you examples to show every nuance, and every punctuation character.  However, this is a practical rather than a technical explanation.

Let me begin with a reminder of the context.  We are employing the command: Get-Eventlog -List, as a vehicle to experiment with the -f format operator.  This script uses the standard loop technique, and what we are particularly interested in is the alignment of the three properties:
$Log.log, $Log.OverflowAction, and $Log.MaximumKilobytes

In Example 2 (above), we achieved the regular alignment with this format operator: “{0,-28} {1,-20} {2,8}” -f

Note 1:  Each individual element in the output is enclosed by a set of braces {1,-20}.  The first number, zero, one or two, refers to the column in the output (first, second or third). If you study example 2, the first item, $Log.log, is referenced by zero in the first set of braces {0,-28}

Following the comma, comes the second number (-20 or 8), this determines the padding.  Providing this number is larger than the number of letters in the longest data element, the columns align nicely.

Note 2:  Minus, and I emphasise minus, -28 not only pads the element, but also makes sure that the first letters of each element line up vertically.  Actually the best way to see what I mean is try the script WITHOUT the minus.  The reason that I am hesitating to use the words left and right is because when I read a technical article on the subject, the technical author referred to left and right in the opposite way to my logic.

Note 3: Speech marks.  In this example there are three separate elements enclosed in one set of speech marks :”{0,-28} {1,-20} {2,8}”.  Incidentally, another solution is plain Format-Table

Note 4: -f this comes at the end of the formatting instruction, and is outside the speech marks.  Also be aware of the logic whereby the -f format statement comes before the actual data.

Note 5: Naturally, the number of sets of braces needs to match the number of elements you want to show in the output, three elements, thee sets of braces.  Once again, make my day and try an experiment, for example remove the second or third element, try just: “{0,-28}” -f

Note 6: For the last element, {2,8}, I deliberately chose a positive number, the result is that the numbers align under the smallest digit, which makes the numbers easier to compare.

Addendum
It often helps to have a second person explain a topic, this is what Simon L. says:

I have read through and done some examples of formatting and think I understand it now. It might be clearer to state something like:

{0,10} would create a column for the 1st item 10 characters wide and would right-align the contents because the 10 is positive.

{2,-20} would create a column for the 3rd item 20 characters wide and would left-align the contents because the 20 is negative.
“{0,28} {1, 20} {2,-8}” -f ` creates:

A column for the 1st item of 28 characters, right-aligned and adds a space
A column for the 2nd item of 20 characters right-aligned and adds a space
A column for the 3rd item of 8 characters left-aligned.

Guy Recommends: Free WMI Monitor for PowerShell

Windows Management Instrumentation (WMI) is one of the hidden treasures of Microsoft’s operating systems.  Fortunately, SolarWinds have created a Free WMI Monitor so that you can discover these gems of performance information, and thus improve your PowerShell scripts.

Take the guess work out of which WMI counters to use when scripting the operating system, Active Directory, or Exchange Server. Give this WMI monitor a try – it’s free.

Download your free copy of WMI Monitor

More Challenges for PowerShell Format Output -f

I found that the best way to understand the -f formatting was to experiment with different settings.  To see what I mean, take example 2 as your test-bed and substitute the commands below for “{0,-28} {1,-20} {2,8}” -f `.  Before I go any further, the tiny backtick symbol ` tells PowerShell to wrap the command to the next line.  I also positioned the backtick to emphasise the split between the formatting commands and the data.  Try these:

It almost goes without saying, that while I have used, Get-Eventlog -List, to illustrate PowerShell’s -f format operator, there innumerable other PowerShell commands that benefit from this control over the display of your data.  You could even try this if you don’t have another ‘vehicle’ for testing:

“{3,-10} {2, -10} {1,-20}” -f 1, 2, 3, 4

Even More Control Over -f Formatting

While I chose to use only integers for simple formatting, PowerShell offers even more control, here are examples:

Number of Decimal Places – Formatting with :N2

Note 7: :N0 would result in an integer.  Actually, ‘N’ means numeric rather than number.  There is a separate ‘D’ decimal formatter, which I don’t like!

Hexadecimal
“{0:x}” This is the simplest hex format. If the FIRST data element returned 500, what you would see displayed is:
1f4

“0x{0:x}” -f 500
The result displays: 0x1f4

“0x{0:X}” -f 500
The result displays: 0x1F4

Deliberate Mistake: “0x{0:X}” -f “500” If you enclose the 500 in speech marks, it does not produce the desired hex conversion.

Another Deliberate Mistake: “0x{0,X}” -f 500. That comma is incorrect, it should be a colon. My point is that you have to be so careful with each and every punctuation mark.

Currency Format
Fittingly, the letter for currency is: C

Try this: “{1,25:C}” -f 137.30, 88.90

Percentage
‘P’ is for percentage

Try this: “{0,-10:p}” -f 0.875, 0.790

Decimal
I haven’t found much use for this.  It adds leading zeros

Try this ” Dec {0:D5}” -f 365

PowerShell Formatting for Time and Date

You can display date and time with the usual hh = hours, mm= minutes
Also dd = day (number) ddd = Mon and dddd = Monday

{1:hh} Would display the SECOND item as hours  {0:hh} displays the first item.

Try this: “{0:hh}:{0:mm}” -f (Get-Date)
or these:

Note 8:  A reminder that zero means the first position, actually there is only one item, but we still need that initial {0:

Formatting Very Large Numbers

I have developed a function for formatting numbers into terabyte, gigabyte, and megabyte.  Its main purpose would be to display output values obtained by Get-WmiObject in a more readable format, for example, 4289793200 as 4GB.

See more on PowerShell format disksize function »

Summary of -f PowerShell Format Output Operator

Appending | Format-Table is the standard method of formatting PowerShell’s output, however, there are situations where the -f operator gives you greater control over the output of your data.

See more Microsoft PowerShell output tutorials:

• PShell Home   • Out-File   • Out-GridView   • ConvertTo-Csv   • ConvertTo-Html   • ConvertFrom-Csv

• Tee-Object   • Import-CSV   • Format-Table   • PowerShell Here-String  • ConvertFrom-JSON

• Export-CliXml   • Format-List   • Read-Host    • PowerShell Get-History   • -f format   • Pipe to file

Please email me if you have a better example script. Also please report any factual mistakes, grammatical errors or broken links, I will be happy to correct the fault.