Windows PowerShell

By Bruce Payette

ABOUT WINDOWS POWERSHELL

Why PowerShell? Why Now? PowerShell was designed to do for Windows what the UNIX shells do for UNIX: provide a powerful, well-integrated command-line experience for the operation system. Unfortunately since Windows is mostly managed through objects (WMI, COM and .NET) this required creating a new kind of shell. So why create it now? As Windows moves off the desktop and into server farms or application servers like print, DNS and LDAP services, command-line automation becomes a fundamental requirement.

This refcard covers starting and using Windows PowerShell, including the syntax for all statements, operators and other elements of the language. Also included are examples of how to use .NET, COM, ADSI and WMI objects from PowerShell. Finally, it includes tips and tricks"short examples showing how to perform common tasks from PowerShell.

Getting Started with PowerShell

PowerShell is freely available through the Microsoft Windows Update Service packaged as an optional update for Windows XP SP2, Windows Vista and Windows Server 2003. It is also included with Windows Server 2008 as an optional component. Once installed, it can be started from the Start menu or simply by running "powershell.exe". Basic things you need to know:

• Use the "exit" keyword to exit the shell
• Ctrl-C will interrupt the current task returning you to the prompt
• A command can be spread over multiple lines and the interpreter will prompt for additional input. The line continuation character is the back-quote "`" (also called the back-tick).
• To get help about a command you can do "help command". The help command by itself will give you a list of topics.
• The help command supports wildcards so "help get-*" will return all of the commands that start with "get-".
• You can also get basic help on a command by doing "commandName -?" like "dir -?"
• As well as cmdlet help, there is a collection of general help topics prefixed with "about_". You can get a list of these topics by going help about_*

Command-Line editing in Powershell: Command-line Editing works just like it does in cmd.exe: use the arrow keys to go up and down, the insert and delete keys to insert and delete characters and so on.

The Language

PowerShell parses text in one of two modes"command mode, where quotes are not required around a string and expression mode where strings must be quoted. The parsing mode is determined by what"s at the beginning of the statement. If it"s a command, then the statement is parsed in command mode. If it"s not a command then the statement is parsed in expression mode as shown:

PS (1) > echo 2+2 Hi there # command mode " starts with "echo" command
2+2 Hi there
PS (2) > 2+2; "Hi there" # expression mode starts with 2
4
Hi there
PS (3) > echo (2+2) Hi (echo there) # Mixing and matching modes with brackets)
4 Hi there

Commands: There are 4 categories of commands in PowerShell:

Pipelines: As with any shell, pipelines are central to the operation of PowerShell. However, instead of returning strings from external processes, PowerShell pipelines are composed of collections of commands. These commands process pipeline objects one at a time, passing each object from pipeline element to pipeline element. Elements can be processed based on properties like Name and Length instead of having to extract substrings from the objects.

PowerShell Literals: PowerShell has the usual set of literal values found in dynamic languages: strings, numbers, arrays and hashtables.

Numbers: PowerShell supports all of the signed .NET number formats. Hex numbers are entered as they are in C and C# with a leading "0x" as in 0xF80e. Floating point includes Single and Double precisions and Decimal. Banker"s rounding is used when rounding values. Expressions are widened as needed. A unique feature in PowerShell are the multiplyer suffixes which make it convenient to enter larger values easily:

Strings: PowerShell uses .NET strings. Single and Double quoted strings are supported. Variable substitution and escape sequence processing is done in double-quoted strings but not in single quoted ones as shown:

PS (1) > $x="Hi"
PS (2) > "$x bob`nHow are you?"
Hi bob
How are you?
PS (3) > "$x bob`nHow are you?"
$x bob`nHow are you?

The escape character is backtick instead of backslash so that file paths can be written with either forward slash or backslash.

Variables: In PowerShell, variables are organized into namespaces. Variables are identified in a script by prefixing their names with a "$" sign as in "$x = 3". Variable names can be unqualified like $a or they can be name-space qualified like: $variable:a or $env:path. In the latter case, $env:path is the environment variable path. PowerShell allows you to access functions through the function names space: $function:prompt and command aliases through the alias namespace alias:dir

Arrays: Arrays are constructed using the comma "," operator. Unless otherwise specified, arrays are of type Object[]. Indexing is done with square brackets. The "+" operator will concatenate two arrays.

PS (1) > $a = 1, 2, 3
PS (2) > $a[1]
2
PS (3) > $a.length
3
PS (4) > [string] ($a + 4, 5)
1 2 3 4 5

Because PowerShell is a dynamic language, sometimes you don"t know if a command will return an array or a scalar. PowerShell solves this problem with the @( ) notation. An expression evaluated this way will always be an array. If the expression is already an array, it will simple be returned. If it wasn"t an array, a new single-element array will be constructed to hold this value.

HashTables: The PowerShell hashtable literal produces an instance of the .NET type System.Collections.Hashtable. The hashtable keys may be unquoted strings or expressions; individual key/value pairs are separated by either newlines or semicolons as shown:

PS (1) > $h = @{a=1; b=2+2
>> ("the" + "date") = get-date}
>>
PS (2) > $h
Name Value
---- -----
thedate 10/24/2006 9:46:13 PM
a 1
b 4
PS (3) > $h["thedate"]
Tuesday, October 24, 2006 9:46:13 PM
PS (4) > $h.thedate
Tuesday, October 24, 2006 9:46:13 PM
@{ a=1; b=2}
Types
[typename]

Type Conversions: For the most part, traditional shells only deal with strings. Individual tools would have to interpret (parse) these strings themselves. In PowerShell, we have a much richer set of objects to work with. However, we still wanted to preserve the ease of use that strings provide. We do this through the PowerShell type conversion subsystem. This facility will automatically convert object types on demand in a transparent way. The type converter is careful to try and not lose information when doing a conversion. It will also only do one conversion step at a time. The user may also specify explicit conversions and, in fact, compose those conversions. Conversions are typically applied to values but they may also be attached to variables in which case anything assigned to that variable will be automatically be converted.

Here"s is an example where a set of type constraints are applied to a variable. We want anything assigned to this variable to first be converted into a string, then into an array of characters and finally into the code points associated with those characters.

PS (1) > [int[]][char[]][string]$v = @()                # define variable
PS (2) > $v = "Hello"                                   # assign a string
PS (3) > [string] $v                                    # display the code points
72 101 108 108 111
101
108
108
111
PS (4) > $v=2+2                                         # assign a number
PS (5) > $v                                             # display the code points
52
PS (6) > [char] 52                                      # cast it back to char

Flow-control Statements: PowerShell has the usual collection of looping and branching statements. One interesting difference is that in many places, a pipeline can be used instead of a simple expression.

if Statement:

if ($a "eq 13) { "A is 13} else {"A is not 13"}

The condition part of an if statement may also be a pipeline.

if (dir | where {$_.length "gt 10kb}) {
"There were files longer than 10kb"
}

while Loop:

$a=1; while ($a "lt 10) { $a }
$a=10 ; do { $a } while (--$a)

for Loop:

for ($i=0; $i "lt 10; $i++) {
"5 * $i is $(5 * $i)"
}

foreach Loop:

foreach ($i in 1..10) { "`$i is $i" }
foreach ($file in dir "recurse "filter *.cs  sort length)
{
$_.Filename
}|

foreach Cmdlet: This cmdlet can be used to iterate over collections of operators (similar to the map() operation found in many other languages like Perl.) There is a short alias for this command "%". Note that the $_ variable is used to access the current pipeline object in the foreach and where cmdlets.

1..10  foreach { $_ * $_ }
$t = 0; dir | foreach { $t += $_ } ; $t
1..10 | %{ "*" * $_ }|

where Cmdlet: This cmdlet selects a subset of objects from a stream based on the evaluation of a condition. The short alias for this command is "?".

1..10  where {$_ -gt 2 "and $_ -lt 10}
get-process | where {$_.handlecount "gt 100 }|

switch Statement: The PowerShell switch statement combines both branching and looping. It can be used to process collections of objects in the condition part of the statement or it can be used to scan files using the "file option.

Operators

PowerShell has a very rich set of operators for working with numbers, strings, collections and objects. These operators are shown in the following tables.

Arithmetic operators: The arithmetic operators work on numbers. The "+" and "*" operators also work on collections. The "+" operator concatenates strings and collections or arrays. The "*" operator will duplicate a collection the specified number of times.

Assignment Operators: PowerShell has the set of assignment operators commonly found in C-derived languages. The semantics correspond to the binary forms of the operator.

Comparison Operators: Most of the PowerShell operators are the same as are usually found in C-derived languages. The comparison operators, however, are not. To allow the ">" and "<" operators to be used for redirection, a different set of characters had to be chosen so PowerShell operators match those found in the Bourne shell style shell languages. (Note: when applying a PowerShell operator against collection, the elements of the collection that compare appropriately will be returned instead of a simple Boolean.)

Pattern Matching Operators: PowerShell supports two sets of pattern-matching operators. The first set uses regular expressions and the second uses wildcard patterns (sometimes called globbing patterns).

[console]::In.ReadToEnd() > foo.txt

function prompt { "$PWD [" + $count++ + "]" }

$host.UI.RawUI.WindowTitle = "PATH: $PWD"

Regular Expression Patterns: PowerShell regular expressions are implemented using the .NET regular expressions.

PowerShell Functions: Functions can be defined with the function keyword. Since PowerShell is a shell, every statement in a PowerShell function may return a value. Use redirection to $null to discard unnecessary output. The following diagram shows a simple function definition.

Advanced Functions: functions can also be defined like cmdlets with a begin, process and end clause for handling processing in each stage of the pipeline.

Unary Operators:

Basic Tasks - Text and Files

In general, the easiest way to get things done in PowerShell is with cmdlets. Basic file operations are carried out with the "core" cmdlets. These cmdlets work on any namespace. This means that you can use them to manipulate files and directories but can also use them to list the defined variables by doing

dir variables:

or remove a function called "junk" by doing:

del function:/junk

I/O Redirection

Searching Through Text: The fastest way to search through text and files is to use the select-string cmdlet as shown:

select-string Username *.txt "case               # case-sensitive search for Username
dir "rec "filter *.txt  select-string            # case-insensitive search                          
                                                 # through a set of files
dir "rec "filter *.cs |
select-string "list Main                         # only list the first match|

The Select-String cmdlet is commonly aliased to "grep" by UNIX users.

Formatting and Output: by default the output of any expression that isn"t redirected will be displayed by PowerShell. The default display mode can be overridden using the formatting cmdlets:

Output is also handled by a set of cmdlets that send the output to different locations.

ErrorForegroundColor : Red
ErrorBackgroundColor : Black
WarningForegroundColor : Yellow
WarningBackgroundColor : Black
DebugForegroundColor : Yellow
DebugBackgroundColor : Black
VerboseForegroundColor : Yellow
VerboseBackgroundColor : Black
ProgressForegroundColor : Yellow
ProgressBackgroundColor : DarkCyan

Types and Objects

Unlike most scripting languages, the basic object model for PowerShell is .NET which means that instead of a few simple built-in types, PowerShell has full access to all of the types in the .NET framework. Since there are certain common types that are used more often than others, PowerShell includes shortcuts or type accelerators for those types. The set of accelerators is a superset of the type shortcuts in C#. (Note: a type literal in Powershell is specified by using the type name enclosed in square brackets like [int] or [string].

Operators For Working With Types

Accessing Instance Members: as is the case with most object oriented languages, instance members (fields, properties and method) are accesses through the dot "." operator.

"Hi there".length
"Hi there".SubString(2,5)

The dot operator can also be used with an argument on the right hand side:

"Hi there".("len" + "th")

Methods can also be invoked indirectly:

$m = "Hi there".substring
$m.Invoke(2,3)

Static methods are invoked using the "::" operator with an expression that evaluates to a type on the left-hand side and a member on the right hand side

[math]::sqrt(33)
$m = [math]
$m::pow(2,8)

Working With Collections: Foreach-Object, Where-Object

The .NET Framework

Loading Assemblies:

[void][reflection.assembly]::LoadWithPartialName
("System.Windows.Forms")

Using Windows Forms to do GUI Programming from PowerShell:

$form = new-object Windows.Forms.Form
$form.Text = "My First Form"
$button = new-object Windows.Forms.Button
$button.text="Push Me!"
$button.Dock="fill"
$button.add_click({$form.close()})
$form.controls.add($button)
$form.Add_Shown({$form.Activate()})
$form.ShowDialog()

$now = get-date; $now

$now = [datetime]::now ; $now

$thisYear = [datetime]"2006/01/01"

$now.DayOfWeek

($now-$thisyear).TotalDays

($now-$thisyear).TotalHours

(([datetime] "12/25/2006")-$now).TotalDays

([datetime] "12/25/2006").DayOfWeek

COM (Component Object Model)

Along with .NET, PowerShell also lets you work with COM object. This is most commonly used as the Windows automation mechanism. The following example shows how the Microsoft Word automation model can be used from PowerShell:

Listing: Get-Spelling Script" this script uses Word to spell check a document

if ($args.count -gt 0)
{ #1
@"
Usage for Get-Spelling:

Copy some text into the clipboard, then run this script. It will display the Word spellcheck tool that will let you correct the spelling on the text you"ve selected. When you"re done it will put the text back into the clipboard so you can paste back into the original document.

"@
exit 0
}

$shell = new-object -com wscript.shell
$word = new-object -com word.application
$word.Visible = $false

$doc = $word.Documents.Add()
$word.Selection.Paste()

if ($word.ActiveDocument.SpellingErrors.Count -gt 0)
{
$word.ActiveDocument.CheckSpelling()
$word.Visible = $false
$word.Selection.WholeStory()
$word.Selection.Copy()
$shell.PopUp( "The spell check is complete, " +
"the clipboard holds the corrected text." )
}
else
{
[void] $shell.Popup("No Spelling Errors were detected.")
}

$x = [ref] 0
$word.ActiveDocument.Close($x)
$word.Quit()

$pat = [regex] "[0-9]+\+|\-|\*|/| +"
$m = $pat.match("11+2 * 35 -4")
while ($m.Success) {
$m.value
$m = $m.NextMatch()
}|

WMI (Windows Management Infrastructure)

The other major object model used in PowerShell is WMI"Windows Management Infrastructure. This is Microsoft"s implementation of the Common Instrumentation Model or CIM. CIM is an industry standard created by Microsoft, HP, IBM and many other computer companies with the intent of coming up with a common set of management abstractions. WMI is accessed in PowerShell through the Get-WMIObject cmdlet and through the [WMI] [WMISearcher] type accelerators. For example, to get information about the BIOS on your computer, you could do:

PS (1) > (Get-WmiObject win32_bios).Name
v3.20

ADSI (active directory)

Support for active directory is accomplished through type accelerators. A string can be cast into an ADSI (LDAP) query and then used to manipulate the directory as shown:

$domain = [ADSI] `
>> "LDAP://localhost:389/dc=NA,dc=fabrikam,dc=com"
PS (2) > $newOU = $domain.Create("OrganizationalUnit", "ou=HR")
PS (3) > $newOU.SetInfo()
PS (5) > $ou = [ADSI] `
>> "LDAP://localhost:389/ou=HR,dc=NA,dc=fabrikam,dc=com"
>>
PS (7) > $newUser.Put("title", "HR Consultant")
PS (8) > $newUser.Put("employeeID", 1)
PS (9) > $newUser.Put("description", "Dog")
PS (10) > $newUser.SetInfo()
PS (12) > $user = [ADSI] ("LDAP://localhost:389/" +
>> "cn=Dogbert,ou=HR,dc=NA,dc=fabrikam,dc=com")
>>

Building Custom Objects in Powershell

PowerShell has no language support for creating new types. Instead this is done through a series of commands that allow you to add members (properties, fields and methods) to existing object. Here"s an example:

PS (1) > $a = 5 # assign $a the integer 5
PS (2) > $a.square()
Method invocation failed because [System.Int32] doesn"t contain a method named "square".
At line:1 char:10
+ $a.square( <<<< )
PS (3) > $a = 5  add-member -pass scriptmethod square {$this * $this}
PS (4) > $a
5
PS (5) > $a.square()
25
PS (6) > $a.gettype().Fullname
System.Int32|

Working With XML Data: PowerShell directly supports XML. XML documents can be created with a simple cast and document elements can be accessed as though they were properties.

PS (1) > $d = [xml] "<a><b>1</b><c>2</c></a>"
PS (2) > $d.a.b
1
PS (3) > $d.a.c
2

Building Custom Objects in PowerShell

Errors and Debugging: The success or failure status of the last command can be determined by checking $?. A command may also have set a numeric code in the $LASTEXITCODE variables. (This is typically done by external applications.)

PS (11) > "exit 25" > invoke-exit.ps1
PS (12) > ./invoke-exit
PS (13) > $LASTEXITCODE

The default behavior when an error occurs can be controlled globally with the $ErrorActionPreference variable or, for a single command, with the -ErrorAction Parameter.

The trap Statement: will catch any exceptions thrown in a block. The behavior of the trap statement can be altered with the break and continue statements.

The throw Statement: along with the trap statement, there is a throw statement. This statement may be used with no arguments in which case a default exception will be constructed. Alternatively, an arbitrary value may be thrown that will be automatically wrapped in a PowerShell runtime exception.

"0x{0:X} {1:hh} {2,5}|{3,-5}|{4,5}" -f 255, (get-date), "a","b","c"|

About The Author

Bruce Payette

Bruce Payette is a Principal Developer with the Windows PowerShell team at Microsoft. He is a founding member of the PowerShell team, co-designer of the PowerShell language and implementer of the language. Prior to joining Microsoft to try and fix the Windows command-line, he worked at a variety of companies including MKS and Softway Systems (the makers of Interix), trying to fix the Windows command line. Bruce lives in Bellevue, Washington, with his wife and three extremely over-bonded cats.

Publications

• Windows PowerShell in Action, 2006

Recommended Book

Windows PowerShell in Action is a logically oriented and clearly expressed introduction to a big subject. It is also an invaluable guide for veterans to the expert techniques they need to know to draw a lot more power of this incredible tool.

---

BUY NOW

books.dzone.com/books/windowsps-in-action