Don Jones
Jeffery Hicks
Richard Siddaway
SECOND EDITION
Praise for the First Edition
A thorough look at PowerShell from three of the best writers in the PowerShell community. —Mike Shepard, Solutions Architect
Jack Henry & Associates The most wonderful PowerShell administrative guide.
—Kais Ayari, PowerShell Expert, Microsoft Another great PowerShell book for my desk!
—Thomas Lee, PowerShell Consultant, PS Partnership Hicks, Jones, and Siddaway have come together to deliver the ultimate PowerShell resource.
—James Berkenbile, Principal Consultant Berkenbile Consulting I have many books on my shelves. This is one that will be on my desk!
—Trent Whiteley, Software Engineer, Fiserv The authors know their audience and never lose sight of their readers. They use their knowledge and understanding in very clever ways to help readers understand even complex subjects.
—Rolf Åberg, Platform Architect Active Directory, SEB An end-all, be-all resource in the working man’s hands. I can finally give Google a rest.
—Eric Stoker, Network Administrator, Spokane Teacher’s Credit Union Hands-down the best PowerShell book to date. The authors are some of the most respected in the PowerShell community and this book illustrates why! These guys know this stuff inside and out.
—Adam Bell, Solution Architect, ZOE Systems Pty Ltd. Priceless, practical guidance.
PowerShell in Depth
Second Edition
DON JONES
JEFFERY HICKS
RICHARD SIDDAWAY
M A N N I N G
SHELTER ISLANDwww.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: [email protected]
©2015 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: Karen Miller 20 Baldwin Road Copyeditor: Liz Welch
PO Box 261 Proofreaders: Toma Mulligan, Andy Carroll Shelter Island, NY 11964 Typesetter: Dennis Dalinnik
Cover designer: Marija Tudor
ISBN: 9781617292187
Printed in the United States of America
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 19
4 ■
The basics of PowerShell syntax 33
5 ■Working with PSSnapins and modules 44
6 ■
Operators 52
7 ■
Working with objects 69
8 ■
The PowerShell pipeline 106
9 ■Formatting 125
P
ART
2
P
OWER
S
HELL
MANAGEMENT
... 143
10 ■
PowerShell Remoting 145
11 ■
Background jobs and scheduling 181
12 ■Working with credentials 196
13 ■
Regular expressions 206
15 ■
PSDrives and PSProviders 244
16 ■
Variables, arrays, hash tables, and script blocks 260
17 ■
PowerShell security 282
18 ■
Advanced PowerShell syntax 296
P
ART
3
P
OWER
S
HELL
SCRIPTING
AND
AUTOMATION
...315
19 ■
PowerShell’s scripting language 317
20 ■
Basic scripts and functions 332
21 ■Creating objects for ouput 344
22 ■
Scope 361
23 ■
PowerShell workflows 376
24 ■
Advanced syntax for scripts and functions 406
25 ■Script modules and manifest modules 427
26 ■
Custom formatting views 439
27 ■Custom type extensions 451
28 ■
Data language and internationalization 465
29 ■Writing help 477
30 ■
Error handling techniques 484
31 ■Debugging tools and techniques 496
32 ■
Functions that work like cmdlets 520
33 ■Tips and tricks for creating reports 539
P
ART
4
A
DVANCED
P
OWER
S
HELL
...549
34 ■
Working with the Component
Object Model (COM) 551
35 ■
Working with .NET Framework objects 560
36 ■
Accessing databases 573
37 ■Proxy functions 581
38 ■
Building a GUI 593
39 ■WMI and CIM 613
40 ■
Working with the web 640
41 ■Desired State Configuration 656
ix
contents
preface xxiacknowledgments xxiii about this book xxv
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
12
2.3
The PowerShell ISE
14
2.5
Transcripts
17
2.6
Summary
18
3
Using the PowerShell help system
19
3.1
The help commands
19
3.2
Where’s the help?
20
3.3
Saving help
23
3.4
Using the help
24
3.5
“About” help files
27
3.6
Provider help
28
3.7
Interpreting command help
28
3.8
Common parameters
31
3.9
Summary
32
4
The basics of PowerShell syntax
33
4.1
Commands
34
Aliases: nicknames for commands 35 ■ Command name tab completion 36
4.2
Parameters
36
Truncating parameter names 39 ■ Parameter name tab completion 39
4.3
Typing trick: line continuation
40
4.4
Parenthetical commands and expressions
41
4.5
Script blocks
42
4.6
Summary
42
5
Working with PSSnapins and modules
44
5.1
There’s only one shell
44
5.2
PSSnapins vs. modules
45
5.3
Loading, autoloading, and profiles
46
5.4
Using extensions
46
Discovering extensions 46 ■ Loading extensions 48
Discovering extensions’ additions 48 ■ Managing extensions 49
5.5
Command name conflicts
50
5.6
Managing module autoloading
51
5.7
Summary
51
CONTENTS xi
6
Operators
52
6.1
Logical and comparison operators
53
The –contains operator 55 ■ The -in and -notin operators 56 Boolean, or logical, operators 57 ■ Bitwise operators 58
6.2
Arithmetic operators
61
6.3
Other operators
62
String and array manipulation operators 62 Object type operators 63 ■ Format operator 64 Miscellaneous operators 65
6.4
Math operators
67
6.5
Summary
68
7
Working with objects
69
7.1
Introduction to objects
70
7.2
Members: properties, methods, and events
71
7.3
Sorting objects
77
7.4
Selecting objects
78
Use 1: choosing properties 78 ■ Use 2: choosing a subset of objects 80 ■ Use 3: making custom properties 82 Use 4: extracting and expanding properties 84 Use 5: choosing properties and a subset of objects 88
7.5
Filtering objects
88
Simplified syntax 89 ■ Full syntax 90 The Where method 90
7.6
Grouping objects
94
7.7
Measuring objects
96
7.8
Enumerating objects
97
Full syntax 97 ■ Simplified syntax 98 The ForEach method 99
7.9
Importing, exporting, and converting objects
100
7.10
Comparing objects
104
7.11
Summary
105
8
The PowerShell pipeline
106
8.1
How the pipeline works
106
The old way of piping 107 ■ The PowerShell way of piping 107
8.2
Parameter binding ByValue
108
8.3
Pipeline binding ByPropertyName
111
8.4
Troubleshooting parameter binding
117
8.5
When parameter binding lets you down
122
8.6
Nested pipelines
123
8.7
The pipeline with external commands
124
8.8
Summary
124
9
Formatting
125
9.1
The time to format
125
9.2
The formatting system
127
Is there a predefined view? 127 ■ What properties should be displayed? 128 ■ List or table? 128
9.3
The Format cmdlets
128
Formatting wide lists 128 ■ Formatting tables 130 Formatting lists 134 ■ Same objects, different formats 136 Custom formatting 137
9.4
Eliminating confusion and “gotchas”
139
Formatting is the end of the line 139 ■ Select or format? 140 Format, out, export—which? 141
9.5
Summary
142
P
ART
2 P
OWER
S
HELL
MANAGEMENT
...143
10
PowerShell Remoting
145
10.1
The many forms of remote control
146
10.2
Remoting overview
147
Authentication 148 ■ Firewalls and security 148
10.3
Using Remoting
148
Enabling Remoting 149 ■ 1-to-1 Remoting 152 1-to-many Remoting 153 ■ Remoting caveats 154 Remoting options 156
10.4
PSSessions
158
Creating a persistent session 158 ■ Using a session 159 Managing sessions 159 ■ Disconnecting and
reconnecting sessions 160
10.5
Advanced session techniques
162
CONTENTS xiii
10.6
Creating a custom endpoint
164
Custom endpoints for delegated administration 166
10.7
Connecting to non-default endpoints
167
10.8
Enabling the “second hop”
168
10.9
Setting up WinRM listeners
169
Creating an HTTP listener 170 ■ Adding an HTTPS listener 171
10.10
Other configuration scenarios
172
Cross-domain Remoting 172 ■ Quotas 172 Configuring on a remote machine 173 Key WinRM configuration settings 174Adding a machine to your Trusted Hosts list 175 Using Group Policy to configure Remoting 176
10.11
Implicit Remoting
177
10.12
Standard troubleshooting methodology
179
10.13
Summary
180
11
Background jobs and scheduling
181
11.1
Remoting-based jobs
182
Starting jobs 182 ■ Checking job status 183
Working with child jobs 184 ■ Waiting for a job 185 Stopping jobs 185 ■ Getting job results 185
Removing jobs 186 ■ Investigating failed jobs 187
11.2
WMI jobs
188
11.3
Scheduled jobs
188
Scheduled jobs overview 189 ■ Creating a scheduled job 189 Managing scheduled jobs 191 ■ Working with scheduled job results 191 ■ Removing scheduled jobs 192
11.4
Job processes
193
Jobs created with Start-Job 193 ■ Jobs created with Invoke-Command 193 ■ Jobs created through the
WMI cmdlets 195 ■ Jobs created through the scheduler 195
11.5
Summary
195
12
Working with credentials
196
12.1
About credentials
197
12.2
Using credentials
200
12.3
Crazy credentials ideas
201
Packaging your script 201 ■ Saving a credential object 202 Creating a credential without the GUI 203
Supporting credentials in your script 204
12.4
Summary
205
13
Regular expressions
206
13.1
Basic regular expression syntax
207
13.2
The –match operator
210
13.3
The Select-String cmdlet
212
13.4
The Switch statement
213
13.5
The REGEX object
214
Replacing with REGEX 216 ■ Splitting with REGEX 216
13.6
Subexpressions and named captures
217
13.7
Summary
221
14
Working with HTML and XML data
222
14.1
Working with HTML
222
Retrieving an HTML page 223 ■ Working with the HTML results 224 ■ Practical example 227 Creating HTML output 228
14.2
Using XML to persist data
231
14.3
XML basics
233
14.4
Reading XML files
235
14.5
Modifying XML
237
14.6
Creating XML
239
14.7
Select-XML
242
14.8
Summary
242
15
PSDrives and PSProviders
244
15.1
Why use PSProviders?
244
15.2
What are PSProviders?
245
15.3
What are PSDrives?
246
15.4
Working with PSDrives
247
Filter, Include, and Exclude 248 ■ Working with PSDrive items 249 ■ Working with item properties 252
15.5
Transactional operations
255
CONTENTS xv
15.6
Every drive is different
257
15.7
Summary
259
16
Variables, arrays, hash tables, and script blocks
260
16.1
Variables
260
Variable names 261 ■ Variable types 262 Being strict with variables 264
16.2
Built-in variables and the Variable: drive
267
16.3
Variable commands
268
16.4
Arrays
269
16.5
Hash tables and ordered hash tables
273
Ordered hash tables 277 ■ Common uses for hash tables 278 Defining default parameter values 278
16.6
Script blocks
279
16.7
Summary
281
17
PowerShell security
282
17.1
PowerShell security goals
282
17.2
PowerShell security mechanisms
283
Script execution requires a path 283 Filename extension associations 28417.3
Execution policy
285
A digital signature crash course 286 ■ Understanding script signing 287 ■ The execution policy in depth 289
17.4
Blocked files
293
17.5
The PowerShell security debate
294
17.6
Summary
295
18
Advanced PowerShell syntax
296
18.1
Splatting
296
18.2
Defining default parameter values
299
18.3
Running external utilities
303
18.4
Expressions in quotes: $($cool)
309
18.5
Parentheticals as objects
310
18.6
Increasing the format enumeration limit
311
18.7
Hash tables as objects
312
P
ART
3 P
OWER
S
HELL
SCRIPTING
AND
AUTOMATION
...315
19
PowerShell’s scripting language
317
19.1
Defining conditions
318
19.2
Loops: For, Do, While, Until
318
The For loop 318 ■ The other loops 32019.3
ForEach
321
19.4
Break and Continue
323
19.5
If . . . ElseIf . . . Else
324
19.6
Switch
326
19.7
Mastering the punctuation
329
19.8
Summary
331
20
Basic scripts and functions
332
20.1
Script or function?
332
20.2
Execution lifecycle and scope
333
20.3
Starting point: a command
334
20.4
Accepting input
334
20.5
Creating output
336
20.6
“Filtering” scripts
338
20.7
Moving to a function
340
20.8
Filter construct
342
20.9
Summary
343
21
Creating objects for output
344
21.1
Why output objects?
345
21.2
Syntax for creating custom objects
346
Technique 1: using a hash table 346 ■ Technique 2: using Select-Object 348 ■ Technique 3: using Add-Member 349 Technique 4: using a Type declaration 350 ■ Technique 5: creating a new class 351 ■ What’s the difference? 352
21.3
Complex objects: collections as properties
353
21.4
Applying a type name to custom objects
356
21.5
So, why bother?
357
CONTENTS xvii
22
Scope
361
22.1
Understanding scope
361
22.2
Observing scope in action
365
22.3
Dot sourcing
367
22.4
Manipulating cross-scope elements
369
22.5
Being private
372
22.6
Being strict
373
22.7
Summary
375
23
PowerShell workflows
376
23.1
Workflow overview
377
23.2
Workflow basics
378
Common parameters for workflows 379 ■ Activities and stateless execution 380 ■ Persisting state 381
Suspending and resuming workflows 381 Workflow limitations 381 ■ Parallelism 385
23.3
General workflow design strategy
387
23.4
Example workflow scenario
388
23.5
Writing the workflow
388
23.6
Workflows vs. functions
389
23.7
Specific workflow techniques
390
Sequences 391 ■ InlineScript 392
23.8
Running a workflow
395
Workflow jobs 395 ■ Suspending and restarting a workflow 395 ■ Workflow credentials 397
23.9
A practical example
398
23.10
Invoke-AsWorkflow
400
23.11
PSWorkflowSession
401
23.12
Troubleshooting a workflow
403
23.13
Summary
404
24
Advanced syntax for scripts and functions
406
24.1
Starting point
407
24.2
Advanced parameters
407
24.3
Variations on parameter inputs
413
24.4
Parameter aliases
414
24.6
Parameter sets
420
24.7
WhatIf and Confirm parameters
422
24.8
Verbose output
423
24.9
Summary
426
25
Script modules and manifest modules
427
25.1
Making a script module
428
25.2
Exporting module members
430
25.3
Making a module manifest
434
25.4
Creating dynamic modules
436
25.5
Summary
438
26
Custom formatting views
439
26.1
Object type names
440
26.2
Getting view templates
441
26.3
Starting a view file
442
26.4
Adding view types
443
26.5
Importing view data
445
26.6
Using named views
448
26.7
Going further
450
26.8
Summary
450
27
Custom type extensions
451
27.1
What are type extensions?
452
27.2
Creating and loading a type extension file
453
27.3
Making type extensions
455
AliasProperty 455 ■ ScriptProperty 456 ■ ScriptMethod 456 DefaultDisplayPropertySet 457
27.4
A complete example
457
27.5
Updating type data dynamically
459
27.6
Get-TypeData
462
27.7
Remove-TypeData
463
27.8
Summary
463
28
Data language and internationalization
465
28.1
Internationalization basics
466
28.2
Adding a data section
468
CONTENTS xix
28.3
Storing translated strings
470
28.4
Testing localization
473
28.5
Summary
476
29
Writing help
477
29.1
Comment-based help
478
29.2
Writing About topics
480
29.3
XML-based help
480
29.4
Summary
483
30
Error handling techniques
484
30.1
About errors and exceptions
485
30.2
Using $ErrorActionPreference and –ErrorAction
485
30.3
Using –ErrorVariable
487
30.4
Using $?
488
30.5
Using $Error
489
30.6
Trap constructs
490
30.7
Try...Catch...Finally constructs
493
30.8
Summary
495
31
Debugging tools and techniques
496
31.1
Debugging: all about expectations
497
31.2
Write-Debug
505
31.3
Breakpoints
510
31.4
Using Set-PSDebug
512
31.5
Remote debugging
514
31.6
Debugging workflows
517
31.7
Debugging in third-party editors
519
31.8
Summary
519
32
Functions that work like cmdlets
520
32.1
Defining the task
521
32.2
Building the command
522
32.3
Parameterizing the pipeline
523
32.4
Adding professional features
526
32.5
Error handling
526
Adding verbose and debug output 528 ■ Defining a custom object name 531
32.6
Making it a function and adding help
531
32.7
Creating a custom view
533
32.8
Creating a type extension
535
32.9
Making a module manifest
536
32.10
Summary
538
33
Tips and tricks for creating reports
539
33.1
What not to do
539
33.2
Working with HTML fragments and files
541
Getting the information 542 ■ Producing anHTML fragment 542 ■ Assembling the final HTML page 543
33.3
Sending email
547
33.4
Summary
547
P
ART
4 A
DVANCED
P
OWER
S
HELL
...549
34
Working with the Component Object Model (COM)
551
34.1
Introduction to COM objects
552
34.2
Instantiating COM objects in PowerShell
554
34.3
Accessing and using COM objects’ members
555
34.4
PowerShell and COM examples
557
34.5
Summary
559
35
Working with .NET Framework objects
560
35.1
Classes, instances, and members
561
35.2
.NET Framework syntax in PowerShell
562
35.3
.NET support in PowerShell
563
35.4
Accessing static members
564
35.5
Finding the right framework bits
565
35.6
Creating and working with instances
569
35.7
Summary
571
36
Accessing databases
573
36.1
Native SQL vs. OLEDB
574
36.2
Connecting to data sources
574
CONTENTS xxi
36.3
Querying data
576
Databases with DataAdapters 576 ■ Databases with DataReaders 577
36.4
Adding, changing, and deleting data
577
36.5
Calling stored procedures
578
36.6
A module to make it easier
578
36.7
Summary
580
37
Proxy functions
581
37.1
The purpose of proxy functions
581
37.2
How proxy functions work
582
37.3
Creating a basic proxy function
582
37.4
Adding a parameter
585
37.5
Removing a parameter
588
37.6
Turning it into a function
590
37.7
Summary
592
38
Building a GUI
593
38.1
WinForms via PowerShell Studio
594
Creating the GUI 595 ■ Adding the code 597 Using the script 60238.2
Windows Presentation Foundation (WPF)
and ShowUI
608
38.3
WinForms vs. WPF
610
38.4
Ideas for leveraging a GUI tool
611
38.5
Summary
612
39
WMI and CIM
613
39.1
What is WMI?
614
39.2
WMI cmdlets
615
Get-WmiObject 616 ■ Remove-WmiObject 618 Set-WmiInstance 618 ■ Invoke-WmiMethod 619 Register-WmiEvent 62239.3
CIM cmdlets
623
Get-CimClass 626 ■ Get-CimInstance 628 Remove-CimInstance 630 ■ Set-CimInstance 630 Invoke-CimMethod 631 ■ Register-CimIndicationEvent 63239.4
CIM sessions
632
39.5
“Cmdlets over objects”
635
39.6
Summary
639
40
Working with the web
640
40.1
Getting data from the web
641
40.2
Using web sessions
642
40.3
Working with web responses
645
Working with HTML documents 645 ■ Working with JSON data 646
40.4
Using REST services
649
40.5
Using SOAP web services
654
40.6
Just in case
655
40.7
Summary
655
41
Desired State Configuration
656
41.1
What is DSC?
656
41.2
DSC architecture
657
41.3
Writing the configuration script
659
41.4
Getting the configuration to the computer
663
Pull model 66441.5
Creating and testing a DSC pull server
667
Configuring a DSC pull server 670 ■ Sample configuration 674 Configuring a machine to use the pull server 675
41.6
Writing DSC resources
676
Create the MOF Schema 676 ■ Create the script module 678 Create the module manifest 679 ■ Putting it all together 679
41.7
DSC vs. Group Policy
683
41.8
Summary
684
appendix A
Best practices
685
appendix B
PowerShell Web Access
690
appendix C
PowerShell versions
695
xxi
preface
Windows PowerShell is viewed by many IT professionals as a necessary evil, but 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 VBScript, but 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 also run it in a graphical environment like the PowerShell Integrated Scripting Envi-ronment (ISE), or through a third-party tool like PowerGUI or PowerShell Plus.
As you might imagine, the fourth version of a product offers substantially more fea-tures and benefits than the first, and PowerShell 4.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.1 and Windows Server 2012 R2 as operating systems for the cloud, then PowerShell 4.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.
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.
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 making 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 questions 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, Andy Carroll, 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 Arthur Zubarev, Braj Panda, David Moravec, Jan Vinterberg, Jim Gray, Lincoln Bovee, Michel Clomp, Nick Selpa, Stuart Caborn, and Wayne Boaz.
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.
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.
JEFF would like to thank the members of the PowerShell community who make a book like this possible. He would also like to thank his coauthors for making this one of the best authoring experiences possible.
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 time zones makes for some interesting conversations.
xxv
about this book
This book was written as a reference for system administrators. You can read the book cover to cover, and we’ve tried to arrange the chapters in a logical progression, but in the end it works best as a reference, where you can explore a topic more deeply in the chapter that is devoted to a particular subject. Chapter 1 will tell you more about what you will learn in the book, and what you need to know before you start.
The 41 chapters in the book are arranged into four parts, as follows:
■ Part 1, “PowerShell Fundamentals,” includes chapters 1 through 9, which cover
the basics associated with using PowerShell. Although we didn’t write this book as a tutorial, there are a few basics you’ll need to explore before you can use PowerShell effectively: the pipeline, the concept of PowerShell hosts, the shell’s help system, and so forth. We’ll dive deeper into some of these topics than a tutorial normally would, so even if you’re already familiar with these founda-tional concepts, it’s worth a quick read-through of these chapters.
■ Part 2, “PowerShell management,” covers topics such as remote control,
back-ground jobs, regular expressions, and HTML and XML. These are just a few of the core technologies accessible within PowerShell that make server and client management easier, more scalable, and more effective. Chapters 10 through 18 tackle these technologies individually, and we dive as deeply as we can into them, so that you can master their intricacies and subtleties.
■ Part 3, “PowerShell scripting and automation,” includes chapters 19 through 33, which have a single goal: repeatability. Using PowerShell’s scripting language,
along with associated technologies like workflow, you can begin to create reus-able tools that automate key tasks and processes in your environment.
■ Part 4, “Advanced PowerShell,” consists of chapters 34 through 41. One of Power-Shell’s greatest strengths is its ability to connect to other technologies, such as
WMI, CIM, COM, .NET, and a host of other acronyms. The chapters in part 4 look at each of these and demonstrate how PowerShell can utilize them. We give you a starting place for doing this, and then we provide you with some direction for further independent exploration.
Code conventions and downloads
All source code in listings or in text is in a fixed-width font like this to separate it from ordinary text. Code annotations accompany many of the listings, highlighting important concepts. In some cases, numbered bullets link to explanations that follow the listing. The code samples are based on PowerShell 4.0. We intended the samples to be instructive, but we did not design them for production use. They may not always be the “best” PowerShell—our code examples were designed to reinforce concepts and make points.
We have tried to fit code samples into the confines of a printed page, which means that sometimes we have had to bend some rules. You are welcome to try the code snip-pets on your computer, but remember that the book is not intended as a tutorial. Longer code samples are displayed as code listings; we don’t expect you to type these. If you want to try them, the files can be downloaded from the book’s page on the pub-lisher’s website at www.manning.com/PowerShellinDepthSecondEdition.
We, along with our technical reviewer, strove to test and retest everything, but sometimes errors will still sneak through. We encourage you to use the Author Online forum for this book at www.manning.com/PowerShellinDepthSecondEdition to post any corrections, as well as your comments or questions on the book’s content.
Author Online
Purchase of PowerShell in Depth, Second Edition includes free access to a private web forum run by Manning Publications, where you can make comments about the book, ask technical questions, and receive help from the authors and from other users. To access the forum and subscribe to it, point your web browser to www.manning.com/ PowerShellinDepthSecondEdition. 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 con-duct on the forum.
Manning’s commitment to our readers is to provide a venue where a meaningful dia-logue between individual readers and between readers and the authors can take place. It is not a commitment to any specific amount of participation on the part of the authors, whose contribution to the book’s forum remains voluntary (and unpaid). We suggest you try asking the authors some challenging questions, lest their interest stray!
The Author Online forum and the archives of previous discussions will be accessi-ble from the publisher’s website as long as the book is in print.
ABOUT THIS BOOK xxvii
About the authors
DON JONES has more than 20 years of experience in the IT industry and is a recog-nized expert in Microsoft’s server platform. He’s a multiple-year recipient of Micro-soft’s prestigious Most Valuable Professional (MVP) award and writes the “Windows PowerShell” column for Microsoft TechNet Magazine. Don has authored more than 50 books on information technology topics, including three books in the popular Learn PowerShell in a Month of Lunches series from Manning. He is a regular and top-rated speaker at numerous technology conferences and symposia worldwide, and a founding director of PowerShell.org, a community-owned and community-operated resource for PowerShell users.
JEFFERY HICKS is an IT veteran with over 25 years of experience, much of it spent as an
IT infrastructure consultant specializing in Microsoft server technologies with an emphasis in automation and efficiency. He is a multi-year recipient of the Microsoft
MVP Award in Windows PowerShell. He works today as an independent author, trainer, and consultant. Jeff has authored or co-authored numerous books written for a variety of online sites and print publications, is a contributing editor at Petri.com, and is a frequent speaker at technology conferences and user groups. You can keep up with Jeff at his blog (http://jdhitsolutions.com/blog) or on Twitter (@jeffhicks).
RICHARD SIDDAWAY has been working with Microsoft technologies for over 25 years, having spent time in most IT roles. He has always been interested in automation techniques (including automating job creation and submission on mainframes many years ago). PowerShell caught his interest, and Richard has been using it since the early beta versions. He regularly blogs about PowerShell, and using PowerShell, at http://blogs.msmvps.com/richardsiddaway/. Richard founded the UK PowerShell User Group and has been a PowerShell MVP for the last seven years. He’s a regular speaker and writer on PowerShell topics, and his previous Manning books include PowerShell in Practice and PowerShell and WMI.
THE AUTHORS would love to hear from you and are eager to help spread the good news about PowerShell. We hope you’ll come up to us at conferences like TechEd and let us know how much (hopefully) you enjoyed the book. If you have any other PowerShell questions, we encourage you to use the forums at PowerShell.org, where we all are active participants, or Manning’s Author Online forum at www.manning.com/ PowerShellinDepthSecondEdition.
About the cover illustration
The figure on the cover of PowerShell in Depth, Second Edition is captioned a “Man from Split, Dalmatia.” The illustration is taken from the reproduction published in 2006 of a nineteenth-century collection of costumes and ethnographic descriptions entitled Dalmatia by Professor Frane Carrara (1812–1854), an archaeologist and historian and
the first director of the Museum of Antiquity in Split, Croatia. The illustrations were obtained from a helpful librarian at the Ethnographic Museum (formerly the Museum of Antiquity), itself situated in the Roman core of the medieval center of Split: the ruins of Emperor Diocletian’s retirement palace from around AD 304. The book includes finely colored illustrations of figures from different regions of Croatia, accompanied by descriptions of the costumes and of everyday life.
The man on the cover is wearing dark blue woolen trousers and a black vest over a white linen shirt. Over his shoulder is a brown jacket, and a red belt and a red cap complete the outfit; in his hand he holds a long pipe. The elaborate and colorful embroidery on his costume is typical for this region of Croatia.
Dress codes have changed since the nineteenth century and the diversity by region, so rich at the time, has faded away. It is now hard to tell apart the inhabitants of different continents, let alone different towns or regions. Perhaps we have traded cultural diversity for a more varied personal life—certainly for a more varied and fast-paced technological 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.
Part 1
PowerShell fundamentals
I
n part 1, we’ll cover some of the basics associated with using PowerShell. Although we didn’t write this book as a tutorial, there are nonetheless a few basics you’ll need to explore before you can use PowerShell effectively: the pipe-line, the concept of PowerShell hosts, the shell’s help system, and so forth. We’ll dive a bit deeper into some of these topics than a tutorial normally might do, so even if you’re already familiar with these foundational concepts, it’s worth a quick read-through of these chapters.3
Introduction
As of this writing, Windows PowerShell is on to its seventh year of existence and in its fourth major release, with a fifth version in preview. In that time, it’s changed the way people look at administering many Microsoft, and even some non-Microsoft, products. Although the graphical user interface (GUI) will always be an important part of administration in many ways, PowerShell has given administrators options: Use an easy, intuitive GUI; manage from a rich, interactive command-line console; or fully automate with a simple scripting language. We’re delighted that so many administrators have started using PowerShell, and we’re honored that you’ve cho-sen this book to further your own PowerShell education.
1.1
Who this book is for
We wrote this book for system administrators, not developers. In the Microsoft world, administrators go by the catchall title “IT professional” or “IT pro” and that’s who we had in mind. As such, we assume you’re not a full-time programmer, although
This chapter covers
■ What the book will and won’t teach
■ The boundaries of this book
if you have some programming or scripting experience it’ll make certain parts of Power-Shell easier to learn.
We assume you’re primarily interested in automating various administrative tasks and processes, or at least being more efficient, but we don’t make any assumptions about the products with which you work. You may be an Exchange Server administra-tor, or maybe SharePoint or SQL Server is your thing. Perhaps you manage Active Directory, or you’re in charge of file servers. You may even manage a Citrix or VMware environment (yes, they can be managed by PowerShell). It doesn’t matter, because what we’ll focus on in this book is the core technologies of PowerShell itself: the tech-niques and features you’ll need to use no matter what products you’re administering. We do use Active Directory in a few examples, but every technique, pattern, practice, and trick we show you will apply equally well, no matter where you’ve chosen to use PowerShell.
1.2
What this book will teach you
You can certainly read this book cover to cover, and we’ve tried to arrange the chap-ters in a logical progression. But in the end, we intend for this book to be a reference. Need to figure out PowerShell Remoting? Skip to that chapter. Confused about how commands pipe data from one to another? We’ve written a chapter for that. Need to access a database from within a PowerShell script? There’s a chapter for that.
We’ve no intention of making you a programmer—we don’t claim to be program-mers—we all have backgrounds as IT pros. Yes, PowerShell can support some robust scripts, but you can also accomplish a lot by running commands. If you have program-ming experience, it’ll serve you well, and you may be tempted to approach PowerShell more as a scripting language, which is fine. If you’ve never scripted or programmed a single line of code, you’ll probably see PowerShell as a pure command-line interface, where you run commands to make stuff happen, and that’s fine, too. Either way you win because you get to automate your tedious, repetitive work. The other winning fea-ture is that what you learn by using PowerShell at the command line is directly usable when you start writing scripts—there’s no wasted learning with PowerShell.
1.3
What this book won’t teach you
We assume you’re already an experienced administrator and that you’re familiar with the inner workings of whatever technology you manage. We aren’t going to teach you what an Active Directory user account is, or what an Exchange mailbox does, or how to create a SharePoint site. PowerShell is a tool that lets you accomplish administrative tasks, but like any tool it assumes you know what you’re doing.
To use a noncomputer analogy, PowerShell is a hammer, and this book will teach you how to swing that hammer and not smash your thumb. We won’t teach you about building houses, though—we assume you already know how to do that and that you’re looking for a more efficient way to do it than pounding nails with a rock.
5 Beyond PowerShell
1.4
Where we drew the line
It’s safe to say that PowerShell can’t do everything for you. You’ll find some things with which it’s completely incapable of helping, as with any technology. But you’ll also find tasks for which PowerShell works well. And you’ll encounter that weird middle ground where you could do something in PowerShell, but to do it you’d have to go beyond the strict boundaries of what PowerShell is. For example, PowerShell doesn’t natively contain a way to map a network printer.
NOTE There is a PrintManagement module containing an Add-Printer cmd-let, but it’s part of Windows (specifically Windows 8/2012 and later) rather than PowerShell.
You could instantiate a Component Object Model (COM) object to accomplish the task from within PowerShell, but it has nothing to do with PowerShell. Instead, it’s the shell giving you a way to access completely external technologies. In these cases (which are becoming increasingly rare in the latest version of Windows), we’ll only say, “You can’t do that in PowerShell yet.” We know our statement isn’t 100% true, but we want to keep this book focused on what PowerShell is and what it does natively. If we turn this book into “everything you can do with PowerShell natively, plus all the external stuff like .NET and COM and so on that you can get to from PowerShell,” it’d grow to 7,000 pages in length and we’d never finish.
That said, we’re including material in the book on using some of these external technologies, along with some guidance on where you can find resources to educate yourself on them more completely if you’ve a mind to do so.
1.5
Beyond PowerShell
PowerShell is a lot like the Microsoft Management Console (MMC), with which you’re probably familiar. On its own, it’s useless. Both the MMC and PowerShell only become useful when you add extensions, which in the MMC would be “snap-ins,” and in Power-Shell would be either a “snap-in” or a “module.” Those extensions give you access to Exchange, Active Directory, SharePoint, SQL Server, and so on. The later versions of Windows (Windows 8 and later) ship with over 50 additional modules, not counting the Remote Server Administration Tools (RSAT) modules. This additional functionality is blurring the boundaries of PowerShell. The thing to remember is that in this book we’re concentrating on the core of PowerShell so that you understand how it works. Using the other modules will become obvious once you understand PowerShell itself.
Understand that the folks at Microsoft who write PowerShell don’t write the exten-sions. They provide some tools and rules for the developers who do create extensions, but their job is to create the core PowerShell stuff. Extensions are made by other product teams: The Exchange team makes the Exchange PowerShell extension, the Active Directory team makes its extension, and so on. If you’re looking at a particular extension and don’t like what you see, blame the product team that produced it, not PowerShell. If you’d like to administer something—maybe Windows Internet Name
Service (WINS) Server, for example—and PowerShell has no way to administer it, it’s not the PowerShell team’s fault. Blame the owners of the technology you’re trying to work with, and encourage them to get on board and produce a PowerShell extension for their product.
This division of labor is one reason why we’re keeping this book focused on the core of PowerShell. That core is what you’ll use no matter what extensions you end up deploying to achieve your administrative goals.
1.6
Ready?
Okay, that’s enough of an introduction. If you want to follow along, make sure you have PowerShell v4 installed on a Windows 7 or later client. You’ll also find it useful to have a test server running PowerShell v4, ideally on Windows Server 2012 R2.
NOTE The examples and code in this book will work with PowerShell v5 if you have that installed. The major new feature in PowerShell v5 is software management through the OneGet module.
7
PowerShell hosts
PowerShell can be confusing to use because it behaves differently in different situa-tions. Here’s an example from PowerShell v2: When you run the Read-Host com-mand in the PowerShell.exe console, it behaves differently than if you run that same command in the PowerShell Integrated Scripting Editor (ISE). The reason you encounter these differences has to do with the fact that you don’t interact directly with PowerShell. Instead, you give commands to the PowerShell engine by means of a host. It’s up to the host to determine how to interact with the PowerShell engine.
NOTE The difference in the response of Read-Host between the console and the ISE has been eliminated in PowerShell v3 and later.
The PowerShell engine is a set of .NET Framework classes stored in a DLL file. You can’t interact with it directly. Instead, the application you interact with loads the
This chapter covers
■ The purpose of PowerShell hosts
■ The PowerShell console and ISE hosts
■ The differences between 64-bit and 32-bit hosts
engine. For example, if you’ve ever used the Exchange Server 2007 (or later) graphi-cal management console (graphi-called the Exchange Management Console, or EMC), then you’ve used a PowerShell host. The EMC lets you interact by clicking icons, filling in dialog boxes, and so forth, but it’s PowerShell that performs the actions it takes. You never “see” the shell, but it’s hiding under the GUI. That’s why it can show you the PowerShell commands for the actions it has performed. Exchange also provides a console-based shell that exposes the underlying PowerShell engine together with the Exchange cmdlets.
When we talk about “using PowerShell,” we’re most often talking about using it through a host that looks more like a command-line shell. Microsoft provides two dif-ferent hosts for that purpose: the console and the ISE. Third-party vendors can also produce host applications, and many popular PowerShell editors—PrimalScript,
Power-GUI, PowerShell Plus, PowerSE, and so forth—all host the PowerShell engine. You can write your own .NET programs to run PowerShell scripts or even call the underlying classes directly. How you interact with the shell and what your results look like will depend on the host you’re using. Results might look and work one way in the Micro-soft-supplied console, but they might look and work differently in a third-party appli-cation—or in some cases may not work at all. Conversely, some things that have worked in a third-party host don’t work in the Microsoft hosts.
TIP Remember that if things work in one host but not in another, it’s mostly likely due to the differences in the hosts rather than it being a PowerShell error. If you have an error in a third-party host that you can’t resolve, make sure you test it in the Microsoft PowerShell console as a lowest common denominator.
For this book, we’ll assume you’re using one of the two Microsoft-supplied hosts, which we’ll describe in this chapter.
2.1
32-bit vs. 64-bit, and administrator vs. not
The way you access the shortcuts for Microsoft’s PowerShell host applications depends on the version of the operating system and the install options you’ve chosen. The first thing you need to be aware of is that PowerShell v4 isn’t available on all versions of Windows. It’s installed as part of the base build on
■ Windows 8.1 x86 and x64
■ Windows Server 2012 R2 x64
The Windows Management Framework (WMF) download (PowerShell v4, WinRM v3 [the version of WinRM hasn’t changed between PowerShell v3 and v4], and the new
WMIAPI) is available for
■ Windows 7 SP1 (or above) x86 and x64 ■ Windows Embedded Standard 7
■ Windows Server 2008 R2SP1 (or above) x64 ■ Windows Server 2012
9 32-bit vs. 64-bit, and administrator vs. not
The WMF download is available from www.microsoft.com/en-us/download/details .aspx?id=40855. Check the version you need for your system in the download instruc-tions. You’ll notice that PowerShell v4 isn’t available for Windows 8. This is deliberate because it’s included in the free Windows 8.1 upgrade.
NOTE If you’re using Windows XP, Windows Vista, Windows Server 2008, or any flavor of Windows Server 2003, you can’t install PowerShell v4. Check appendix C for further information on the differences between the Power-Shell versions.
You’ll need to install Microsoft .NET Framework 4.5 (use the full offline installer from http://msdn.microsoft.com/en-us/library/5a4x27ek(v=vs.110).aspx) before install-ing WMF 4.0. The 4.5 version of the framework is preinstalled on Windows 8.1 and Windows Server 2012 R2.
Microsoft, and other vendors, have produced tablet devices with Windows RT
installed. These devices, such as the Microsoft Surface, do have PowerShell installed, but the instance of PowerShell is constrained in that you can’t access some features. Which features are unavailable depends on whether the device is running Windows 8 or Windows 8.1 RT, but here are some examples:
■ You can’t remote into the device.
■ You can’t run workflows.
■ You can’t use Desired State Configuration. In addition, the ISE isn’t available on Surface devices.
NOTE The Microsoft Surface Pro devices run a full version of PowerShell, including the ISE.
In the Windows 8/2012 family of products, the way you access applications has changed. You use the Start screen instead of the Start menu. If you’re on the Windows
Application incompatibilities
Don’t install WMF 4.0 on a system running any of the following:
■ System Center 2012 Configuration Manager (but you can install SP1 to remove the incompatibility)
■ Microsoft Exchange Server 2013
■ Microsoft Exchange Server 2010
■ Microsoft Exchange Server 2007
■ Microsoft SharePoint Server 2013
■ Microsoft SharePoint Server 2010
■ Windows Small Business Server 2011 Standard
These restrictions also apply to WMF 3.0 (PowerShell 3.0), but they may be changed with the issue of Service Packs for these applications. Please check the application documentation to see if there are any changes.
Desktop, press the Win button to access the Start screen or click the Start button in Windows 8.1/2012 R2. Scroll to the right to find the PowerShell icon. Alternatively, press Win-Q to access the application search menu.
On earlier versions of Windows you’ll find shortcuts to Microsoft’s host applica-tions on your computer’s Start menu. If you’re on a Server Core (Windows Server 2008 R2 or later) system that doesn’t have a Start menu, run powershell to start the console host. You’ll need to install PowerShell because it isn’t part of the default Win-dows Server 2008 R2 server core install. The shortcuts can usually be found under Accessories > Windows PowerShell.
NOTE PowerShell and the old command prompt use the same underlying console technology, which means you can type Powershell in a command prompt or cmd in a PowerShell console and “switch” to the other shell. Typing exit will revert back to the starting shell.
On a 32-bit system (on any Windows version), you’ll find shortcuts for PowerShell— what we refer to as “the console”—and for the PowerShell ISE. Obviously, these short-cuts both point to 32-bit versions of PowerShell. But on a 64-bit system you’ll find four shortcuts:
■ Windows PowerShell—the 64-bit console ■ Windows PowerShell ISE—also 64-bit
■ Windows PowerShell (x86)—the 32-bit console ■ Windows PowerShell ISE (x86)—also 32-bit
It’s important to run the proper version, either 32-bit or 64-bit. PowerShell itself behaves the same either way, but when you’re ready to load extensions you can only load ones built on the same architecture. The 64-bit shell can only load 64-bit exten-sions. If you have a 32-bit extension, you’ll have to load it from the 32-bit shell. Once you launch, the window title bar will also display “(x86)” for the 32-bit versions, which means you can always see which one you’re using.
TIP We recommend that you pin PowerShell to your taskbar. Doing so makes access much quicker. Right-clicking the icon on the taskbar provides access to the PowerShell console and the ISE in addition to providing links to run as Administrator for both hosts.
On computers that have User Account Control (UAC) enabled, you’ll need to be a bit careful. If your PowerShell window title bar doesn’t say “Administrator,” you’re not running PowerShell with Administrator authority.
WARNING Watch the top-left corner of the host as it starts. It will say “Admin-istrator: Windows PowerShell” or “Admin“Admin-istrator: Windows PowerShell ISE” during at least some of the startup period. Some of us, like Richard, modify the title bar to display the path to the current working directory so the title bar won’t show “Administrator” once the profile has finished executing.
11 32-bit vs. 64-bit, and administrator vs. not
If you’re not running as an Administrator, some tasks may fail with an “Access Denied” error. For example, you can only access some WMI classes when you’re using Power-Shell with the elevated privileges supplied by running as Administrator. If your title bar doesn’t say “Administrator” and you need to be an Administrator to do what you’re doing, close the shell. Reopen it by right-clicking one of the Start menu short-cuts and selecting Run as Administrator from the context menu. That’ll get you a win-dow title bar like the one shown in figure 2.1, which is what you want. In Winwin-dows 8, either right-click the taskbar shortcut or right-click the title on the Start screen to access the Run as Administrator option.
It’s always worth taking a moment to verify whether your session is elevated before continuing with your work. One way you can do this is to modify your profile so that the console top border indicates whether PowerShell is elevated (in addition to speci-fying whether it’s x86 or x64 and the current folder). You can then set a smaller prompt so that you have more of the console to type in. By default the current path is shown at the prompt, as you can see in figure 2.1. The function you need to add to your profile appears in listing 2.1.
function prompt {
if ([System.IntPtr]::Size -eq 8) {$size = '64 bit'} else {$size = '32 bit'}
$currentUser = [Security.Principal.WindowsIdentity]::GetCurrent() $secprin = New-Object Security.Principal.WindowsPrincipal $currentUser if ($secprin.IsInRole([Security.Principal.WindowsBuiltinRole]::Administrator)) {$admin = 'Administrator'}
else {$admin = 'non-Administrator'} $host.ui.RawUI.WindowTitle = "$admin $size $(get-location)" "£> "
}
Listing 2.1 Prompt function for PowerShell profile
Figure 2.1 An elevated PowerShell session from Windows 8.1. Notice the Administrator label in the caption. Determine 64- or 32-bit
