Using Format Control Strings.

PSMDTAG:FAQ: How do I display large numbers with commas?
PSMDTAG:FAQ: How do I use .NET formatting strings?

As scripters, we often spend tons of times trying to get our data formated just the right way.  Often this is an error-prone, frustrating experience.  Windows PowerShell leverages .NET objects to make this task a ton simpler.  In .NET, every type supports ToString() and many of them support rich ToString Methods taking control strings.

To tell if an object supports a format control string, just take an instance of the object and pipe it to Get-Member asking for the ToString member:

PS> $GUID = [GUID]::NewGUID()
PS> $DATE = get-date
PS> $GUID,$DATE |get-member ToString |ft -wrap

   TypeName: System.Guid

Name     MemberType Definition
----     ---------- ----------
ToString Method     System.String ToString(), System.String ToString(Strin
                    g format), System.String ToString(String format, IForm
                    atProvider provider)

   TypeName: System.DateTime

Name     MemberType Definition
----     ---------- ----------
ToString Method     System.String ToString(), System.String ToString(Strin
                    g format), System.String ToString(IFormatProvider prov
                    ider), System.String ToString(String format, IFormatPr
                    ovider provider)

If you examine the DEFINITION field you'll see that both of these take a format string.

Now to understand what the format string options are, you'll have to look up the documentation for that type.  Here is a link to the documentation for GUID http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfSystemGuidClassToStringTopic2.asp

PSTIP: The technique that I use to help find .NET documentation is to always include the term "members" in your search engine. 

Try searching for "GUID" and compare those results against the results of a search for "GUID Members".  You can seach for "GUID Members ToString" to get even closer.  These links will show you the help for the class, you'll want to link through to the ToString() method and then click through on the particular signature which takes the CONTROL STRING parameter and this will show you the values for the control string.  Here is how you can use it:

PS> $GUID = [GUID]::NewGUID()
PS> foreach ($S in "N","D","B","P") {
>> "GUID Formatted with $S : {0}" -f $GUID.ToString($S)
>> }
>>
GUID Formatted with N : 0388d55e648046fea31d95d167fb36e6
GUID Formatted with D : 0388d55e-6480-46fe-a31d-95d167fb36e6
GUID Formatted with B : {0388d55e-6480-46fe-a31d-95d167fb36e6}
GUID Formatted with P : (0388d55e-6480-46fe-a31d-95d167fb36e6)

PS> $DATE = get-date
PS> foreach ($S in "d","D","f","F","g","G","m","r","s","t","T","u","U",
>> "y","dddd, MMMM dd yyyy","M/yy","dd-MM-yy") {
>> "DATE formatted with $S : {0}" -f $DATE.ToString($S)
>> }
>>
DATE formatted with d : 6/16/2006
DATE formatted with D : Friday, June 16, 2006
DATE formatted with f : Friday, June 16, 2006 11:57 AM
DATE formatted with F : Friday, June 16, 2006 11:57:36 AM
DATE formatted with g : 6/16/2006 11:57 AM
DATE formatted with G : 6/16/2006 11:57:36 AM
DATE formatted with m : June 16
DATE formatted with r : Fri, 16 Jun 2006 11:57:36 GMT
DATE formatted with s : 2006-06-16T11:57:36
DATE formatted with t : 11:57 AM
DATE formatted with T : 11:57:36 AM
DATE formatted with u : 2006-06-16 11:57:36Z
DATE formatted with U : Friday, June 16, 2006 6:57:36 PM
DATE formatted with y : June, 2006
DATE formatted with dddd, MMMM dd yyyy : Friday, June 16 2006
DATE formatted with M/yy : 6/06
DATE formatted with dd-MM-yy : 16-06-06
PS>

Format strings are great for Admins.  Let me prove it.  Quick - what is the number below

10000000000

Is that a million, ten million, a hundred million?  With format strings you can do the following

PS> "{0:N0}" -f 10000000000
10,000,000,000

I've heard that "diamonds may be a girl's best friend".  I don't know about that but I do know this: "commas are an Admin's best friend"!

So take few minutes to explore how to use format strings.  Here is a script you can run to find all the classes which support format strings in your current process:

[appdomain]::currentdomain.getassemblies() | % {
   $_.GetExportedTypes() |where {! $_.IsSubclassof([System.Enum])}
  } | % {
     $Methods = $_.getmethods() |where {$_.name -eq "tostring"} |%{"$_"};
     if ($methods -eq "System.String ToString(System.String)") {
           $_.fullname
     }
   }

Enjoy
Jeffrey Snover
Windows PowerShell Architect

PSMDTAG:DOTNET: Format strings