I Found this PowerShell Function—Now What Do I Do? Part 1
Summary: A reader found needed code, but it is contained in a function. Microsoft Scripting Guy, Ed Wilson, provides the scoop about how to use functions.
Hey, Scripting Guy! I have some experience with scripting—primarily VBScript script. I also have written a lot of batch files. But recently, I have begun to learn Windows PowerShell by reading your column and by watching some of your videos. What I am confused about is Windows PowerShell functions—I do not know what to do with them. Can you help?
Microsoft Scripting Guy, Ed Wilson, is here. We had a great SQL Server Week, and the Scripting Games are still going strong. The Scripting Wife has been doing well in the 2013 Scripting Games, and now she busy getting ready for TechEd 2013 in New Orleans. She is already planning excursions to get beignets and pralines.
There are several ways to use a Windows PowerShell function. The way you anticipate using a Windows PowerShell function will determine what you will do with the function after you have it. As an example, I am going to use the Set-ScreenResolution function, which was written by Andy Schneider. Teresa and I had a chance to catch up with Andy at the Windows PowerShell Summit where he gave a great talk for IT pros about source control. Here is a picture of Andy during his presentation.
Probably the easiest way to use a function is in a Windows PowerShell script, in much the same way that you used to use functions and subroutines back in the VBScript days. I will talk about this functionality today, and I will discuss the other methodologies next week.
Copy and paste the function directly into your script
When I go to the Scripting Guys Script repository, and I find Andy’s Set-ScreenResolution function, all I need to do is use the control from the Script Repository and copy it to my clipboard. This technique is shown here.
Therefore, if I want the “run the script so it does stuff” option, it is easiest to copy the function to the clipboard, open the Windows PowerShell ISE, and paste the function at the top. This is shown here:
If I run my script right now, it will appear that nothing is happening because there is no code that calls the function. If I drop down to the interactive Windows PowerShell prompt (the bottom blue pane) and type the name of the function, I can actually call the function as shown here.
The solution is to add a line at the bottom of the script that contains the function that calls the function and passes values for the two required parameters: height and width. Here is the modification,
Set-ScreenResolution -Width 800 -Height 600
This is shown here:
So now, if I run the script, it will automatically change the screen resolution on my primary monitor to 800×600.
Running the script with the function
There are several ways to run the script that contains the Set-ScreenResolution function. Depending on your needs, you may decide one is better than the other.
Open in Windows PowerShell ISE and run it
The first way is to open the script in the Windows PowerShell ISE, and click the green triangle on the tool bar (press F5) to run the script. I use this technique in the following circumstances:
- When I am delivering a Windows PowerShell demo, and am showing a lot of scripts.
- When I am in the middle of writing a Windows PowerShell script.
- When I want to edit a script prior to running it (such as to change the width and height settings in the script).
Run from the Windows PowerShell console
To run the Set-ScreenResolution.ps1 script from the Windows PowerShell console, all I need to do is to pass the path to the script (note that there are no spaces in the name or path). This causes Windows PowerShell to execute the script as shown here.
Run from the Start/Run command
I can also run a Windows PowerShell script by passing it as an argument to the Run command. (This is the same technique that I use when I use the Task Scheduler to run a Windows PowerShell script.) Here is the script:
This is shown here in the Run dialog box.
JB, that is all there is to using a function in a Windows PowerShell script. Join me tomorrow when I will reveal the 2013 Scripting Games Event 3.
I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at firstname.lastname@example.org, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.
Ed Wilson, Microsoft Scripting Guy