I Found this PowerShell Function—Now What Do I Do? Part 2

Summary: Microsoft Scripting Guy, Ed Wilson, continues his discussion about what to do with a Windows PowerShell function.

Microsoft Scripting Guy, Ed Wilson, is here. Last week I did not get a chance to finish answering a question from JB about how to use a Windows PowerShell function.

Note  This is the second part of a multipart series about using Windows PowerShell functions and modules. You should read the first blog post, I Found this PowerShell Function—Now What Do I Do? – Part 1 prior to reading this post.

Functions promote code reuse

In the first installment in this series about using functions, I talked about the more traditional technique of copying and pasting the function directly into a script. This works well if you want to write a script. But one of the powerful things about Windows PowerShell is that I do not have to write a script. In fact, the great thing about Andy Schneider’s Set-ScreenResolution function is that he wrote it as a function.

Top ten Windows PowerShell function best practices

Of course, being able to reuse the code depends on a well written function. Here is my top ten list of Windows PowerShell function best practices.

A function should:

1. Use the standard Verb-Noun naming convention.
2. Do one thing and do it well.
3. Return an object.
4. Incorporate comment-based Help.
5. Expose parameters instead of using hard-coded values.
6. Accept piped input if it makes sense for the use-case scenario.
7. Run and return default information if it makes sense for the use-case scenario (instead of requiring input, or returning an error when it is run without parameters).
8. Offer parameter aliases for common parameters (for example, CN for ComputerName).
9. Name parameters in accordance with standard Windows PowerShell cmdlets (for example ComputerName instead of server, laptop, or machine).
10. Use parameter validation techniques to limit user input.

Note  For more information about Windows PowerShell functions, see this collection of Hey, Scripting Guy! Blog posts.

Save the function into a .ps1 script file

So suppose you find a well-written function and you want to be able to use it in the Windows PowerShell console. A well-written Windows PowerShell function will, in fact, act and behave like a Windows PowerShell cmdlet. So bringing it into the Windows PowerShell console will enhance the interactive use experience of Windows PowerShell.

Let’s go back to the Set-ScreenResolution function that I used last week (written by Andy Schneider). I go to the Scripting Guys Script Repository, find the Set-ScreenResolution script and copy it to the clipboard. Now, I paste it into the Windows PowerShell ISE, and I save it with a file name like Set-ScreenResolutionFunction.ps1. Here is the script:

Dot source the script file

When I have the function stored in a script file, I can use the function in my Windows PowerShell console, or even in another Windows PowerShell script. The key to doing this is to store the script file that contains the function in an easily locatable folder. For me, that folder is off the root of drive C (C:\fso). I have used this folder for my scratch folder for over a decade.

Keys to success for using dot sourcing

1. Save the function into a script file with a similar name to the function.
2. Save the script file that contains the function in an easily accessed location.
3. Make sure that the script file contains only the function, and no “entry code” that will automatically launch the function.
4. Dot source functions into scripts that may have code that changes for ease of update.
5. Use the syntax: period, space, path to script (<.><space><path>).

To dot source the Set-ScreenResolutionFunction.ps1 script into the Windows PowerShell console, I use the syntax shown here:

. C:\fso\Set-ScreenResolutionFunction.ps1

To call the Set-ScreenResolution function, I type the function name, just like I would do with a regular Windows PowerShell cmdlet. In fact, tab expansion even works. This is shown here:

Set-ScreenResolution -Width 800 -Height 600

This technique is shown in the image that follows.

I can also use this technique in the Windows PowerShell ISE. In the image that follows, I dot source the Set-ScreenResolutionFunction.ps1 script into my script.

Well, that is about all for now. Now What Do I Do? Week will continue tomorrow when I will continue to talk about using Windows PowerShell functions.

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