Winter Scripting Games 2014 Tip #2: Use #Requires to let PowerShell do the work for you

In Version 2 of PowerShell, you had the ability to use #Requires –Version 2.0 to ensure that your scripts/functions would only run at a specified PowerShell version to prevent folks running an older version from wondering why things weren’t working that well.

image

In this article, I will show you a couple of new additions to the #Requires statement that will make your life easier when writing functions that require specific pre-requisites rather than coding your own methods.

Modules

This was fine, but only lent itself to scripts that were not version compatible. Fortunately, with Version 3, we gained a better #Requires statement for modules. Rather than adding extra code to handle the checking of whether a module existed or not, we can just add the following statement and if the module existed, the running of the code would continue and if it didn’t work, a terminating error is thrown and the codes stops running.

Let’s try it out!

#Requires -Module ActiveDirectory

Ok, I have this statement placed right after my commented help block and before the [cmdletbinding()] statement as so:

Function Get-SomeUser {
    #Requires -Module ActiveDirectory
    [cmdletbinding()]
    Param ($User)
    Get-ADUser -Identity $User
}

When I dot source the function, nothing happens, meaning that the function found the module required.

image

Nothing happens as expected. The module was found and it was also loaded up. So what happens when a module doesn’t exist on the system in which we are calling the function on?

image

My DoesntExists module…well…doesn’t actually exist and when I try to dot source the script to load that function which requires that specific module, it fails stating that it is missing and therefor unable to proceed any further. Pretty handy if you do not want your stuff to run without a specific module available.

Running as an Administrator

I’ve actually written a small script back in the day as well as a Hey, Scripting Guy! article that was used to detect if the current user was running PowerShell ‘as an administrator’ before running a script. Another possibility that could be used is this:

[bool]((whoami /all) -match "S-1-16-12288")

In PowerShell V4 we were gifted with really one of the best little additions that can really cut down on the amount of code that could be used to detect whether the script/function was being ‘run as an administrator’.  That little #Requires gem is called RunAsAdministrator.

Function Set-Something {
<#
    .SYNOPSIS
#>
#Requires -RunAsAdministrator
    [cmdletbinding()]
    Param ($Item)

}

image

Now lets try this when I am not running my console as an administrator and see what happens.

Capture

Perfect! With just a small line of text, we have made sure that this script can only be run by someone with Administrator rights and also is running the script in a console that was opened using the ‘run as administrator’ context.

By utilizing these two small things, you can ensure that you are letting PowerShell do the work for you and saving time coding checks that are already available to you out of the box!

About these ads

About Boe Prox

Microsoft PowerShell MVP working as a Senior Systems Administrator
This entry was posted in powershell, V3, V4, Winter Scripting Games 2014 and tagged , , , , , . Bookmark the permalink.

2 Responses to Winter Scripting Games 2014 Tip #2: Use #Requires to let PowerShell do the work for you

  1. Dave Wyatt says:

    These are handy, but it’s a shame that they can only apply to an entire script or module file. Sometimes it’s nice to only require a module or admin rights when the script needs to perform specific tasks, at which point you’re back to using older methods.

  2. Pingback: Winter Scripting Games 2014 Tip #2: Use #Requires to let PowerShell do the work for you | PowerShell.org

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s