In this article you will learn the basics of running PowerShell script files.
This is the third installment of a multi-part series on Windows PowerShell for Windows systems administrators. To get caught up on our subject matter, you might want to read the two previous articles about cmdlets and the pipeline and about aliases and drives.
Now, then—on with the show. While issuing ad-hoc PowerShell cmdlets from a PowerShell prompt is all well and good for occasional or on-demand use, you don’t truly begin to leverage the strengths of Windows PowerShell until you aggregate your code (which can include variables, branching, looping, error handling, etc.) into script files.
In a future installment we will begin to drill into practical examples of administering Windows using PowerShell. In this essay I will teach you the basics of creating and running PowerShell scripts from an overview perspective.
What is a PowerShell script?
A Windows PowerShell script file is nothing more than a plain text file that (a) has the .ps1 file extension; and (b) contains one or more lines of PowerShell source code.
Plaintext script file
Like VBScript, Python, and most other so-called “scripting languages,” your code is not compiled at run-time but is rather interpreted, line-by-line, by the PowerShell interpreter.
Therefore, you will get exactly nowhere unless and until you have PowerShell 2.0 installed on your target system. When you download PowerShell 2.0 (wonkily called the Windows Management Framework by Microsoft), you not only receive the PowerShell runtime environment, but you also receive the PowerShell Integrated Scripting Environment (ISE).
The ISE is a graphical interface (specifically a host application) for Windows PowerShell, and in my opinion should be your de facto scripting environment.
NOTE: In PowerShell nomenclature, a host application is a management tool that includes the Windows PowerShell runtime within its framework. For instance, the Microsoft Exchange Administrator console is a PowerShell host application, as are all third-party PowerShell ISEs.
The following exhibit shows the unique, three-paned interface of the PowerShell ISE:
The Windows PowerShell ISE
The three viewing panes have the following purpose:
- Script Pane: Enables you to edit your PowerShell scripts
- Output Pane: Displays the output from your scripts
- Command Pane: Enables you to issue PowerShell statements interactively
While we’re at it, in the name of completeness why don’t we briefly explain the function of the primary toolbar buttons as well:
Figure 2: The PowerShell ISE toolbar
- 1: New
- 2: Open
- 3: Save
- 4: Cut
- 5: Copy
- 6: Paste
- 7: Clear Output Pane
- 8: Undo
- 9: Redo
- 10: Run Script
- 11: Run Selection
- 12: Stop Execution
- 13: New Remote PowerShell Tab
- 14: Start PowerShell.exe
- 15: Show Script Pane Top
- 16: Show Script Pane Right
- 17: Show Script Pane Maximized
Creating a PowerShell script
Authoring a Windows PowerShell script is as easy as typing or pasting your code into the ISE script pane and then pressing the Run Script toolbar button. Be sure to save your file with the .ps1 extension; the PowerShell ISE takes care of that pesky little detail for you.
If you are a beginner to PowerShell scripting, then you will want to (1) purchase a great textbook or computer-based training course on the subject; and (2) make use of the wonderful Microsoft TechNet Script Repository.
In point of fact, the simple PowerShell script we use as an example in this article was borrowed from the TechNet Script Repository.
Running a PowerShell script
Before we learn how to run a PowerShell script from outside the ISE, we need to explain PowerShell execution policy, formally defined as Code Access Security.
By default, Windows PowerShell runs in the Restricted execution policy, which means that Windows PowerShell can be used only in interactive mode from a PowerShell prompt or from an ISE. This prohibition of PowerShell scripts from running “free” on a host system was done by design and obviously for security purposes.
The other three PowerShell execution policies are:
- AllSigned: Only scripts that are digitally signed by a trusted publisher are allowed to run
- RemoteSigned: Locally created scripts can run fine; downloaded scripts must be digitally signed by a trusted publisher in order to run
- Unrestricted: All PowerShell scripts can run without restriction (not recommended for most environments)
To change the PowerShell script execution policy on a system, open an elevated command prompt, start PowerShell by typing powershell, and then invoke the Set-ExecutionPolicy cmdlet. To verify the current execution policy, run Get-ExecutionPolicy.
The following exhibit demonstrates how to both verify the current execution policy, as well as how to change the default execution policy to something a bit more reasonable in a development environment—RemoteSigned.
Setting Windows PowerShell execution policy
Now for the good stuff. To run a PowerShell script from an elevated command prompt, perform one of the following actions:
- .\<script>.ps1 (You can use this form if your OS prompt is already focused in the local directory that contains the target PowerShell script file)
- C:\Scripts\<script.ps1> (Here we specify the fully qualified filename of the target PowerShell script)
As long as Windows is properly configured to associate the .ps1 extension with Windows PowerShell, the inclusion of the file extension in your scripts is optional.
If, by contrast, you are already within PowerShell, you can employ the Invoke-Expression cmdlet to run the script. To wit:
PS> Invoke-Expression “C:\Scripts\<script>.ps1”
NOTE: The use of quotation marks is required only if your directory path includes spaces. Be aware, also, that by default you must always fully qualify the location of the script file even if your present working directory is the same location as the target script.
Finally, you can use the ampersand (&) shortcut to run a script from within PowerShell. That is to say:
At this point you know a thing or two about creating and running Windows PowerShell scripts. I will leave you with some helpful links to foster further learning. If there are other PowerShell-related topics on which you would like to see coverage here at 4Sysops, then please feel free to leave those requests in the comments portion of this post.
For Further Study:
- Running Scripts
- Best IDE for PowerShell?
- Introducing the Windows PowerShell ISE
- Windows PowerShell Owner’s Manual
- Windows PowerShell 2.0 Administrator’s Pocket Consultant