Table Of Content

Toolmaking Best Practices Checklist  A tool does one thing and one thing only.  The verb in a tool name accurately describes functionality.  All input is via parameters.  Handle pipeline input correctly.  Enable and use common parameters.  Objects are the only form of pipeline output emitted.  Catch and handle anticipated errors.  Include comment-based help at a minimum. The Single-Task-Tool Rant PowerShell is predicated on the idea of small, single-purpose tools (you know them as cmdlets and functions) that you can string together in a pipe- lined expression to achieve amazing results with minimal effort. We strug- gle all the time to help folks understand this “single-task tool” principle, and we want to say something specific about it here. It’s easy to think, “Well, provisioning a new user is a single task.” No, it isn’t. It’s a process, and if you think about how you’d perform it manually, you’d realize instantly that it consists of multiple actual tasks. You have to create the user, set up a home folder, create a user library in SharePoint, and so on. Were you to start coding the process, you’d create a tool for each task: new user, new home folder, SharePoint account, and so forth (many of those tasks can be accomplished using tools Microsoft has already written). You’d then “connect” those tools together, into a process, by writing what we call a controller script. Even something as simple as writing information to a CSV file is a single task (and PowerShell has a tool that does that). If you have a script that both produces new information and takes the time to format it as CSV and write it to a file, then you’re not only doing it wrong—you’re working too hard. From this point on, start thinking about making things smaller. For any given process that you need to automate, what are the smallest units of work you can create to accomplish each task within the process? Can anything be made smaller, or broken into multiple discrete pieces? This is the essence of toolmaking. Learn PowerShell Scripting in a Month of Lunches Learn PowerShell Scripting in a Month of Lunches DON JONES JEFFERY HICKS MANNING 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 761 Shelter Island, NY 11964 Email: [email protected] ©2018 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: Frances Lefkowitz 20 Baldwin Road Technical development editor: James Berkenbile PO Box 761 Project editor: Janet Vail Shelter Island, NY 11964 Copyeditor: Tiffany Taylor Proofreader: Alyson Brener Technical proofreader: James Berkenbile Typesetter: Dennis Dalinnik Cover designer: Leslie Haimes ISBN: 9781617295096 Printed in the United States of America 1 2 3 4 5 6 7 8 9 10 – EBM – 22 21 20 19 18 17 brief contents PART 1 INTRODUCTION TO SCRIPTING ......................................1 1 ■ Before you begin 3 2 ■ Setting up your scripting environment 8 3 ■ WWPD: what would PowerShell do? 19 4 ■ Review: parameter binding and the PowerShell pipeline 25 5 ■ Scripting language crash course 36 6 ■ The many forms of scripting (and which to use) 48 7 ■ Scripts and security 58 PART 2 BUILDING A POWERSHELL SCRIPT................................67 8 ■ Always design first 69 9 ■ Avoiding bugs: start with a command 80 10 ■ Building a basic function and script module 88 11 ■ Going advanced with your function 99 12 ■ Objects: the best kind of output 111 13 ■ Using all the pipelines 122 v vi BRIEF CONTENTS 14 ■ Simple help: making a comment 136 15 ■ Dealing with errors 146 16 ■ Filling out a manifest 158 PART 3 GROWN-UP SCRIPTING...............................................169 17 ■ Changing your brain when it comes to scripting 171 18 ■ Professional-grade scripting 190 19 ■ An introduction to source control with git 202 20 ■ Pestering your script 221 21 ■ Signing your script 234 22 ■ Publishing your script 244 PART 4 ADVANCED TECHNIQUES............................................253 23 ■ Squashing bugs 255 24 ■ Making script output prettier 272 25 ■ Wrapping up the .NET Framework 292 26 ■ Storing data—not in Excel! 302 27 ■ Never the end 314 contents preface xvii acknowledgments xix about this book xx about the authors xxii PART 1 INTRODUCTION TO SCRIPTING ............................1 1 Before you begin 3 1.1 What is toolmaking? 3 1.2 Is this book for you? 4 1.3 Here’s what you need to have 5 PowerShell version 5 ■ Administrative privileges 5 SQL Server 5 ■ Script editor 6 1.4 How to use this book 6 1.5 Expectations 7 1.6 How to ask for help 7 1.7 Summary 7 vii viii CONTENTS 2 Setting up your scripting environment 8 2.1 The operating system 8 2.2 Windows PowerShell 9 2.3 Administrative privileges and execution policy 9 2.4 A script editor 9 2.5 Setting up a virtual environment 13 2.6 Example code 14 2.7 SQL Server Express 14 2.8 Your turn 18 3 WWPD: what would PowerShell do? 19 3.1 Writing single-task tools 19 3.2 Naming tools 20 3.3 Naming parameters 21 3.4 Producing output 22 3.5 Don’t assume 23 3.6 Avoid innovation 23 3.7 Summary 24 4 Review: parameter binding and the PowerShell pipeline 25 4.1 Visualizing the pipeline 25 4.2 It’s all in the parameters 26 4.3 Plan A: ByValue 27 Introducing Trace-Command 28 ■ Tracing ByValue parameter binding 28 ■ When ByValue fails 31 4.4 ByPropertyName 31 Let’s trace ByPropertyName 32 ■ When ByPropertyName fails 34 ■ Planning ahead 35 4.5 Summary 35 5 Scripting language crash course 36 5.1 Comparisons 36 Wildcards 37 ■ Collections 38 ■ Troubleshooting comparisons 38 5.2 The If construct 38 5.3 The ForEach construct 41