about_Scripting_Best_Practices.help.txt
|
TOPIC
about_Scripting_Best_Practices SHORT DESCRIPTION A list of recommended scripting best practices. LONG DESCRIPTION Writing a PowerShell script or function is only a little different than using the interactive console. If you can run a command at the console you can copy and paste that into your script file and vice versa. But, whereas the goal in the console is economy and efficiency, in scripting the goal is clarity and consistency. To that end, here a some recommended best practices for writing your own PowerShell scripts and functions. NAMING Wherever possible, name your scripts and functions using the accepted Verb-Noun format. Use one of the standard verbs that you see when running Get-Verb. The noun can be a bit more flexible, but try to keep it singular. If you think your noun might conflict with another cmdlet, then use a prefix. If you are building a collection of functions or a module you might want to do this anyway. Instead of creating a function called Get-File you might call it Get-MyFile. NO ALIASES When calling a cmdlet in your script or function, always refer to it by it's full name and never an alias. It may take a moment longer to write, but you only have to do it once and the full cmdlet name makes it easier to understand. An exception can be made for well known aliases like DIR. PARAMETERS On a related note, always use full parameter names, even for positional parameters. A command like: Get-WMIObject -class win32_operatingsystem -computername SERVER01 is much easier to understand than: gwmi win32_operatingsystem -co SERVER01 Yes, the command may take longer to write, but at least it will be clear and self-documenting. FUNCTIONS OR SCRIPTS? One of your first decisions is whether you are writing a standalone script or a function. Of course, functions need to reside in a script file that you can then dot source or include in a module. My rule of thumb is to write functions for repeatable, modular, or atomic commands that can be incorporated into the pipeline or a larger script. I use stand-alone scripts when I have a series of commands that I need repeated periodically but obviously don't want to type them. Or I need to ensure consistency. I think of these scripts as "canned" PowerShell sessions. In fact a great way to build this type of script is to start a transcript, run through your commands and then edit your transcript, deleting everything but your commands. The resulting script can be run at anytime to "recreate" the PowerShell session. Of course, you can include your own functions as well. Remember that functions must be defined before you can call them. SINGLE PURPOSE Especially when writing functions, keep your function focused on a single task. Don't write a monolithic function that does everything. Write a function that does one thing and that can participate in the pipeline. You want to maintain flexibility. For example, if you include code in your function to write your data to Format-Table, you can't do anything else with that function except send it to a cmdlet like Out-File. If tomorrow you decide you need to sort on the output, you can't. My corollary best practice is to keep formatting separate from your scripts and functions. RETURN vs WRITE Try to avoid using the RETURN keyword at the end of your function. Think "writing objects to the pipeline" and not "returning values". When you use RETURN, PowerShell will write the value to the pipeline and then terminate the pipeline. If you have more data or more commands after RETURN you'll never see them. WRITE-HOST Do not use Write-Host to output data from your script or function. This cmdlet writes to the console and not the pipeline which means you can't pipe your script or function to other PowerShell cmdlets such as Sort-Object or Out-File. Using Write-Host for informational messages is a good use. I recommend using a foreground or background color with Write-Host so you can differentiate your messages from the actual output. You might also consider implementing Write-Verbose or Write-Progress. CODE FORMATTING Make your PowerShell scripts easy to read. Take advantage of whitespace and indentations. The worst thing you can do is create a 100 line script that is single spaced and left-justified. Nobody will be able to help you debug or troubleshoot. There are no performance penalties. You should also come up with a formatting style or template and be consistent. This is especially important if you are developing scripts in a team setting. DOCUMENTATION Finally, it is very important that you document your script, especially sections that might be complex or involve scripting constructs like IF or SWITCH. The comment character is #. You can use it like this: get-service | where-object {$_.status -eq 'Running'} #Get all running services Or like this, which is what I prefer: #Get all running services get-service | where-object {$_.status -eq 'Running'} If you have several documentation lines, then use this format: <# I am a long document comment. It is very important that you read me. #> I recommend that when you start developing your script or function to write each step or task that you want to accomplish as a comment. This helps you organize your thoughts and layout the script of function. Then all you need to do is write code to meet the documentation and when you are finished, your script is already documented. SEE ALSO About_functions About_functions_advanced |