\nPart 3: Controller Scripts and Visual Scripting

With your tools constructed and tested, it’s time to put them to work - and that means writing controller scripts. Not sure what that means? Keep reading. We’ll look at several kinds, from simple to complex, and look at a couple of other, unique ways in which you can put your tools to work.

",{"_333":334,"_43":44,"_47":48,"_45":46,"_70":71,"_335":336,"_404":331},"previewContent","

\n About This Book\n
\n Dedication\n
- \n Acknowledgments\n
\n
\n About the Authors\n
- \n Additional Credits\n
\n
\n Foreword\n
\n Introduction\n
- \n Pre-Requisites\n
- \n Versioning\n
- \n The Journey\n
- \n Following Along\n
- \n Providing Feedback\n
\n
\n Part 1: Review PowerShell Toolmaking\n
\n Functions, the Right Way\n
- \n Tool Design\n
- \n Start with a Command\n
- \n Build a Basic Function and Module\n
- \n Adding CmdletBinding and Parameterizing\n
- \n Emitting Objects as Output\n
- \n Using Verbose, Warning, and Informational Output\n
- \n Comment-Based Help\n
- \n Handling Errors\n
- \n Are You Ready\n
\n
\n Part 2: Professional-Grade Toolmaking\n
\n Publishing Your Tools\n
- \n Begin with a Manifest\n
- \n Publishing to PowerShell Gallery\n
- \n Publishing to Private Repositories or Galleries\n
- \n Your Turn\n
- \n Let’s Review\n
\n
\n Part 3: Controller Scripts and Visual Scripting\n
\n Proxy Functions\n
- \n For Example\n
- \n Creating the Proxy Base\n
- \n Modifying the Proxy\n
- \n Adding or Removing Parameters\n
- \n Your Turn\n
- \n Let’s Review\n
\n
\n Part 4: The Data Connection\n
\n Working with SQL Server Data\n
- \n SQL Server Terminology and Facts\n
- \n Connecting to the Server and Database\n
- \n Writing a Query\n
- \n Running a Query\n
- \n Invoke-SqlCmd\n
- \n Thinking About Tool Design Patterns\n
- \n Let’s Review\n
- \n Review Answers\n
\n
\n Part 5: Seriously Advanced Toolmaking\n
\n Measuring Tool Performance\n
- \n Is Performance Important\n
- \n Measure What’s Important\n
- \n Factors Affecting Performance\n
- \n Key Take-Away\n
\n
\n Part 6: Pester\n
\n Why Pester Matters\n
\n Part 7: PowerShell 7 Scripting\n
\n Cross Platform Scripting\n
- \n Know Your OS\n
- \n State Your Requirements\n
- \n Testing Variables\n
- \n Environment Variables\n
- \n Paths\n
- \n Watch Your Aliases\n
- \n Using Culture\n
- \n Leverage Remoting\n
- \n Custom Module Manifests\n
\n

\nAbout This Book

\n\n

The ‘Forever Edition’ of this book is published on Leanpub, a digital publishing platform. That means the book is published as we write it, and that means we’ll be able to revise it as needed in the future. We also appreciate your patience with any typographical errors, and we appreciate you pointing them out to us - to keep the book as “agile” as possible, we’re forgoing a traditional copyedit. We hope that you’ll appreciate getting the technical content quickly, and won’t mind helping us catch any errors we may have made. You paid a bit more for the book than a traditional one, but that up-front price means you can come back whenever you like and download the latest version. We plan to expand and improve the book pretty much forever, so it’s hopefully the last one you’ll need to buy on this topic!

\n\n

You may also find this book offered by traditional booksellers like Amazon. In those cases, the book is sold as a specific edition, such as “Second Edition.” These represent a point-in-time snapshot of the book and are offered at a lower price than the Leanpub-published version. These traditionally published editions do not include future updates.

\n\n

If you purchased this book, thank you. Know that writing a book like this takes hundreds of hours of effort, during which we’re not making any other income. Your purchase price is important to keeping a roof over our families’ heads and food on our tables. Please treat your copy of the book as your copy - it isn’t to be uploaded anywhere, and you aren’t meant to give copies to other people. We’ve made sure to provide a DRM-free file (excepting any DRM added by a bookseller other than Leanpub) so that you can use your copy any way that’s convenient for you. We appreciate your respecting our rights and not making unauthorized copies of this work.

\n\n

If you got this book for free from someplace, know that you are making it difficult for us to write books. When we can’t make even a small amount of money from our books, we’re encouraged to stop writing them. If you find this book useful, we would greatly appreciate you purchasing a copy from LeapPub.com or another bookseller. When you do, you’ll be letting us know that books like this are useful to you and that you want people like us to continue creating them.

\n\n\n\n

\n\n

This book is copyrighted (c)2017-2024 by Don Jones and Jeffery Hicks, and all rights are reserved. This book is not open source, nor is it licensed under a Creative Commons license. This book is not free, and the authors reserve all rights.

\n\n

\nDedication

\n\n

This book is fondly dedicated to the many hardworking PowerShell users who have, for more than a decade, invited us into their lives through our books, conference appearances, instructional videos, live classes, and more. We’re always humbled and honored by your support and kindness, and you inspire us to always try harder and to do more. Thank you.

\n\n

\nAcknowledgments

\n\n

Thanks to Michael Bender, who has selflessly provided a technical review of the book. Any remaining errors are, of course, still the authors’ fault, but Michael has been tireless in helping us catch many of them.

\n\n\n

\nAbout the Authors

\n\n

Don Jones was an on-stage presenter during the launch of Windows PowerShell at TechEd Europe 2006 and was the co-author of the first three published books on PowerShell. He was a 16-year recipient of Microsoftâ€™s Most Valuable Professional (MVP) Award, co-founder of PowerShell Summit and The DevOps Collective, and co-author of the bestselling Learn Windows PowerShell in a Month of Lunches through its first three editions. Don also wrote more than sixty books on a variety of technology and business topics. Today, most of Donâ€™s writing consists of fantasy and science fiction novels, which you can find at DonJones.com.

\n\n

Jeff Hicks is an IT veteran with over 30 years of experience, much of it spent as an IT infrastructure consultant specializing in Microsoft server technologies with an emphasis on automation and efficiency. He is a multi-year recipient of the Microsoft MVP Award for his PowerShell-related contributions. He works today as an independent author, teacher, and consultant. Jeff has taught and presented about PowerShell and the benefits of automation to IT Pros worldwide for over 25 years. He has authored and co-authored several books, writes for numerous online sites, is a Pluralsight author, and is a frequent speaker at technology conferences and user groups.

\n\n

You can learn about all of Jeff’s online identities and activities at jdhitsolutions.github.io.

\n\n

\nAdditional Credits

\n\n

Technical editing has been helpfully provided not only by our readers but also by Michael Bender. We’re grateful to Michael for not only catching a lot of big and little problems but for fixing most of them for us. Michael rocks, and you should watch his Pluralsight videos. However, anything Michael didn’t catch is still firmly the authors’ responsibility.

\n\n\n

\nForeword

\n\n

After the success of Learn PowerShell in a Month of Lunches, Jeff and I wanted to write a book that took people down the next step, into actual scripting. The result, of course, was Learn PowerShell Toolmaking in a Month of Lunches. In the intervening years, as PowerShell gained more traction and greater adoption, we realized that there was a lot more of the story that we wanted to tell. We wanted to get into help authoring, unit testing, and more. We wanted to cover working with different data sources, coding in Visual Studio, and so on. These were really out of scope for the Month of Lunches series’ format. And even in the “main” narrative of building a proper tool, we wanted to go into more depth. So while the Month of Lunches book was still a valuable tutorial in our minds, we wanted something with more teeth.

\n\n

At the same time, this stuff is changing very fast these days. Fast enough that a traditional publishing process - which can add as much as four months to a book’s publication - just can’t keep up. Not only are we kind of constantly tweaking our narrative approach to explaining these topics, but the topics themselves are constantly evolving, thanks in part to many incredibly robust community-building add-ons like Pester, Platyps, and more.

\n\n

So after some long, hard thinking, we decided to launch this effort. As an Agile-published book on Leanpub, we can continuously add new content, update old content, fix the mistakes you point out to us, and so on. We can then take major milestones and publish them as “snapshots” on places like Amazon, increasing the availability of this material. We hope you find the project as exciting and dynamic as we do, and we hope you’re generous with your suggestions - which may be sent to us via the author contact form from this book’s page on Leanpub.com. We’ll continue to use traditional paper publishing, but through a self-publishing outlet that doesn’t impose as much process overhead on getting the book in print. These hard copy editions will be a “snapshot” or “milestone edition” of the electronic version.

\n\n

It’s important to know that we still think traditional books have their place. PowerShell Scripting in a Month of Lunches, the successor to Learn PowerShell Toolmaking in a Month of Lunches, covers the kind of long-shelf-life narrative that is great for traditionally published books. It’s an entry-level story about the right way to create PowerShell tools, and it’s very much the predecessor to this book. If Month of Lunches is about getting your feet under you and putting them on the right path, this book is about refining your approach and going a good bit further on your journey.

\n\n

Toolmaking, for us, is where PowerShell has always been headed. It’s the foundation of a well-designed automation infrastructure, of a properly built DSC model, and of pretty much everything else you might do with PowerShell. Toolmaking is understanding what PowerShell is, how PowerShell wants to work, and how the world engages with PowerShell. Toolmaking is a big responsibility.

\n\n

My first job out of high school was as an apprentice for the US Navy. In our first six weeks, we rotated through various shops - electronics, mechanical, and so on - to find a trade that we thought we’d want to apprentice for. For a couple of weeks, I was in a machine shop. Imagine a big, not-climate-controlled warehouse full of giant machines, each carving away at a piece of metal. Lubrication and metal chips are flying everywhere, and you wash shavings out of yourself every evening when you go home. It was disgusting, and I hated it. It was also boring - you set a block of metal into the machine, which might take hours to get precisely set up, and then you just sat back and kind of watched it happen. Ugh. Needless to say, I went into the aircraft mechanic trade instead. Anyway, in the machine shop, all the drill bits and stuff in the machine were called tools and dies. Back in the corner of the shop, in an enclosed, climate-controlled room sat a small number of nicely-dressed guys in front of computers. They were using CAD software to design new tools and dies for specific machining purposes. These were the tool makers, and I vowed that if I was ever going to be in this hell of a workplace, I wanted to be a toolmaker and not a tool user. And that’s the genesis of this book’s title. All of us - including the organizations we work for - will have happier, healthier, more comfortable lives as high-end, air-conditioned toolmakers rather than the sweaty, soaked, shavings-filled tool users out on the shop floor.

\n\n

Enjoy!

\n\n

Don Jones

\n\n\n

\nIntroduction

\n\n

\nPre-Requisites

\n\n

We’re assuming that you’ve already finished reading an entry-level tutorial like, Learn Windows PowerShell in a Month of Lunches, or that you’ve got some solid PowerShell experience already under your belt. Specifically, nothing on this list should scare you:

\n\n

Find commands and learn to use them by reading help
Write very basic “batch file” style scripts
Use multiple commands together in the pipeline
Query WMI/CIM classes
Connect to remote computers by using Remoting
Manipulate command output to format it, export it, or convert it, using PowerShell commands to perform those tasks

\n\n

If you’ve already done things like written functions in PowerShell, that’s marvelous - but, you may need to be open to un-learning some things. Some of PowerShell’s best practices and patterns aren’t immediately obvious, and especially if you know how to code in another language, it’s easy to go down a bad path in PowerShell. We’re going to teach you the right way to do things, but you need to be willing to re-do some of your past work if you’ve been following the Wrong Ways.

\n\n

We also assume that you’ve read PowerShell Scripting in a Month of Lunches, a book we wrote for Manning. It provides the core narrative of “the right way to write PowerShell functions and tools,” this book essentially picks up where that one leaves off. Look for that book in late 2017 from Manning or your favorite bookseller. Part 1 of this book briefly slams through this “the right way” narrative just to make sure you’ve got it in your mind, but the Month of Lunches title digs into those ideas in detail.

\n\n

\nVersioning

\n\n

This book is primarily written against Windows PowerShell v5/v5.1 running on Microsoft Windows. In January 2018, Microsoft announced the General Availability of PowerShell Core 6.0, which is a distinct cross-platform “branch” of PowerShell. This branch has now become PowerShell 7, which was released in early 2020. As far as we can tell, everything we teach in this book applies to PowerShell 7, too - although some of our specific examples may still only work on Windows PowerShell, the concepts and techniques apply to PowerShell 7. However, PowerShell 7 includes some new scripting features which we’ll cover in a dedicated chapter or two.

\n\n

\nThe Journey

\n\n

This book is laid out into seven parts:

\n\n

A quick overview of “the right way” to write functions.
Professional-grade toolmaking, where you amp up your skills, comes next in a second narrative. This part is less tightly coupled than the first, so you can just read what you think you need, but we still recommend reading the chapters in order.
Moving on from toolmaking for a moment, we’ll cover different kinds of controller scripts that can put your tools to use. Read these in whatever order you like.
Data sources are often a frustrating point in PowerShell, and so this part is dedicated to those. Again, read whichever ones you think you need.
More advanced topics complete the book, and again you can just read these as you encounter a need for them.
A high-level introduction to using Pester in your toolmaking development.
Scripting for the PowerShell 7 and cross-platform world.

\n\n

\nFollowing Along

\n\n

We’ve taken some pains to provide review Q&A at the end of most chapters, and to provide lab exercises (and example answers) at the end of many chapters. We strongly encourage you to follow along and complete those exercises - doing is a lot more effective than just reading. We’ve tried to design the labs so that they only need a Windows client computer - so you won’t need a complex, multi-machine lab setup. Of course, if you have more than one computer to play with, some of the labs can be more interesting since you can write tools that query multiple computers and so forth. But the code’s the same even if you’re just on a single Windows client, so you’ll be learning what you need to learn.

\n\n

\nProviding Feedback

\n\n

Finally, we hope that you’ll feel encouraged to give us feedback on this book. There’s a “Contact the Authors” form on this book’s page on Leanpub.com.

\n\n\n\n

\nPart 1: Review PowerShell Toolmaking

\n\n

This first Part of the book is essentially a light-speed refresher of what PowerShell Scripting in a Month of Lunches covers. If you’ve read that book, or feel you have equivalent experience, then this short Part will help refresh you on some core terminology and techniques. If you haven’t… well, we strongly recommend you get that fundamental information under your belt first.

\n\n\n

\nFunctions, the Right Way

\n\n

This chapter is essentially meant to be a warp-speed review of the material we presented in the core narrative of Learn PowerShell Toolmaking in a Month of Lunches (and its successor, PowerShell Scripting in a Month of Lunches). This material is, for us, “fundamental” in nature, meaning it remains essentially unchanged from version to version of PowerShell. Consider this chapter a kind of “pre-req check;” if you can blast through this, nodding all the while and going, “yup,” then you’re good to skip to the next Part of this book. If you run across something where you’re like, “Wait, what?” then a review of those foundational, prerequisite books might be in order, along with a thorough reading of this Part of this book.

\n\n\n\n

\nTool Design

\n\n

We strongly advocate that you always begin building your tools by first designing them. What inputs will they require? What logical decisions will they have to make? What information will they output? What inputs might they consume from other tools, and how might their output be consumed? We try to answer all of these questions - often in writing! - upfront. Doing so helps us think through how our tool will be used, by different people at different times, and to make good decisions about how to build the tool when it comes time to code.

\n\n

\nStart with a Command

\n\n

Once we know what the tool’s going to do, we begin a console-based (never in a script editor) process of discovery and prototyping. Or, in plain English, we figure out the commands we’re going to need to run, figure out how to run them correctly, and, figure out what they produce and how we’re going to consume it. This isn’t a lightweight step - it can often be time-consuming, and it’s where all of your experimentation can occur.

\n\n

A user in PowerShell.org’s forums once posted a request for help with the following:

\n\n\n\n

And yup - that’s what “Start with a Command” means. We’d probably start by planning that out - inputs are clearly some kind of DFS root name or server name and an output path for the reports to be written. Then the discovery process would begin: how can PowerShell connect to a DFS root? How can it enumerate targets? How can it resolve the target physical location and query NTFS permissions? Good ol’ Google, and experience, would be our main tool here, and we wouldn’t go an inch further until we had a text file full of answers, sample commands, and notes.

\n\n

\nBuild a Basic Function and Module

\n\n

With all the functional bits in hand, we begin building tools. We almost always start with a basic function (no [CmdletBinding()] attribute) located in a script module. Why a script module? It’s the end goal for us, and it’s easier to test. We’d fill in our parameters, and start adding the functional bits to the function itself. We tend to add things in stages. So, taking that DFS example, we’d first write a function that simply connected to a DFS root and spewed out its targets. Once that was working, we’d add the bit for enumerating the targets’ physical locations. Then we’d add permission querying… and so on, and so on, until we were done. None of that along-the-way output would be pretty - it’d just be verifying that our code was working.

\n\n

\nAdding CmdletBinding and Parameterizing

\n\n

We’d then professional-ize the function, adding [CmdletBinding()] to enable the common parameters. If we’d hard-coded any changeable values (we do that sometimes, during development), we’d move those into the Param() block. We’d also dress up our parameters, specifying data [types], mandatory-ness, pipeline input, validation attributes, and so on. We’d obviously re-test.

\n\n

\nEmitting Objects as Output

\n\n

Next, we work on cleaning up our output. We remove any “development” output created by Write-Output or Write-Host (yeah, it happens when you’re hacking away). Our function’s only output would be an object, and in the DFS example, it’d probably include stuff like the DFS root name, target, physical location, and a “child object” with permissions.

\n\n\n\n

\nUsing Verbose, Warning, and Informational Output

\n\n

If we hadn’t already done so, we’d take the time to add Write-Verbose calls to our function so that we could track its progress. We tend to do that habitually as we write, almost instead of comments a lot of the time, but we have built that up as a habit. We’d add warning output as needed, and potentially add Write-Information calls if we wanted to create structured, queryable “sidebar” output.

\n\n

\nComment-Based Help

\n\n

We’d definitely “dress up” our code using comment-based help if not full help (we cover that later in the book). We’d make sure to provide usage examples, documentation for each parameter, and a pretty detailed description of what the tool did.

\n\n

\nHandling Errors

\n\n

Finally, and again if we hadn’t habitually done so already, we’d anticipate errors and try to handle them gracefully. “Permission Denied” querying permissions on a file? Handled - perhaps outputting an object, for that file, indicating the error.

\n\n

\nAre You Ready

\n\n

That’s our process. The entire way through, we make sure we’re conforming as much as possible to PowerShell standards. Input via parameters only; output only to the pipeline, and only as objects. Standardized naming, including Verb-Noun naming for the function, and parameter names that reflect existing patterns in native PowerShell commands. We try to get our command to look and feel as much like a “real” PowerShell command as possible, and we do that by carefully observing what “real” PowerShell commands do.

\n\n

Ok, if you’ve gotten this far and you’re still thinking, “Yup, got all that and good to go,” then you’re… well, you’re good to go. Proceed.

\n\n\n

\nPart 2: Professional-Grade Toolmaking

\n\n

In this Part, we’re going to try and take your toolmaking skills a bit further. This is the stuff that sets the beginners apart from the real pros. We’ve constructed these chapters into a kind of storyline, so each one builds on what the previous ones taught. That said, the storyline here isn’t tightly coupled, so feel free to dive into whatever chapter seems of most interest or use to you. Because we’re moving into Toolmaking areas that are more optional and as-you-need, you won’t see “Your Turn” lab elements in every chapter - but that doesn’t mean you shouldn’t try and play along! Just follow along with your own code. However, when we include a “Your Turn” section, we obviously strongly suggest you follow along with that “lab.”

\n\n\n

\nPublishing Your Tools

\n\n

Inevitably, you’ll come to a point where you’re ready to share your tools. Hopefully, you’ve put those into a PowerShell module, as we’ve been advocating throughout this book because in most cases it’s a module that you’ll share.

\n\n

\nBegin with a Manifest

\n\n

You’ll typically need to ensure that your module has a .psd1 manifest file since most repositories will use information from that to populate repository metadata. Here’s the manifest from our downloadable sample code.

\n\n

#\n# Module manifest for module 'PowerShell-Toolmaking'\n#\n# Generated by: Don Jones & Jeffery Hicks\n#\n\n@{\n\n# Script module or binary module file associated with this manifest.\nRootModule = 'PowerShell-Toolmaking.psm1'\n\n# Version number of this module.\nModuleVersion = '2.0.0.0'\n\n# Supported PSEditions\nCompatiblePSEditions = @(\"Desktop\")\n\n# ID used to uniquely identify this module\nGUID = '3926b244-469c-4434-a4b1-70ce3b0bfb5d'\n\n# Author of this module\nAuthor = 'Don Jones & Jeffery Hicks'\n\n# Company or vendor of this module\nCompanyName = 'Unknown'\n\n# Copyright statement for this module\nCopyright = '(c) 2024 Don Jones & Jeffery Hicks. All rights reserved.'\n\n# Description of the functionality provided by this module\nDescription = \"Sample for for 'The PowerShell Scripting and Toolmaking Book' by Don \\\nJones and Jeffery Hicks published on Leanpub.com.\"\n\n# Minimum version of the Windows PowerShell engine required by this module\n# PowerShellVersion = ''\n\n# Name of the Windows PowerShell host required by this module\n# PowerShellHostName = ''\n\n# Minimum version of the Windows PowerShell host required by this module\n# PowerShellHostVersion = ''\n\n# Minimum version of Microsoft .NET Framework required by this module. This prerequi\\\nsite is valid for the PowerShell Desktop edition only.\n# DotNetFrameworkVersion = ''\n\n# Minimum version of the common language runtime (CLR) required by this module. This\\\n prerequisite is valid for the PowerShell Desktop edition only.\n# CLRVersion = ''\n\n# Processor architecture (None, X86, Amd64) required by this module\n# ProcessorArchitecture = ''\n\n# Modules that must be imported into the global environment prior to importing this \\\nmodule\n# RequiredModules = @()\n\n# Assemblies that must be loaded prior to importing this module\n# RequiredAssemblies = @()\n\n# Script files (.ps1) that are run in the caller's environment prior to importing th\\\nis module.\n# ScriptsToProcess = @()\n\n# Type files (.ps1xml) to be loaded when importing this module\n# TypesToProcess = @()\n\n# Format files (.ps1xml) to be loaded when importing this module\n# FormatsToProcess = @()\n\n# Modules to import as nested modules of the module specified in RootModule/ModuleTo\\\nProcess\n# NestedModules = @()\n\n# Functions to export from this module, for best performance, do not use wildcards a\\\nnd do not delete the entry, use an empty array if there are no functions to export.\nFunctionsToExport = '*'\n\n# Cmdlets to export from this module, for best performance, do not use wildcards and\\\n do not delete the entry, use an empty array if there are no cmdlets to export.\nCmdletsToExport = '*'\n\n# Variables to export from this module\nVariablesToExport = '*'\n\n# Aliases to export from this module, for best performance, do not use wildcards and\\\n do not delete the entry, use an empty array if there are no aliases to export.\nAliasesToExport = '*'\n\n# DSC resources to export from this module\n# DscResourcesToExport = @()\n\n# List of all modules packaged with this module\n# ModuleList = @()\n\n# List of all files packaged with this module\n# FileList = @()\n\n# Private data to pass to the module specified in RootModule/ModuleToProcess. This m\\\nay also contain a PSData hashtable with additional module metadata used by PowerShel\\\nl.\nPrivateData = @{\n\n    PSData = @{\n\n        # Tags applied to this module. These help with module discovery in online ga\\\nlleries.\n        # Tags = @()\n\n        # A URL to the license for this module.\n        # LicenseUri = ''\n\n        # A URL to the main website for this project.\n        # ProjectUri = ''\n\n        # A URL to an icon representing this module.\n        # IconUri = ''\n\n        # ReleaseNotes of this module\n        # ReleaseNotes = ''\n\n    } # End of PSData hashtable\n\n} # End of PrivateData hashtable\n\n# HelpInfo URI of this module\n# HelpInfoURI = ''\n\n# Default prefix for commands exported from this module. Override the default prefix\\\n using Import-Module -Prefix.\n# DefaultCommandPrefix = ''\n\n}\n

\n\n\n\n

A lot of this is commented out, which is the default when you use New-ModuleManifest. The specifics you must provide will differ based on your repository’s requirements, but in general, we recommend at least the following be completed:

\n\n

\nRootModule. This is mandatory for the .psd1 to work, and it should point to the “main” .psm1 file of your module.
\nModuleVersion. This is generally mandatory, too, and is at the very least a very good idea.
\nGUID. This is mandatory and generated automatically by New-ModuleManifest.
\nAuthor. This could be your or your organization. You might even include an email address.
\nDescription. Don’t be skimpy here. This is what people will read to decide if they want to use your module. Write a meaningful description that explains what your module does and why it’s useful.

\n\n\n\n

These are, incidentally, the minimums for publishing to PowerShell Gallery. we also recommend, in the strongest possible terms, that you specify the FunctionsToExport array, as well as VariablesToExport, CmdletsToExport, and AliasesToExport if those are applicable. Ours, as you’ll see above, are set to *, which is a bad idea. In our specific example here, it makes sense, because our root module is empty - we aren’t exporting anything; the module is just a kind of container for our sample code to live in. But in your case, the recommended best practice is to explicitly list function, alias, and variable (without the $ sign) names which will achieve two benefits:

\n\n

Auto-discovery of your commands will be faster since PowerShell can just read the .psd1 rather than parsing the entire .psm1.
Some repositories may be able to provide per-command search capabilities if you specify which commands your module offers.

\n\n

\nPublishing to PowerShell Gallery

\n\n

PowerShellGallery.com is a Microsoft-owned, public NuGet repository for released code. It can host PowerShell modules, DSC resources, and other artifacts. Start by heading over to PowerShellGallery.com and logging in or registering, using your Microsoft ID. Once signed in, click on your name. As part of your Gallery profile, you’ll be able to request, view, and see your API key. This is a long hexadecimal identifier that you’ll need when publishing code. Keep this secure.

\n\n

With your API key in hand, it’s literally as easy as going into PowerShell and running Publish-Module (which is part of the PowerShellGet module, which ships with PowerShell v5 and later and can be downloaded from PowerShellGallery.com for other PowerShell versions). Provide the name of your module, and your API key (via the -NuGetApiKey parameter), and you’re good to go.

\n\n

Publish-Module -path c:\\scripts\\MyAwesomeModule -nugetapikey $mykey\n

\n\n\n\n

You may be prompted for additional information if it can’t be found in your module manifest.

\n\n\n\n

You’ll likely receive a confirmation email from the Gallery, which may include a few PSScriptAnalyzer notifications. As we describe in the chapter on Analyzing Your Script, the Gallery automatically runs several PSScriptAnalyzer best practices rules on all submitted code, and you should try hard to confirm with these unless you have a specific reason not to.

\n\n

So what’s appropriate for PowerShell Gallery publication?

\n\n

Production-ready code. Don’t submit untested, pre-release code unless you’re doing so as part of a public beta test, and be sure to clearly indicate that the code isn’t production-ready (for example, using Write-Warning to display a message when the module is loaded).
Open-source code. Gallery code is, by implication, open-source; you should consider hosting your development code in a public OSS repository like GitHub, and only publish “released” code to the Gallery. Be sure not to include any proprietary information.
Useful code. There are like thirty-seven million 7Zip modules in the Gallery. More are likely not needed. Try to publish code that provides unique value.

\n\n

Items can be removed from Gallery if you change your mind, but Microsoft can’t go out and delete whatever people may have already downloaded. Bear that in mind before contributing.

\n\n

\nPublishing to Private Repositories or Galleries

\n\n

Microsoft’s vision is that organizations will host private and internal repositories. You may want to use a private repository merely for testing purposes. Ideally, these internal repositories will be based on Nuget. Setting up one of these is outside the scope of this book. However, you can set up a repository with a simple file share.

\n\n

We’ve created a local file share and made sure that the admins group has write access.

\n\n

New-SMBShare -name MyRepo -path c:\\MyRepo -FullAccess Administrators `\n-ReadAccess Everyone\n

\n\n\n\n\n\n

Next, you can register this file share as a repository.

\n\n

Register-PSRepository -name MyRepo -SourceLocation c:\\MyRepo `\n-InstallationPolicy Trusted\n

\n\n\n\n

We set the repository to be trusted because we know what is going in it, and we don’t want to be bothered later when we try to install from it. If you forget, you can modify the repository later:

\n\n

Set-PSRepository -Name MyRepo -InstallationPolicy Trusted\n

\n\n\n\n

Now you can publish locally:

\n\n

Publish-Module -Path c:\\scripts\\onering -Repository MyRepo\n

\n\n\n\n

This local repository can be used just like the PowerShell gallery.

\n\n

PS C:\\> Find-Module -Repository MyRepo\n\nVersion    Name           Type       Repository      Description\n-------    ----           ----       ----------      -----------\n0.0.1.0    onering        Module     MyRepo          The module that ...\n

\n\n\n\n

You can even install locally to verify everything works as expected.

\n\n

PS C:\\> Install-Module onering -Repository MyRepo\nPS C:\\> Get-Command -module OneRing -ListImported\n\nCommandType     Name                                Version    Source\n-----------     ----                                -------    ------\nFunction        Disable-Ring                        0.0.1.0    OneRing\nFunction        Enable-Ring                         0.0.1.0    OneRing\nFunction        Get-Ring                            0.0.1.0    OneRing\nFunction        Remove-Ring                         0.0.1.0    OneRing\nFunction        Set-Ring                            0.0.1.0    OneRing\n

\n\n\n\n

We set this up locally as a proof of concept. It shouldn’t take that much more work to set up a repository on a company file share. Just mind your permissions.

\n\n

\nYour Turn

\n\n

We aren’t going to offer a real hands-on lab in this chapter, mainly because we think it’s a bad idea to use a public repo like PowerShell Gallery as a “lab environment!” It’s also non-trivial to set up your private repository, and if you go through that trouble, we think you’ll want it to be in production, not in a lab so that you can benefit from that work.

\n\n

That said, we do want to encourage you to sign into the PowerShell Gallery and create your API key, as we’ve described in this chapter. It’s a first step toward getting ready to publish your code.

\n\n

\nLet’s Review

\n\n

We aren’t going to ask you to publish anything to the gallery. You may never need to publish or share your work. But let’s see if you picked up anything in this chapter.

\n\n

The Microsoft PowerShell Gallery is based on what technology?
What important file is required to publish to the gallery that contains critical module metadata?
What should you publish to any repository?

\n\n

\nReview Answers

\n\n

Hopefully, you came up with answers like this:

\n\n

Nuget
A module manifest.
Any unique project that offers value and is production-ready. You can publish your project that might be in beta or under development but that should be made clear to any potential consumer such as through version numbering.

\n\n\n

\nPart 3: Controller Scripts and Visual Scripting

\n\n

\n\n\n

\nProxy Functions

\n\n

In PowerShell, a proxy function is a specific kind of wrapper function. That is, it “wraps” around an existing command, usually with the intent of either:

\n\n

Removing functionality
Hard-coding functionality and removing access to it
Adding functionality

\n\n

In some cases, a proxy command is meant to “replace” an existing command. This is done by giving the proxy the same name as the command it wraps; since the proxy gets loaded into the shell last, it’s the one that gets run when you run the command name.

\n\n\n\n

\nFor Example

\n\n

You’re probably familiar with PowerShell’s ConvertTo-HTML command. We’d like to make a version that “replaces” the existing command, providing full access to it but always injecting a particular CSS style sheet, so that the resulting HTML can be a bit prettier.

\n\n

\nCreating the Proxy Base

\n\n

PowerShell automates the first step, which is generating a “wrapper” that exactly duplicates whatever command you’re wrapping. Here’s how to use it (we’ll put our results into a Step1 subfolder in this chapter’s sample code):

\n\n

$cmd = New-Object System.Management.Automation.CommandMetaData (Get-Command ConvertT\\\no-HTML)\n[System.Management.Automation.ProxyCommand]::Create($cmd) |\nOut-File ConvertToHTMLProxy.ps1\n

\n\n\n\n

Here’s the rather lengthy result (once again, apologies for the backslashes, which represent line-wrapping; it’s unavoidable in this instance, but the downloadable sample code won’t show them):

\n\n

[CmdletBinding(DefaultParameterSetName='Page',\nHelpUri='http://go.microsoft.com/fwlink/?LinkID=113290',\nRemotingCapability='None')]\nparam(\n    [Parameter(ValueFromPipeline=$true)]\n    [PSObject]\n    ${InputObject},\n\n    [Parameter(Position=0)]\n    [System.Object[]]\n    ${Property},\n\n    [Parameter(ParameterSetName='Page', Position=3)]\n    [string[]]\n    ${Body},\n\n    [Parameter(ParameterSetName='Page', Position=1)]\n    [string[]]\n    ${Head},\n\n    [Parameter(ParameterSetName='Page', Position=2)]\n    [ValidateNotNullOrEmpty()]\n    [string]\n    ${Title},\n\n    [ValidateNotNullOrEmpty()]\n    [ValidateSet('Table','List')]\n    [string]\n    ${As},\n\n    [Parameter(ParameterSetName='Page')]\n    [Alias('cu','uri')]\n    [ValidateNotNullOrEmpty()]\n    [uri]\n    ${CssUri},\n\n    [Parameter(ParameterSetName='Fragment')]\n    [ValidateNotNullOrEmpty()]\n    [switch]\n    ${Fragment},\n\n    [ValidateNotNullOrEmpty()]\n    [string[]]\n    ${PostContent},\n\n    [ValidateNotNullOrEmpty()]\n    [string[]]\n    ${PreContent})\n\nbegin\n{\n    try {\n        $outBuffer = $null\n        if ($PSBoundParameters.TryGetValue('OutBuffer', [ref]$outBuffer))\n        {\n            $PSBoundParameters['OutBuffer'] = 1\n        }\n        $wrappedCmd = $ExecutionContext.InvokeCommand.GetCommand('Microsoft.PowerShe\\\nll.Utility\\ConvertTo-Html',\n        [System.Management.Automation.CommandTypes]::Cmdlet)\n        $scriptCmd = {& $wrappedCmd @PSBoundParameters }\n        $steppablePipeline = $scriptCmd.GetSteppablePipeline($myInvocation.CommandOr\\\nigin)\n        $steppablePipeline.Begin($PSCmdlet)\n    } catch {\n        throw\n    }\n}\n\nprocess\n{\n    try {\n        $steppablePipeline.Process($_)\n    } catch {\n        throw\n    }\n}\n\nend\n{\n    try {\n        $steppablePipeline.End()\n    } catch {\n        throw\n    }\n}\n<#\n\n.ForwardHelpTargetName Microsoft.PowerShell.Utility\\ConvertTo-Html\n.ForwardHelpCategory Cmdlet\n\n#>\n

\n\n\n\n

This isn’t wrapped in a function, so that’s the first thing we’ll do in the next step (which we’ll put into a file in Step 2, so you can differentiate).

\n\n

\nModifying the Proxy

\n\n

In addition to wrapping our proxy code in a function, we’re going to play with the -Head parameter. We’re not going to remove access to it; we want users to be able to pass content to -Head. We just want to intercept it, and add our stylesheet to it, before letting the underlying ConvertTo-HTML command take over. So we’ll need to test and see if our command was even run with -Head or not, and if it was, grab that content and concatenate our own. The final result:

\n\n

proxy-functions/Step2/ConvertToHTMLProxy.ps1

function NewConvertTo-HTML {\n    [CmdletBinding(DefaultParameterSetName = 'Page',\n        HelpUri = 'http://go.microsoft.com/fwlink/?LinkID=113290',\n        RemotingCapability = 'None')]\n    param(\n        [Parameter(ValueFromPipeline = $true)]\n        [PSObject]$InputObject,\n\n        [Parameter(Position = 0)]\n        [System.Object[]]$Property,\n\n        [Parameter(ParameterSetName = 'Page', Position = 3)]\n        [string[]]$Body,\n\n        [Parameter(ParameterSetName = 'Page', Position = 1)]\n        [string[]]$Head,\n\n        [Parameter(ParameterSetName = 'Page', Position = 2)]\n        [ValidateNotNullOrEmpty()]\n        [string]$Title,\n\n        [ValidateNotNullOrEmpty()]\n        [ValidateSet('Table', 'List')]\n        [string]$As,\n\n        [Parameter(ParameterSetName = 'Page')]\n        [Alias('cu', 'uri')]\n        [ValidateNotNullOrEmpty()]\n        [uri]$CssUri,\n\n        [Parameter(ParameterSetName = 'Fragment')]\n        [ValidateNotNullOrEmpty()]\n        [switch]$Fragment,\n\n        [ValidateNotNullOrEmpty()]\n        [string[]]$PostContent,\n\n        [ValidateNotNullOrEmpty()]\n        [string[]]$PreContent\n\n    begin {\n        try {\n            $outBuffer = $null\n            if ($PSBoundParameters.TryGetValue('OutBuffer', [ref]$outBuffer)) {\n                $PSBoundParameters['OutBuffer'] = 1\n            }\n            $wrappedCmd = $ExecutionContext.InvokeCommand.GetCommand('Microsoft.Powe\\\nrShell.Utility\\ConvertTo-Html',\n                [System.Management.Automation.CommandTypes]::Cmdlet)\n\n            # create our css\n            $css += @'\n        <style>\n        th { color:white; background-color: black;}\n        body { font-family: Calibri; padding: 2px }\n        </style>\n'@\n\n            # was -head specified?\n            if ($PSBoundParameters.ContainsKey('head')) {\n                $PSBoundParameters.head += $css\n            }\n            else {\n                $PSBoundParameters += @{'Head' = $css }\n            }\n\n            $scriptCmd = { & $wrappedCmd @PSBoundParameters }\n            $steppablePipeline = $scriptCmd.GetSteppablePipeline($myInvocation.Comma\\\nndOrigin)\n            $steppablePipeline.Begin($PSCmdlet)\n        }\n        catch {\n            throw\n        }\n    }\n\n    process {\n        try {\n            $steppablePipeline.Process($_)\n        }\n        catch {\n            throw\n        }\n    }\n\n    end {\n        try {\n            $steppablePipeline.End()\n        }\n        catch {\n            throw\n        }\n    }\n    <#\n\n.ForwardHelpTargetName Microsoft.PowerShell.Utility\\ConvertTo-Html\n.ForwardHelpCategory Cmdlet\n\n#>\n}\n

\n\n\n\n

Our changes begin at around line 50, with the #create our css comment.

\n\n

Creating CSS

            # create our css\n            $css += @'\n        <style>\n        th { color:white; background-color: black;}\n        body { font-family: Calibri; padding: 2px }\n        </style>\n'@\n

\n\n\n\n

Under that, we check to see if -head had been specified; if it was, we append our CSS to it. If not, we add a “head” parameter to $PSBoundParameters. Then we let the proxy function continue just as normal.

\n\n\n\n

\nAdding or Removing Parameters

\n\n

You’re likely to run into occasions when you do want to add or remove a parameter. For example, a new parameter might simplify usage or unlock functionality; removing a parameter might enable you to hard-code a value that the user shouldn’t be changing. The real key is the $PSBoundParametersCollection.

\n\n

\nAdding a Parameter

\n\n

Adding a parameter is as easy as declaring it in your proxy function’s Param() block. Add whatever attributes you like, and you’re good to go. You just want to remove the added parameter from $PSBoundParameters before the underlying command executes, since that command won’t know what to do with your new parameter.

\n\n

$PSBoundParameters.Remove('MyNewParam')\n$scriptCmd = {& $wrappedCmd @PSBoundParameters }\n

\n\n\n\n

Just remove it before that $scriptCmd line, and you’re good to go.

\n\n

\nRemoving a Parameter

\n\n

This is even easier - just delete the parameter from the Param() block! If you’re removing a mandatory parameter, you’ll need to internally provide a value with it. For example:

\n\n

$PSBoundParameters += @{'RemovedParam'=$MyValue}\n$scriptCmd = {& $wrappedCmd @PSBoundParameters }\n

\n\n\n\n

This will re-connect the -RemovedParam parameter, feeding it whatever’s in $MyValue, before running the underlying command.

\n\n

\nYour Turn

\n\n

Now it’s your turn to create a proxy function.

\n\n

\nStart Here

\n\n

In this exercise, you’ll be extending the Export-CSV command. However, you’re not going to “overwrite” the existing command. Instead, you’ll be creating a new command that uses Export-CSV under the hood.

\n\n

\nYour Task

\n\n

Create a proxy function named Export-TDF. This should be a wrapper around Export-CSV, and should not include a -Delimiter parameter. Instead, it should hard-code the delimiter to be a tab. Hint: you can specify a tab by putting a backtick, followed by the letter “t,” inside double quotes.

\n\n

\nOur Take

\n\n

Here’s what we came up with - also in the lab results folder in the downloadable code.

\n\n

Export-TDF

function Export-TDF {\n    [CmdletBinding(DefaultParameterSetName = 'Delimiter',\n        SupportsShouldProcess,\n        ConfirmImpact = 'Medium')]\n    param(\n        [Parameter(\n            Mandatory,\n            ValueFromPipeline,\n            ValueFromPipelineByPropertyName\n        )]\n        [PSObject]$InputObject,\n\n        [Parameter(Position = 0)]\n        [ValidateNotNullOrEmpty()]\n        [string]$Path,\n\n        [Alias('PSPath')]\n        [ValidateNotNullOrEmpty()]\n        [string]$LiteralPath,\n\n        [switch]$Force,\n\n        [Alias('NoOverwrite')]\n        [switch]$NoClobber,\n\n        [ValidateSet('Unicode', 'UTF7', 'UTF8', 'ASCII', 'UTF32',\n            'BigEndianUnicode', 'Default', 'OEM')]\n        [string]$Encoding,\n\n        [switch]$Append,\n\n        [Parameter(ParameterSetName = 'UseCulture')]\n        [switch]$UseCulture,\n\n        [Alias('NTI')]\n        [switch]$NoTypeInformation\n    )\n\n    begin {\n        try {\n            $outBuffer = $null\n            if ($PSBoundParameters.TryGetValue('OutBuffer', [ref]$outBuffer)) {\n                $PSBoundParameters['OutBuffer'] = 1\n            }\n            $wrappedCmd = $ExecutionContext.InvokeCommand.GetCommand('Microsoft.Powe\\\nrShell.Utility\\Export-Csv',\n                [System.Management.Automation.CommandTypes]::Cmdlet)\n            $PSBoundParameters += @{'Delimiter' = \"`t\" }\n            $scriptCmd = { & $wrappedCmd @PSBoundParameters }\n            $steppablePipeline = $scriptCmd.GetSteppablePipeline($myInvocation.Comma\\\nndOrigin)\n            $steppablePipeline.Begin($PSCmdlet)\n        }\n        catch {\n            throw\n        }\n    }\n    process {\n        try {\n            $steppablePipeline.Process($_)\n        }\n        catch {\n            throw\n        }\n    }\n    end {\n        try {\n            $steppablePipeline.End()\n        }\n        catch {\n            throw\n        }\n    }\n} #close function\n

\n\n\n\n

We just removed one parameter definition and added one line of code to hard-code the delimiter. We removed the {} around the parameter names and lined things up in the Param() block the way we would normally write code. We also removed the forwarded help links. We would still need to create new comment-based help for this command. Probably by copying a lot of the help from the original command.

\n\n\n\n

\nLet’s Review

\n\n

See if you can answer a couple of questions on proxy functions:

\n\n

The boilerplate proxy function behaves exactly like what?
If you define an additional parameter in a proxy function, what must you do before the wrapped command is allowed to run?
If you delete a non-mandatory parameter definition in a proxy function, what must you do before the wrapped command is allowed to run?

\n\n

\nReview Answers

\n\n

Here are our answers:

\n\n

The command it wraps.
Remove the new parameter from $PSBoundParameters.
You don’t need to do anything since the wrapped command can run without the removed parameter.

\n\n\n

\nPart 4: The Data Connection

\n\n

In this Part, we’ll look at various kinds of structured data that you may need to work with from within PowerShell. It might mean grabbing something from some type of data source or perhaps putting something into a particular data type. We’ll try and use some realistic examples that illustrate how to use these different structured data constructs and give you some tips for keeping out of trouble.

\n\n\n

\nWorking with SQL Server Data

\n\n

We often see people struggle - really, really hard, in some cases - to store data in Microsoft Excel, using PowerShell to automate the process. This makes us sad. Programmatically, Excel is kind of a hunk of junk. Sure, it can make charts and graphs - but only with significant effort and a lot of delicacy. But, people say, “I already have it!” This also makes us sad, because for the very reasonable price of $FREE, you can have SQL Server (Express), and in fact, you probably have some flavor of SQL Server on your network that you could use. But why?

\n\n

SQL Server is easy to use from PowerShell code. Literally a handful of lines, and you’re done.
SQL Server Reporting Services (also free in the Express edition) can turn SQL Server data into gorgeous reports with charts and graphs - and can automate the production and delivery of those reports with zero effort from you.
SQL Server is something that many computers can connect to at once, meaning you can write scripts that run on servers, letting those servers update their data in SQL Server. This is faster than a script that reaches out to query many servers to update a spreadsheet.

\n\n

We don’t know how to better evangelize using SQL Server for data storage over Microsoft Excel.

\n\n

\nSQL Server Terminology and Facts

\n\n

Let’s quickly get some terminology and basic facts out of the way.

\n\n

SQL Server is a service that runs on a server. Part of what you’ll need to know, to use it, is the server’s name. A single machine (physical or VM) can run multiple instances of SQL Server, so if you need to connect to an instance other than the default, you’ll need the instance name also. The naming pattern is SERVER\\INSTANCE.
A SQL Server instance can host one or more databases. You will usually want a database for each major data storage purpose. For example, you might ask a DBA to create an “Administration Data” database on one of your SQL Server computers, giving you a place to store stuff.
Databases have a recovery mode option. Without getting into a lot of details, you can use the “Simple” recovery mode (configurable in SQL Server Management Studio by right-clicking the database and accessing its Options page) if your data isn’t irreplaceable and you don’t want to mess with maintaining the database’s log files. For anything more complex, either take a DBA to lunch or read Don’s Learn SQL Server Administration in a Month of Lunches.
Databases contain tables, each of which is analogous to an Excel worksheet.
Tables consist of rows (entities) and columns (fields), which correspond to the rows and columns of an Excel sheet.
Columns have a data type, which determines the kind of data they can store, like text (NVARCHAR), dates (DATETIME), or numbers (INT). The data type also determines the data ranges. For example, NVARCHAR(10) can hold 10 characters; NVARCHAR(MAX) has no limit. INT can store smaller values than BIGINT, and bigger values than TINYINT.
SQL Server defaults to Windows Authentication mode, which means the domain user account running your scripts must have permission to connect to the server (a login), and permission to use your database (a database user). This is the safest means of authentication as it doesn’t require passwords to be kept in your script. If running a script as a scheduled task, the task can be set to “run as” a domain user with the necessary permissions.

\n\n

Just seven little things to know, and you’re good to go.

\n\n\n\n

\nConnecting to the Server and Database

\n\n

You’ll need a connection string to connect to a SQL Server computer/instance, and connect to a specific database. If you’re not using Windows Authentication, the connection string can also contain a clear-text username and password, which is a horrible practice. We use ConnectionStrings.com to look up connection string syntax, but here’s the one you’ll use a lot:

\n\n

Use Server=SERVER\\INSTANCE;Database=DATABASE;Trusted_Connected=True; to connect to a given server and instance (omit the \\INSTANCE if you’re connecting to the default instance) and database. Note that SQL Server Express usually installs, by default, as an instance named SQLEXPRESS. You can run Get-Service in PowerShell to see any running instances on a computer, and the service name will include the instance name (or just MSSQLSERVER if it’s the default).

\n\n

With that in mind, it’s simple to code up a connection:

\n\n

$conn = New-Object -Type System.Data.SqlClient.SqlConnection\n$conn.ConnectionString = 'Server=SQL1;Database=MyDB;Trusted_Connection=True;'\n$conn.Open()\n

\n\n\n\n

You can leave the connection open for your entire script; be sure to run $conn.Close() when you’re done, though. It’s not a tragedy to not close the connection; when your script ends, the connection object will vanish, and SQL Server will automatically close the connection a bit later. But if you’re using a server that’s pretty busy, the DBA is going to get in your face about leaving the connection open. And, if you run your script multiple times in a short period of time, you’ll create a new connection each time rather than re-using the same one. The DBAs will definitely notice this and get agitated.

\n\n\n\n

\nWriting a Query

\n\n

The next thing you need to do is retrieve, insert, update, or remove some data. This is done by writing queries in the Transact-SQL (T-SQL) language, which corresponds with the ANSI SQL standard, meaning most queries look the same on most database servers. There’s a great free online SQL tutorial if you need one, but we’ll get you started with the basics.

\n\n

To do this, you’ll need to know the table and column names from your database. SQL Server Management Studio is a good way to discover these.

\n\n

For the following sections, we’re going to focus on query syntax, and then give you an example of how we might build that query in PowerShell. Once your query is in a variable, it’s easy enough to run it - and we’ll cover how to do that in a bit. Also, we’re not going to be providing exhaustive coverage of SQL syntax; we’re covering the basics. There are plenty of resources, including the aforementioned online tutorial, if you need to dig deeper.

\n\n

\nAdding Data

\n\n

Adding data is done by using an INSERT query. The basic syntax looks like this:

\n\n

INSERT INTO <tablename>\n    (Column1, Column2, Column3)\n    VALUES (Value1, Value2, Value3)\n

\n\n\n\n

So you’ll need to know the name of the table you’re adding data to, and you’ll need to know the column names. You also need to know a bit about how the table was defined. For example, if a “Name” column is marked as mandatory (or “NOT NULL”) in the table design, then you must list that column and provide a value for it. Sometimes, a table may define a default value for a column, in which case you can leave the column out if you’re okay with that default value. Similarly, a table can permit a given column to be empty (NULL), and you can omit that column from your list if you don’t want to provide a value.

\n\n

Whatever order you list the columns in, your values must be in the same order. You’re not forced to use the column order that the table defines; you can list them in any order.

\n\n

Numeric values aren’t delimited in T-SQL. String values are delimited in single quotes; any single quotes within a string value (like “O’Leary”) must be doubled (“O’‘Leary”) or your query will fail. Dates are treated as strings and are delimited with single quotes.

\n\n\n\n

We might build a query in PowerShell like this:

\n\n

$ComputerName = \"SERVER2\"\n$OSVersion = \"Win2012R2\"\n$query = \"INSERT INTO OSVersion (ComputerName,OS) VALUES('$ComputerName','$OSVersion\\\n')\"\n

\n\n\n\n

This assumes a table named OSVersion, with columns named ComputerName and OS. Notice that we’ve put the entire query into double quotes, allowing us to just drop variables into the VALUES list.

\n\n\n\n

\nRemoving Data

\n\n

A DELETE query is used to delete rows from a table, and it is almost always accompanied by a WHERE clause so that you don’t delete all the rows. Be very careful, as there’s no such thing as an “UNDO” query!

\n\n

DELETE FROM <tablename> WHERE <criteria>\n

\n\n\n\n

So, suppose we’re getting ready to insert a new row into our table, which will list the OS version of a given computer. We don’t know if that computer is already listed in the table, so we’re going to just delete any existing rows before adding our new one. Our DELETE query might look like this:

\n\n

$query = \"DELETE FROM OSVersions WHERE ComputerName = '$ComputerName'\"\n

\n\n\n\n

There’s no error generated if you attempt to delete rows that don’t exist.

\n\n

\nChanging Data

\n\n

An UPDATE query is used to change an existing row, and is accompanied by a SET clause with the changes, and a WHERE clause to identify the rows you want to change.

\n\n

UPDATE <tablename>\n   SET <column> = <value>, <column> = <value>\n   WHERE <criteria>\n

\n\n\n\n

For example:

\n\n

$query = \"UPDATE DiskSpaceTracking `\n          SET FreeSpaceOnSysDrive = $FreeSpace `\n          WHERE ComputerName = '$ComputerName'\"\n

\n\n\n\n

We’d ordinarily do that all on one line; we’ve broken it up here just to make it fit more easily in the book. This assumes that $FreeSpace contains a numeric figure and that $ComputerName contains a computer name.

\n\n\n\n

\nRetrieving Data

\n\n

Finally, the big daddy of queries is the SELECT query. This is the only one that returns data (although the other three will return the number of rows they affected). This is also the most complex query in the language, so we’re only tackling the basics.

\n\n

SELECT <column>,<column>\n       FROM <tablename>\n       WHERE <criteria>\n       ORDER BY <column>\n

\n\n\n\n

The WHERE and ORDER BY clauses are optional, and we’ll come to them in a moment.

\n\n

Beginning with the core SELECT, you follow with a list of columns you want to retrieve. While the language permits you to use * to return all columns, this is a poor practice. For one, it performs slower than a column list. For another, it makes your code harder to read. So stick with listing the columns you want.

\n\n

The FROM clause lists the table name. This can get a ton more complex if you start doing multi-table joins, but we’re not getting into that in this book.

\n\n

A WHERE clause can be used to limit the number of rows returned, and an ORDER BY clause can be used to sort the results on a given column. Sorting is ascending by default, or you can specify descending. For example:

\n\n

$query = \"SELECT DiskSpace,DateChecked `\n          FROM DiskSpaceTracking `\n          WHERE ComputerName = '$ComputerName' `\n          ORDER BY DateChecked DESC\"\n

\n\n\n\n

\nCreating Tables Programmatically

\n\n

It’s also possible to write a data definition language (DDL) query that creates tables. The four queries we’ve covered up to this point are data manipulation language (DML) queries. The ANSI specification doesn’t cover DDL as much as DML, meaning DDL queries differ a lot between server brands. We’ll continue to focus on T-SQL for SQL Server; we just wanted you to be aware that you won’t be able to re-use this syntax on other products without some tweaking.

\n\n

CREATE TABLE <tablename> (\n    <column> <type>,\n    <column> <type>\n)\n

\n\n\n\n

You list each column name, and for each, provide a datatype. In SQL Server, you’ll commonly use:

\n\n

Int or BigInt for integers
VarChar(x) or VarChar(MAX) for string data; “x” determines the maximum length of the field while “MAX” indicates a binary large object (BLOB) field that can contain any amount of text.
DateTime

\n\n

You want to use the smallest data type possible to store the data you anticipate putting into the table, because oversized columns can cause a lot of wasted disk space.

\n\n

\nRunning a Query

\n\n

You’ve got two potential types of queries: ones that return data (SELECT) and ones that don’t (pretty much everything else). Running them starts the same:

\n\n

$command = New-Object -Type System.Data.SqlClient.SqlCommand\n$command.Connection = $conn\n$command.CommandText = $query\n

\n\n\n\n

This assumes $conn is an open connection object, and that $query has your T-SQL query. How you run the command depends on your query. For queries that don’t return results:

\n\n

$command.ExecuteNonQuery()\n

\n\n\n\n

That can produce a return object, which you can pipe to Out-Null if you don’t want to see it. For queries that produce results:

\n\n

$reader = $command.ExecuteReader()\n

\n\n\n\n

This generates a DataReader object, which gives you access to your queried data. The trick with these is that they’re forward-only, meaning you can read a row, and then move on to the next row - but you can’t go back to read a previous row. Think of it as an Excel spreadsheet, in a way. Your cursor starts on the first row of data, and you can see all the columns. When you press the down arrow, your cursor moves down a row, and you can only see that row. You can’t ever press the up arrow, though - you can only keep going down the rows.

\n\n

You’ll usually read through the rows using a While loop:

\n\n

while ($reader.read()) {\n  #do something with the data\n}\n

\n\n\n\n

The Read() method will advance to the next row (you start “above” the first row, so executing Read() the first time doesn’t “skip” any data), and return True if there’s a row after that.

\n\n

To retrieve a column, inside the While loop, you run GetValue(), and provide the column ordinal number of the column you want. This is why it’s such a good idea to explicitly list your columns in your SELECT query; you’ll know which column is in what position. The first column you listed in your query will be 0, the one after that 1, and so on.

\n\n

So here’s a full-fledged example:

\n\n

$conn = New-Object -Type System.Data.SqlClient.SqlConnection\n$conn.ConnectionString = 'Server=SQL1;Database=MyDB;Trusted_Connection=True;'\n$conn.Open()\n\n$query = \"SELECT ComputerName,DiskSpace,DateTaken FROM DiskTracking\"\n\n$command = New-Object -Type System.Data.SqlClient.SqlCommand\n$command.Connection = $conn\n$command.CommandText = $query\n$reader = $command.ExecuteReader()\n\nwhile ($reader.read()) {\n    [PSCustomObject]@{'ComputerName' = $reader.GetValue(0)\n                         'DiskSpace' = $reader.GetValue(1)\n                         'DateTaken' = $reader.GetValue(2)\n                        }\n}\n\n$conn.Close()\n

\n\n\n\n

This snippet will produce objects, one object for each row in the table, and with each object having three properties that correspond to three of the table\ncolumns.

\n\n

If by chance you don’t remember your column positions, you can use something like this to auto-discover the column number.

\n\n

while ($reader.read()) {\n    [PSCustomObject]@{\n    'ComputerName' = $reader.GetValue($reader.GetOrdinal(\"computername\"))\n    'DiskSpace' = $reader.GetValue($reader.GetOrdinal(\"diskspace\"))\n    'DateTaken' = $reader.GetValue($reader.GetOrdinal(\"datetaken\"))\n    }\n}\n

\n\n\n\n

Regardless of the approach, we’d usually wrap this in a Get- function, so that we could just run the function and get objects as output. Or a corresponding Set-, Update- or Remove- function depending on your SQL query.

\n\n

\nInvoke-SqlCmd

\n\n

If you by chance have installed a local instance of SQL Server Express, you will also have a set of SQL-related PowerShell commands and a SQLSERVER PSDrive. We aren’t going to cover them as this isn’t a SQL Server book. But you will want to take advantage of Invoke-SqlCmd.

\n\n

Instead of dealing with the .NET Framework to create a connection, command and query, you can simply invoke the query.

\n\n

Invoke-SqlCmd \"Select Computername,DiskSpace,DateTaken from DiskTracking\" `\n-Database MyDB\n

\n\n\n\n

You can use any of the query types we’ve shown you in this chapter. One potential downside to this approach in your toolmaking is that this will only work locally, or where the SQL Server modules have been installed. Also, there is a bit of a lag while the module is initially loaded.

\n\n

\nThinking About Tool Design Patterns

\n\n

If you’ve written a tool that retrieves or creates some data that you intend to put into SQL Server, then you’re on the right track. The next step would be a tool that inserts the data into SQL Server (Export-Something), and perhaps a tool to read the data back out (Import-Something). This approach maintains a good design pattern of each tool doing one thing, and doing it well, and lets you create tools that can be composed in a pipeline to perform complex tasks. You can read a bit more about that approach, and even get a “generic” module for piping data in and out of SQL Server databases in Ditch Excel: Making Historical & Trend Reports in PowerShell, a free ebook.

\n\n

\nLet’s Review

\n\n

Because we don’t want to assume that you have access to a SQL Server computer, we aren’t going to present a hands-on experience in this chapter. However, we do encourage you to try and answer these questions:

\n\n

How to you prevent DELETE from wiping out a table?
What method do you use to execute an INSERT query?
What method reads a single database row from a reader object?

\n\n

\nReview Answers

\n\n

Here are our answers:

\n\n

Specify a WHERE clause to limit the deleted rows.
The ExecuteNonQuery() method.
The Read() method.

\n\n\n

\nPart 5: Seriously Advanced Toolmaking

\n\n

In this Part of the book, we’ll dive into some deep, “extra” topics. These are all things we’re pretty sure you should know, but that you might not use right away, especially if you are an apprentice toolmaker. This Part isn’t constructed in a storyline, so you can just pick and choose the bits you think you’ll need or you find interesting.

\n\n\n

\nMeasuring Tool Performance

\n\n

We PowerShell geeks will often get into late-night, at-the-pub arguments about which bits of PowerShell perform best under certain circumstances. You’ll hear arguments like, “The ForEach-Object cmdlet is slower because its script block has to be parsed each time” or, “Storing all those objects in a variable will make everything take longer because of how arrays are managed.” At the end of the day, if performance is important to you, this is the chapter for you.

\n\n

\nIs Performance Important

\n\n

Well, maybe. Why is performance important to you? Look, if you’ve written a command that will have to reboot a dozen computers, then we’re going to be splitting hairs all night about which way is faster or slower. It won’t matter. But if you’re writing code that needs to manipulate thousands of objects, or tens of thousands or more, then a minute performance gain per object will add up quickly. The point is, before you sweat this stuff, know that tweaking PowerShell for millisecond performance gains isn’t useful unless there are a lot of milliseconds to be saved.

\n\n

\nMeasure What’s Important

\n\n

But if performance is important, then you need to measure it. Forget every possible argument for or against any given technique, and measure it. And, as you measure, make sure you’re measuring to the scale that your command will eventually run. That is, don’t test a command with five objects when the plan is to run against five hundred thousand. Pressures like memory, disk I/O, network, and CPU won’t interact in meaningful ways at a small scale, and so small-scale measurements won’t prove out as you scale up your workload.

\n\n

Think of it this way: just because a one-lane road can carry 100 cars an hour, doesn’t mean a 4-lane road can carry 400 an hour. It’s a different situation, with different dynamics. So measure against the workload you plan to run.

\n\n

You’ll perform that measurement using the Measure-Command cmdlet. Feed it your command, script, pipeline, or whatever, and it’ll run it - and spit out how long it took it to complete. Take this short script as an example (this is test.ps1 in the sample files):

\n\n

measuring-tool-performance/test.ps1

Write-Host 'Round 1' -ForegroundColor Green\nMeasure-Command -Expression {\n    Get-Service |\n    ForEach-Object { $_.Name }\n}\n\nWrite-Host 'Round 2' -ForegroundColor Yellow\nMeasure-Command -Expression {\n    Get-Service |\n    Select-Object Name\n}\n\nWrite-Host 'Round 3' -ForegroundColor Cyan\nMeasure-Command -Expression {\n    ForEach ($service in (Get-Service)) {\n        $service.name\n    }\n}\n

\n\n\n\n

This does the same thing in different ways. Let’s run that to see what happens:

\n\n

Round 1\n\nDays              : 0\nHours             : 0\nMinutes           : 0\nSeconds           : 0\nMilliseconds      : 148\nTicks             : 1486572\nTotalDays         : 1.72056944444444E-06\nTotalHours        : 4.12936666666667E-05\nTotalMinutes      : 0.00247762\nTotalSeconds      : 0.1486572\nTotalMilliseconds : 148.6572\n\nRound 2\nDays              : 0\nHours             : 0\nMinutes           : 0\nSeconds           : 0\nMilliseconds      : 37\nTicks             : 379826\nTotalDays         : 4.39613425925926E-07\nTotalHours        : 1.05507222222222E-05\nTotalMinutes      : 0.000633043333333333\nTotalSeconds      : 0.0379826\nTotalMilliseconds : 37.9826\n\nRound 3\nDays              : 0\nHours             : 0\nMinutes           : 0\nSeconds           : 0\nMilliseconds      : 38\nTicks             : 389199\nTotalDays         : 4.50461805555556E-07\nTotalHours        : 1.08110833333333E-05\nTotalMinutes      : 0.000648665\nTotalSeconds      : 0.0389199\nTotalMilliseconds : 38.9199\n

\n\n\n\n

There’s a significant penalty, time-wise, for the first method, while the second two are almost tied. Neat, right?

\n\n\n\n

One thing to watch for when running Measure-Command is that a single test isn’t necessarily absolute proof. There could be any number of factors that might influence the result. Sometimes it helps to run the test several times. Jeff wrote a command called Test-Expression in the PSScriptTools module that allows you to run a test multiple times, giving you (hopefully) a more meaningful result. There’s even a GUI version.

\n\n

\nFactors Affecting Performance

\n\n

There are a bunch of things that can impact a tool’s performance.

\n\n

Collections and arrays can get very slow if they get really big and you keep adding objects to them one at a time. This slowdown has to do with how .NET allocates and manages memory for these things.

\n\n

Anything storing a lot of data in memory can be affected if .NET has to stop and garbage-collect variables that are no longer referenced. Generally, you want to try and manage reasonable amounts of data in memory, not great huge wodges of 60GB text files.

\n\n

Compiling script blocks - as ForEach-Object requires - can incur a performance penalty. It’s not always avoidable, but it isn’t the fastest operation on the planet in some cases.

\n\n

Wasting memory can result in disk paging, which can slow things down. For example, in the below fragment, we’re still storing a potentially and unnecessarily huge list of users in $users long past the point where we’re done with it.

\n\n

$users = Get-ADUser -filter *\n$filtered = $users | Where { $_.Department -like '*IT*' }\n$final = $filtered | Select Name,Cn\n$final | Out-File names.txt\n

\n\n\n\n

It’d be better do to this entirely without variables, and let the filtering happen on the domain controller:

\n\n

Get-ADUser -filter \"Department -like '*IT*'\" |\nSelect Name,Cn |\nOut-File names.txt\n

\n\n\n\n

Now we’re getting massively less data back from Active Directory, and storing none of it in persistent variables. Or to put it more precisely, this is an example of the benefits of early filtering.

\n\n

Here’s the problem - We often see beginners write a command like this:

\n\n

Get-CimInstance win32_service -computername server01 |\nwhere state -eq 'running'\n

\n\n\n\n

This may not seem like a big deal but imagine the CIM command was going to return 1000 objects. With the approach we just showed, the first command has to complete and send all 1000 objects, in this case across the wire and then the results are figured. Compared to letting Get-CimInstance do the filtering in place - on the server - and then only sending the filtered results back.

\n\n

Get-CimInstance win32_service -computername server01 -filter \"state = 'running'\"\n

\n\n\n\n

There’s one other feature you should take advantage of when using Get-CimInstance and not many people do. Let’s say you are using code like this:

\n\n

Get-CimInstance win32_service -computername $computers-filter \"state = 'running'\" |\nSelect-Object -property Name,StartMode,StartName,ProcessID,SystemName\n

\n\n\n\n

The $Computers variable is a list of computer names. This pattern is pretty common. Get something and then select the things that matter to you. However, the remote server is assembling a complete Win32_Server instance with all the properties. But you are throwing most of them away. The better approach is to limit what Get-CimInstance will send back.

\n\n

$CimParams=@{\n  ClassName    = 'win32_service'\n  ComputerName = $computers\n  Filter       = \"state = 'running'\"\n  Property     = 'Name','StartMode','StartName','ProcessID','SystemName'\n}\nGet-CimInstance  @CimParams |\nSelect-Object -property Name,StartMode,StartName,\nProcessID,@{Name=\"Computername\";Expression={$_.SystemName}}\n

\n\n\n\n

PowerShell will want to display the results using its default formatting. You’ll most likely use Select-Object or create your custom object. Regardless, this approach should run slightly faster. It may be small, but it can add up. You’ll appreciate this when you are querying 500 servers.

\n\n\n\n

\nKey Take-Away

\n\n

You should get used to using Measure-Command to test your code, especially if there are several ways you could go. We’ll look at other performance-related concepts in the Scripting at Scale chapter. But for now your key take-away should be that good coding practices can go a long way toward avoiding performance problems!

\n\n\n

\nPart 6: Pester

\n\n

We provided an introduction to Pester earlier in this book, but now we’d like to dig deep. Pester is a pretty important part of the PowerShell universe these days, and if you’re going to be a professional-grade PowerShell toolmaker, you should make Pester a big part of your world.

\n\n\n

\nWhy Pester Matters

\n\n

In the world of DevOps and automation, it’s crucial that your code - you know, the thing that enables your automation - be reliable. In the past, you’d accomplish reliability, or attempt to, by manually testing your code. The problems with manual testing are legion:

\n\n

You’re likely to be inconsistent. That is, you might forget to test some things sometimes, which opens the door to devastating bugs.
You’re going to spend a lot of time, if you’re doing it right (and the time commitment is what makes most people not “do it right” in the first place).
You end up wasting time setting up “test harnesses” to safely test your code, amongst other “supporting” tasks.

\n\n

This is where Pester comes in. Simply put, it’s a testing automation tool for PowerShell code, as we explained earlier in this book.

\n\n

Pester is consistent. It tests the same things, every time, so you never “miss” anything. And, if you discover a new bug that you weren’t testing for, you can add it to your automated tests to make sure that bug never “sneaks by” again.
Pester can be automated, so it takes none of your time to perform tests.
Pester integrates well with continual integration tools, like Visual Studio Team Services (VSTS), Jenkins, Team City, and so on, so that spinning up test environments and running tests can also be completely automated.

\n\n

The vision goes something like this:

\n\n

You check in your latest PowerShell code to a code repository, like Git or VSTS. That code includes Pester tests.
A miracle occurs.
Your tested code is either rejected due to failed tests (and you’re notified), or your code appears in a production repository, such as a NuGet repository where it can be deployed via PowerShellGet.

\n\n

The “miracle” here is some kind of automated workflow. VSTS, for example, might spin up a test environment, load your code into it, and run your Pester tests against your code. We’re not going to cover how to make the miracle work, as it’s not technically a PowerShell thing per se, and because there are so many combinations of options you could choose. We are going to focus on how to write those Pester tests, though.

\n\n

The big thing here is that you need to be writing testable code, a concept we’ll devote a specific chapter to. But if you’re looking for the short answer to, “What is testable code?” It’s basically “follow the advice we’ve been giving you in this book.” Write concise, self-contained, single-task functions to do everything.

\n\n

The other thing you’ll want to quickly embrace is to write your Pester tests immediately, if not actually in advance of your code (something we’ll discuss more in the chapter on test-driven development). This is going to require an act of will for most PowerShell folks because we tend to want to just dive in and start experimenting, rather than worrying about writing tests. But the difference between the adults and the babies, here, is that the adults do the right thing because they know it’s the right thing to do. Having tests available from the outset of your project is how you reap the advantages of Pester, and indeed of PowerShell more generally.

\n\n

So that’s why Pester is important. We don’t think anyone should write any code unless they’re also going to write automated tests for it.

\n\n

It’s also important to understand what Pester does, and this gets a bit squishy. First, it’s worth considering the different kinds of testing you might want to perform in your life. Here are a few testing patterns but by no means all:

\n\n

\nUnit testing is nothing more than making sure your code runs. You want to make sure it behaves properly when passed various combinations of parameters, for example, and that its internal logic behaves as expected. You usually try to test the code in isolation, meaning you prevent it from making any permanent changes to systems, databases, and so on. You’re also just testing your code, not anybody else’s. If your code internally runs Get-CimInstance, then you prevent it from doing so, since Get-CimInstance isn’t your code. Unit testing is what Pester is all about, and it contains functionality to help you achieve all of the above. The idea is to isolate your code as much as possible to make testing more practical, and to make debugging easier.
\nIntegration testing is a bit more far-reaching. It’s designed to test your code running in conjunction with whatever other code is involved. This is where you’d go ahead and let internal Get-CimInstance calls run correctly, so make sure your code operates well when integrated with other code. Integration testing is more “for real” than unit testing, and typically runs in something close to a production environment, rather than in isolation.
\nInfrastructure validation can be thought of as an extension of integration testing. Because so much of our PowerShell code is about modifying computer systems, such as building VMs or deploying software, infrastructure validation runs our code and then reaches out to check the results. Pester can also be used for this kind of testing, and we’ll get into it more later in this book.

\n\n

All of this is important to understand because it helps you better understand what a Pester test looks like. If you’ve written a function that’s little more than a wrapper around ConvertTo-HTML, for example, then your Pester tests aren’t going to be very complex, because you probably didn’t write much code. You’re not trying to make sure ConvertTo-HTML itself works because that’s not your code, so it’s not your problem in a unit test. Because so much of our PowerShell code is leveraging other people’s code, our own Pester tests are often simpler and easier to grasp.

\n\n\n

\nPart 7: PowerShell 7 Scripting

\n\n

PowerShell 7, which is essentially today’s PowerShell and runs cross-platform, offers a few new features that you can use in your scripting projects. Of course, these will only work when the code is run on a PowerShell 7 platform. The chapters in this section will introduce you to some new operators, variables, and parameters.

\n\n\n

\nCross Platform Scripting

\n\n

When Microsoft moved PowerShell to the open-source world a few years ago, it opened up an entirely new world of scripting possibilities. Microsoft wants you to be able to manage anything from anywhere on whatever platform you need. Of course, you’ll want to build scripts and tools to use in this new world. And even if you aren’t in a situation now that requires cross-platform management, you never know what’s gonna happen tomorrow. And frankly, some of the things you need to keep in mind when it comes to cross-platform scripting can make you a better scripter for Windows PowerShell.

\n\n

What do we mean when we say “cross-platform”? We mean that you can develop a tool that can be used on any PowerShell-supported platform and ideally, can manage or work with any platform. Instead of writing one tool to run on Linux and another to run on Windows, you write one tool that can run on both. Don’t build multiple tools to manage remote servers depending on the target operating system. Write one command that you can use regardless of the OS. To meet these requirements, there are a few things we want you to keep in mind. We are under no illusion that everything you want to do cross-platform will work. It won’t. There will be situations where a true cross-platform solution simply doesn’t work.

\n\n\n\n

\nKnow Your OS

\n\n

When you are building something that can potentially be used cross-platform you need to think about the operating system where your code will be running. As cool as PowerShell 7 is, not every feature or command is supported on every operating system. You don’t need to be an expert-level Linux engineer, but you do need to understand some basics. For example, Linux doesn’t have the same concept of services as we understand them in the Windows world, so there is no Get-Service command in PowerShell 7 on non-Windows systems. Likewise, Linux doesn’t have WMI or CIM so you won’t find Get-CimInstance. Nor could you use Get-CimInstance to target a remote Linux machine. The OS doesn’t support these features so they aren’t available.

\n\n

What this means is that you need to know what OS your code is running on and there are some things you can do to make your life easier.

\n\n

\nState Your Requirements

\n\n

First off, if you are writing a PowerShell function that uses PowerShell 7 features, such as the new ternary operator, you need to make sure the person running your script is using PowerShell 7. This means adding a #requires statement at the top of your file:

\n\n

#requires -version 7.0\n

\n\n\n\n

Honestly, this is something you should have been doing all along but you absolutely need it now. Because PowerShell 7 features and commands can also change between versions, you should be as specific as possible.

\n\n

#requires -version 7.4\n

\n\n\n\n

If you need specific modules that might be Windows-specific, state that requirement as well.

\n\n

#requires -modules CIMCmdlets\n

\n\n\n\n

If someone runs this on a Linux box they’ll get an error like:

\n\n

The script 'Get-Miracle.ps1' cannot be run because the following modules that are sp\\\necified by the \"#requires\" statements of the script are missing: CimCmdlets.\n

\n\n\n\n

If you are building a module, in the manifest you can use this setting to set requirements.

\n\n

# Supported PSEditions\nCompatiblePSEditions = @('Desktop','Core')\n

\n\n\n\n

Desktop means Windows PowerShell. Core means the open-source and cross-platform version of PowerShell, regardless of operating system. This can be a little tricky. Because even though Get-CimInstance doesn’t work on a Mac in PowerShell 7, it will work just fine on a Windows desktop running PowerShell 7. Still, this high-level compatibility setting should be set. Delete whatever isn’t supported.

\n\n

\nTesting Variables

\n\n

Even though the Core setting is potentially problematic, there are some new automatic variables you can use in your code, to validate and test.

\n\n

\nPSEdition - On PowerShell 7, this will have a value of Core. On Windows PowerShell, it will return Desktop. Look familiar?
\nIsWindows - A boolean value indicating if you are running Windows. Requires PowerShell 7.
\nIsLinux - A boolean value indicating if you are running Linux. Requires PowerShell 7.
\nIsMac - A boolean value indicating if you are running MacOS. Requires PowerShell 7.
\nIsCoreCLR - A boolean value indicating if you are running .NET Core which most likely means you are running PowerShell 7. This variable isn’t defined in Windows PowerShell.

\n\n

And of course, don’t forget $PSVersionTable.

\n\n

PS C:\\> $PSVersionTable\n\nName                           Value\n----                           -----\nPSVersion                      7.4.2\nPSEdition                      Core\nGitCommitId                    7.4.2\nOS                             Microsoft Windows 10.0.22631\nPlatform                       Win32NT\nPSCompatibleVersions           {1.0, 2.0, 3.0, 4.0â€¦}\nPSRemotingProtocolVersion      2.3\nSerializationVersion           1.1.0.1\nWSManStackVersion              3.0\n

\n\n\n\n

Which can vary by platform.

\n\n

PS /home/jeff> $PSVersionTable\n\nName                           Value\n----                           -----\nPSVersion                      7.4.2\nPSEdition                      Core\nGitCommitId                    7.4.2\nOS                             Ubuntu 22.04.4 LTS\nPlatform                       Unix\nPSCompatibleVersions           {1.0, 2.0, 3.0, 4.0â€¦}\nPSRemotingProtocolVersion      2.3\nSerializationVersion           1.1.0.1\nWSManStackVersion              3.0\n

\n\n\n\n

It is also different on Windows PowerShell.

\n\n

PS C:\\> $PSVersionTable\n\nName                           Value\n----                           -----\nPSVersion                      5.1.22621.2506\nPSEdition                      Desktop\nPSCompatibleVersions           {1.0, 2.0, 3.0, 4.0...}\nBuildVersion                   10.0.22621.2506\nCLRVersion                     4.0.30319.42000\nWSManStackVersion              3.0\nPSRemotingProtocolVersion      2.3\nSerializationVersion           1.1.0.1\n

\n\n\n\n

These are all potentially useful items you can use to build If constructs or even dynamic parameters.

\n\n

\nEnvironment Variables

\n\n

One of the major challenges in cross-platform scripting is breaking out of the old way of doing things. Here’s a great example using a common parameter definition you might see in Windows PowerShell.

\n\n

[string[]]$Computername = $env:ComputerName\n

\n\n\n\n

This sets the %COMPUTERNAME% environment variable as the default value for $Computername. This will work just fine on Windows PowerShell and even PowerShell 7 running on Windows. But non-Windows platforms have different environment variables and this will fail. Instead, you can use a .NET code snippet to get the same information.

\n\n

[environment]::MachineName\n

\n\n\n\n

This is also true with $env:UserName which can be replaced with [environment]::UserName. If you are used to referencing environment variables, you’ll need to add a step to verify they are defined or begin using .NET alternatives.

\n\n

\nPaths

\n\n

PowerShell has always never cared about the direction of slashes in paths. You can run Test-Path c:\\windows or Test-Path c:/windows. This is even true on non-Windows systems. You can use test-path /etc/ssh or test-path \\etc\\ssh. But you really should be careful. Many of you probably have used or seen code like this:

\n\n

$file = \"$foo\\child\\file.dat\"\n

\n\n\n\n

There’s a good chance it will work cross-platform. But the better approach, which you should be using anyway, is to use the path cmdlets like Join-Path. Here’s a sample.

\n\n

Export-Data

Function Export-Data {\n  [cmdletbinding()]\n  Param(\n    [ValidateScript({ Test-Path $_ })]\n    [string]$Path = '.'\n  )\n\n  $time = Get-Date -Format FileDate\n  $file = \"$($time)_export.json\"\n  $ExportPath = Join-Path -Path (Convert-Path $Path) -ChildPath $file\n  Write-Verbose \"Exporting data to $exportPath\"\n\n  # code ...\n}\n

\n\n\n\n

Instead of worrying about which direction to put the slashes, let PowerShell do it for you.

\n\n

If you need it, you can use [System.IO.Path]::DirectorySeparatorChar to get the directory separator character. For the %PATH% variable, you can use [System.IO.Path]::PathSeparator. Let’s say you want to split the %PATH% environment variable into an array of locations. A simple cross-platform approach would be $env:PATH -split [System.IO.Path]::PathSeparator. Don’t forget that Linux is case-sensitive.

\n\n

\nWatch Your Aliases

\n\n

You’ve most likely heard us go on and on about the downside of using aliases in your PowerShell scripts. Use them all you want interactively at a prompt but in written code, use full cmdlet names. Now you need to.

\n\n

In the old days, we’d happily write a command like this:

\n\n

Get-Process | sort handles -descending\n

\n\n\n\n

And it would work just fine on Windows, even under PowerShell 7. But not Linux.

\n\n

PS /home/jeff> Get-Process | sort handles -descending\n/usr/bin/sort: invalid option -- 'e'\nTry '/usr/bin/sort --help' for more information.\n

\n\n\n\n

What happened? In PowerShell 7 on Linux, any alias that could resolve to a native command has been removed. So there is no sort alias for Sort-Object. PowerShell thinks you want to run the native sort command. If you’ve been in the habit of using Linux aliases like ps or ls, you’ll need to get over it. You need to start writing expressions like:

\n\n

Get-Process | Sort-Object handles -descending\n

\n\n\n\n

Now there’s no mistaking what you want to do and it will run everywhere.

\n\n\n\n

\nUsing Culture

\n\n

If you are writing code that relies on culture information, such as from Get-Culture, note that in PowerShell 7, you won’t get the same information. In Windows PowerShell, we are used to getting output like this:

\n\n

PS C:\\> Get-Culture\n\nLCID             Name             DisplayName\n----             ----             -----------\n1033             en-US            English (United States)\n

\n\n\n\n

On Windows platforms running PowerShell 7, this will still work as expected. But not on non-Windows platforms. You’ll get output like this:

\n\n

PS /home/jeff> Get-Culture\n\nLCID             Name             DisplayName\n----             ----             -----------\n127                               Invariant Language (Invariant Country)\n\nPS /home/jeff> Get-UICulture\n\nLCID             Name             DisplayName\n----             ----             -----------\n127                               Invariant Language (Invariant Country)\n

\n\n\n\n

You still have access to culture-specific information from the .NET Framework.

\n\n

PS /home/jeff> [System.Globalization.CultureInfo]::GetCultureInfo(\"en-gb\")\n\nLCID             Name             DisplayName\n----             ----             -----------\n2057             en-GB            English (United Kingdom)\n

\n\n\n\n

But PowerShell can’t detect the culture information on non-Windows platforms.

\n\n\n\n

You’ll need to be aware of this and test your code accordingly if you are relying on detected culture information.

\n\n

\nLeverage Remoting

\n\n

One of the most anticipated features of PowerShell 7 is the use of ssh for remoting. Non-Windows systems won’t support the WSMan protocol which means no remoting the way you used to do it. But you may still want to use remoting in your toolmaking. In our opinion, leveraging remoting is a smart idea. Going to PowerShell 7 just means a little more work on your part.

\n\n\n\n

One relatively easy approach you can use is parameter sets. Define one parameter set for a computer name and another for PSSession objects. PowerShell already follows this model. You can too. Here’s a proof of concept function.

\n\n

Get-RemoteData

Function Get-RemoteData {\n  [cmdletbinding(DefaultParameterSetName = 'computer')]\n  Param(\n    [Parameter(\n      Position = 0,\n      Mandatory,\n      ValueFromPipeline,\n      ParameterSetName = 'computer'\n    )]\n    [Alias('cn')]\n    [string[]]$Computername,\n    [Parameter(ParameterSetName = 'computer')]\n    [alias('RunAs')]\n    [PSCredential]$Credential,\n    [Parameter(ValueFromPipeline, ParameterSetName = 'session')]\n    [System.Management.Automation.Runspaces.PSSession]$Session\n  )\n  Begin {\n    $sb = { \"Getting remote data from $([environment]::MachineName) [$PSEdition]\" }\n    $PSBoundParameters.Add('Scriptblock', $sb)\n  }\n  Process {\n    Invoke-Command @PSBoundParameters\n  }\n  End {}\n}\n

\n\n\n\n

The person running the function can either pass a computername with an optional credential, or a previously created PSSession object. They may have existing connections to a mix of platforms, some using SSH connections. Now they can run one command that works for all.

\n\n

PS C:\\> Get-PSSession | Get-RemoteData\nGetting remote data from SRV2 [Desktop]\nGetting remote data from FRED [Core]\nGetting remote data from SRV1 [Desktop]\n

\n\n\n\n

In this example, FRED is a Linux server running Fedora. Start simple like this.

\n\n

But when you are ready, you can get very creative. Here’s a function that defines dynamic parameters if the user is running PowerShell 7.

\n\n

cross-platform-scripting/Stop-RemoteProcess.ps1

#requires -version 5.1\n\nFunction Stop-RemoteProcess {\n    [cmdletbinding(DefaultParameterSetName = 'computer')]\n    Param(\n        [Parameter(\n            ParameterSetName = 'computer',\n            Mandatory,\n            Position = 0,\n            ValueFromPipeline,\n            ValueFromPipelineByPropertyName,\n            HelpMessage = 'Enter the name of a computer to query.'\n        )]\n        [ValidateNotNullOrEmpty()]\n        [Alias('cn')]\n        [string[]]$ComputerName,\n        [Parameter(\n            ParameterSetName = 'computer',\n            HelpMessage = 'Enter a credential object or username.'\n        )]\n        [Alias('RunAs')]\n        [PSCredential]$Credential,\n        [Parameter(ParameterSetName = 'computer')]\n        [switch]$UseSSL,\n\n        [Parameter(\n            ParameterSetName = 'session',\n            ValueFromPipeline\n        )]\n        [ValidateNotNullOrEmpty()]\n        [System.Management.Automation.Runspaces.PSSession[]]$Session,\n\n        [ValidateScript( { $_ -ge 0 })]\n        [int32]$ThrottleLimit = 32,\n\n        [Parameter(Mandatory, HelpMessage = 'Specify the process to stop.')]\n        [ValidateNotNullOrEmpty()]\n        [string]$ProcessName,\n\n        [Parameter(HelpMessage = 'Write the stopped process to the pipeline')]\n        [switch]$Passthru,\n\n        [Parameter(HelpMessage = 'Run the remote command with -WhatIf')]\n        [switch]$WhatIfRemote\n    )\n    DynamicParam {\n        #Add an SSH dynamic parameter if in PowerShell 7\n        if ($IsCoreCLR) {\n            $paramDictionary = New-Object -Type System.Management.Automation.Runtime\\\nDefinedParameterDictionary\n\n            #a CSV file with dynamic parameters to create\n            #this approach doesn't take any type of parameter validation into account\n            $data = @'\nName,Type,Mandatory,Default,Help\nHostName,string[],1,,\"Enter the remote host name.\"\nUserName,string,0,,\"Enter the remote user name.\"\nSubsystem,string,0,\"powershell\",\"The name of the ssh subsystem. The default is power\\\nshell.\"\nPort,int32,0,,\"Enter an alternate SSH port\"\nKeyFilePath,string,0,,\"Specify a key file path used by SSH to authenticate the user\"\nSSHTransport,switch,0,,\"Use SSH to connect.\"\n'@\n\n            $data | ConvertFrom-Csv | ForEach-Object -Begin { } -Process {\n                $attributes = New-Object System.Management.Automation.ParameterAttri\\\nbute\n                $attributes.Mandatory = ([int]$_.mandatory) -as [bool]\n                $attributes.HelpMessage = $_.Help\n                $attributes.ParameterSetName = 'SSH'\n                $attributeCollection = New-Object -Type System.Collections.ObjectMod\\\nel.Collection[System.Attribute]\n                $attributeCollection.Add($attributes)\n                $dynParam = New-Object -Type System.Management.Automation.RuntimeDef\\\ninedParameter($_.name, $($_.type -as [type]), $attributeCollection)\n                $dynParam.Value = $_.Default\n                $paramDictionary.Add($_.name, $dynParam)\n            } -End {\n                return $paramDictionary\n            }\n        }\n    } #dynamic param\n\n    Begin {\n        $start = Get-Date\n        #the first verbose message uses a pseudo timespan to reflect the idea we're \\\njust starting\n        Write-Verbose \"[00:00:00.0000000 BEGIN  ] Starting $($MyInvocation.MyCommand\\\n)\"\n\n        #a script block to be run remotely\n        Write-Verbose \"[$(New-TimeSpan -Start $start) BEGIN  ] Defining the scriptbl\\\nock to be run remotely\"\n\n        $sb = {\n            param([string]$ProcessName, [bool]$Passthru, [string]$VerbPref = 'Silent\\\nlyContinue', [bool]$WhatPref)\n\n            $VerbosePreference = $VerbPref\n            $WhatIfPreference = $WhatPref\n\n            Try {\n                Write-Verbose \"[$(New-TimeSpan -Start $using:start) REMOTE ] Getting\\\n Process $ProcessName on $([System.Environment]::MachineName)\"\n                $Processes = Get-Process -Name $ProcessName -ErrorAction stop\n                Try {\n                    Write-Verbose \"[$(New-TimeSpan -Start $using:start) REMOTE ] Sto\\\npping $($Processes.count) Processes on $([System.Environment]::MachineName)\"\n                    $Processes | Stop-Process -ErrorAction Stop -PassThru:$Passthru\n                }\n                Catch {\n                    Write-Warning \"[$(New-TimeSpan -Start $using:start) REMOTE ] Fai\\\nled to stop Process $ProcessName on $([System.Environment]::MachineName). $($_.Excep\\\ntion.message).\"\n                }\n            }\n            Catch {\n                Write-Verbose \"[$(New-TimeSpan -Start $using:start) REMOTE ] Process\\\n $ProcessName not found on $([System.Environment]::MachineName)\"\n            }\n\n        } #scriptblock\n\n        #parameters to splat to Invoke-Command\n        Write-Verbose \"[$(New-TimeSpan -Start $start) BEGIN  ] Defining parameters f\\\nor Invoke-Command\"\n\n        #remove my parameters from PSBoundParameters because they can't be used with\\\n New-PSSession\n        $myParams = 'ProcessName', 'WhatIfRemote', 'passthru'\n        foreach ($my in $myParams) {\n            if ($PSBoundParameters.ContainsKey($my)) {\n                [void]($PSBoundParameters.remove($my))\n            }\n        }\n\n        $icmParams = @{\n            Scriptblock      = $sb\n            ArgumentList     = @($ProcessName, $Passthru, $VerbosePreference, $WhatI\\\nfRemote)\n            HideComputerName = $False\n            ThrottleLimit    = $ThrottleLimit\n            ErrorAction      = 'Stop'\n            Session          = $null\n        }\n\n        #initialize an array to hold session objects\n        [System.Management.Automation.Runspaces.PSSession[]]$All = @()\n        If ($Credential.username) {\n            Write-Verbose \"[$(New-TimeSpan -Start $start) BEGIN  ] Using alternate c\\\nredential for $($credential.username)\"\n        }\n    } #begin\n\n    Process {\n        Write-Verbose \"[$(New-TimeSpan -Start $start) PROCESS] Detected parameter se\\\nt $($PSCmdlet.ParameterSetName).\"\n\n        $remotes = @()\n        if ($PSCmdlet.ParameterSetName -match 'computer|ssh') {\n            if ($PSCmdlet.ParameterSetName -eq 'ssh') {\n                $remotes += $PSBoundParameters.HostName\n                $param = 'HostName'\n            }\n            else {\n                $remotes += $PSBoundParameters.ComputerName\n                $param = 'ComputerName'\n            }\n\n            foreach ($remote in $remotes) {\n                $PSBoundParameters[$param] = $remote\n                $PSBoundParameters['ErrorAction'] = 'Stop'\n                Try {\n                    #create a session one at a time to better handle errors\n                    Write-Verbose \"[$(New-TimeSpan -Start $start) PROCESS] Creating \\\na temporary PSSession to $remote\"\n                    #save each created session to $tmp so it can be removed at the e\\\nnd\n                    $all += New-PSSession @PSBoundParameters -OutVariable +tmp\n                } #Try\n                Catch {\n                    #TODO: Decide what you want to do when the new session fails\n                    Write-Warning \"Failed to create session to $remote. $($_.Excepti\\\non.Message).\"\n                    #Write-Error $_\n                } #catch\n            } #foreach remote\n        }\n        Else {\n            #only add open sessions\n            foreach ($sess in $session) {\n                if ($sess.state -eq 'opened') {\n                    Write-Verbose \"[$(New-TimeSpan -Start $start) PROCESS] Using ses\\\nsion for $($sess.ComputerName.ToUpper())\"\n                    $all += $sess\n                } #if open\n            } #foreach session\n        } #else sessions\n    } #process\n\n    End {\n        $icmParams['session'] = $all\n        Try {\n            Write-Verbose \"[$(New-TimeSpan -Start $start) END    ] Querying $($all.c\\\nount) computers\"\n\n            Invoke-Command @icmParams | ForEach-Object {\n                #TODO: PROCESS RESULTS FROM EACH REMOTE CONNECTION IF NECESSARY\n                $_\n            } #foreach result\n        } #try\n        Catch {\n            Write-Error $_\n        } #catch\n\n        if ($tmp) {\n            Write-Verbose \"[$(New-TimeSpan -Start $start) END    ] Removing $($tmp.c\\\nount) temporary PSSessions\"\n            $tmp | Remove-PSSession\n        }\n        Write-Verbose \"[$(New-TimeSpan -Start $start) END    ] Ending $($MyInvocatio\\\nn.MyCommand)\"\n    } #end\n} #close function\n

\n\n\n\n

This function essentially follows the same model as the previous example. But this one creates several dynamic parameters if PowerShell 7 is detected. Notice we’re using one of the new variables. When the user runs help in PowerShell 7, they’ll get the new parameters.

\n\n\n

\"Stop-RemoteProcess — Stop-RemoteProcess Help

\n\n\n

The last parameter set is the dynamic one. Instead of having to write several versions of the command, you can write a single function. Check out https://jdhitsolutions.com/blog/powershell/7458/a-powershell-remote-function-framework/ for a bit more detail on this function.

\n\n

\nCustom Module Manifests

\n\n

The last cross-platform scripting feature to consider is a custom module manifest. In the code downloads for this chapter, you’ll find a demo module called CrossDemo. The module has several commands, some of which will only work in PowerShell 7. The goal is to only export the commands (and aliases) that are supported. Here’s how.

\n\n

Normally, a psd1 is static and can’t contain code. But there is an exception for a module manifest. You can use a simple If statement to tell PowerShell what functions to export.

\n\n

FunctionsToExport = if ($PSEdition -eq 'desktop') {\n    'Export-Data','Get-DiskFree'\n    }\n    else {\n    'Export-Data','Get-DiskFree','Get-Status','Get-RemoteData'\n    }\n...\nAliasesToExport = if ($PSEdition -eq 'desktop') {\n    'df'\n    }\n    else {\n    'df','gst'\n    }\n

\n\n\n\n

When the module is imported on Windows PowerShell, only 2 functions and 1 alias are exported. PowerShell 7 systems get everything.

\n\n

Even so, you still may need to fine-tune platform requirements. For example, if you look at our sample code for the Get-DiskFree function, you’ll see code like this:

\n\n

 if ($IsWindows -OR $PSEdition -eq 'desktop') {\n        $Drive = (Get-Item $Path).Root -replace \"\\\\\"\n        Write-Verbose \"Getting disk information for $drive in $As\"\n        ...\n    } #if Windows\n    else {\n        Write-Warning 'This command requires a Windows platform.'\n    }\n

\n\n\n\n

Because the function uses Get-CimInstance it requires a Windows platform. It will work in PowerShell 7 on Windows but not Linux. So even though we’re exporting the function for PowerShell 7, it will only run on Windows. You’ll need to keep things like this in mind. Will it work in PowerShell 7 and what are the platform dependencies?

\n\n\n\n

We’ll be honest with you and say that a lot of community-accepted best practices for cross-platform scripting are still being developed. But if you use a little common sense and follow the best practices that are accepted, you shouldn’t have too much trouble.

\n\n

\n\n","tocStructure",[337,338,339,340,341,342,343,344,345,346,347,348,349,350,351,352,353,354,355,356,357,358,359,360,361,362,363,364,365,366,367,368,369,370,371,372,373,374,375,376,377,378,379,380,381,382,383,384,385,386,387,388,389,390,391,392,393,394,395,396,397,398,399,400,401,402,403],{"_80":81,"_43":82,"_75":-5,"_83":84,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":81,"_43":90,"_75":-5,"_83":91,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":95,"_75":-5,"_83":96,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":81,"_43":100,"_75":-5,"_83":101,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":104,"_75":-5,"_83":105,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":81,"_43":107,"_75":-5,"_83":108,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":81,"_43":111,"_75":-5,"_83":112,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":115,"_75":-5,"_83":116,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":118,"_75":-5,"_83":119,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":121,"_75":-5,"_83":122,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":124,"_75":-5,"_83":125,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":127,"_75":-5,"_83":128,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":81,"_43":130,"_75":-5,"_83":131,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":81,"_43":134,"_75":-5,"_83":135,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":138,"_75":-5,"_83":139,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":141,"_75":-5,"_83":142,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":144,"_75":-5,"_83":145,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":147,"_75":-5,"_83":148,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":150,"_75":-5,"_83":151,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":153,"_75":-5,"_83":154,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":156,"_75":-5,"_83":157,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":159,"_75":-5,"_83":160,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":162,"_75":-5,"_83":163,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":81,"_43":165,"_75":-5,"_83":166,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":81,"_43":169,"_75":-5,"_83":170,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":173,"_75":-5,"_83":174,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":176,"_75":-5,"_83":177,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":179,"_75":-5,"_83":180,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":182,"_75":-5,"_83":183,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":185,"_75":-5,"_83":186,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":81,"_43":188,"_75":-5,"_83":189,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":81,"_43":192,"_75":-5,"_83":193,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":196,"_75":-5,"_83":197,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":199,"_75":-5,"_83":200,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":202,"_75":-5,"_83":203,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":205,"_75":-5,"_83":206,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":182,"_75":-5,"_83":208,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":185,"_75":-5,"_83":210,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":81,"_43":212,"_75":-5,"_83":213,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":81,"_43":216,"_75":-5,"_83":217,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":220,"_75":-5,"_83":221,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":223,"_75":-5,"_83":224,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":226,"_75":-5,"_83":227,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":229,"_75":-5,"_83":230,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":232,"_75":-5,"_83":233,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":235,"_75":-5,"_83":236,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":185,"_75":-5,"_83":238,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":240,"_75":-5,"_83":241,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":81,"_43":243,"_75":-5,"_83":244,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":81,"_43":247,"_75":-5,"_83":248,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":251,"_75":-5,"_83":252,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":254,"_75":-5,"_83":255,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":257,"_75":-5,"_83":258,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":260,"_75":-5,"_83":261,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":81,"_43":263,"_75":-5,"_83":264,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":81,"_43":267,"_75":-5,"_83":268,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":81,"_43":271,"_75":-5,"_83":272,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":81,"_43":275,"_75":-5,"_83":276,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":279,"_75":-5,"_83":280,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":282,"_75":-5,"_83":283,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":285,"_75":-5,"_83":286,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":288,"_75":-5,"_83":289,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":291,"_75":-5,"_83":292,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":294,"_75":-5,"_83":295,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":297,"_75":-5,"_83":298,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":300,"_75":-5,"_83":301,"_76":85,"_97":-5,"_98":-5,"_88":-5},{"_80":94,"_43":303,"_75":-5,"_83":304,"_76":85,"_97":-5,"_98":-5,"_88":-5},"publicChapterContent","nextChapter","sections",[],"routes/_store+/_layout","routes/_store+/_readers+/_layout","actionData","errors"]

\nPart 3: Controller Scripts and Visual Scripting

Table of Contents

\nAbout This Book

\nDedication

\nAcknowledgments

\nAbout the Authors

\nAdditional Credits

\nForeword

\nIntroduction

\nPre-Requisites

\nVersioning

\nThe Journey

\nFollowing Along

\nProviding Feedback

\nPart 1: Review PowerShell Toolmaking

\nFunctions, the Right Way

\nTool Design

\nStart with a Command

\nBuild a Basic Function and Module

\nAdding CmdletBinding and Parameterizing

\nEmitting Objects as Output

\nUsing Verbose, Warning, and Informational Output

\nComment-Based Help

\nHandling Errors

\nAre You Ready

\nPart 2: Professional-Grade Toolmaking

\nPublishing Your Tools

\nBegin with a Manifest

\nPublishing to PowerShell Gallery

\nPublishing to Private Repositories or Galleries

\nYour Turn

\nLet’s Review

\nReview Answers

\nPart 3: Controller Scripts and Visual Scripting

\nProxy Functions

\nFor Example

\nCreating the Proxy Base

\nModifying the Proxy

\nAdding or Removing Parameters

\nAdding a Parameter

\nRemoving a Parameter

\nYour Turn

\nStart Here

\nYour Task

\nOur Take

\nLet’s Review

\nReview Answers

\nPart 4: The Data Connection

\nWorking with SQL Server Data

\nSQL Server Terminology and Facts

\nConnecting to the Server and Database

\nWriting a Query

\nAdding Data

\nRemoving Data

\nChanging Data

\nRetrieving Data

\nCreating Tables Programmatically

\nRunning a Query

\nInvoke-SqlCmd

\nThinking About Tool Design Patterns

\nLet’s Review

\nReview Answers

\nPart 5: Seriously Advanced Toolmaking

\nMeasuring Tool Performance

\nIs Performance Important

\nMeasure What’s Important

\nFactors Affecting Performance

\nKey Take-Away

\nPart 6: Pester

\nWhy Pester Matters

\nPart 7: PowerShell 7 Scripting

\nCross Platform Scripting

\nKnow Your OS

\nState Your Requirements

\nTesting Variables

\nEnvironment Variables

\nPaths

\nWatch Your Aliases

\nUsing Culture

\nLeverage Remoting