Tips for Preparing for the 2012 PowerShell Scripting Games

Tips for Preparing for the 2012 PowerShell Scripting Games

  • Comments 7
  • Likes

Summary: Guest commentator, Boe Prox, talks about practical tips for preparing for the 2012 Windows PowerShell Scripting Games.

Microsoft Scripting Guy, Ed Wilson, is here. Guest blogger, Boe Prox, is with us today. He is going to talk to us about preparing for the 2012 Scripting Games. First, a little bit about Boe…

Photo of Boe Prox

Boe Prox is currently a senior systems administrator with BAE Systems. He has been in the IT industry since 2003, and he has been working with Windows PowerShell since 2009. Boe looks to script whatever he can, whenever he can. He is also a moderator on the Hey, Scripting Guy! Forum. Check out his current projects published on CodePlex: PoshWSUS and PoshPAIG.
Boe’s blog: Learn PowerShell | Achieve More

Take it away Boe…

With the Scripting Games coming up on April 2, you might be asking yourself, “What do I need to do to be prepared for these games?” You are in luck because I am going to show some things that will help you in your quest for scripting glory!

These tips are in no particular order of importance, and they cover a wide variety of items that should be used to increase the readability of your code and to ease any issues that the people who are using your scripts may run into. So without further ado, let’s get started!

Variables that make sense

When you are deciding what you want to call the variables that are used in your code, keep in mind that others will be reading your code, whether it is in the Scripting Games or at your place of work. Or you might have to debug or add something to your code several months later, so using something like this for your code will only make the effort to read the code more difficult.

$strServers = 'server1','server2'

$d = Get-Date

ForEach ($C in $strServers) {

  $objp = Get-WmiObject -computer $c Win32_Process

}

There are a couple of things here that can stand to be changed. First off, the $strservers that is using Hungarian notation is not needed. Although it is often used in VBScript script, it isn’t needed in Windows PowerShell script. Using something that lets you know what the variable is holding—in this case, servers—is suitable, rather than knowing the type of the variable.

Although, I would rather use ComputerName because that is a common parameter in Windows PowerShell cmdlets. $d, $objp, and $c are the remaining the variables that fail to make it easy to know what is being used for each variable. Given, this is a small snippet of code, but imagine if you are working with 100+ lines of code. It would be more difficult to back track and find out what each variable is. Something like this would be much easier to read and understand.

$Computername = 'server1','server2'

$date = Get-Date

ForEach ($computer in $Computername) {

  $processes = Get-WmiObject -computer $computer Win32_Process

}

Error handling

If you are writing functions or scripts (or whatever), you need to be using some sort of error handling in your code. This will prevent unwanted errors from popping up and preventing your code from working. Now, I don’t mean to add $ErrorActionPreference = ‘SilentlyContinue’ at the top of your code and let it fly. If you are using that to solve your error handling, you are only fooling yourself. In other words, remove it immediately! It’s OK, I’ll wait.

What you should be doing is investing in using Try/Catch in your code to handle any potential errors that might pop up. All cmdlets have the ErrorAction parameter, and you can choose to use Stop. Or if you really don’t want to catch any errors (or even know about errors), you can use SilentlyContinue. The benefit of using this parameter is that it will only affect that command, not the all of the commands in the code. The following example of using this method will catch an error if something goes wrong.

ForEach ($Computer in $Computername) {

  If (Test-Connection -ComputerName $Computer -Count 1 -Quiet) {

    Try {

      Get-WmiObject -Computer $Computer -Class Win32_Process -ErrorAction Stop

    } Catch {

      Write-Warning ("{0}: {1}" -f $Computer,$_.Exception.Message)

    }

  } Else {

    Write-Warning ("{0}: Unavailable" -f $Computer)

  }

}

A couple of other types of error handling use specific cmdlets to test for. Test-Connection checks if a system is online before making a connection for a query or some other operation. Test-Path checks to see if a folder or file exists.

Also, checking for Administrator rights is a useful thing to do within your code, especially when working with remote systems or accessing parts of a system that are otherwise off limits to a regular user account. It also helps if you have UAC enabled and are not running the script “as an Administrator.” I wrote a guest blog last year that talked about this: Check for Admin Credentials in a PowerShell Script.

Code formatting

Making your code readable can be just as important as making your code work properly to perform the action that you want it to do. Having code that is not readable makes it difficult to debug when something goes wrong. In addition, others trying to read the code may end up spending more time putting it into a proper format than actually debugging it or modifying it for their own environment. Things to consider when writing your code are:

  • Use spacing between areas of code to separate blocks of code.
  • Use natural line breaks: “|”,”{“.
  • Indent your code in areas where groups of code are being used logically, such as after an opening bracket “{“ or after a pipeline character is used. This ensures that all the lines of code within the construct are easy to identify and work with.
  • Use splatting for parameters where it threatens to force the use of a back tick (“`”) to enable a line break to continue the code.

Following is an example of poorly formatted code:

Image of code

There is a lot wrong with this code, ranging from no spacing, to indenting blocks of code where it is incased in a {} construct, to cmdlets using enough parameters to warrant a line break to keep everything from going off of the screen. Also, there are areas in the code that really aren’t needed, such as saving the result of the Test-Connection cmdlet and then comparing the return when it is a Boolean value in the If statement.

This is what it should look like:

Image of code

What you have now is something that is not only easier to read, but also takes advantage of other techniques, such as splatting the parameters for Get-WmiObject and taking advantage of the Boolean return value for using the Quiet parameter in Test-Connection for the If statement. Instead of using something like @{L='Computer';E={$_.__Server}},@{L='TimeGenerated';E={Get-Date}}} to add a couple extra properties to the output that is difficult to read, I used a ForEach loop and created my own object to make it easier to read. This really starts to show its usefulness when you are trying to add multiple properties to the output that are not available any other way.

There are more lines of code being used here. But trust me, it is worth it to have more readable code than taking shortcuts by cramming it all together.

Comment-based Help

Something that I saw last year (especially in the first few events), and I sometimes still see, are people writing their own Help in their code. Although it is great to see that some sort of Help is being added into their code so other people know what is going on with it, there is no reason to be doing this. The Windows PowerShell team has put together an amazing thing called comment-based Help that does practically all of the work for you. It has some great features such as displaying examples, viewing the full Help of the command, and looking at the details of a particular parameter. It is so simple that you can practically do it in your sleep! See this example:

Image of code

Everything within “<#” and “ #>” that uses the appropriate keywords will be read by Windows PowerShell and used to format the Help correctly so it shows something similar to the following:

Get-Help Get-StoppedService

 Image of command output

Everything that can help a person figure out what to do with this code is here. Want to know the specifics about the ComputerName property? Simple! Just do this:

Get-Help Get-StoppedService –Parameter Computername

Image of command output

How cool is that? This is much better than only getting one option when writing your own Help—which is typically to display everything at once. Need an example? Just do this:

Get-Help Get-StoppedService -Example

Image of command output

Remember, comment-based Help is your friend, and it should be used instead of writing your own Help. For more information about comment-based Help, run the following command:

Get-Help about_Comment_Based_Help

Other things to consider

I don’t have the time to dive into detail about these other items, but they are by no means any less important to think about and use while writing your code. It is just that I only have a limited amount of time and space to pick and choose which items to talk about.

  • Use output objects instead of text, and make it pipeline friendly.
  • Do not use aliases for anything (this includes cmdlets and parameters).
  • Use properly named functions (Verb-Singular noun).
  • Use Get-Verb to see approved verbs.
  • Keep inline comments to a minimum (consider using Write-Verbose instead).
  • Use [cmdletbinding()] and Param() in advanced functions; This allows the use of common parameters such as Verbose, Debug, WhatIf, and ErrorAction.
  • Consider using Write-Progress for long running tasks where you are looping through a collection; this allows the user to know where the script is and does not assume it has locked up.

Final thoughts

Keep in mind that during the Scripting Games you may not always get the score that you were hoping for. But don’t let that get you down! Keep writing code and submitting your scripts, learn from what the judges say, and look at the scripts your fellow scripters have submitted. You will improve on your current skills and continue to put together great scripts!

To quote myself from last year on twitter during the 2011 Scripting Games: “Remember that as long as you did your best on your script and are happy with what you did, then grading should be secondary.”

Good luck to all of the scripters this year!

~Boe

Thank you Boe. This is a great summary of things to keep in mind for the 2012 Scripting Games. Join us tomorrow for more Scripting Games prep week.

I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

Ed Wilson, Microsoft Scripting Guy 

Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment
  • Hi Boe,

    thank you for this excellent summary of advices to write "code with style"!

    I agree upon everything you mentioned here and I know that you could definitely add much more to the list!

    One thing, I would add to the list is (refering to the last HSG! articles):

    use: Set-StrictMode -Version latest and don't forget to initialize variables!

    Another note: there is a small mistake in your Get-ServerService function.

    We could correct this easily with Powershell :-)

    @'

    if ($PSBoundParameters['Credential']) {

       $wmi.Credential = $credential

    }

    '@ -replace 'wmi', 'wmihash'

    Thanks again for having agreed to being a judge for the next scripting games!

    I know that it takes away a big part (if not all) of your free time and that you have to do your daily work regardless of this voluntary extra job!

    Btw: In preparation of the #2012sg:

    There is one (completely different?) thing I would like to ask you, or Ed or ...

    What are the criteria to choose whether to take part in the beginner or advanced section? Is there a need to be admin? Have we got to be member of a domain? Are there special skills needed: exchange, sharepoint, sqlserver ...?

    Klaus (Schulte)

  • @Klaus: Thanks for the catch on that typo! And you are right, there is so much more that could have been added to the list. This easily could have been a multi-part article. I am definitely looking forward to seeing all of the entries that come in for the Scripting Games. It is going to be a great time!

  • @K_Schulte The biggest criteria in determining if you are advanced or beginner is the level of your basic Windows PowerShell skill. You will not need access to Active Directory, Exchange, or anything other than basic Windows with Windows PowerShell 2.0 installed. There are a few exercises that will require admin rights on the computer, but you do not need to be performing a job with the title of administrator (for example one could easily be a developer). There is a new quiz I created at www.scriptingguys.com/learnpowershell that will help one decide if they are a beginner or advanced scripter.

  • Hi Ed,

    Love the quiz, scored 15 out of 25 but didn’t have anything displayed in the “Further Information” pane, was it suppose to?  I feel like a beginner so I’m guessing that’s my level.

    I’ll be driving to the local supermarket for my daily quiz down/upload while on holiday in a caravan with no Internet Access, do I get extra points for effort! :o)

  • What score range would you consider for Advanced and Beginners?

  • @John Yes, I deliberately did NOT do a summary evaluation because in the end, I want each person to feel they are doing the level that is good for them. The most important part is actually following the links after each question ... especially if you got the question wrong, but also if you got the answer right but guessed :-) Yes, if you got 15 out of 25, and you feel like you are a beginner, you should definately do the beginner events. I would love to give you extra points for the extra effort of driving to a supermarket to get wireless access to submit your entries, but unfortunately I cannot. However, I am glad to see you making the effort to do the games this year! Well done, and good luck!!!

  • @LA Richards I do not have a hard and fast rule on that. It is more like how do you feel about your skills. If you easily got all of the questions right, or even 90% of the questions right, and you also feel good about your ability to compose a script, then go for the advanced level. IF you do not feel good about writing scripts, then stay at the beginner level. I can tell you this, at the Advanced level you will be called upon to write some scripts ... at the beginner level, there are a few questions that will require a short script.