Link to Parent: PowerShell - Deep Dive and Best Practice

Reference for dealing with parameter attributes

What  are parameter attributes

Parameter attributes allow you to control the features/function of a parameter such as making a specific parameter mandatory.

MSDN - Cmdlet Parameters

Cmdlet Binding Attributes

Cmdlet Binding Attributes allow you to control the features/function of how the cmdlet itself works. For example specifying the url for external help on the cmdlet or settings its impact, which controls prompting the users.


The ConfirmImpact attribute is used to set the importance of what a cmdlet can do, typically based around its ability to destroy data.


MSDN - ConfirmImpact ENUM


If your script makes use of multiple ParameterSet, you can use the DefaultParameterSetName property to define which set of parameters to use by default, if the user's input does not expressly define one of the available sets.  You can also specify "None" as a value


For this Script block below there are two Parameter Sets, ByUserName and ByUserID.  The action of these sets is that if a user provides a -Name field, PowerShell will know to prompt for the mandatory $Email property as well.  However, if the user provides a value for -Id, then PowerShell will not prompt for the other values of the Parameter Set.  If the user provides no parameters at all, PowerShell will default to the ByUserName parameter set, and prompt for both mandatory values.

function Get-SomeValue{
param (
    switch ($psCmdlet.ParameterSetName) {
         "ByUserName"  {#Actions to process for ByUserName
         "ByUserId"  {#Actions to process for ByUserName

MSDN - DefaultParameterSetName Metadata
MSDN - Cmdlet Parameter Sets
MSDN PowerShell Blog - ParameterSets


Simply an external help reference.


MSDN - Writing Help for Windows PowerShell




You can use the SupportsShouldProcess Cmdlet binding to instruct PowerShell's underlying engine to allow for the -WhatIf Parameter.  In the following Function, you will see both how to instruct PowerShell to Support Should Process, and also how to use it within your functions.

Function Set-Something{
    [Parameter(Mandatory=$false,Position=0,HelpMessage="Please specify the users to be Set")]
    #You use the syntax on the following line to determine whether or not -WhatIf was specified
    #The syntax is as follows for the Generated -WhatIf message:
    #What if: Performing the operation "Operation" on target "Target".
    if($PSCmdlet.ShouldProcess($User,"Set Property to '$SomeProperty'")){
        Write-output ("Preparing to Set-Something: $SomeProperty on $User")



Parameter Attribute

These are used to modify how individual parameters are managed. They are applied in the following form:

    [parameter(attribute=value, attribute=value)]



This is used to make a parameter required. It takes a true or false value. The default is false so typically this is only applied if you want to make a parameter required.




If a function is called with parameters and the parameter isn't assigned by name, its done by position, and the Position parameter attributes value indicates which value is assigned to which parameter. This is 0 based assignment.

Function Get-NameAndAge {
write-host "Name: $name Age: $age"
#can be called the normal way,
Get-NameAndAge -Name Justin -age 30
#or, because we've defined position values we can call it without named parameters
Get-NameAndAge Justin 30


This is used to define different combinations of parameters. For example if you have a function that can take a username, or a computername and action, you could say that if you provide a computername then the user can not also provide a username.

function Invoke-OnElement {
    "byname" { Set-NameProperty -user $username -description $description}
    "bycomputer" { Set-ComputerProperty -computer $computername -description $description}



This is used to accept data from the pipeline. This part can actually get a little tricky in how you design your function. There are two uses cases for something like this, one being passing values over the pipe or using them directly.

"serverA","serverB" | Test-Server
Test-Server -ComputerName "serverA","serverB"

In order to have both of these work you'll need to define your function in this way.

function Test-Server {
    foreach($system in $computername)
        #run tests

In order for the function to handle the items from the pipe, you need to use the begin/process/end blocks (only process shown above) but in order for it to handle an array passed in to the param you need the foreach loop. This doesn't make for the prettiest function but this is the setup for it.








As a cmdlet or function changes over time, you may want to change the name for a parameter for better self-documentation or consistency with another set of functions or cmdlets. However, this may carry the risk of breaking existing callers.

The Alias parameter attribute allows you to accept different names for the same input.  The function below may have taken only MachineName before. It will now accept either ComputerName or MachineName as its primary parameter, and ComputerName will be shown as the preferred name.

Function Get-SomeValue {
      Get-WmiObject -Class Win32_ComputerSystem -ComputerName $ComputerName

Parameter Validation Attributes

All validation attributes are in the same general form  [type(condition)] so the following sections will only contain the name/format for these.
For more details read the About_Functions_Advanced_Parameters
Here is a basic example


Allows $null value


Allows "" values


Allows @() as a value


Checks number of items in a collection


Checks the length of the value passed in


Checks the value against a Regular Expression (regex)


Checks to make sure the number provided is within a range. You'll want to make sure the type for the parameter is a valid number type


Uses PS syntax to validate a value. The $_ is used to represent the parameter value
[ValidateScript( { $_ -ge (get-date) } ) ]


Makes sure the value is in the provided set. This also provides intellisense for the cmdlet



Makes sure the value is anything but null


Makes sure the value is not null or and empty string ""

Dynamic Parameters


Switch Parameters

You can specify the name of a Switch parameter if you would like to allow the user to be able to run an operation if the switch is provided.  

For instance, consider the below snippet, which would move users from one Active Directory OU to another, and you wanted to provide your end-user the option to display a certain attribute when running, you could create a [Switch] Parameter named 'ListOU'.  

Function Move-Users {
    [Parameter(Mandatory=$false,Position=0,HelpMessage="Please specify the users to be moved to the appropriate OUs.  This can be either names within a file, or a hashtable.")]
            [string[]]$DestinationOU = 'corp.dc/destination/ou',
   $Users = Import-Csv $UserList
   ForEach ($User in $Users){
   $UserObj = Get-ADUser $Users.Name
     If ($ListOUs) { "User Moving from $($UserObj.Fullname) to $DestinationOu"}
     #Code Continues...

If the command is executed without the switch Provided, this value will return as $False, and the code block which displays the message will not be displayed.  However, if they do provide the -ListOU switch, $ListOU will have a value of $True and then the code-block will be executed, displaying the special message.



PowerShell Help

See Also


Other Languages