powershell in depth

MANNING
Don Jones
Richard Siddaway
Jeffery Hicks
An administrator’s guide
Covers PowerShell 3.0
www.it-ebooks.info
PowerShell in Depth
www.it-ebooks.info
www.it-ebooks.info
PowerShell in Depth
A
N

ADMINISTRATOR
’
S

GUIDE
DON JONES
RICHARD SIDDAWAY
JEFFERY HICKS
MANNING
S
HELTER
I
SLAND
www.it-ebooks.info
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:
©2013 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 the importance of preserving what has been written, it is Manning’s policy to have
the books we publish printed on acid-free paper, and we exert our best efforts to that end.
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 Technical proofreader: Aleksandar Nikolic
Shelter Island, NY 11964 Proofreader: Linda Recktenwald
Typesetter: Dennis Dalinnik
Cover designer: Marija Tudor
ISBN: 9781617290558
Printed in the United States of America
1 2 3 4 5 6 7 8 9 10 – MAL – 19 18 17 16 15 14 13
www.it-ebooks.info
v

brief contents
P
ART
1 P
OWER
S
HELL

FUNDAMENTALS
. 1
1
■
Introduction 3
2
■
PowerShell hosts 7
3
■
Using the PowerShell help system 17
4
■
The basics of PowerShell syntax 29
5
■
Working with PSSnapins and modules 39
6
■
Operators 46
7
■

Working with objects 60
8
■
The PowerShell pipeline 93
9
■
Formatting 111
P
ART
2 P
OWER
S
HELL

MANAGEMENT
127
10
■
PowerShell Remoting 129
11
■
Background jobs and scheduling 160
12
■
Working with credentials 174
13
■
Regular expressions 184
14
■

Working with HTML and XML data 196
www.it-ebooks.info
BRIEF CONTENTS
vi
15
■
PSDrives and PSProviders 210
16
■
Variables, arrays, hash tables, and scriptblocks 224
17
■
PowerShell security 244
18
■
Advanced PowerShell syntax 257
P
ART
3 P
OWER
S
HELL

SCRIPTING

AND

AUTOMATION
275
19

■
PowerShell’s scripting language 277
20
■
Basic scripts and functions 291
21
■
Creating objects for output 301
22
■
Scope 317
23
■
PowerShell workflows 332
24
■
Advanced syntax for scripts and functions 359
25
■
Script modules and manifest modules 379
26
■
Custom formatting views 391
27
■
Custom type extensions 403
28
■
Data language and internationalization 417
29

■
Writing help 429
30
■
Error handling techniques 435
31
■
Debugging tools and techniques 447
32
■
Functions that work like cmdlets 466
33
■
Tips and tricks for creating reports 485
P
ART
4 A
DVANCED
P
OWER
S
HELL
495
34
■
Working with the Component
Object Model (COM) 497
35
■
Working with .NET Framework objects 505

36
■
Accessing databases 517
37
■
Proxy functions 525
38
■
Building a GUI 538
39
■
WMI and CIM 557
40
■
Best practices 584
www.it-ebooks.info
vii
contents
preface xxi
acknowledgments xxiii
about this book xxv
about the authors xxvii
about the cover illustration xxix
P
ART
1 P
OWER
S
HELL

FUNDAMENTALS
. 1
1
Introduction 3
1.1 Who this book is for 3
1.2 What this book will teach you 4
1.3 What this book won’t teach you 4
1.4 Where we drew the line 5
1.5 Beyond PowerShell 5
1.6 Ready? 6
2
PowerShell hosts 7
2.1 32-bit vs. 64-bit, and administrator vs. not 8
2.2 The console 10
2.3 The PowerShell ISE 12
www.it-ebooks.info
CONTENTS
viii
2.4 Command history buffer vs. PowerShell’s history 15
2.5 Transcripts 16
2.6 Summary 16
3
Using the PowerShell help system 17
3.1 The help commands 17
3.2 Where’s the help? 18
3.3 Using the help 20
3.4 “About” help files 23
3.5 Provider help 24
3.6 Interpreting command help 25
3.7 Common parameters 27

3.8 Summary 28
4
The basics of PowerShell syntax 29
4.1 Commands 30
Aliases: nicknames for commands 31
■
Command name
tab completion 32
4.2 Parameters 32
Truncating parameter names 34
■
Parameter name
tab completion 35
4.3 Typing trick: line continuation 35
4.4 Parenthetical commands and expressions 36
4.5 Script blocks 37
4.6 Summary 38
5
Working with PSSnapins and modules 39
5.1 There’s only one shell 39
5.2 PSSnapins vs. modules 40
5.3 Loading, autoloading, and profiles 41
5.4 Using extensions 41
Discovering extensions 41
■
Loading extensions 43
Discovering extensions’ additions 43
■
Managing extensions 44
5.5 Command name conflicts 44

5.6 Managing module autoloading 45
5.7 Summary 45
www.it-ebooks.info
CONTENTS
ix
6
Operators 46
6.1 Logical and comparison operators 47
The –contains operator 48
■
The -in and -notin operators 49
Boolean, or logical, operators 50
■
Bitwise operators 51
6.2 Arithmetic operators 53
6.3 Other operators 55
String and array manipulation operators 55
Object type operators 56
■
Format operator 57
Miscellaneous operators 58
6.4 Summary 59
7
Working with objects 60
7.1 Introduction to objects 61
7.2 Members: properties, methods, and events 63
7.3 Sorting objects 68
7.4 Selecting objects 69
Use 1: choosing properties 70
■

Use 2: choosing a subset
of objects 71
■
Use 3: making custom properties 73
Use 4: extracting and expanding properties 75
Use 5: choosing properties and a subset of objects 79
7.5 Filtering objects 79
Simplified syntax 79
■
Full syntax 81
7.6 Grouping objects 81
7.7 Measuring objects 83
7.8 Enumerating objects 84
Full syntax 85
■
Simplified syntax 85
7.9 Importing, exporting, and converting objects 86
7.10 Comparing objects 90
7.11 Summary 92
8
The PowerShell pipeline 93
8.1 How the pipeline works 93
The old way of piping 94
■
The PowerShell way of piping 95
8.2 Parameter binding ByValue 96
8.3 Pipeline binding ByPropertyName 98
8.4 Troubleshooting parameter binding 104
www.it-ebooks.info
CONTENTS

x
8.5 When parameter binding lets you down 109
8.6 The pipeline with external commands 110
8.7 Summary 110
9
Formatting 111
9.1 The time to format 111
9.2 The formatting system 113
Is there a predefined view? 113
■
What properties should
be displayed? 113
■
List or table? 114
9.3 The Format cmdlets 114
Formatting wide lists 114
■
Formatting tables 115
Formatting lists 120
■
Same objects, different formats 122
9.4 Eliminating confusion and “gotchas” 122
Formatting is the end of the line 122
■
Select or format? 123
Format, out, export—which? 124
9.5 Summary 125
P
ART
2 P

OWER
S
HELL

MANAGEMENT
127
10
PowerShell Remoting 129
10.1 The many forms of remote control 130
10.2 Remoting overview 130
Authentication 131
■
Firewalls and security 132
10.3 Using Remoting 132
Enabling Remoting 132
■
1-to-1 Remoting 133
1-to-many Remoting 134
■
Remoting caveats 136
Remoting options 138
10.4 PSSessions 140
Creating a persistent session 140
■
Using a session 140
Managing sessions 141
■
Disconnecting and
reconnecting sessions 141
10.5 Advanced session techniques 144

Session parameters 144
■
Session options 145
10.6 Creating a custom endpoint 145
Custom endpoints for delegated administration 147
www.it-ebooks.info
CONTENTS
xi
10.7 Connecting to nondefault endpoints 148
10.8 Enabling the “second hop” 149
10.9 Setting up WinRM listeners 150
10.10 Other configuration scenarios 152
Cross-domain Remoting 152
■
Quotas 153
■
Configuring on
a remote machine 154
■
Key WinRM configuration settings 154
Adding a machine to your Trusted Hosts list 155
■
Using Group
Policy to configure Remoting 156
10.11 Implicit Remoting 157
10.12 Summary 159
11
Background jobs and scheduling 160
11.1 Remoting-based jobs 160
Starting jobs 161

■
Checking job status 162
■
Working with
child jobs 162
■
Waiting for a job 164
■
Stopping jobs 164
Getting job results 164
■
Removing jobs 165
Investigating failed jobs 166
11.2 WMI jobs 166
11.3 Scheduled jobs 167
Scheduled jobs overview 168
■
Creating a scheduled job 168
Managing scheduled jobs 169
■
Working with scheduled
job results 170
11.4 Job processes 170
Jobs created with Start-Job 171
■
Jobs created with
Invoke-Command 172
■
Jobs created through the WMI
cmdlets 173

■
Jobs created through the scheduler 173
11.5 Summary 173
12
Working with credentials 174
12.1 About credentials 175
12.2 Using credentials 178
12.3 Crazy credentials ideas 179
Packaging your script 179
■
Saving a credential object 179
Creating a credential without the GUI 181
Supporting credentials in your script 181
12.4 Summary 183
www.it-ebooks.info
CONTENTS
xii
13
Regular expressions 184
13.1 Basic regular expression syntax 185
13.2 The –match operator 188
13.3 The select-string cmdlet 190
13.4 Switch statement 190
13.5 The REGEX object 192
13.6 Summary 195
14
Working with HTML and XML data 196
14.1 Working with HTML 196
Retrieving an HTML page 197
■

Working with the
HTML results 198
■
Practical example 201
Creating HTML output 202
14.2 Working with XML 206
Using XML to persist data 206
■
Reading arbitrary
XML data 207
■
Creating XML data and files 208
Using XML XPath queries 209
14.3 Summary 209
15
PSDrives and PSProviders 210
15.1 Why use PSProviders? 210
15.2 What are PSProviders? 211
15.3 What are PSDrives? 212
15.4 Working with PSDrives 213
Working with PSDrive items 214
■
Working with
item properties 216
15.5 Transactional operations 219
15.6 Every drive is different 221
15.7 Summary 223
16
Variables, arrays, hash tables, and scriptblocks 224
16.1 Variables 224

Variable names 225
■
Variable types 226
■
Being strict
with variables 228
16.2 Built-in variables and the Variable: drive 230
16.3 Variable commands 231
www.it-ebooks.info
CONTENTS
xiii
16.4 Arrays 232
16.5 Hash tables and ordered hash tables 235
Ordered hash tables 239
■
Common uses for hash tables 241
Defining default parameter values 241
16.6 Scriptblocks 241
16.7 Summary 243
17
PowerShell security 244
17.1 PowerShell security goals 244
17.2 PowerShell security mechanisms 245
Script execution requires a path 245
Filename extension associations 246
17.3 Execution policy 247
A digital signature crash course 247
■
Understanding script
signing 249

■
The execution policy in depth 251
17.4 The PowerShell security debate 255
17.5 Summary 256
18
Advanced PowerShell syntax 257
18.1 Splatting 257
18.2 Defining default parameter values 259
18.3 Running external utilities 263
18.4 Expressions in quotes: $($cool) 269
18.5 Parentheticals as objects 270
18.6 Increase the format enumeration limit 271
18.7 Hash tables as objects 272
18.8 Summary 274
P
ART
3 P
OWER
S
HELL

SCRIPTING

AND

AUTOMATION
275
19
PowerShell’s scripting language 277
19.1 Defining conditions 277

19.2 Loops: For, Do, While, Until 278
The For loop 278
■
The other loops 280
19.3 ForEach 281
19.4 Break and Continue 283
www.it-ebooks.info
CONTENTS
xiv
19.5 If . . . ElseIf . . . Else 284
19.6 Switch 286
19.7 Mastering the punctuation 289
19.8 Summary 290
20
Basic scripts and functions 291
20.1 Script or function? 291
20.2 Execution lifecycle and scope 292
20.3 Starting point: a command 293
20.4 Accepting input 293
20.5 Creating output 295
20.6 “Filtering” scripts 297
20.7 Moving to a function 299
20.8 Summary 300
21
Creating objects for output 301
21.1 Why output objects? 302
21.2 Syntax for creating custom objects 303
Technique 1: using a hash table 303
■
Technique 2: using

Select-Object 305
■
Technique 3: using Add-Member 306
Technique 4: using a Type declaration 307
Technique 5: creating a new class 307
What’s the difference? 309
21.3 Complex objects: collections as properties 309
21.4 Applying a type name to custom objects 312
21.5 So, why bother? 313
21.6 Summary 316
22
Scope 317
22.1 Understanding scope 317
22.2 Observing scope in action 321
22.3 Dot sourcing 323
22.4 Manipulating cross-scope elements 324
22.5 Being private 328
22.6 Being strict 328
22.7 Summary 331
www.it-ebooks.info
CONTENTS
xv
23
PowerShell workflows 332
23.1 Workflow overview 333
23.2 Workflow basics 334
Common parameters for workflows 335
■
Activities and
stateless execution 335

■
Persisting state 337
Suspending and resuming workflows 337
Workflow limitations 337
■
Parallelism 340
23.3 General workflow design strategy 341
23.4 Example workflow scenario 342
23.5 Writing the workflow 342
23.6 Workflows vs. functions 343
23.7 Specific workflow techniques 345
Sequences 345
■
InlineScript 346
23.8 Running a workflow 349
Workflow jobs 349
■
Suspending and restarting
a workflow 350
■
Workflow credentials 351
23.9 A practical example 351
23.10 Invoke-AsWorkflow 353
23.11 PSWorkflowSession 355
23.12 Troubleshooting a workflow 357
23.13 Summary 358
24
Advanced syntax for scripts and functions 359
24.1 Starting point 360
24.2 Advanced parameters 360

24.3 Variations on parameter inputs 365
24.4 Parameter aliases 366
24.5 Parameter validation 367
24.6 Parameter sets 372
24.7 WhatIf and Confirm parameters 373
24.8 Verbose output 375
24.9 Summary 378
25
Script modules and manifest modules 379
25.1 Making a script module 380
25.2 Exporting module members 382
www.it-ebooks.info
CONTENTS
xvi
25.3 Making a module manifest 386
25.4 Creating dynamic modules 387
25.5 Summary 390
26
Custom formatting views 391
26.1 Object type names 392
26.2 Getting view templates 393
26.3 Starting a view file 393
26.4 Adding view types 394
26.5 Importing view data 397
26.6 Using named views 399
26.7 Going further 401
26.8 Summary 402
27
Custom type extensions 403
27.1 What are type extensions? 404

27.2 Creating and loading a type extension file 405
27.3 Making type extensions 407
AliasProperty 407
■
ScriptProperty 407
■
ScriptMethod 408
DefaultDisplayPropertySet 409
27.4 A complete example 409
27.5 Updating type data dynamically 411
27.6 Get-TypeData 414
27.7 Remove-TypeData 415
27.8 Summary 416
28
Data language and internationalization 417
28.1 Internationalization basics 418
28.2 Adding a data section 420
28.3 Storing translated strings 422
28.4 Testing localization 425
28.5 Summary 428
29
Writing help 429
29.1 Comment-based help 430
29.2 Writing About topics 432
www.it-ebooks.info
CONTENTS
xvii
29.3 XML-based help 432
29.4 Summary 434
30

Error handling techniques 435
30.1 About errors and exceptions 436
30.2 Using $ErrorActionPreference and –ErrorAction 436
30.3 Using –ErrorVariable 438
30.4 Using $Error 439
30.5 Trap constructs 440
30.6 Try Catch Finally constructs 443
30.7 Summary 446
31
Debugging tools and techniques 447
31.1 Debugging: all about expectations 448
31.2 Write-Debug 456
31.3 Breakpoints 460
31.4 Using Set-PSDebug 463
31.5 Debugging in third-party editors 465
31.6 Summary 465
32
Functions that work like cmdlets 466
32.1 Defining the task 467
32.2 Building the command 468
32.3 Parameterizing the pipeline 469
32.4 Adding professional features 472
32.5 Error handling 472
Adding verbose and debug output 474
■
Defining a custom
object name 477
32.6 Making it a function and adding help 477
32.7 Creating a custom view 479
32.8 Creating a type extension 480

32.9 Making a module manifest 481
32.10 Summary 484
www.it-ebooks.info
CONTENTS
xviii
33
Tips and tricks for creating reports 485
33.1 What not to do 485
33.2 Working with HTML fragments and files 487
Getting the information 488
■
Producing an
HTML fragment 488
■
Assembling the final HTML page 489
33.3 Sending email 492
33.4 Summary 493
P
ART
4 A
DVANCED
P
OWER
S
HELL
495
34
Working with the Component Object Model (COM) 497
34.1 Introduction to COM objects 498
34.2 Instantiating COM objects in PowerShell 500

34.3 Accessing and using COM objects’ members 500
34.4 PowerShell and COM examples 503
34.5 Summary 504
35
Working with .NET Framework objects 505
35.1 Classes, instances, and members 506
35.2 .NET Framework syntax in PowerShell 507
35.3 .NET support in PowerShell 508
35.4 Accessing static members 509
35.5 Finding the right framework bits 509
35.6 Creating and working with instances 514
35.7 Summary 516
36
Accessing databases 517
36.1 Native SQL vs. OLEDB 518
36.2 Connecting to data sources 518
36.3 Querying data 519
Databases with DataAdapters 520
■
Databases with
DataReaders 520
36.4 Adding, changing, and deleting data 521
36.5 Calling stored procedures 521
36.6 A module to make it easier 522
36.7 Summary 524
www.it-ebooks.info
CONTENTS
xix
37
Proxy functions 525

37.1 The purpose of proxy functions 525
37.2 How proxy functions work 526
37.3 Creating a basic proxy function 526
37.4 Adding a parameter 528
37.5 Removing a parameter 532
37.6 Turning it into a function 534
37.7 Summary 536
38
Building a GUI 538
38.1 WinForms via PowerShell Studio 539
Creating the GUI 540
■
Adding the code 543
Using the script 548
38.2 Windows Presentation Foundation (WPF) and ShowUI 552
38.3 WinForms vs. WPF 554
38.4 Ideas for leveraging a GUI tool 555
38.5 Summary 556
39
WMI and CIM 557
39.1 What is WMI? 558
39.2 WMI cmdlets 559
Get-WmiObject 559
■
Remove-WmiObject 561
Set-WmiInstance 562
■
Invoke-WmiMethod 563
Register-WmiEvent 566
39.3 CIM cmdlets 567

Get-CIMClass 570
■
Get-CimInstance 571
Remove-CimInstance 573
■
Set-CimInstance 574
Invoke-CimMethod 574
■
Register-CimIndicationEvent 575
39.4 CIM sessions 576
39.5 “Cmdlets over objects” 578
39.6 Summary 583
40
Best practices 584
40.1 PowerShell general best practices 584
40.2 PowerShell scripting best practices 585
40.3 PowerShell in the enterprise best practices 587
index 589
www.it-ebooks.info
www.it-ebooks.info
xxi
preface
Windows PowerShell is viewed by many
IT
professionals as a necessary evil; we see it as
a management marvel. The challenge from the beginning has been to wrap one’s
head around the PowerShell paradigm of an object-based shell. Some people view
PowerShell as just another scripting language like
VBS
cript. The truth is that Power-

Shell is an automation and management engine. You can run this engine in a tradi-
tional console application, which is how most
IT
pros are first exposed to it. You can
run it in a graphical environment like the PowerShell Integrated Scripting Environ-
ment (
ISE
), or through a third-party tool like Power
GUI
or PowerShell Plus.
As you might imagine, the third version of a product offers substantially more fea-
tures and benefits than the first, and PowerShell 3.0 fits this model. This version of
PowerShell naturally builds on what came before, but it takes off from there. If you
think of Windows 8 and Windows Server 2012 as operating systems for the cloud,
then PowerShell 3.0 is the automation and management engine for the cloud, although
PowerShell “scales down” to help you better manage any size environment.
Collectively, we have close to 70 years of
IT
experience. We have worked with
PowerShell from its days as a beta product and have written on the topic for nearly as
long. Our goal is to bring this knowledge and experience into a single reference book.
Notice the key word, “reference.” This is not a how-to or teach yourself PowerShell
book, although you can learn much from reading it cover to cover. Rather, this book is
intended as the reference guide you keep at your desk or on your mobile device so
that when you need to better understand a topic, like PowerShell remoting, you have
a place to which you can turn.
www.it-ebooks.info
PREFACE
xxii
We have tried to keep our examples practical and targeted towards

IT
professionals
responsible for Windows system administration. It is our hope that this will be the
book you go to for answers.
www.it-ebooks.info
xxiii
acknowledgments
As you can imagine, a book of this scope and magnitude is not an easy undertaking,
even with three coauthors. There are many, many people who had a hand in mak-
ing this possible. First, we’d like to thank the entire PowerShell product team at
Microsoft. Many of them took time from their busy schedules to answer our ques-
tions and offer guidance on a number of new features, even while they were still
being developed!
The authors would also like to thank the fine folks at Manning Publications:
Cynthia Kane, Karen Miller, Maureen Spencer, Liz Welch, Linda Recktenwald, Janet
Vail, and Mary Piergies. They have taken what can be a grueling process and turned it
into something pleasant yet productive in helping us bring this book to publication.
That is not easy.
We also thank the cadre of what we think of as “real-world” reviewers who offered
their opinions on how we could make this a book that they, and you, would want on
your bookshelf. They include Adam Bell, Andre Sune, Bart Vermeulen, Bruno
Gomes, Eric Flamm, Eric Stoker, Gary Walker, Greg Heywood, Innes Fisher, James
Berkenbile, Jelmer Siljee, Jonathan Medd, Kais Ayari, Klaus Schulte, Mike Shepard,
Peter Monadjemi, Richard Beckett, Rolf Åberg, Santiago I. Cánepa, Thomas Lee,
and Trent Whiteley.
We would especially like to thank Aleksandar Nikolic for his time and dedication
in reviewing the technical content of our book. Aleksandar shares our desire to pro-
duce the best possible PowerShell reference and we truly appreciate his efforts.
www.it-ebooks.info
ACKNOWLEDGMENTS

xxiv
DON
would like to thank everyone at Manning for their support of, and commitment
to, this project. He’d also like to thank his coauthors for their hard work, and his fam-
ily for being so giving of their time.
RICHARD
would like to thank everyone who has taken the time to comment on the
book and the PowerShell community for their willingness to share. He would like to
thank Don and Jeff for making this a very enjoyable experience—working across eight
timezones makes for some interesting conversations.
JEFF
would like to extend a special thanks to Steve Murawski and Travis Jones for their
PowerShell 3.0 insights. He would also like to thank his coauthors for making this one
of the best authoring experiences possible.
www.it-ebooks.info