You have an item (for example, an error record, directory item, or .NET object), and you want to display detailed information about that object in a list format.

To display detailed information about an item, pass that item to the Format-List cmdlet. For example, to display an error in list format, type the commands:

$currentError = $error[0]
$currentError | Format-List -Force

Many commands by default display a summarized view of their output in a table format. For example, the Get-Process cmdlet:

PS > Get-Process PowerShell

Handles  NPM(K)    PM(K)      WS(K) VM(M)   CPU(s)     Id ProcessName
-------  ------    -----      ----- -----   ------     -- -----------
    920      10    43808      48424   183     4.69   1928 powershell
    149       6    18228       8660   146     0.48   1940 powershell
    431      11    33308      19072   172            2816 powershell

In most cases, the output actually contains a great deal more information. You can use the Format-List cmdlet to view it:

PS > Get-Process PowerShell | Format-List *


__NounName                 : Process
Name                       : powershell
Handles                    : 443
VM                         : 192176128
WS                         : 52363264
PM                         : 47308800
NPM                        : 9996
Path                       : C:\WINDOWS\system32\WindowsPowerShell\v1.0\power
                             shell.exe
Company                    : Microsoft Corporation
CPU                        : 4.921875
FileVersion                : 6.0.6002.18139 (vistasp2_gdr_win7ip_winman(wmbla
                             ).090902-1426)
ProductVersion             : 6.0.6002.18139
Description                : Windows PowerShell
(...)

The Format-List cmdlet is one of the four PowerShell formatting cmdlets. These cmdlets include Format-Table, Format-List, Format-Wide, and Format-Custom. The Format-List cmdlet takes input and displays information about that input as a list.

By default, PowerShell takes the list of properties to display from the *.format.ps1xml files in PowerShell's installation directory. In many situations, you'll only get a small set of the properties:

PS > Get-Process PowerShell | Format-List

Id      : 2816
Handles : 431
CPU     :
Name    : powershell

Id      : 5244
Handles : 665
CPU     : 10.296875
Name    : powershell

To display all properties of the item, type Format-List *. If you type Format-List * but still do not get a list of the item's properties, then the item is defined in the *.format.ps1xml files, but does not define anything to be displayed for the list command. In that case, type Format-List -Force.

One common stumbling block in PowerShell's formatting cmdlets comes from putting them in the middle of a script or pipeline:

PS > Get-Process PowerShell | Format-List | Sort Name
out-lineoutput : The object of type "Microsoft.PowerShell.Commands.Internal.F
ormat.FormatEntryData" is not valid or not in the correct sequence. This is l
ikely caused by a user-specified "format-*" command which is conflicting with
 the default formatting.

Internally, PowerShell's formatting commands generate a new type of object: Microsoft.PowerShell.Commands.Internal.Format.*. When these objects make it to the end of the pipeline, PowerShell then automatically sends them to an output cmdlet: by default, Out-Default. These Out-* cmdlets assume that the objects arrive in a certain order, so doing anything with the output of the formatting commands causes an error the the output system.

To resolve this problem, try to avoid calling the formatting cmdlets in the middle of a script or pipeline. When you do this, the output of your script no longer lends itself to the object-based manipulation so synonymous with PowerShell. If you want to display formatted output anyway, send the output through the Out-String cmdlet:

Get-Process PowerShell | Format-List | Out-String -Stream

Object-manipulations commands will still not work (since the objects have been converted to strings), but at least the the script will not generate errors.

For more information about the Format-List cmdlet, type Get-Help Format-List.

You have a set of items (for example, error records, directory items, or .NET objects), and you want to display summary information about them in a table format.

To display summary information about a set of items, pass those items to the Format-Table cmdlet. This is the default type of formatting for sets of items in PowerShell and provides several useful features.

To use PowerShell's default formatting, pipe the output of a cmdlet (such as the Get-Process cmdlet) to the Format-Table cmdlet:

Get-Process | Format-Table

To display specific properties (such as Name and WorkingSet), in the table formatting, supply those property names as parameters to the Format-Table cmdlet:

Get-Process | Format-Table Name,WS

To instruct PowerShell to format the table in the most readable manner, supply the -Auto flag to the Format-Table cmdlet. PowerShell defines "WS" as an alias of the WorkingSet property for processes:

Get-Process | Format-Table Name,WS -Auto

To define a custom column definition (such as a process's Working Set in megabytes), supply a custom formatting expression to the Format-Table cmdlet:

$fields = "Name",@{Label = "WS (MB)"; Expression = {$_.WS / 1mb}; Align = "Right"} 
Get-Process | Format-Table $fields -Auto

The Format-Table cmdlet is one of the four PowerShell formatting cmdlets. These cmdlets include Format-Table, Format-List, Format-Wide, and Format-Custom. The Format-Table cmdlet takes input and displays information about that input as a table. By default, PowerShell takes the list of properties to display from the *.format.ps1xml files in PowerShell's installation directory. You can display all properties of the items if you type Format-Table *, although this is rarely a useful view.

The -Auto parameter to Format-Table is a helpful way to automatically format the table in the most readable way possible. It does come at a cost, however. To figure out the best table layout, PowerShell needs to examine each item in the incoming set of items. For small sets of items, this doesn't make much difference, but for large sets (such as a recursive directory listing) it does. Without the -Auto parameter, the Format-Table cmdlet can display items as soon as it receives them. With the -Auto flag, the cmdlet only displays results after it receives all the input.

Perhaps the most interesting feature of the Format-Table cmdlet is illustrated by the last example: the ability to define completely custom table columns. You define a custom table column similarly to the way that you define a custom column list. Rather than specify an existing property of the items, you provide a hashtable. That hashtable includes up to three keys: the column's label, a formatting expression, and alignment. The Format-Table cmdlet shows the label as the column header and uses your expression to generate data for that column. The label must be a string, the expression must be a script block, and the alignment must be either "Left", "Center",or "Right". In the expression script block, the $_ variable represents the current item being formatted.

The expression shown in the last example takes the working set of the current item and divides it by 1 megabyte (1 MB).

One common stumbling block in PowerShell's formatting cmdlets comes from putting them in the middle of a script or pipeline:

PS > Get-Process PowerShell | Format-Table | Sort Name
out-lineoutput : The object of type "Microsoft.PowerShell.Commands.Internal.F
ormat.FormatEntryData" is not valid or not in the correct sequence. This is l
ikely caused by a user-specified "format-*" command which is conflicting with
 the default formatting.

Internally, PowerShell's formatting commands generate a new type of object: Microsoft.PowerShell.Commands.Internal.Format.*. When these objects make it to the end of the pipeline, PowerShell then automatically sends them to an output cmdlet: by default, Out-Default. These Out-* cmdlets assume that the objects arrive in a certain order, so doing anything with the output of the formatting commands causes an error the the output system.

To resolve this problem, try to avoid calling the formatting cmdlets in the middle of a script or pipeline. When you do this, the output of your script no longer lends itself to the object-based manipulation so synonymous with PowerShell. If you want to display formatted output anyway, send the output through the Out-String cmdlet:

Get-Process PowerShell | Format-Table | Out-String -Stream

Object-manipulations commands will still not work (since the objects have been converted to strings), but at least the the script will not generate errors.

For more information about the Format-Table cmdlet, type Get-Help Format-Table. For more information about hashtables, see the section called “Create a Hashtable or Associative Array”. For more information about script blocks, see the section called “Write a Script Block”.

You want to store the output of a pipeline or command for later use, or to work with it in more detail.

To store output for later use, store the output of the command in a variable. You can access this information later, or even pass it down the pipeline as though it was the output of the original command:

PS > $result = 2 + 2
PS > $result
4
PS > $processes = Get-Process
PS > $processes.Count
85
PS > $processes | Where-Object { $_.ID -eq 0 }

Handles  NPM(K)    PM(K)      WS(K) VM(M)   CPU(s)    Id ProcessName
-------  ------    -----      ----- -----   -----     -- -----------
      0       0        0         16     0              0 Idle

Variables in PowerShell (and all other scripting and programming languages) let you store the output of something so that you can use it later. A variable name starts with a dollar sign ($) and can be followed by nearly any character. A small set of characters have special meaning to PowerShell, so PowerShell provides a way to make variable names that include even these.

For more information about the syntax and types of PowerShell variables, see the section called “Variables”.

You can store the result of any pipeline or command in a variable to use it later. If that command generates simple data (such as a number or string), then the variable contains simple data. If the command generates rich data (such as the objects that represent system processes from the Get-Process cmdlet), then the variable contains that list of rich data. If the command (such as a traditional executable) generates plain text (such as the output of traditional executable), then the variable contains plain text.

In addition to variables that you create, PowerShell automatically defines several variables that represent things such as the location of your profile file, the process ID of PowerShell, and more. For a full list of these automatic variables, type Get-Help about_automatic_variables.

You want to use an environment variable (such as the system path, or current user's name) in your script or interactive session.

PowerShell offers several ways to access environment variables.

To list all environment variables, list the children of the env drive:

Get-ChildItem env:

To get an environment variable using a more concise syntax, precede its name with $env:

$env:variablename

i.e.: $env:username

To get an environment variable using its Provider path, supply env: or Environment:: to the Get-ChildItem cmdlet:

Get-ChildItem env:variablename
Get-ChildItem Environment::variablename

PowerShell provides access to environment variables through its environment provider. Providers let you work with data stores (such as the registry, environment variables, and aliases) much as you would access the filesystem.

By default, PowerShell creates a drive (called env) that works with the environment provider to let you access environment variables. The environment provider lets you access items in the env: drive as you would any other drive: dir env:\variablename or dir env:variablename. If you want to access the provider directly (rather than go through its drive), you can also type dir Environment::variablename.

However, the most common (and easiest) way to work with environment variables is by typing $env:variablename. This works with any provider but is most typically used with environment variables.

This is because the environment provider shares something in common with several other providers—namely support for the *-Content set of core cmdlets (see Example 3.1, “Working with content on different providers”).

PS > "hello world" > test
PS > Get-Content test
hello world
PS > Get-Content c:test
hello world
PS > Get-Content variable:ErrorActionPreference
Continue
PS > Get-Content function:more
param([string[]]$paths)
$OutputEncoding = [System.Console]::OutputEncoding

if($paths)
{
    foreach ($file in $paths)
    {
        Get-Content $file | more.com
    }
}
else
{
    $input | more.com
}
PS > Get-Content env:systemroot
C:\WINDOWS

For providers that support the content cmdlets, PowerShell lets you interact with this content through a special variable syntax (see Example 3.2, “Using PowerShell's special variable syntax to access content”).

PS > $function:more
param([string[]]$paths); if(($paths -ne $null) -and ($paths.length -ne 0)) { ...
       Get-Content $local:file | Out-Host -p } } else { $input | Out-Host ...
PS > $variable:ErrorActionPreference
Continue
PS > $c:test
hello world
PS > $env:systemroot
C:\WINDOWS

This variable syntax for content management lets you to both get and set content:

PS > $function:more = { $input | less.exe }
PS > $function:more
$input | less.exe

Now, when it comes to accessing complex provider paths using this method, you'll quickly run into naming issues (even if the underlying file exists):

PS > $c:\temp\test.txt
Unexpected token '\temp\test.txt' in expression or statement.
At line:1 char:17
+ $c:\temp\test.txt <<<<

The solution to that lies in PowerShell's escaping support for complex variable names. To define a complex variable name, enclose it in braces:

PS > ${1234123!@#$!@#$12$!@#$@!} = "Crazy Variable!"
PS > ${1234123!@#$!@#$12$!@#$@!}
Crazy Variable!
PS > dir variable:\1*

Name                              Value
----                              -----
1234123!@#$!@#$12$!@#$@!          Crazy Variable!

… and the content equivalent (assuming that the file exists):

PS > ${c:	emp	est.txt}
hello world

Since environment variable names do not contain special characters, this Get-Content variable syntax is the best (and easiest) way to access environment variables.

For more information about working with PowerShell variables, see the section called “Variables”. For more information about working with environment type Get-Help About_Environment_Variable.

You want to control how you define (or interact with) the visibility of variables, aliases, functions, and drives.

PowerShell offers several ways to access variables.

To create a variable with a specific scope, supply that scope before the variable name:

$SCOPE:variable = value

To access a variable at a specific scope, supply that scope before the variable name:

$SCOPE:variable

To create a variable that remains even after the script exits, create it in the GLOBAL scope:

$GLOBAL:variable = value

To change a scriptwide variable from within a function, supply SCRIPT as its scope name:

$SCRIPT:variable = value

PowerShell controls access to variables, functions, aliases, and drives through a mechanism known as scoping. The scope of an item is another term for its visibility. You are always in a scope (called the current or local scope), but some actions change what that means.

When your code enters a nested prompt, script, function, or script block, PowerShell creates a new scope. That scope then becomes the local scope. When it does this, PowerShell remembers the relationship between your old scope and your new scope. From the view of the new scope, the old scope is called the parent scope. From the view of the old scope, the new scope is called a child scope. Child scopes get access to all the variables in the parent scope, but changing those variables in the child scope doesn't change the version in the parent scope.

When your code exits a nested prompt, script, function, or script block, the opposite happens. PowerShell removes the old scope, then changes the local scope to be the scope that originally created it—the parent of that old scope.

Some scopes are so common that PowerShell gives them special names:

When you define the scope of an item, PowerShell supports two additional scope names that act more like options: Private and AllScope. When you define an item to have a Private scope, PowerShell does not make that item directly available to child scopes. PowerShell does not hide it from child scopes, though, as child scopes can still use the -Scope parameter of the Get-Variable cmdlet to get variables from parent scopes. When you specify the AllScope option for an item (through one of the *-Variable, *-Alias, or *-Drive cmdlets), child scopes that change the item also affect the value in parent scopes.

With this background, PowerShell provides several ways for you to control access and scope of variables and other items.

$SCRIPT:myVariable = value

function GLOBAL:MyFunction { ... }
GLOBAL:MyFunction args

You want to use and interact with one of the features that make PowerShell so powerful—its intrinsic support for .NET objects.

PowerShell offers ways to access methods (both static and instance) and properties.

To call a static method on a class, place the type name in square brackets, and then separate the class name from the method name with two colons:

[ClassName]::MethodName(parameter list)

To call a method on an object, place a dot between the variable that represents that object and the method name:

$objectReference.MethodName(parameter list)

To access a static property on a class, place the type name in square brackets, and then separate the class name from the property name with two colons:

[ClassName]::PropertyName

To access a property on an object, place a dot between the variable that represents that object and the property name:

$objectReference.PropertyName

One feature that gives PowerShell its incredible reach into both system administration and application development is its capability to leverage Microsoft's enormous and broad .NET Framework. The .NET Framework is a large collection of classes. Each class embodies a specific concept and groups closely related functionality and information. Working with the .NET Framework is one aspect of PowerShell that introduces a revolution to the world of management shells.

An example of a class from the .NET Framework is System.Diagnostics.Process—the grouping of functionality that "provides access to local and remote processes, and enables you to start and stop local system processes."

Classes contain methods (which let you perform operations) and properties (which let you access information).

For example, the Get-Process cmdlet generates System.Diagnostics.Process objects, not a plain-text report like traditional shells. Managing these processes becomes incredibly easy, as they contain a rich mix of information (properties) and operations (methods). You no longer have to parse a stream of text for the ID of a process—you can just ask the object directly!

PS > $process = Get-Process Notepad
PS > $process.Id
3872

[ClassName]::MethodName(parameter list)

PS > [System.Diagnostics.Process]::GetProcessById(0)

Handles NPM(K) PM(K) WS(K) VM(M) CPU(s) Id ProcessName
------- ------ ----- ----- ----- ------ -- -----------
      0      0     0    16     0         0 Idle

$objectReference.MethodName(parameter list)

PS > $process = Get-Process Notepad
PS > $process.WaitForExit()

PS > $now = Get-Date
PS > $now.AddDays

MemberType : Method
OverloadDefinitions : {System.DateTime AddDays(Double value)}
TypeNameOfValue : System.Management.Automation.PSMethod
Value : System.DateTime AddDays(Double value)
Name : AddDays
IsInstance : True

PS > $now.AddDays.OverloadDefinitions
System.DateTime AddDays(double value)

PS > Trace-Command MemberResolution -PsHost {
>>     [System.Diagnostics.Process]::GetProcessById(0) }
>>
DEBUG: MemberResolution Information: 0 : cache hit, Calling Method: static
 System.Diagnostics.Process GetProcessById(int processId)
DEBUG: MemberResolution Information: 0 : Method argument conversion.
DEBUG: MemberResolution Information: 0 :     Converting parameter "0" to
"System.Int32".
DEBUG: MemberResolution Information: 0 : Checking for possible references.

Handles  NPM(K)    PM(K)      WS(K) VM(M)   CPU(s)     Id ProcessName
-------  ------    -----      ----- -----   ------     -- -----------
      0       0        0         12     0               0 Idle

[ClassName]::PropertyName

[ClassName]::PropertyName = value

PS > [System.DateTime]::Now
Saturday, June 2, 2010 4:57:20 PM

$objectReference.PropertyName

$objectReference.PropertyName = value

PS > $today = Get-Date
PS > $today.DayOfWeek
Saturday

You want to create an instance of a .NET object to interact with its methods and properties.

Use the New-Object cmdlet to create an instance of an object.

To create an instance of an object using its default constructor, use the New-Object cmdlet with the class name as its only parameter:

PS > $generator = New-Object System.Random
PS > $generator.NextDouble()
0.853699042859347

To create an instance of an object that takes parameters for its constructor, supply those parameters to the New-Object cmdlet. In some instances, the class may exist in a separate library not loaded in PowerShell by default, such as the System.Windows.Forms assembly. In that case, you must first load the assembly that contains the class:

Add-Type -Assembly System.Windows.Forms
$image = New-Object System.Drawing.Bitmap source.gif
$image.Save("source_converted.jpg","JPEG")

To create an object and use it at the same time (without saving it for later), wrap the call to New-Object in parentheses:

PS > (New-Object Net.WebClient).DownloadString("http://live.com")

Many cmdlets (such as Get-Process and Get-ChildItem) generate live .NET objects that represent tangible processes, files, and directories. However, PowerShell supports much more of the .NET Framework than just the objects that its cmdlets produce. These additional areas of the .NET Framework supply a huge amount of functionality that you can use in your scripts and general system administration tasks.

When it comes to using most of these classes, the first step is often to create an instance of the class, store that instance in a variable, and then work with the methods and properties on that instance. To create an instance of a class, you use the New-Object cmdlet. The first parameter to the New-Object cmdlet is the type name, and the second parameter is the list of arguments to the constructor, if it takes any. The New-Object cmdlet supports PowerShell's type shortcuts, so you never have to use the fully qualified type name. For more information about type shortcuts, see the section called “Work with .NET Objects”.

$startInfo = New-Object Diagnostics.ProcessStartInfo -Property @{
    'Filename' = "powershell.exe";
    'WorkingDirectory' = $pshome;
    'Verb' = "RunAs"
}
[Diagnostics.Process]::Start($startInfo)

Since the second parameter to the New-Object cmdlet is an array of parameters to the type's constructor, you might encounter difficulty when trying to specify a parameter that itself is a list. Assuming $byte is an array of bytes:

PS > $memoryStream = New-Object System.IO.MemoryStream $bytes
New-Object : Cannot find an overload for ".ctor" and the argument count: "11".
At line:1 char:27
+ $memoryStream = New-Object <<<< System.IO.MemoryStream $bytes

To solve this, provide an array that contains an array:

PS > $parameters = ,$bytes
PS > $memoryStream = New-Object System.IO.MemoryStream $parameters

or

PS > $memoryStream = New-Object System.IO.MemoryStream @(,$bytes)

You want to reduce the amount of redundant information in your script when you interact with classes that have long type names.

To reduce typing for static methods, store the type name in a variable:

$math = [System.Math]
$math::Min(1,10)
$math::Max(1,10)

To reduce typing for multiple objects in a namespace, use the -f (format) operator:

$namespace = "System.Collections.{0}"
$arrayList = New-Object ($namespace -f "ArrayList")
$queue = New-Object ($namespace -f "Queue")

To reduce typing for static methods of multiple types in a namespace, use the -f (format) operator along with a cast:

$namespace = "System.Diagnostics.{0}"
([Type] ($namespace -f "EventLog"))::GetEventLogs()
([Type] ($namespace -f "Process"))::GetCurrentProcess()

One thing you will notice when working with some .NET classes (or classes from a third-party SDK), is that it quickly becomes tiresome to specify their fully qualified type names. For example, many useful collection classes in the .NET Framework all start with "System.Collections". This is called the namespace of that class. Most programming languages solve this problem with a using directive that lets you to specify a list of namespaces for that language to search when you type a plain class name such as "ArrayList". PowerShell lacks a using directive, but there are several options to get the benefits of one.

If you are repeatedly working with static methods on a specific type, you can store that type in a variable to reduce typing as shown in the solution:

$math = [System.Math]
$math::Min(1,10)
$math::Max(1,10)

If you are creating instances of different classes from a namespace, you can store the namespace in a variable and then use the PowerShell -f (format) operator to specify the unique class name:

$namespace = "System.Collections.{0}"
$arrayList = New-Object ($namespace -f "ArrayList")
$queue = New-Object ($namespace -f "Queue")

If you are working with static methods from several types in a namespace, you can store the namespace in a variable, use the -f (format) operator to specify the unique class name, and then finally cast that into a type:

$namespace = "System.Diagnostics.{0}"
([Type] ($namespace -f "EventLog"))::GetEventLogs()
([Type] ($namespace -f "Process"))::GetCurrentProcess()

For more information about PowerShell's format operator, see the section called “Place Formatted Information in a String”.

You want to create a COM object to interact with its methods and properties.

Use the New-Object cmdlet (with the –ComObject parameter) to create a COM object from its ProgID. You can then interact with the methods and properties of the COM object as you would any other object in PowerShell.

$object = New-Object -ComObject ProgId

For example:

PS > $sapi = New-Object -Com Sapi.SpVoice
PS > $sapi.Speak("Hello World")

Historically, many applications have exposed their scripting and administration interfaces as COM objects. While .NET APIs (and PowerShell cmdlets) are becoming more common, interacting with COM objects is still a common administrative task.

As with classes in the .NET Framework, it is difficult to know what COM objects you can use to help you accomplish your system administration tasks. For a hand-picked list of the COM objects most useful to system administrators, see Appendix H, Selected COM Objects and Their Uses.

For more information about the New-Object cmdlet, type Get-Help New-Object.

You have an instance of an object and want to know what methods and properties it supports.

The most common way to explore the methods and properties supported by an object is through the Get-Member cmdlet.

To get the instance members of an object you've stored in the $object variable, pipe it to the Get-Member cmdlet:

$object | Get-Member
Get-Member -InputObject $object

To get the static members of an object you've stored in the $object variable, supply the -Static flag to the Get-Member cmdlet:

$object | Get-Member -Static
Get-Member -Static -InputObject $object

To get the static members of a specific type, pipe that type to the Get-Member cmdlet, and also specify the –Static flag:

[Type] | Get-Member -Static
Get-Member -InputObject [Type]

To get members of the specified member type (for example, Method, Property) from an object you have stored in the $object variable, supply that member type to the –MemberType parameter:

$object | Get-Member -MemberType MemberType
Get-Member -MemberType memberType -InputObject $object

The Get-Member cmdlet is one of the three commands you will use most commonly as you explore Windows PowerShell. The other two commands are Get-Command and Get-Help.

If you pass the Get-Member cmdlet a collection of objects (such as an Array or ArrayList) through the pipeline, PowerShell extracts each item from the collection, and then passes them to the Get-Member cmdlet one-by-one. The Get-Member cmdlet then returns the members of each unique type that it receives. Although helpful the vast majority of the time, this sometimes causes difficulty when you want to learn about the members or properties of the collection class itself.

If you want to see the properties of a collection (as opposed to the elements it contains), provide the collection to the –InputObject parameter, instead. Alternatively, you may wrap the collection in an array (using PowerShell's unary comma operator) so that the collection class remains when the Get-Member cmdlet unravels the outer array:

PS > $files = Get-ChildItem
PS > ,$files | Get-Member

   TypeName: System.Object[]

Name               MemberType     Definition
----               ----------     ----------
Count              AliasProperty  Count = Length
Address            Method         System.Object& Address(Int32 )
(...)

For another way to learn detailed information about types and objects, see the section called “Get Detailed Documentation About Types and Objects”.

For more information about the Get-Member cmdlet, type Get-Help Get-Member.

You have a type of object and want to know detailed information about the methods and properties it supports.

The documentation for the .NET Framework (available on http://msdn.microsoft.com) is the best way to get detailed documentation about the methods and properties supported by an object. That exploration generally comes in two stages:

When the Get-Member cmdlet does not provide the information you need, the MSDN documentation for a type is a great alternative. It provides much more detailed information than the help offered by the Get-Member cmdlet—usually including detailed descriptions, related information, and even code samples. MSDN documentation focuses on developers using these types through a language such as C#, though, so you may find interpreting the information for use in PowerShell to be a little difficult at first.

Typically, the documentation for a class first starts with a general overview, and then provides a hyperlink to the members of the class—the list of methods and properties it supports.

Documentation for the members of a class lists its methods and properties, as does the output of the Get-Member cmdlet. The S icon represents static methods and properties. Click the member name for more information about that method or property.

C#
public static DateTime Now { get; }

C#
public DateTime AddDays (
    double value
)

You have an object and want to add your own custom properties or methods (members) to that object.

Use the Add-Member cmdlet to add custom members to an object.

The Add-Member cmdlet is extremely useful in helping you add custom members to individual objects. For example, imagine that you want to create a report from the files in the current directory, and that report should include each file's owner. The Owner property is not standard on the objects that Get-ChildItem produces, but you could write a small script to add them, as shown in Example 3.9, “A script that adds custom properties to its output of file objects”.

$files = Get-ChildItem
foreach($file in $files)
{
    $owner = (Get-Acl $file).Owner
    $file | Add-Member NoteProperty Owner $owner
    $file
}
	

For more information about running scripts, see the section called “Run Programs, Scripts, and Existing Tools”.

Although it is most common to add static information (such as a NoteProperty), the Add-Member cmdlet supports several other property and method types—including AliasProperty, ScriptProperty, CodeProperty, CodeMethod, and ScriptMethod. For a more detailed description of these other property types, see the section called “Working with the .NET Framework”, as well as the help documentation for the Add-Member cmdlet.

Although the Add-Member cmdlet lets you to customize specific objects, it does not let you customize all objects of that type. For information on how to do that, see the following section the section called “Add Custom Methods and Properties to Types”.

Get-ChildItem |
  Select-Object Name,
      @{Name="Size (MB)"; Expression={ "{0,8:0.00}" -f ($_.Length / 1MB) } }

You want to return structured results from a command so that users can easily sort, group, and filter them.

Use the New-Object cmdlet to create a new PsObject, and then supply a hashtable with the custom information to the -Property parameter:

$output = @{
    'User' = 'DOMAIN\User';
    'Quota' = 100MB;
    'ReportDate' = Get-Date;
}

New-Object PsObject -Property $output

If you want to create a custom object with associated functionality, place the functionality in a module, and load that module with the -AsCustomObject parameter.

$obj = Import-Module PlottingObject -AsCustomObject
$obj.Move(10,10)

$obj.Points = SineWave
while($true) { $obj.Rotate(10); $obj.Draw(); Sleep -m 20 }

When your script outputs information to the user, always prefer richly-structured data over hand-formatted reports. By emitting custom objects, you give the end-user as much control over your script's output as PowerShell gives you over the output of its own commands.

Despite the power enabled by the output of custom objects, user-written scripts have frequently continued to generate plain text output. This can be partly blamed on PowerShell's previously cumbersome support for the creation and initialization of custom objects.

$output = New-Object PsObject
Add-Member -InputObject $output NoteProperty User 'DOMAIN\user'
Add-Member -InputObject $output NoteProperty Quota 100MB
Add-Member -InputObject $output NoteProperty ReportDate (Get-Date)

$output

In PowerShell version one, creating a custom object required creating a new object (of the type PsObject), and then calling the Add-Member cmdlet multiple times to add the desired information. As shown in the solution, PowerShell version two adds the -Property parameter to the New-Object cmdlet that makes this immensely easier.

While creating a new PsObject makes it easy to create data-centric objects (often called property bags), it does not let you add functionality to those objects. When you need functionality as well, the next step is to create a module, and import that module with the -AsCustomObject parameter. Any variables exported by that module become properties on the resulting object, and any functions exported by that module become methods on the resulting object.

<#

.EXAMPLE

Remove-Module PlottingObject
function SineWave { -15..15 | % { ,($_,(10 * [Math]::Sin($_ / 3))) } }
function Box { -5..5 | % { ($_,-5),($_,5),(-5,$_),(5,$_) } }

$obj = Import-Module PlottingObject -AsCustomObject
$obj.Move(10,10)

$obj.Points = SineWave
while($true) { $obj.Rotate(10); $obj.Draw(); Sleep -m 20 }

$obj.Points = Box
while($true) { $obj.Rotate(10); $obj.Draw(); Sleep -m 20 }

#>

$SCRIPT:x = 0
$SCRIPT:y = 0
$SCRIPT:angle = 0
$SCRIPT:xScale = -50,50
$SCRIPT:yScale = -50,50

$SCRIPT:Points = @()
Export-ModuleMember -Variable Points

function Rotate($angle)
{
    $SCRIPT:angle += $angle
}
Export-ModuleMember -Function Rotate

function Move($xDelta, $yDelta)
{
    $SCRIPT:x += $xDelta
    $SCRIPT:y += $yDelta
}
Export-ModuleMember -Function Move

function Draw
{
    $degToRad = 180 * [Math]::Pi
    Clear-Host

    PutPixel 0 0 +

    foreach($point in $points)
    {
        $pointX,$pointY = $point
        $pointX = $pointX + $SCRIPT:x
        $pointY = $pointY + $SCRIPT:y

        $newX = $pointX * [Math]::Cos($SCRIPT:angle / $degToRad ) -
            $pointY * [Math]::Sin($SCRIPT:angle / $degToRad )
        $newY = $pointY * [Math]::Cos($SCRIPT:angle / $degToRad ) +
            $pointX * [Math]::Sin($SCRIPT:angle / $degToRad )

        PutPixel $newX $newY O
    }

    [Console]::WriteLine()
}
Export-ModuleMember -Function Draw

function PutPixel($x, $y, $character)
{
    $scaledX = ($x - $xScale[0]) / ($xScale[1] - $xScale[0])
    $scaledX *= [Console]::WindowWidth

    $scaledY = (($y * 4 / 3) - $yScale[0]) / ($yScale[1] - $yScale[0])
    $scaledY *= [Console]::WindowHeight

    try
    {
        [Console]::SetCursorPosition($scaledX,
            [Console]::WindowHeight - $scaledY)
        [Console]::Write($character)
    }
    catch
    {
    }
}
      

For more information about creating modules, see the section called “Package Common Commands in a Module”.

If neither of these options suit your requirements (or if you need to create an object that can be consumed by other .NET libraries), use the Add-Type cmdlet. For more information about this approach, see the section called “Define or Extend a .NET Class”.

You want to add your own custom properties or methods to all objects of a certain type.

Use custom type extension files to add custom members to all objects of a type.

Although the Add-Member cmdlet is extremely useful in helping you add custom members to individual objects, it requires that you add the members to each object that you want to interact with. It does not let you automatically add them to all objects of that type. For that purpose, PowerShell supports another mechanism—custom type extension files.

Type extensions are simple XML files that PowerShell interprets. They let you (as the administrator of the system) easily add your own features to any type exposed by the system. If you write code (for example, a script or function) that primarily interacts with a single type of object, then that code might be better suited as an extension to the type instead.

For example, imagine a script that returns the free disk space on a given drive. That might be helpful as a script, but you might find it easier to instead make PowerShell's PSDrive objects themselves tell you how much free space they have left.

<?xml version="1.0" encoding="utf-8" ?>
<Types>
</Types>

$typeFile = (Join-Path (Split-Path $profile) "Types.Custom.ps1xml")
Update-TypeData -PrependPath $typeFile

<?xml version="1.0" encoding="utf-8" ?>
<Types>
  <Type>
    <Name>System.Management.Automation.PSDriveInfo</Name>
    <Members>
        add members such as <ScriptProperty> here
    <Members>
  </Type>
</Types>

<ScriptProperty>
  <Name>AvailableFreeSpace</Name>
  <GetScriptBlock>
    if($this.Provider.ImplementingType -eq
       [Microsoft.PowerShell.Commands.FileSystemProvider])
    {
       $driveRoot = $this.Root
       $fileZone = [System.Security.Policy.Zone]::CreateFromUrl(`
                 $driveRoot).SecurityZone
       if($fileZone -eq "MyComputer")
       {
          $drive = New-Object System.IO.DriveInfo $driveRoot
          $drive.AvailableFreeSpace
       }
    }
  </GetScriptBlock>
  <SetScriptBlock>
   $availableFreeSpace = $this.AvailableFreeSpace

   $spaceDifference = (([long] $args[0]) - $availableFreeSpace) / 1MB

   if($spaceDifference -gt 0)
   {
       $message = "To obtain $args bytes of free space, " +
          " free $spaceDifference megabytes."
       Write-Host $message
    }
   else
   {
       $spaceDifference = $spaceDifference * -1
       $message = "To obtain $args bytes of free space, " +
           " use up $spaceDifference more megabytes."
        Write-Host $message
    }
  </SetScriptBlock>
</ScriptProperty>

<AliasProperty>
  <Name>Free</Name>
  <ReferencedMemberName>AvailableFreeSpace</ReferencedMemberName>
</AliasProperty>

<ScriptMethod>
  <Name>Remove</Name>
  <Script>
    $force = [bool] $args[0]
    if($force)
    {
       $this | Remove-PSDrive
    }
    else
    {
       $this | Remove-PSDrive -WhatIf
    }
  </Script>
</ScriptMethod>