Learn more about SQL Server tools

mssqltips logo
 

Tutorials          DBA          Dev          BI          Career          Categories          Webcasts          Whitepapers          Today's Tip          Join

Tutorials      DBA      Dev      BI      Categories      Webcasts

DBA    Dev    BI    Categories

 

Validating PowerShell Parameters - Part I


By:   |   Last Updated: 2016-04-01   |   Comments (2)   |   Related Tips: More > PowerShell

Problem

We've been passing many of our PowerShell scripts to our junior developers and DBAs to use and wanted to know some of the basics for parameter validation to limit ranges as well as enforce standards in our environment.

Solution

Restricting parameters provides advantages with being able to hand scripts to junior developers or DBAs, enforcing good naming convention, maintaining security, and generating meaningful errors to the environment. Some of the most common parameters are strings and numbers, but in many of my PowerShell scripts, I'll also pass in file locations (such as the SMO or RMO library). Let's look at some of the functions with limits on what parameters enter the function and what errors are thrown when they're violated.

In the below code, we will limit the parameter $string to a range of characters between 1 and 10 and we call the function, passing in Server as the parameter. It runs without an error because server is six characters long, so it fits within the allowed range. Let's change the length range from (1,10) to (1,2) and pass in the same parameter.

Function Pass-String {
    Param(
        [ValidateLength(1,10)][string]$string
    )
    Process
    {
        Write-Host $string
    }
}

Pass-String -string "Server"

Function Pass-String {
    Param(
        [ValidateLength(1,2)][string]$string
    )
    Process
    {
        Write-Host $string
    }
}

Pass-String -string "Server"

We receive the error:

"Pass-String : Cannot validate argument on parameter 'string'. The argument length of 6 is too long. Shorten the length of the argument to less than or equal to "2" and then try the command again."

This enforces string validation and this is very useful in many different contexts, especially when wanting to restrict naming convention or enhancing security - not everything can be passed to the function. Consider, if you do need to pass in a large string, such as a query, you may want to give your parameter some character space.

In a similar manner, we might want to limit a range of integers when using numbers. In this case, instead of validating the length, we'll be validating the range. In the first example, we pass in 1 when we have a range of 1 to 10. In the second example, we try to pass in 13.

Function Pass-Integer {
    Param(
        [ValidateRange(0,10)][int]$integer
    )
    Process
    {
        Write-Host $integer
    }
}

Pass-Integer -integer 1

Function Pass-Integer {
    Param(
        [ValidateRange(0,10)][int]$integer
    )
    Process
    {
        Write-Host $integer
    }
}

Pass-Integer -integer 13

In the second example, we get the error:

"Pass-Integer : Cannot validate argument on parameter 'integer'. The 13 argument is greater than the maximum allowed range of 10. Supply an argument that is less than or equal to 10 and then try the command again."

This error prevents us from passing in an invalid range and this is helpful in situations where we want to keep some numbers from being passed into our functions.

One common need in many of my PowerShell scripts is the SMO (SQL Management Objects) library, which is a dynamic link library found in the SQL Server assemblies file location and varies by version (for instance, the below code is 2014). In the below two examples, I pass in a valid location for the SMO library and get the location printed out, and in the other script, I pass a non-existent file and get an error. In this case, I'm validating the script and without the correct location, the script becomes invalid. Keep this in mind, especially when handing scripts to junior developer or DBAs - if parameters aren't correct, you want the script invalidated.

Function Pass-Path {
    Param(
        [ValidateScript({Test-Path $_})][string]$smolibrary
    )
    Process
    {
        Write-Host $smolibrary
    }
}

Pass-Path -smolibrary "C:\Program Files (x86)\Microsoft SQL Server\120\SDK\Assemblies\Microsoft.SqlServer.Smo.dll"

Function Pass-Path {
    Param(
        [ValidateScript({Test-Path $_})][string]$smolibrary
    )
    Process
    {
        Write-Host $smolibrary
    }
}

Pass-Path -smolibrary "C:\ExistenceInQuestion\NotTheSMOLibrary.dll"

In the latter example, we get the error:

"Pass-Path : Cannot validate argument on parameter 'smolibrary'. The Test-Path $_ validation script for the argument with value C:\ExistenceInQuestion\NotTheSMOLibrary.dll did not return true. Determine why the validation script failed and then try the command again."
Next Steps
  • When limiting lengths of parameters, consider which lengths will follow the standards of your environment.
  • Consider what pieces of a script need to be validated before using, so that if passing scripts to junior developers or DBAs, these can warn them when they're missing the pieces.


Last Updated: 2016-04-01


next webcast button


next tip button



About the author
MSSQLTips author Tim Smith Tim Smith works as a DBA and developer and also teaches Automating ETL on Udemy.

View all my tips
Related Resources




Post a comment or let the author know this tip helped.

All comments are reviewed, so stay on subject or we may delete your comment. Note: your email address is not published. Required fields are marked with an asterisk (*).

*Name    *Email    Email me updates 


Signup for our newsletter
 I agree by submitting my data to receive communications, account updates and/or special offers about SQL Server from MSSQLTips and/or its Sponsors. I have read the privacy statement and understand I may unsubscribe at any time.



    



Friday, April 01, 2016 - 3:22:02 PM - Tim Back To Top

@Terry

Thanks - (1) what error are you getting and (2) varies.


Friday, April 01, 2016 - 8:58:14 AM - Terry Grignon Back To Top

The first Pass-Integer function will not work as written. You need to escape the parens in C:\Program Files (x86) with the 'accent grave' character (under the tilde).


Learn more about SQL Server tools