Bruce Payette SECOND EDITION
Covers PowerShell v 2
PRAISE FOR THE FIRST EDITION
The book on PowerShell, it has all the secrets.
—James Truher, PowerShell Program Manager, Microsoft If all it had going for it was the authoritative pedigree of the writer, it might be worth it, but it’s also well-written, well-organized, and thorough, which I think makes it invaluable as both a learning tool and a reference.
—Slashdot.org
...an encyclopedic tome of PowerShell scripting bringing the reader through the basics with simple shell scripts through powerful and flexible scripts any Windows systems administrator will find immediately useful.
—ArsGeek.com
The nuances of PowerShell from the lead language designer himself! Excellent content and easy read- ability!
—Keith Hill, Software Architect
[It gives you] inside information, excellent examples, and a colorful writing style.
—Marc van Orsouw (MOW), PowerShell MVP There’s no better way to learn PowerShell than from someone on the core PowerShell team—and that’s exactly what you get with this book.
—Joe Topjian, adminspotting.net
Where’s the 6 stars option? I haven’t enjoyed a software engineering book to the same extent for a long time.
—T. Kirby Green, Technical Architect, SunGard
Consider this book the definitive reference for PowerShell. As one of the designers of the PowerShell environment, the author knows all the ins and outs, back alleys, hidden rooms, and secret handshakes the language offers, and isn’t afraid to grab you by the hand and drag you along (like it or not!) for the tour of your life.
—Jase T. Wolfe, Amazon reader I love this book!
—Scott Hanselman ComputerZen.com
Windows PowerShell
in Action, Second Edition
B RUCE P AYETTE
M A N N I N G
Shelter Island
For online information and ordering of this and other Manning books, please visit www.manning.com. The publisher offers discounts on this book when ordered in quantity.
For more information, please contact:
Special Sales Department Manning Publications Co.
20 Baldwin Road PO Box 261
Shelter Island, NY 11964 Email: orders@manning.com
©2011 by Manning Publications Co. All rights reserved.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by means electronic, mechanical, photocopying, or otherwise, without prior written permission of the publisher.
Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in the book, and Manning
Publications was aware of a trademark claim, the designations have been printed in initial caps or all caps.
Recognizing also our responsibility to conserve the resources of our planet, Manning books are printed on paper that is at least 15 percent recycled and processed without the use of elemental chlorine
Manning Publications Co. Development Editor Cynthia Kane
20 Baldwin Road Copyeditor: Liz Welch
PO Box 261 Typesetter: Marija Tudor
Shelter Island, NY 11964 Cover designer: Marija Tudor
ISBN 9781935182139
Printed in the United States of America
1 2 3 4 5 6 7 8 9 10 – MAL – 16 15 14 13 12 11
v
brief contents
Part 1 Learning PowerShell 1
1 Welcome to PowerShell 3 2 Foundations of PowerShell 36 3 Working with types 72
4 Operators and expressions 110
5 Advanced operators and variables 151 6 Flow control in scripts 198
7 PowerShell functions 236
8 Advanced functions and scripts 275 9 Using and authoring modules 322 10 Module manifests and metadata 361
11 Metaprogramming with scriptblocks and dynamic code 392 12 Remoting and background jobs 447
13 Remoting: configuring applications and services 502 14 Errors and exceptions 553
15 The PowerShell ISE and debugger 606
Part 2 Using PowerShell 661
16 Working with files, text, and XML 663 17 Extending your reach with .NET 719 18 Working with COM 760
19 Management objects: WMI and WS-MAN 797
20 Responding in real time with eventing 847
21 Security, security, security 888
vii
contents
preface xix
acknowledgments xxi about this book xxiii
about the cover illustration xxix
Part 1 Learning PowerShell 1
1 Welcome to PowerShell 3
1.1 What is PowerShell? 5
Shells, command lines, and scripting languages 6 ✦ Why a new shell? Why now? 7 ✦ The last mile problem 8
1.2 Soul of a new language 9
Learning from history 9 ✦ Leveraging .NET 10 1.3 Brushing up on objects 11
Reviewing object-oriented programming 11 ✦ Objects in PowerShell 13
1.4 Up and running with PowerShell 13
PowerShell 14 ✦ Starting PowerShell 14 ✦ The PowerShell console host 14 ✦ The PowerShell Integrated Scripting Environment 17 ✦ Command completion 20 1.5 Dude! Where’s my code? 22
Navigation and basic operations 22 ✦ Basic expressions and variables 23 ✦ Processing data 25 ✦ Flow control
statements 30 ✦ Scripts and functions 31 ✦ Remoting and the Universal Execution Model 32
1.6 Summary 35
2 Foundations of PowerShell 36
2.1 Getting a sense of the PowerShell language 37 2.2 The core concepts 38
Command concepts and terminology 38 ✦ Commands and cmdlets 38 ✦ Command categories 42
2.3 Aliases and elastic syntax 46 2.4 Parsing and PowerShell 50
How PowerShell parses 51 ✦ Quoting 51 ✦ Expression- mode and command-mode parsing 54 ✦ Statement termination 56 ✦ Comment syntax in PowerShell 58 2.5 How the pipeline works 60
Pipelines and streaming behavior 61 ✦ Parameters and parameter binding 62
2.6 Formatting and output 64
The formatting cmdlets 64 ✦ The outputter cmdlets 67 2.7 Summary 70
3 Working with types 72
3.1 Type management in the wild, wild West 72
PowerShell: a type-promiscuous language 73 ✦ The type system and type adaptation 75
3.2 Basic types and literals 77
String literals 77 ✦ Numbers and numeric literals 82 3.3 Collections: dictionaries and hash tables 85
Creating and inspecting hash tables 85 ✦ Modifying and manipulating hash tables 88 ✦ Hash tables as reference types 90
3.4 Collections: arrays and sequences 91
Collecting pipeline output as an array 91 ✦ Array indexing 92 ✦ Polymorphism in arrays 92 ✦ Arrays as reference types 93 ✦ Singleton arrays and empty arrays 94 3.5 Type literals 96
Type name aliases 96 ✦ Generic type literals 98 ✦ Accessing static members with type literals 99
3.6 Type conversions 101
How type conversion works 101 ✦ PowerShell’s type- conversion algorithm 104 ✦ Special type conversions in parameter binding 107
3.7 Summary 109
CONTENTS ix
4 Operators and expressions 110
4.1 Arithmetic operators 112
The addition operator 113 ✦ The multiplication operator 116 Subtraction, division, and the modulus operator 117
4.2 The assignment operators 119
Multiple assignments 120 ✦ Multiple assignments with type qualifiers 121 ✦ Assignment operations as
value expressions 123 4.3 Comparison operators 124
Scalar comparisons 125 ✦ Comparisons and case sensitivity 127 ✦ Using comparison operators with collections 129
4.4 Pattern matching and text manipulation 131
Wildcard patterns and the -like operator 132 ✦ Regular expressions 133 ✦ The -match operator 134 ✦ The -replace operator 137 ✦ The -join operator 139 ✦ The -split operator 143
4.5 Logical and bitwise operators 148 4.6 Summary 150
5 Advanced operators and variables 151
5.1 Operators for working with types 152 5.2 The unary operators 154
5.3 Grouping and subexpressions 157
Subexpressions $( ... ) 159 ✦ Array subexpressions @( ... ) 160 5.4 Array operators 162
The comma operator 162 ✦ The range operator 165 Array indexing and slicing 167 ✦ Using the range operator with arrays 170 ✦ Working with multidimensional arrays 171
5.5 Property and method operators 173
The dot operator 174 ✦ Static methods and the double-colon operator 177 ✦ Indirect method invocation 178
5.6 The format operator 179
5.7 Redirection and the redirection operators 181 5.8 Working with variables 184
Creating variables 185 ✦ Variable name syntax 186 Working with the variable cmdlets 188
Splatting a variable 193 5.9 Summary 196
6 Flow control in scripts 198
6.1 The conditional statement 200 6.2 Looping statements 203
The while loop 203 ✦ The do-while loop 204 ✦ The for loop 205 ✦ The foreach loop 207
6.3 Labels, break, and continue 212 6.4 The switch statement 215
Basic use of the switch statement 215 ✦ Using wildcard patterns with the switch statement 216 ✦ Using regular expressions with the switch statement 217 ✦ Processing files with the switch statement 221 ✦ Using the $switch loop enumerator in the switch statement 222
6.5 Flow control using cmdlets 223
The ForEach-Object cmdlet 223 ✦ The Where-Object cmdlet 228
6.6 Statements as values 231 6.7 A word about performance 233 6.8 Summary 234
7 PowerShell functions 236
7.1 Fundamentals of PowerShell functions 237
Passing arguments using $args 237 ✦ Example functions:
ql and qs 239 ✦ Simplifying $args processing with multiple assignment 240
7.2 Declaring formal parameters for a function 241
Mixing named and positional parameters 242 ✦ Adding type constraints to parameters 243 ✦ Handling variable numbers of arguments 245 ✦ Initializing function parameters with default values 246 ✦ Handling mandatory parameters, v1-style 248 Using switch parameters to define command switches 248 Switch parameters vs. Boolean parameters 252
7.3 Returning values from functions 257
Debugging problems in function output 259 ✦ The return statement 262
7.4 Using simple functions in a pipeline 263
Filters and functions 265 ✦ Functions with begin, process, and end blocks 266
7.5 Managing function definitions in a session 267
CONTENTS xi 7.6 Variable scoping in functions 269
Declaring variables 270 ✦ Using variable scope modifiers 272 7.7 Summary 273
8 Advanced functions and scripts 275
8.1 PowerShell scripts 276
Script execution policy 276 ✦ Passing arguments to scripts 278 ✦ Exiting scripts and the exit statement 280 Scopes and scripts 281 ✦ Managing your scripts 284 Running PowerShell scripts from other applications 285 8.2 Writing advanced functions and scripts 287
Specifying script and function attributes 288 ✦ The CmdletBinding attribute 289 ✦ The OutputType attribute 293 ✦ Specifying parameter attributes 296 Creating parameter aliases with the Alias attribute 303 Parameter validation attributes 305
8.3 Dynamic parameters and dynamicParam 311
Steps for adding a dynamic parameter 312 ✦ When should dynamic parameters be used? 314
8.4 Documenting functions and scripts 314
Automatically generated help fields 315 ✦ Creating manual help content 315 ✦ Comment-based help 316 ✦ Tags used in documentation comments 318
8.5 Summary 321
9 Using and authoring modules 322
9.1 The role of a module system 323
Module roles in PowerShell 324 ✦ Module mashups: composing an application 324
9.2 Module basics 325
Module terminology 326 ✦ Modules are single-instance objects 326
9.3 Working with modules 327
Finding modules on the system 327 ✦ Loading a module 331 Removing a loaded module 335
9.4 Writing script modules 337
A quick review of scripts 338 ✦ Turning a script into a module 340 ✦ Controlling member visibility with Export- ModuleMember 343 ✦ Installing a module 347 ✦ How scopes work in script modules 348 ✦ Nested modules 350
9.5 Binary modules 353
Binary modules versus snap-ins 354 ✦ Creating a binary module 355 ✦ Nesting binary modules in script modules 357 9.6 Summary 360
10 Module manifests and metadata 361
10.1 Module folder structure 362 10.2 Module manifest structure 363 10.3 Production manifest elements 366
Module identity 368 ✦ Runtime dependencies 368 10.4 Construction manifest elements 370
The loader manifest elements 371 ✦ Module component load order 374
10.5 Content manifest elements 375 10.6 Language restrictions in a manifest 376 10.7 Advanced module operations 378
The PSModuleInfo object 378 ✦ Using the PSModuleInfo methods 382 ✦ The defining module versus the calling module 384 ✦ Setting module properties from inside a script module 388 ✦ Controlling when modules can be unloaded 388 Running an action when a module is removed 389
10.8 Summary 390
11 Metaprogramming with scriptblocks and dynamic code 392
11.1 Scriptblock basics 393
Invoking commands 394 ✦ The scriptblock literal 397 Defining functions at runtime 398
11.2 Building and manipulating objects 400
Looking at members 400 ✦ Using Add-Member to extend objects 402 ✦ Adding note properties with New-Object 409
11.3 Using the Select-Object cmdlet 410 11.4 Dynamic modules 412
Dynamic script modules 412 ✦ Closures in PowerShell 414 Creating custom objects from modules 417
11.5 Steppable pipelines 418
How steppable pipelines work 418 ✦ Creating a proxy command with steppable pipelines 420
11.6 A closer look at the type-system plumbing 423 Adding a property 425 ✦ Shadowing an existing property 427
CONTENTS xiii 11.7 Extending the PowerShell language 428
Little languages 428 ✦ Adding a CustomClass keyword to PowerShell 428 ✦ Type extension 433
11.8 Building script code at runtime 436
The Invoke-Expression cmdlet 436 ✦ The ExecutionContext variable 437 ✦ The ExpandString() method 437 ✦ The InvokeScript() method 438 ✦ Mechanisms for creating scriptblocks 438 ✦ Creating functions using the function:
drive 439
11.9 Compiling code with Add-Type 440
Defining a new .NET class: C# 440 ✦ Defining a new enum at runtime 442 ✦ Dynamic binary modules 443
11.10 Summary 445
12 Remoting and background jobs 447
12.1 Getting started with remoting 448
Commands with built-in remoting 448 ✦ The PowerShell remoting subsystem 449 ✦ Enabling remoting 450 Additional setup steps for workgroup environments 451 Enabling remoting in the enterprise 452
12.2 Applying PowerShell remoting 454
Basic remoting examples 454 ✦ Adding concurrency to the examples 455 ✦ Solving a real problem: multimachine monitoring 457
12.3 Sessions and persistent connections 462
Additional session attributes 466 ✦ Using the New-PSSession cmdlet 468 ✦ Interactive sessions 469 ✦ Managing PowerShell sessions 472
12.4 Implicit remoting 473
Using implicit remoting 474 ✦ How implicit remoting works 476
12.5 Background jobs in PowerShell 481
The job commands 483 ✦ Working with the job cmdlets 483 Working with multiple jobs 487 ✦ Starting jobs on remote computers 489 ✦ Running jobs in existing sessions 492 12.6 Considerations when running commands remotely 493
Remote session startup directory 494 ✦ Profiles and remoting 494 ✦ Issues running executables remotely 495 Reading and writing to the console 496 ✦ Remote output vs. local output 497 ✦ Processor architecture issues 498
12.7 Summary 500
13 Remoting: configuring applications and services 502
13.1 Remoting infrastructure in depth 503
The PowerShell remoting protocol stack 503 ✦ Using the WSMan cmdlets and providers 509 ✦ Authenticating the target computer 511 ✦ Authenticating the connecting user 514 Addressing the remoting target 518 ✦ Windows version-specific connection issues 520 ✦ Managing resource consumption 522 13.2 Building custom remoting services 527
Remote service connection patterns 527 ✦ Working with custom configurations 530 ✦ Creating a custom configuration 531 Access controls and endpoints 533 ✦ Constraining a PowerShell session 535 ✦ Creating a constrained execution environment 543 13.3 Summary 551
14 Errors and exceptions 553
14.1 Error handling 554
ErrorRecords and the error stream 555 ✦ The $error variable and –ErrorVariable parameter 560 ✦ Determining if a command had an error 564 ✦ Controlling the actions taken on an error 566 14.2 Dealing with errors that terminate execution 569
The trap statement 570 ✦ The try/catch/finally statement 575 The throw statement 578
14.3 Debugging with the host APIs 580
Catching errors with strict mode 582 ✦ The Set-StrictMode cmdlet in PowerShell v2 584 ✦ Static analysis of scripts 589 14.4 Capturing session output 593
Starting the transcript 593 ✦ What gets captured in the transcript 595
14.5 PowerShell and the event log 597
The EventLog cmdlets 597 ✦ Examining the PowerShell event log 603
14.6 Summary 605
15 The PowerShell ISE and debugger 606
15.1 The PowerShell ISE 607
Controlling the ISE pane layout 607 ✦ Using the ISE editor 610 ✦ Executing commands in the ISE 614 Considerations when running scripts in the ISE 616 15.2 Using multiple PowerShell tabs 618
Local in-memory session tabs 619 ✦ Remote session tabs in PowerShell ISE 619
CONTENTS xv 15.3 Extending the ISE 622
The $psISE variable 622 ✦ Using the Options property 624 Managing tabs and files 625 ✦ Working with text panes 629 Adding a custom menu 633
15.4 PowerShell script debugging features 638
The Set-PSDebug cmdlet 638 ✦ Nested prompts and the Suspend operation 643
15.5 The PowerShell v2 debugger 647 The graphical debugger 648 15.6 Command-line debugging 652
Working with breakpoint objects 653 ✦ Setting breakpoints on commands 656 ✦ Setting breakpoints on variable assignment 657 ✦ Debugger limitations and issues 658 15.7 Summary 659
Part 2 Using PowerShell 661
16 Working with files, text, and XML 663
16.1 PowerShell and paths 664
Providers and the core cmdlets 664 ✦ Working with PSDrives 665 ✦ Working with paths that contain wildcards 667 ✦ Suppressing wildcard processing in paths 668 ✦ The -LiteralPath parameter 670 The Registry provider 671
16.2 File processing 672
Reading and writing files 674 ✦ Writing files 679 ✦ All together now—reading and writing 680 ✦ Performance caveats with Get-Content 680
16.3 Processing unstructured text 681
Using System.String to work with text 681 ✦ Using hashtables to count unique words 684 ✦ Using regular expressions to
manipulate text 686 ✦ Searching files with the Select-String cmdlet 688
16.4 XML structured text processing 693
Using XML as objects 693 ✦ Adding elements to an XML object 695 ✦ Loading and saving XML files 697
Processing XML documents in a pipeline 701 ✦ Processing XML with XPath 702 ✦ A hint of XLinq 709 ✦ Rendering objects as XML 711
16.5 Summary 717
17 Extending your reach with .NET 719
17.1 Using .NET from PowerShell 720
.NET basics 720 ✦ Working with assemblies 721 ✦ Finding types 725 ✦ Creating instances of types 727 ✦ Defining new types with Add-Type 729 ✦ Working with generic types 739 17.2 PowerShell and the internet 740
Retrieving a web page 740 ✦ Processing an RSS feed 742 17.3 PowerShell and graphical user interfaces 743
PowerShell and WinForms 744 ✦ Creating a winforms module 750
PowerShell and Windows Presentation Foundation 753 17.4 Summary 759
18 Working with COM 760
18.1 Working with COM in PowerShell 761
Creating COM objects 761 ✦ Identifying and locating COM classes 762
18.2 Automating Windows with COM 764
Exploring with the Shell.Application class 765 ✦ Managing browser windows using COM 767 ✦ A browser window management module 770
18.3 Working with the WScript.Shell class 777 18.4 Using COM to manage applications 779
Looking up a word using Internet Explorer 779 ✦ Using Microsoft Word to do spell checking 781
18.5 The WSH ScriptControl class 783
Embedding VBScript code in a PowerShell script 784 Embedding JScript code in a PowerShell script 785 18.6 Working with the Windows Task Scheduler 786
Getting started with the Schedule.Service class 786 ✦ Listing running tasks 787 ✦ Creating a new scheduled task 788 Credentials and scheduled tasks 789 ✦ Viewing the life cycle of a task 792
18.7 Issues with COM 793
64-bit vs. 32-bit issues 793 ✦ Threading model problems 793 Interop assemblies, wrappers, and typelibs 793
18.8 Summary 795
19 Management objects: WMI and WS-MAN 797
19.1 Working with WMI in PowerShell 798
Exploring WMI 798 ✦ The WMI infrastructure 799
CONTENTS xvii 19.2 The WMI cmdlets 801
The WMI cmdlet common parameters 802 ✦ The Get-WmiObject cmdlet 804 ✦ The Set-WmiInstance cmdlet 813 ✦ The Invoke-WmiMethod cmdlet 819 ✦ The Remove-WmiObject cmdlet 822
19.3 The WMI object adapter 824
The WMI type accelerators 825 ✦ Putting modified WMI objects back 828
19.4 Exploring WS-Man 830
The WS-Man cmdlets 831 ✦ Using Get-WSManInstance to retrieve management data 832 ✦ Updating resources using Set-WSManInstance 840 ✦ Invoking methods with Invoke-WSManAction 841
19.5 Summary 845
20 Responding in real time with eventing 847
20.1 Foundations of event handling 848 20.2 Synchronous events 849
Synchronous eventing in GUIs 850 ✦ Delegates and delegation 850
20.3 Asynchronous events 853
Subscriptions, registrations, and actions 854 ✦ The eventing cmdlets 854
20.4 Working with asynchronous .NET events 855 Writing a timer event handler 856 ✦ Managing event subscriptions 859
20.5 Asynchronous event handling with scriptblocks 860 Automatic variables in the event handler 860 ✦ Dynamic modules and event handler state 862
20.6 Queued events and the Wait-Event cmdlet 863 20.7 Working with WMI events 866
WMI event basics 866 ✦ Class-based WMI event registration 867 ✦ Query-based WMI event registrations 871
20.8 Engine events 875
Predefined engine events 875 ✦ Generating events in functions and scripts 876
20.9 Remoting and event forwarding 877
Handling remote EventLog events 879 ✦ Serialization issues with remote events 880
20.10 How eventing works 882
20.11 Summary 885
21 Security, security, security 888
21.1 Introduction to security 889
What security is and what it isn’t 889 ✦ Security: perception and reality 890
21.2 Security modeling 891
Introduction to threat modeling 891 ✦ Classifying threats using the STRIDE model 892 ✦ Security basics: threats, assets, and mitigations 893
21.3 Securing the PowerShell environment 897
Secure by default 897 ✦ Enabling scripting with execution policy 898
21.4 Signing scripts 904
How public key encryption and one-way hashing work 904 Signing authorities and certificates 905 ✦ Self-signed certificates 905 ✦ Using a certificate to sign a script 909
Enabling strong private key protection 913 ✦ Using the PFX file to sign a file 915
21.5 Writing secure scripts 916 21.6 Using the SecureString class 916
Creating a SecureString object 917 ✦ The SecureString cmdlets 918 ✦ Working with credentials 919 ✦ Avoiding Invoke-Expression 923
21.7 Summary 926
index 929
appendix A Comparing PowerShell to other languages appendix B Examples
appendix C PowerShell Quick Reference appendix D Additional PowerShell topics
Appendixes are available for download from
www.manning.com/WindowsPowerShellinActionSecondEdition
xix
preface
Well, it’s been a wild ride since the first edition of this book was released. At that time, PowerShell had just shipped and had a fairly limited scope of influence. Things have changed a lot. PowerShell now ships in the box with Windows (at least Win- dows 7 and Server 2008 R2). The number of PowerShell users is now in the hundreds of thousands, if not millions (this is not a formal estimate—I just looked at some of the download counters for PowerShell-related tools and went from there).
One of the biggest events from my perspective was the release of PowerShell version 2 in July of 2009. Obviously it was time for a sequel to the book. I put together a short proposal and estimate of the amount of work needed to update the book. The initial estimate was for a few months of work—a couple of new chapters, a few updates here and there, and we’re good to go. Wow, was I ever wrong about that! PowerShell v2 was a really big release.
When you are in the middle of something, working heads down, you tend to lose perspective of the overall project—that old forest/trees problem. It wasn’t until I was preparing a talk for MMS (Microsoft Management Summit) that I realized just how BIG it was. In a one-hour talk, we barely had time to list all of the new stuff, much less describe it in detail. But describing it in detail was exactly what I needed to do and that’s why this book took a great deal longer to write than anticipated. It’s also much bigger than I had expected or wanted. At one point it was double the size of the first edition. So we cut some stuff that was no longer as relevant with PowerShell v2, moved some stuff into the online appendixes, and capped the book at about 1000 pages.
So why write the book in the first place? The answer is the same now as it was then—I wanted the PowerShell community to have a way to see “inside the box” and have a more intimate insight into the goals and motivations behind PowerShell.
Although PowerShell draws heavily from existing technologies, it combines them in
novel ways. This kind of novelty leads to misunderstandings which then turn into urban myths, like PowerShell does X because its designers were kitten-eating aliens.
(Trust me—we’re not.)
As we showed our work to the world I found that there were a number of questions that were being asked over and over again. These questions would usually arise as a result of some prior language experience that the user had. Typically a simple expla- nation was all it took to clear up the confusion. Unfortunately we couldn’t keep answering these questions over and over on a one-by-one basis; that just couldn’t scale.
There needed to be a way to gather this information together in one place. The book was my attempt to address that problem, and the second edition continues on with this goal.
I continue to be amazed at just how much power comes out of the synergy of the various technologies underlying PowerShell. We see this in our own internal uses of PowerShell at Microsoft as well as in what the community has done with it. And so a second goal of this book was to try and foster that creativity by conveying just how capable PowerShell is.
And finally, this is the book I wanted to read. I love programming languages and the best books are the ones that explain not only what but also why. Look at the books that continue to sell year after year: Kernighan and Ritchie’s The C Programming Lan- guage, Stroustrup’s book on C++, and Ousterhout’s book on TCL. The TCL book in particular describes a very early version of the TCL language, has never been updated, and yet it continues to sell. Why? Because these books give the reader something more than just technical detail. They convey a sense of the overall design and some element of the intent of the designer. (Let me know if I succeeded, okay?)
xxi
acknowledgments
First and foremost, this book is for my wife Tina. I could not have done it without her patience, support, and encouragement. She kept me fed and sane, and she even read early drafts of material about which she knows nothing. Now that’s support! She also contributed the Gnome picture in chapter 21 and the bird-watching information and pictures in chapter 2. And I can now recognize the call of the California quail.
Thanks to my parents for their love and support over the years. Yes, I am finally done with the second edition!
Of course, there wouldn’t be a PowerShell book without a PowerShell product in the first place and PowerShell wouldn’t exist without the vision of its chief architect Jeffrey Snover. He was kind enough to do extensive reviews of both editions of the book. The book, like the product, has benefited greatly from his insight and sugges- tions.
PowerShell v2 would also not have been possible without the continued efforts on the part of Kenneth Hansen, lead Program Manager of the PowerShell team. Kenneth provided most of the day-to-day leadership during the Version 2/Windows 7 release cycle. He continues to be one of the strongest advocates for the customer that I’ve seen at Microsoft.
I’d like to thank the following PowerShell team members who took time to review specific chapters: Jason Shirk, who implemented most (all?) of the advanced function features in v2, reviewed chapters 7 and 8. Refaat Issa and Lucio Silveira, who were responsible for the design (Refaat) and implementation (Lucio) of the ISE, reviewed chapter 15 which covers the ISE.
To all of the MEAP readers and reviewers, many thanks for your feedback. I’ve incorporated as much of it as possible (boy, I make a lot of typos). In particular, I’d like to thank the following: Peter Johnson, Jonathan Medd, Sam Abraham, Andrew
Tearle, Keith Hill, Richard Siddaway, Paul Grebenc, Kirk Freiheit, Tony Niemann, Amos Bannister, Jeff Copeland, Marcus Baker, Massimo Perga, Tomas Restrepo, Jason Zions, Oisin Grehan, Kanwal Khipple, Brandon Shell, Bernd Schandl, and Matthew Reynolds. Thanks to all of you for your patience. This book took way, way too long to complete.
Finally, special thanks to all of the people who piled on at the end of the project to finally get it done: Cynthia Kane, my development editor, who is still talking to me (I think), even after all of the missed deadlines; also Liz Welch, Mary Piergies, Tiffany Taylor, and everyone else at Manning who helped get this book out the door. All I can say is thanks, and thanks again.
And more super-special thanks to three of our wonderful PowerShell MVPs who helped enormously with the final reviews. Marco Shaw was the technical proofreader who read the chapters during production. Jeffrey Hicks, a fine author in his own right, helped with the last set of “author” reviews. And Aleksandar Nikolic´ went above and beyond the call, turning around reviewed chapters stunningly quickly, and then reviewing the reviews! Dude, you’re a lifesaver!
xxiii
about this book
Windows PowerShell is the next-generation scripting environment created by Micro- soft. It’s designed to provide a unified solution for Windows scripting and automa- tion, able to access the wide range of technologies such as .NET, COM, and WMI through a single tool. Since its release in 2006, PowerShell has become the central component of any Windows management solution. In addition, due to PowerShell’s comprehensive support for .NET, it also has broad application potential outside of the system administration space. PowerShell can be used for text processing, general scripting, build management, creating test frameworks, and so on.
This book was written by one of the principal creators of PowerShell to enable users to get the most out of the PowerShell environment. Using many examples, both small and large, this book illustrates the features of the language and environment and shows how to compose those features into solutions, quickly and effectively.
Note that, because of the broad scope of the PowerShell product, this book has a commensurately broad focus. It was not designed as a cookbook of pre-constructed management examples, like how to deal with Active Directory or how to script Exchange. Instead it provides information about the core of the PowerShell runtime and how to use it to compose solutions the “PowerShell Way.” After reading this book, the PowerShell user should be able to take any example written in other languages like C# or Visual Basic and leverage those examples to build solutions in PowerShell.
Who should read this book?
This book is designed for anyone who wants to learn PowerShell and use it well.
Rather than simply being a book of recipes to read and apply, this book tries to give
the reader a deep knowledge about how PowerShell works and how to apply it. As a consequence, all users of PowerShell should read this book.
So, if you’re a Windows sysadmin, this book is for you. If you’re a developer and you need to get things done in a hurry, if you’re interested in .NET, or just if you like to experiment with computers, PowerShell is for you and this book is for you.
Roadmap
The book is divided into two major parts plus four appendixes (which are available online from the publisher’s website). The two parts of the book are “Learning Power- Shell” and “Using PowerShell.”
Part 1, “Learning PowerShell,” is a comprehensive tour of the PowerShell language and runtime. The goal is to introduce new PowerShell users to the language as well as to provide experienced users with a deep insight into how and why things are the way they are.
In part 1, we look at all aspects of the PowerShell language including the syntax, the type system, and so on. Along the way we present examples showing how each fea- ture works. Because the goal of the first part of the book is to focus on the individual features of the environment, most of the examples are quite small and are intended to be entered in an interactive session. The second part of this book focuses on larger examples that bring the individual features together to build larger applications.
Chapter 1 begins with some history and the rationale for why PowerShell was cre- ated in the first place. It then proceeds through a quick tour of the features of the envi- ronment. The remaining chapters in part 1 cover each element of the language, starting with basic PowerShell concepts in chapter 2.
Chapter 3 introduces the PowerShell type system and discusses its relationship to .NET. This chapter also presents the syntax for each of the PowerShell literal data types.
The discussion of operators and expressions (PowerShell has lots of these) begins in chapter 4 which covers the basic arithmetic, comparison, and assignment operators.
It also covers the wildcard and regular expression pattern matching operators.
Chapter 5 continues the discussion of operators with the advanced operations for working with arrays (indexing, slicing) and objects (properties and methods). It also covers output redirection and the formatting operator, and introduces PowerShell variables.
Chapter 6 covers the PowerShell language constructs like if statements and loops.
Chapter 7 introduces programming in PowerShell and covers basic functions, vari- able scoping, and other programming-related topics.
Chapter 8 builds on the material in chapter 7, covering advanced function meta- data, scripting, and how to create in-line documentation for scripts and functions.
Chapter 9 covers the basics of how to use PowerShell modules and how to create your own basic modules.
ABOUT THIS BO O K xxv Chapter 10 looks at more advanced module features covering module manifests and how to use them to add information like a version number, dependences, and nested modules.
Chapter 11 builds on the material in chapters 7–10, introducing advanced pro- gramming techniques like object construction and extensions. It also covers first-class functions (scriptblocks) and shows how to extend the PowerShell language itself using these features.
Chapter 12 introduces PowerShell remoting, starting with basic configuration and setup. It then covers the various forms of remoting (interactive and non-interactive) and how to apply these techniques.
Chapter 13 explores remoting and the underlying protocols in more detail. Creation of custom remoting endpoints, including constrained endpoints, is included as well.
Chapter 14 covers the PowerShell Integrated Scripting Environment (ISE). This coverage includes basic editor operation and the debugger (graphics and command line), and looks briefly at the ISE extension model which allows you to do things like add custom menu items to the ISE.
Chapter 15 completes part 1, covering the various features available in PowerShell for handling errors and debugging scripts.
In part 2 of the book, “Using PowerShell,” we shift our focus from individual fea- tures towards combining those features into larger examples. This part of the book looks at applying PowerShell in specific technology areas and problem domains.
We begin in chapter 16 looking at how PowerShell can be used to attack the kind of text processing tasks that have traditionally been the domain of languages like Perl.
This chapter begins with basic string processing, then introduces file processing (including handling binary files), and finishes up with a section on working with XML documents.
Then, in chapter 17, we look at how we can explore and apply the vast capabilities of the .NET framework. We cover locating, exploring, and instantiating types in the .NET framework, including generic types. Then we look at a number of applications using these types, including network programming and graphical programming with WinForms and WPF.
In chapter 18 we look at how to work with COM objects. This includes using the application automation models to script applications like Microsoft Word with PowerShell.
Chapter 19 covers Windows Management Instrumentation (WMI) and Web Ser- vices for Management (WS-Man). We look at how to use WMI from the command line and in scripts to inspect, update, and manage a Windows system.
Chapter 20 looks at the asynchronous eventing subsystem in PowerShell. Eventing allows PowerShell scripts to respond to external events in real time—an important characteristic in systems automation.
Finally, in chapter 21, we introduce the security features in PowerShell along with a general discussion of security. This is a very important chapter to read. Like all pow- erful scripting tools (Perl, Python, and so on), PowerShell can be used to create mal- ware-like virus and worm programs. The PowerShell runtime contains a number of features to allow you to deploy it in a manner that minimizes these risks.
In addition, there are four appendixes, available online from the publisher’s website at www.manning.com/WindowsPowerShellinActionSecondEdition.
Appendix A compares and contrasts PowerShell with other languages that the reader may already know. This appendix tries to highlight similarities and the impor- tant differences with each of the languages.
Appendix B includes more examples showing how to apply PowerShell to solve problems. While it’s by no means a complete management cookbook, it does show what can be done with PowerShell and how to do it.
Appendix C is a PowerShell quick reference that condenses much of the content of the book into a relatively short quick-reference document. Finally, appendix D con- tains information about a number of additional, less commonly used features and techniques in PowerShell.
Code conventions
Because PowerShell is an interactive environment, we show a lot of example com- mands as the user would type them, followed by the responses the system generates.
Before the command text there is a prompt string that looks like this: PS (2) >. Fol- lowing the prompt, the actual command is displayed. PowerShell’s responses follow on the next few lines. Because PowerShell doesn’t display anything in front of the out- put lines, you can distinguish output from commands by looking for the prompt string. These conventions are illustrated as follows:
PS (1) > get-date
Sunday, October 08, 2006 11:24:42 PM
Sometimes commands will span multiple lines. In this case subsequent lines of user input will be preceded by >> as shown:
PS (2) > 1..3 |
>> foreach {"+" * $_}
>>
+ ++
+++
PS (4) >
Note that the actual prompt sequence you see in your PowerShell session will be somewhat different than what is shown in the book. The prompt display is user- controllable by redefining the “prompt” function (see appendix A section 1.8 for
ABOUT THIS BO O K xxvii more information). For this book, a prompt sequence was chosen that includes com- mand numbers to make it easier to follow the examples.
Code annotations accompany many of the listings, highlighting important con- cepts. In some cases, numbered bullets link to explanations that follow the listing.
Source code downloads
Source code for all working examples in this book is available for download from the pub- lisher’s website at www.manning.com/WindowsPowerShellinActionSecondEdition.
Author Online
Purchase of Windows PowerShell in Action, Second Edition includes free access to a pri- vate web forum run by Manning Publications where you can make comments about the book, ask technical questions, and receive help from the author and from other users. To access the forum and subscribe to it, point your web browser to www .manning.com/WindowsPowerShellinActionSecondEdition. This page provides information on how to get on the forum once you are registered, what kind of help is available, and the rules of conduct on the forum.
Manning’s commitment to our readers is to provide a venue where a meaningful dialog between individual readers and between readers and the author can take place.
It is not a commitment to any specific amount of participation on the part of the author, whose contribution to the AO remains voluntary (and unpaid). We suggest you try asking the author some challenging questions lest his interest stray!
The Author Online forum and the archives of previous discussions will be acces- sible from the publisher’s website as long as the book is in print.
About the author
Bruce Payette is one of the founding members of the Windows PowerShell team. He is co-designer of the PowerShell language along with Jim Truher and the principal author of the language implementation. He joined Microsoft in 2001 working on Interix, the POSIX subsystem for Windows, then moved to help found the Power- Shell project shortly after that. Prior to joining Microsoft, he worked at various com- panies including Softway (the creators of Interix) and MKS (producers of the MKS Toolkit) building UNIX tools for Windows. He lives in Bellevue, Washington, with his wife, many computers, and two extremely over-bonded codependent cats.
About the title
By combining introductions, overviews, and how-to examples, the In Action books are designed to help learning and remembering. According to research in cognitive science, the things people remember are things they discover during self-motivated exploration.
Although no one at Manning is a cognitive scientist, we are convinced that for learning to become permanent it must pass through stages of exploration, play, and, interestingly, retelling of what is being learned. People understand and remember new things, which is to say they master them, only after actively exploring them. Humans learn in action. An essential part of an In Action book is that it is example driven. It encourages the reader to try things out, to play with new code, and explore new ideas.
There is another, more mundane, reason for the title of this book: our readers are busy.
They use books to do a job or solve a problem. They need books that allow them to jump in and jump out easily and learn just what they want just when they want it. They need books that aid them in action. The books in this series are designed for such readers.
xxix
about the cover illustration
The figure on the cover of Windows PowerShell in Action, Second Edition is a “Mufti,”
the chief of religion or the chief scholar who interpreted the religious law and whose pronouncements on matters both large and small were binding to the faithful. The illustration is taken from a collection of costumes of the Ottoman Empire published on January 1, 1802, by William Miller of Old Bond Street, London. The title page is missing from the collection and we have been unable to track it down to date. The book’s table of contents identifies the figures in both English and French, and each illustration bears the names of two artists who worked on it, both of whom would no doubt be surprised to find their art gracing the front cover of a computer program- ming book...two hundred years later.
The collection was purchased by a Manning editor at an antiquarian flea market in the “Garage” on West 26th Street in Manhattan. The seller was an American based in Ankara, Turkey, and the transaction took place just as he was packing up his stand for the day. The Manning editor did not have on his person the substantial amount of cash that was required for the purchase and a credit card and check were both politely turned down. With the seller flying back to Ankara that evening the situation was getting hopeless. What was the solution? It turned out to be nothing more than an old-fashioned verbal agreement sealed with a handshake. The seller simply pro- posed that the money be transferred to him by wire and the editor walked out with the bank information on a piece of paper and the portfolio of images under his arm.
Needless to say, we transferred the funds the next day, and we remain grateful and impressed by this unknown person’s trust in one of us. It recalls something that might have happened a long time ago.
The pictures from the Ottoman collection, like the other illustrations that appear on our covers, bring to life the richness and variety of dress customs of two centuries
ago. They recall the sense of isolation and distance of that period—and of every other historic period except our own hyperkinetic present.
Dress codes have changed since then and the diversity by region, so rich at the time, has faded away. It is now often hard to tell the inhabitant of one continent from another. Perhaps, trying to view it optimistically, we have traded a cultural and visual diversity for a more varied personal life. Or a more varied and interesting intellectual and technical life.
We at Manning celebrate the inventiveness, the initiative, and, yes, the fun of the computer business with book covers based on the rich diversity of regional life of two centuries ago—brought back to life by the pictures from this collection.
1
P A R T
Learning PowerShell
T
he first part of this book focuses primarily on the PowerShell language and its runtime environment. We’ll cover the complete syntax for PowerShell in detail: the various kinds of conditional and loop statements, the operators, and the syntax for defining functions and modules. We’ll look at how to configure and use PowerShell remoting to do remote access.3
C H A P T E R 1
Welcome to PowerShell
1.1 What is PowerShell? 5 1.2 Soul of a new language 9 1.3 Brushing up on objects 11
1.4 Up and running with PowerShell 13 1.5 Dude! Where’s my code? 22 1.6 Summary 35
Space is big. Really big! You just won’t believe how vastly hugely mind-bogglingly big it is. I mean you may think it’s a long way down the road to the chemist, but that’s just peanuts compared to space!
Don’t Panic.
—Douglas Adams, The Hitchhiker’s Guide to the Galaxy
Welcome to Windows PowerShell, the new command and scripting language from Microsoft. We begin this chapter with two quotes from The Hitchhiker’s Guide to the Galaxy. What do they have to do with a new scripting language? In essence, where a program solves a particular problem or problems, a programming language can solve any problem, at least in theory. That’s the “big, really big” part. The “Don’t Panic” bit is, well—don’t panic. Although PowerShell is new and different, it’s been designed to leverage what you already know, making it easy to learn. It’s also designed to allow you to learn it a bit at a time. Starting at the beginning, here’s the traditional “Hello world” program in PowerShell:
"Hello world."
As you can see, no panic needed. But “Hello world” by itself isn’t very interesting.
Here’s something a bit more complicated:
dir $env:windir\*.log | Select-String -List error | Format-Table path,linenumber –AutoSize
Although this is more complex, you can probably still figure out what it does. It searches all the log files in the Windows directory, looking for the string “error”, and then prints the full name of the matching file and the matching line number. “Useful, but not very special,” you might think, because you can easily do this using cmd.exe on Windows or bash on UNIX. So what about the “big, really big” thing? Well, how about this example?
([xml](New-Object net.webclient).DownloadString(
"http://blogs.msdn.com/powershell/rss.aspx"
)).rss.channel.item | Format-Table title,link
Now we’re getting somewhere. This script downloads the RSS feed from the Power- Shell team blog and then displays the title and a link for each blog entry.
NOTE RSS stands for Really Simple Syndication. This is a mechanism that allows programs to download blogs automatically so they can be read more conveniently than in the browser.
By the way, you weren’t expected to figure out this example yet. If you did, you can move to the head of the class!
Finally, one last example:
[void][reflection.assembly]::LoadWithPartialName(
"System.Windows.Forms")
$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()
This script uses the Windows Forms library (Win- Forms) to build a graphical user interface (GUI) that has a single button displaying the text “Push Me!” The window this script creates is shown in figure 1.1.
Figure 1.1 When you run the code from the example, this window will be displayed. If you don’t see it, it may be hidden behind another window.
WHATIS POWERSHELL? 5 When you click the button, it closes the form and exits the script. With this you go from "Hello world" to a GUI application in less than two pages.
Now let’s come back down to Earth for a minute. The intent of chapter 1 is to set the stage for understanding PowerShell—what it is, what it isn’t, and, almost as important, why the PowerShell team made the decisions they made in designing the PowerShell language. Chapter 1 covers the goals of the project, along with some of the major issues the team faced in trying to achieve those goals. By the end of the chapter you should have a solid base from which to start learning and using Power- Shell to solve real-world problems. All theory and no practice is boring, so the chap- ter concludes with a number of small examples to give you a feel for PowerShell. But first, a philosophical digression: while under development, from 2002 until just before the first public release in 2006, the codename for this project was Monad. The name Monad comes from The Monadology by Gottfried Wilhelm Leibniz, one of the inventors of calculus. Here’s how Leibniz defined the Monad:
The Monad, of which we shall here speak, is nothing but a simple substance, which enters into compounds. By “simple” is meant “without parts.”
—From The Monadology by Gottfried Wilhelm Leibniz (translated by Robert Latta)
In The Monadology, Leibniz described a world of irreducible components from which all things could be composed. This captures the spirit of the project: to create a tool- kit of simple pieces that you compose to create complex solutions.
1.1 W
HAT ISP
OWERS
HELL?
What is PowerShell, and why was it created? PowerShell is the new command-line/
scripting environment from Microsoft. The overall goal for this project was to provide the best shell scripting environment possible for Microsoft Windows. This statement has two parts, and they’re equally important, because the goal wasn’t just to produce a good generic shell environment but rather to produce one designed specifically for the Windows environment. Although drawing heavily from existing command-line shell and scripting languages, the PowerShell language and runtime were designed from scratch to be an optimal environment for the modern Windows operating system.
Historically, the Windows command line has been weak. This is mainly the result of Microsoft’s early focus on computing for the average user, who is considered nei- ther particularly technical nor particularly interested in computers. Most of the devel- opment effort for Windows was put into improving the graphical environment for the nontechnical user, rather than creating an environment for the computer profes- sional. Although this was certainly an enormously successful commercial strategy for Microsoft, it has left some segments of the community underserved.
