Prof. Powershell

Required Scripting Parameters in PowerShell

Make sure the a unsupported script stops at the beginning instead of failing at a later point in time.

• By Jeffery Hicks
• 03/18/2014

When you write a PowerShell script, you are creating something that might be executed by someone else on a totally different computer. A potential obstacle is that the person running your script may not have the necessary cmdlets or permissions for your script to run without error. Sure, you should use error handling and parameter validation, but there are additional steps you can take so that if a requirement isn't met the script won't even get started. Personally, I'd rather have a script fail to start then run part-way and then bomb out.

At the beginning of your script you can insert a few requirements. These are actually commented lines but PowerShell is designed to look for them. First off, you can require a minimum PowerShell version. If you are running a mix of PowerShell v2 and v3 computers and your script uses a v3 feature, you will want to restrict who can run your script. At the beginning of your script insert this line:

#requires –version 3.0

Anyone running PowerShell 1 or 2 will get an error about the version requirement and the script won't even run. Machines running v4 will run. The requirement is therefore really more of a minimum version.

Your script might make use of cmdlets from a snapin installed on your computer. You can make the same requirement for anyone else. In these cases use another #requires statement like this:

#requires -version 3.0
#requires -pssnapin Quest.ActiveRoles.ADManagement

Now, unless the Quest snapin is already loaded, the script will fail to run. I would have to add the snapin and then run the script. If the snapin has a version requirement you can include that as well.

#requires -pssnapin Quest.ActiveRoles.ADManagement -version 1.0

In PowerShell 3 we got the option to require a module.

#requires -module SMBShare

The module doesn't need to be currently loaded but must be found in a folder in $env:PSModulePath. You can require modules that don't exist in the path, but they must be imported prior to running the script.

Finally, in PowerShell 4.0 we got a new requirement that the script is running as administrator in an elevated session.

#Requires –version 4.0
#Requires –RunAsAdministrator

This will eliminate the need for .NET code to test if the user is an administrator. I'm a big fan of this new requirement.

I trust you are picking up you can have as many of these directives as you need. Put them all in the beginning of your script followed by at least one blank line at least for the sake of clarity.

I hope you will take the time to read the details on this topic.

PS C:\> help about_requires

Use these directives to set your script up for success from the beginning.