Use PowerShell to Make Mandatory Parameters

Use PowerShell to Make Mandatory Parameters

  • Comments 6
  • Likes

Summary: Learn how to use Windows PowerShell to create mandatory parameters.

Weekend Scripter

Microsoft Scripting Guy, Ed Wilson, is here. I will admit that yesterday I talked about the easiest default to handle—the case of defaulting to the local computer. Not everything is so easy, nor is everything so cut-and-dry. For example, consider a function that returns users from Active Directory…In a very small environment it may be perfectly fine to return all of the users from the forest by default. In a company the size of Microsoft, such an approach would not be appreciated.

In other cases, performance is not the issue; but rather, the wide range of potential input values makes having a default value useless. For whatever reason, if a default value cannot be assigned, the solution is to make the default parameter mandatory.

In Windows PowerShell 1.0, it was common to use the throw keyword to make a parameter mandatory. I personally do not like this approach because the throw keyword raises an error, and a missing parameter is not really an error. Be that as it may, here is an example of using throw to make a parameter mandatory.

In the function, there are two parameters. The first parameter is the drive letter to query, and the second parameter is the ComputerName to which to connect. The ComputerName parameter uses the $env:computername environmental variable that was discussed in yesterday’s Weekend Scripter blog.

The if statement is used to determine if the $drive variable exists. If the variable exists, it means that it was supplied when the Get-DiskInformation function was called. If the variable does not exist, the throw statement is used to raise an error. Throw generates a terminating error; and therefore, it halts script execution. The Get-WmiObject command is never called if the $drive variable is missing. The complete Get-DiskInformation function is shown here:

Get-DiskInformation function – uses throw

Function Get-DiskInformation

{

 Param(

   [string]$drive,

   [string]$computerName = $env:computerName

) #end param

if(-not($drive)) { Throw "You must supply a value for -drive" }

 Get-WmiObject -class Win32_volume -computername $computername -filter "DriveLetter = '$drive'"

} #end function Get-DiskInformation

When the previous function is called without passing a value for the Disk parameter, the error message shown here is generated:

Image of error message

Because I do not like raising an error for a missing parameter, I used to check for the missing variable, display a friendly message, and exit the script rather than using throw. It was the same thing, but I was able to display more complete information. During the 2011 Scripting Games, I saw several scripts that used throw to make a parameter “mandatory.”

In Windows PowerShell 2.0, a new parameter attribute is introduced. This parameter attribute uses the Parameter keyword, and sets the Mandatory attribute to $true. The syntax to define a particular parameter as mandatory is shown here:

[Parameter(Mandatory=$true)]

A revision to the Get-DiskInformation function so that it uses the new Mandatory parameter attribute allows us to remove the if…throw construction as shown here:

if(-not($drive)) { Throw "You must supply a value for -drive" }

In addition to removing the if…throw construction, the only other change involves adding [Parameter(Mandatory=$true)] to the line immediately above the [string]$drive line. The revised Get-DiskInformation function is shown here:

Function Get-DiskInformation

{

 Param(

   [Parameter(Mandatory=$true)]

   [string]$drive,

   [string]$computerName = $env:computerName

) #end param

 Get-WmiObject -class Win32_volume -computername $computername -filter "DriveLetter = '$drive'"

} #end function Get-DiskInformation

When the Get-DiskInformation function is called, and no value for the Drive parameter is supplied, a pop-up dialog box appears when the function is run in the Windows PowerShell ISE. If the function runs inside the Windows PowerShell console, a prompt similar to the one produced by the Read-Host cmdlet appears. The prompt is shown in the following image.

Image of prompt

The good thing about this prompt, as opposed to one created via Read-Host, is that if you click Cancel, the script gracefully exits. If you click OK, but you have not supplied a value, an error will be generated and the script exits. Therefore, you at least have a chance of exiting the script in a graceful manner (via Cancel).

In the case of gathering disk information, there are two reasonable default values that should be investigated. The first is to hard code the value C: as a default. This is as simple as removing the Mandatory parameter attribute and assigning the value C: to the $drive variable. This is shown here:

Function Get-DiskInformation

{

 Param(

   [string]$drive = "C:",

   [string]$computerName = $env:computerName

) #end param

 Get-WmiObject -class Win32_volume -computername $computername -filter "DriveLetter = '$drive'"

} #end function Get-DiskInformation

This approach works well. It allows you to run the function without any parameters, or to specify a different drive letter to query. However, if the system does not have a drive C, no information displays. While it is true that C: is a fairly safe bet, it is not guaranteed to exist on all systems everywhere.

A better approach, is to use the same technique that is used for the computer system name, that is, use an environmental variable. The SystemDrive environmental variable points to the drive letter where the operating system installs. This is a safer option than randomly choosing drive C. This approach is shown here:

Function Get-DiskInformation

{

 Param(

   [string]$drive = $env:SystemDrive,

   [string]$computerName = $env:computerName

) #end param

 Get-WmiObject -class Win32_volume -computername $computername -filter "DriveLetter = '$drive'"

} #end function Get-DiskInformation

When the previous function is loaded and is called with no parameters, the output shown in the following image appears.

Image of command output

This about wraps another week in the Scripting Center. Join me tomorrow as I look at using Windows PowerShell to troubleshoot Microsoft Outlook load issues.

I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

Ed Wilson, Microsoft Scripting Guy

Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment
  • Hello Ed,

    that's the way PS goes!

    Something to remember ...

    kind regard, Klaus

  • For anyone interested, get-help about_funcitons_advanced_parameters will give you a full list of the wonderful things you can do with parameters, included my favorite HelpMessage, which allows you to tell the user what you are looking for and not just the variable name. This is also were you can find out how to make funtions recieve objects in a pipelin.

  • If you want to make multiple parameters mandatory (but not all), do you have to add the [Parameter(Mandatory=$true)] before each parameter?

  • Making Multiple parameters mandatory

    function Do-Something{

       [CmdletBinding()]

       param(

           [Parameter(Position=0,mandatory=$true)]

           [string] $aMandatoryParam,

           [Parameter(Position=1,mandatory=$true)]

           [string] $anotherMandatoryParam)

       process{

          ...

       }

    }

  • @Klaus Schulte Yes, you are right, it is how PowerShell goes. The parameter attributes are definately worth remembering.

    @Paul Frankovich, yes the online help is always a great way to begin. I love adding a helpmessage as well because it gives additional information to the user of the function. I have an entire chapter about parameter atrributes in my PowerShell 2.0 Best Practices book.

    @Dustin Hedges, yes you need to add the mandatory tag before each parameter.

    @Sachin Sundar, yep, that will work.

  • thank you