Best Practices for Script Design A PowerShell.org TechSession

Remember Find the latest TechSessions at Advanced registration is required to attend the live events, where you can participate in Q&A Recordings posted to YouTube, usually in 48 hours.

Today We’ll be looking at best practices for designing scripts that best leverage PowerShell’s native patterns and capabilities. Please submit questions to the Q&A panel as we go – I’ll address them as you submit them.

Basic Information Level: Best practices and patterns for using complex technologies Pre-requisites: Solid experience with Windows PowerShell scripting/programming

Scripting Goals Ease testing and debugging Maximize reuse Minimize programming effort Conform to existing shell usage patterns Get the job done!

Tools vs. Controllers TOOLS Do one thing and one thing only Not tied to a specific context Accept input only via parameters; output only via pipeline Cmdlet-style naming Advanced functions contained in a script module CONTROLLERS Coordinate multiple tools to complete a process Tied to a specific process May read data from files, params, databases, etc. May not use cmdlet-style naming Monolithic script with minimal functionality; mostly logic

Tools Create information for use by other tools Get-, Import-, ConvertFrom-, etc. Process information and take action Get-, Set-, New-, Remove-, etc. Put raw data into a particular form Export-, ConvertTo-, Format-, Out-

Poor Function Get-Something { [CmdletBinding()] Param( [string[]]$ComputerName, [string]$FileName ) if ($PSBoundParameters.ContainsKey('Filename')) { $ComputerName = Get-Content $FileName }

Improved Function Get-Something { [CmdletBinding()] Param( [Parameter(ValueFromPipeline)] [string[]]$ComputerName ) } Get-Content computers.txt | Get-Something Get-ADComputer –filter * | Select –Expand Name | Get-Something

Poor... $objects += $object $objects | Format-Table }

Improved... Write-Output $object } Do-Whatever | Format-Table

General Guidelines If information could ever possibly come from more than one source, make dedicated tools to get it, and feed it to other tools via the pipeline or parameters. If a tool does formatting, puts data someplace (e.g., a database), etc., then that is all the tool should do.

General Guidelines If a tool is making any kind of change, then that is all it should do. It should never also worry about where input came from or where output is going. Remember: If a tool makes changes, it should support –confirm and –whatif; those can only affect one operational within the tool, so the tool should only do that one thing.

Possible Red Flags One parameter set accepts information (like a computer name), while another accepts a source for that information (like a filename) Any use of Get-Content Any use of Format-, Export-, Out-, or ConvertTo- in a tool that also does other work

Controllers Do very little work. Instead, they implement a lot of logic to decide what work to do – and call commands (tools) to do that work. Responsible for the entire cycle of input/work/output. Automate a process, produce a report, display a menu, etc. These control one or more tools to do something useful. Tools may not do a completely useful thing by themselves; the controllers make that happen.

Tools vs. Controllers (Redux) New-ADUser Does one thing Doesn't complete an entire process (e.g., for a new employee) Has no idea where new user info is coming from ProvisionEmployee.ps1 Does many things (user account, home dir, add to groups, etc.) Has a specific source for new user info (perhaps an HR database or spreadsheet) Uses New-ADUser internally

Goal: Testing and Debugging Tools can be tested independently, using the same input (via parameters) a controller might use Makes debugging simpler and more contained Controllers do nothing, so it's easier to test their logic – especially if you've properly implemented –whatif in your tools.

Goal: Reusability Because tools aren't tied to a specific context or use case, they're easier to reuse Because controllers contain little to no functionality, they don't need to offer reusability

Goal: Minimize and Conform Tools work consistently with existing shell patterns (e.g., the same as cmdlets, when you do it right) Controllers become the traditional "glue" script that pulls tools together Controllers can be written more quickly because they don't do complex work; they're only coordinating pre- tested, pre-existing tools

Let's See an Example

Let’s Take Some Questions I know you’ve got ‘em… ask away.

Thank You! Find the latest TechSessions at Advanced registration is required to attend the live events, where you can participate in Q&A Recordings posted to YouTube, usually in 48 hours. Ask follow-up questions in the Forums on PowerShell.org.