PowerShell Not Your Father’s Command Line Part 8 of 31: Won’t You Take Me To Functiontown? (Part 2)

In my last post, I mentioned getting a little further with functions by covering the runtime life cycle. Now, let’s go a little further and explore some of the arguments of the Parameter attribute, some additional attributes that can be used, and finally the CmdletBinding attribute.

Arguments of the Parameter attribute

When working with parameters in advanced functions, mark them with the Parameter attribute. This tells PowerShell that this is an advanced function and needs to be treated as such. This attribute can take a variety of arguments, including:

• Mandatory – specifies whether the parameter is mandatory. If omitted, the parameter is not mandatory. Note that you need to specify that this equals $true, as this is not like a SwitchParameter.
• Position – specifies where the parameter appears when it is used in a command
• Help message – used with mandatory parameters, this tells the person calling the command what should be entered. This is useless for optional parameters.

Other Attributes

There are other attributes besides the Parameter attribute that you can use while working with advanced functions. There are attributes out there for aliases, validation, and dynamic parameters as well. The Alias attribute allows those entering a command to use a shortened alias for a parameter.

In terms of validation, you can validate to make sure inputs aren’t null, match a pattern, are within a range, allow nulls, and many other things.

The following code sample shows the Parameter, ValidateNotNullOrEmpty, and ValidateLength attributes in action, as well as some of the arguments for the Parameter attribute.

function Get-MaskedString{
param(
    [parameter(Mandatory=$true, Position=0,
    HelpMessage="Enter the string to be masked")]
    [string]
    [ValidateNotNullOrEmpty()]         
    $StringToMask, 
       
    [parameter(Position=1)]
    [string]    
    [ValidateLength(1,2)]  
    $MaskCharacter = '*'
    )
       
    Write-Host ($MaskCharacter * $StringToMask.Length)
}

Some things to note with the above code:

• The Position argument is used on both parameters to control where they appear in a command. However, since the second parameter isn’t mandatory, it may or may not appear as part of the command.
  This is a valid command:

  Get-MaskedString ‘cake’

  This is also a valid command:

  Get-MaskedString ‘cake’ ‘§’

• Since the ValidateNotNullOrEmpty attribute is used, the command will throw an error if it is fed an empty string. It will look like this:
  Image may be NSFW.
  Clik here to view.
• Since the ValidateLength attribute is used, the command will throw an error if $MaskCharacter is present and longer than 2 characters. In this example, 1 is the minimum length, and 2 is the maximum length. It will look like this:
  Image may be NSFW.
  Clik here to view.
  However, this only validates when the $MaskCharacter is present. Otherwise, this parameter has a default value of ‘*’ and will use that if it isn’t present.
• The HelpMessage argument is specified. This appears when you run the command and let it prompt you for the parameters and use ‘!?’ for help in the console, like this:
  Image may be NSFW.
  Clik here to view.

CmdletBinding attribute

The CmdletBinding attribute gives advanced functions access to some functionality that a compiled cmdlet has access to – including SupportsShouldProcess, ConfirmImpact, and DefaultParameterSetName. ConfirmImpact works with the ShouldProcess in determining the impact of an operation. When SupportsShouldProcess and ConfirmImpact are used, the -whatif and -confirm parameters are unlocked.

Learning More

Note that these are just a few of the attributes and features of the CmdletBinding attribute. There are plenty more things you can do in advanced functions and with these attributes. If you really want to dig into writing advanced functions, you will also want to reference the following help topics:

about_functions_advanced
about_functions_advanced_methods
about_functions_advanced_parameters
about_functions_cmdletbindingattribute