Summary: Use Windows PowerShell ISE code snippets to ease the burden of tricky-to-remember syntax.
Microsoft Scripting Guy, Ed Wilson, is here. Today Jonathan Medd, Windows PowerShell MVP, is with us to share some Windows PowerShell goodness.
Take it away, Jonathan…
Often when I am teaching students who are new to Windows PowerShell, one of their complaints (apart from my poor jokes during the class) is, “How do I remember which of these braces and brackets to use for the different types of things I am trying to do?” For instance, they quite regularly get mixed up about when to use parentheses: ()—and when to use braces: {}.
There isn’t always a simple answer, and I usually tell them that a lot of learning a programming language is like learning a foreign spoken language—there are some things you just have to learn, and you will only remember them through practice and experience.
Having said that, one practical piece of advice I give them is to use code snippets within the Windows PowerShell ISE to help with code syntax they are finding difficult to remember. Code snippets are (typically) commonly used standardized short pieces of code that you can insert into your script by picking from a list.
Note Code snippets are typically available in scripting IDEs, and since Windows PowerShell 3.0, they have become easier to use, manage, and create your own. In this post, I’m going to concentrate on the Windows PowerShell ISE; however, you should be able to apply most of these suggestions to other scripting editors.
For example, let’s say that you struggle to remember which type of brackets you need at which point of a foreach statement. Is it the parentheses or the braces?
Within the Windows PowerShell ISE, use the shortcut key Ctrl-J or navigate to Edit\Start Snippets.
This will give you a list of predefined code snippets that ship with Windows PowerShell. For our example, find the foreach snippet and choose it.
The piece of code required for a foreach loop will be inserted into the script pane for you. So there is no need for you to remember which type of brackets were required where for this piece of syntax!
Now amend the variable names that are appropriate for what you are working with, and insert the code you need in between the {} braces.
What if you want to create a snippet of your own because what you need isn’t in the default list of ISE snippets? Handily, since Windows PowerShell 3.0, we have the New-IseSnippet cmdlet to help us.
First though, we need to have a quick look at where code snippets are stored. When you open the Windows PowerShell ISE, it will look for a Snippets folder within your Windows PowerShell profile location, typically C:\Users\username\Documents\WindowsPowerShell .
When you use the New-IseSnippet cmdlet, it will create the Snippets folder for you the first time you create a snippet with it. Or, if you want to create this folder, use the following command:
New-Item (Join-Path (Split-Path $profile.CurrentUserCurrentHost) "Snippets") -ItemType Directory
One area of Windows PowerShell syntax that my students typically have trouble remembering is operators. For instance, when comparing values, we may need to use some of the following operators:
-eq
-gt
-lt
and not:
=
<
>
As is more common in other languages, there is no doubt that when starting with Windows PowerShell, these are not easy to remember. So why not create a few snippets for them?
The following uses of the New-IseSnippet cmdlet will create snippets for three common operators.
Note I have used the parameter CaretOffset. This will place the cursor at the end of the text to insert. Consequently, you will be able to immediately carry on typing after inserting the snippet.
New-IseSnippet -Title "Equals Operator" -Description "Equals Operator" -Text "-eq " -CaretOffset 4
New-IseSnippet -Title "Greater Than Operator" -Description "Greater Than Operator" -Text "-gt " -CaretOffset 4
New-IseSnippet -Title "Less Than Operator" -Description "Less Than Operator" -Text "-lt " -CaretOffset 4
Now, if we are at a point where we need to add the Equals operator, we can pull up the snippets list, and insert our custom Equals Operator snippet.
The text -eq is inserted, and the cursor is placed at the end of the line.
If you look in your Snippets folder now, you will see an XML file that was created for each snippet by New-IseSnippet. These are fully portable; so potentially, they are easy to share with others. Simply send the snippet to someone else and have them copy the XML files into their own Snippets folder. (If you are a bit handy with XML, you can also create them in this manner.)
Here’s the XML to generate the Equals operator snippet:
<?xml version='1.0' encoding='utf-8' ?>
<Snippets xmlns='http://schemas.microsoft.com/PowerShell/Snippets'>
<Snippet Version='1.0.0'>
<Header>
<Title>Equals Operator</Title>
<Description>Equals Operator</Description>
<Author></Author>
<SnippetTypes>
<SnippetType>Expansion</SnippetType>
</SnippetTypes>
</Header>
<Code>
<Script Language='PowerShell' CaretOffset='4'>
<![CDATA[-eq ]]>
</Script>
</Code>
</Snippet>
</Snippets>
That was quite a straightforward example, but how about if you want to add some code that spans multiple lines? Personally, I can never remember the syntax to check if a parameter has been supplied by using $PSBoundParameters. One nice way to do that is to create a Here-String with your code snippet in like this:
$Snippet = @'
if ($PSBoundParameters.ContainsKey('Something')){
}
'@
Then use the New-IseSnippet cmdlet to create the snippet with the $Snippet variable:
New-IseSnippet -Title "Check PSBoundParameters" -Description "Check PSBoundParameters" -Text $Snippet
We can now choose this code snippet from the menu:
And it appears before our eyes…
There you have it. I hope this piece on code snippets helps you and gives you some ideas about how you can save time (and your memory) when writing Windows PowerShell script.
~ Jonathan
Thank you, Jonathan, for taking your time to share your knowledge.
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