Windows PowerShell Tip of the Week

Here’s a quick tip on working with Windows PowerShell. These are published every week for as long as we can come up with new tips. If you have a tip you’d like us to share or a question about how to do something, let us know.

Formatting Dates and Times

Having recently returned from a vacation in Europe, one of the Scripting Guys was reminded of the following fact: just because Americans do something, that doesn’t mean the rest of the world does that very same thing, or at least not in the very same fashion. This is true when it comes to putting ice in drinks; it’s also true when it comes to formatting dates and times.

For example, in the US we use a 12-hour clock. What does that mean? Well, suppose we’re at lunch, and we glance at the clock; the clock says that it’s 12:59 in the afternoon. Let’s assume that we wait one minute and check the clock again. In much of the world, the clock will read 13:00; that’s because a large portion of the world uses a 24-hour clock. In the US, however, the clock will read 1:00; that’s because a US day is broken into two 12-hour segments: the morning segment (AM) and the evening segment (PM).

The same sort of thing is true when it comes to calendar days. Suppose today is August 31, 2007 (which it is). In the US, we’d list the date like this: 8/31/2007, the format being month/day/year. In a very large portion of the world, however, that same date is listed like this: 31/8/2007, the format being day/month/year. This isn’t to say that one of these approaches is right and the other is wrong. (Even though we Americans always believe that we’re right and everyone else is wrong; see “the metric system” for more details.) Instead, it’s just to say that any time you work with dates and times there is a chance for confusion. What time is it if it’s 2:15? In Italy, it’s 2:15 in the morning; in the US, well, it might be 2:15 in the morning, or it might be 2:15 in the afternoon. What date is it if it’s 10/3/2007? Again, in Italy, it’s March 10, 2007; in the US, it’s October 3, 2007. It all depends on where you are and, when it comes to computers, how you’ve configured your Regional and Language Options.

So what does that mean to you, the Windows PowerShell scripter? Well, if you’re working in an international setting, it means that you should always format dates using a specific pattern; that way dates and times will be consistent regardless of a user’s regional and language settings. But what if you’re not working in an international setting? Well, even then it can be useful to know how to format dates and times. For example, when you call the Get-Date cmdlet Windows PowerShell, by default, displays a value similar to this:

Thursday, August 30, 2007 11:13:51 AM

That’s fine, but what if all you really wanted was a value like this:

8/30/2007

Hey, no problem. As it turns out, that’s what this week’s Windows PowerShell tip is all about.

Quick Formatting

Thanks to its ability to tap into the .NET Framework, Windows PowerShell offers scores of different ways to format dates and times. For example, you can create fully-customizable date-time formats, something we’ll address in a moment. Alternatively, you can use one of these standard date-time formats:

Specifier

Format

Sample Output

d

ShortDatePattern

8/30/2007

D

LongDatePattern

Thursday, August 30, 2007

f

Full date and time (long date and short time)

Thursday, August 30, 20

F

FullDateTimePattern (long date and long time)

Thursday, August 30, 2007 11:19:59 AM

g

General (short date and short time)

8/30/2007 11:20 AM

G

General (short date and long time)

8/30/2007 11:20:24 AM

m, M

MonthDayPattern

August 30

o

Round-trip date/time pattern

[Text]

2007-08-30T11:18:49.0312500-07:00

RFC1123Pattern

Thu, 30 Aug 2007 11:21:36 GMT

s

SortableDateTimePattern (based on ISO 8601) using local time

2007-08-30T11:20:36

t

ShortTimePattern

11:20 AM

T

LongTimePattern

11:20:42 AM

u

UniversalSortableDateTimePattern using the format for universal time display

2007-08-30 11:21:50Z

U

Full date and time (long date and long time) using universal time

Thursday, August 30, 2007 6:21:52 PM

y, Y

YearMonthPattern

August, 2007

That’s all well and good, but how do you apply these date-time formats? As it turns out, that’s easy: all you need to do is tack on the –format parameter followed by the appropriate specifier. For example, suppose you want to apply the ShortDatePattern format. No problem:

Get-Date -format d

To apply the LongDatePattern use the D specifier:

Get-Date -format D

Etc., etc.

If you want to, you can also assign this formatted date-time value to a variable, like so:

$a = Get-Date -format M

Do that and display the value of $a; you should get back something that looks like this:

August 30

And that’s all you’re going to get back (the month and the day), no matter where you live and no matter how you’ve configured your regional and language settings.

Custom Formatting

Maybe these built-in date-time formats work for you and maybe they don’t. Let’s assume that they don’t, that you need a customized date-time format. What then?

Well, you know what they say: they say … well, come to think of it, we don’t have any idea what they say. But what they should say is this: if you want a customized date-time format, then you should use the .NET Framework to build a customized date-time format yourself. That’s something you can do using custom date-time specifiers, some of which (the more commonly-used ones) are shown in the following table:

Specifier

Description

d. %d

The day of the month. Single-digit days will not have a leading zero. Specify "%d" if the format pattern is not combined with other format patterns.

dd

The day of the month. Single-digit days will have a leading zero.

ddd

The abbreviated name of the day of the week.

dddd

The full name of the day of the week, as defined in DayNames.

h, %h

The hour in a 12-hour clock. Single-digit hours will not have a leading zero. Specify "%h" if the format pattern is not combined with other format patterns.

hh

The hour in a 12-hour clock. Single-digit hours will have a leading zero.

H, %H

The hour in a 24-hour clock. Single-digit hours will not have a leading zero. Specify "%H" if the format pattern is not combined with other format patterns.

HH

The hour in a 24-hour clock. Single-digit hours will have a leading zero.

m, %m

The minute. Single-digit minutes will not have a leading zero. Specify "%m" if the format pattern is not combined with other format patterns.

mm

The minute. Single-digit minutes will have a leading zero.

M, %M

The numeric month. Single-digit months will not have a leading zero. Specify "%M" if the format pattern is not combined with other format patterns.

MM

The numeric month. Single-digit months will have a leading zero.

MMM

The abbreviated name of the month, as defined in AbbreviatedMonthNames.

MMMM

The full name of the month, as defined in MonthNames.

s, %s

The second. Single-digit seconds will not have a leading zero. Specify "%s" if the format pattern is not combined with other format patterns.

ss

The second. Single-digit seconds will have a leading zero.

t, %t

The first character in the AM/PM designator defined in AMDesignator or PMDesignator, if any. Specify "%t" if the format pattern is not combined with other format patterns.

tt

The AM/PM designator defined in AMDesignator or PMDesignator, if any.

y, %y

The year without the century. If the year without the century is less than 10, the year is displayed with no leading zero. Specify "%y" if the format pattern is not combined with other format patterns.

yy

The year without the century. If the year without the century is less than 10, the year is displayed with a leading zero.

yyy

The year in three digits. If the year is less than 100, the year is displayed with a leading zero.

yyyy

The year in four or five digits (depending on the calendar used), including the century. Will pad with leading zeroes to get four digits. Thai Buddhist and Korean calendars both have five digit years; users selecting the "yyyy" pattern will see all five digits without leading zeros for calendars that have five digits. Exception: the Japanese and Taiwan calendars always behave as if "yy" was selected.

%c

Where c is a format pattern if used alone. That is, to use format pattern "d", "f", "F", "h", "m", "s", "t", "y", "z", "H", or "M" by itself, specify "%d", "%f", "%F", "%h", "%m", "%s", "%t", "%y", "%z", "%H", or "%M". The "%" character can be omitted if the format pattern is combined with literal characters or other format patterns.

\c

Where c is any character. Displays the character literally. To display the backslash character, use "\\".

Note. You can find a complete list of specifiers in the .NET Framework SDK on MSDN.

We aren’t going to bother running through all the possible combinations and permutations here; needless to say, that would take awhile. However, we will show you a couple of examples, the better to get you started in the wonderful world of custom date-time formatting. For example, suppose you’d like a date-time value that looked like this, with the month followed by a period followed by the day (and another period) followed by the year:

8.30.2007

How can we do that? Like this:

Get-Date -format M.d.yyyy

Nothing too fancy here: we simply use the –format parameter followed by the desired format (including the periods). What if we wanted to show the year, the abbreviated name of the month, and then the day, all separated by blank spaces?

2007 Aug 30

We can do that:

Get-Date -format "yyyy MMM d"

Again, there’s nothing complicated about this: we simply add the –format parameter followed by the appropriate specifiers. The one thing to watch out for? Because our formatting string includes blank spaces, we need to enclose the entire string in double quote marks. That’s about as complicated as it gets.

I Format, uFormat, We All Format

You say that’s not enough? You say you want even more custom formatting options? Well, as it turns out, the Get-Date cmdlet includes another parameter (-uformat) which enables you to display date and time information in Unix format. We won’t discuss all the available specifiers in today’s article; for more information, see the Windows PowerShell help file. However, we will mention two interesting (and useful) specifiers: %j and %V. (And yes, you do need to include the percent signs when referencing these specifiers.) The %j specifier returns the day of the year; for example:

Get-Date -uformat %j
242

The %V specifier returns the week of the year:

Get-Date -uformat %V
35

And, as always, the Get-Date cmdlet can be used with any date, not just the current date. Want to know the day of the year for March 13, 2008? Okey-doke:

Get-Date 3/13/2008 -uformat %j
73

Pretty cool, huh? See you next week.