PowerShell Advanced Functions Advanced Parameters

In our previous tutorial we've talked about how to use parameter attirbutes in powerShell advanced functions parameter attributes. In this tutorial I'm going to share how to use advanced parameters with brief example.

The following are the list of advanced parameters used in advanced functions.

  • Alias
  • AllowNull
  • AllowEmptyString
  • AllowEmptyCollection
  • ValidateCount
  • ValidateLength
  • ValidatePattern
  • ValidateRange
  • ValidateScript
  • ValidateSet
  • ValidateNotNull
  • ValidateDrive
  • ValidateUserDrive
  • ValidateNotNullOrEmpty
  • DynamicParam
  • Switch

Especially for dynamicParam, we will talk about it in the next tutorial

Alias

You can create alternate names for parameter, there is no limit of number aliases for a parameter. Example

function Test-Aliases {
    [Cmdletbinding()]
    Param (
        [Parameter(Mandatory=$true)]
        [alias("CN", "MachineName")]
        [String[]] $ComputerName
    )
    Write-Host "Test-Aliases: $ComputerName"
}
Test-Aliases -MachineName "server01", "server02", "server03"
Test-Aliases -CN "server01", "server02", "server03"

AllowNull

The AllowNull attribute allows the value of a mandatory parameter to be null ($null). Example

function Test-AllowNull {
    [Cmdletbinding()]
    Param (
        [Parameter(Mandatory=$true)]
        [AllowNull()][String]$Name
    )
    Write-Host "Test-AllowNull: $Name"
}
Test-AllowNull -Name ([NullString]::Value)

AllowEmptyString

The AllowEmptyString attribute allows the value of a mandatory parameter to be an empty string (""). Example

function Test-AllowEmptyString {
    [Cmdletbinding()]
    Param (
        [Parameter(Mandatory=$true)]
        [AllowEmptyString()][String] $Name
    )
    Write-Host "Test-AllowEmptyString: $Name"
}
Test-AllowEmptyString -Name ""

AllowEmptyCollection

The AllowEmptyCollection attribute allows the value of a mandatory parameter to be an empty collection (@()). Example

function Test-AllowEmptyCollection {
    [Cmdletbinding()]
    Param (
        [Parameter(Mandatory=$true)]
        [AllowEmptyCollection()] [String[]] $Name
    )
    Write-Host "Test-AllowEmptyCollection: $Name"
}
Test-AllowEmptyCollection -Name "Levi"

ValidateCount

The ValidateCount attribute attribute specifies the number of parameter values that a parameter can accepts. PowerShell will generate an error if the number of parameter values is outside the range. Example

function Test-ValidateCount {
    [Cmdletbinding()]
    Param (
        [Parameter(Mandatory=$true)]
        [ValidateCount(1, 3)][String[]]$computerName
    )
    Write-Host "Test-ValidateCount: $computerName"
}
Test-ValidateCount -computerName "server01", "server02", "server03"
# the test below will generate an error, try to uncomment it
# Test-ValidateCount -computerName "server01", "server02", "server03", "server04"

ValidateLength

The ValidateLength attribute specifies the number of characters in a parameter or variable value. PowerShell will generate error if the length of a spesified value is outside the range. Example

function Test-ValidateLength {
    [Cmdletbinding()]
    Param (
        [Parameter(Mandatory=$true)]
        [ValidateLength(1, 10)] [String] $ComputerName
    )
    Write-Host "Test-ValidateLength: $computerName"
}
# Test-ValidateLength -ComputerName "thiswillgenerateError"
Test-ValidateLength -ComputerName "server01"

ValidatePattern

The ValidatePattern attribute specifies a regular expression that is compared to the parameter or variable value. PowerShell will generate error if value does not match the spesified pattern. Example

function Test-ValidatePattern {
    [Cmdletbinding()]
    Param (
        [Parameter(Mandatory=$true)]
        [ValidatePattern("server[0-9][0-9]")]
        [String[]] $ComputerName
    )
    Write-Host "Test-ValidationPattern: $ComputerName"
}
Test-ValidatePattern -ComputerName "server01", "server02"
# the test below will generate an error, try to uncomment it
# Test-ValidatePattern -ComputerName "server1", "server2"

ValidateRange

The ValidateRange attribute specifies a numberic range for each parameter or variable value. PowerShell will generate error if the value is outside the specified range. Example

function Test-ValidateRange {
    [Cmdletbinding()]
    Param (
        [Parameter(Mandatory=$true)]
        [ValidateRange(1, 10)] [Int] $Number
    )
    Write-Host "Test-ValidateRange: $Number"
}
Test-ValidateRange -Number 10
# Test-ValidateRange -Number 34 # this will generate error

ValidateScript

The ValidateScript attribute specifies a script that is used to validate a parameter or variable value. PowerShell pipes the value to the script, and will generate error if the script return "false" or if the script throws an exception. Example

function Test-ValidateScript {
    [CmdletBinding()]
    Param (
         [Parameter(Mandatory=$true)]
         [ValidateScript({ $_ -is [double] })] $number
    )
    Write-Host "Test-ValidateScript: $number"
}
Test-ValidateScript -number 12.32323

ValidateSet

The ValidateSet attribute specifies a set of valid values for a parameter or variable. PowerShell will generate an error if a parameter or variable value does not match any value in the set. Example

function Test-ValidateSet {
    [Cmdletbinding()]
    Param (
        [Parameter(Mandatory=$true)]
        [ValidateSet("Low", "Average", "High")]
        [String[]] $Detail
    )
    Write-Host "Test-ValidateSet: $Detail"
}
Test-ValidateSet -Detail "Low"
# Test-ValidateSet -Detail "Highest" # this will generate error

ValidateNotNull

The ValidateNotNull attribute attribute specifies the parameter value cannot be null ($null) and powerShell will generate error if the parameter value is null. Example

function Test-ValidateNotNull {
    [Cmdletbinding()]
    Param (
        [Parameter(Mandatory=$true)]
        [ValidateNotNull()] [String] $Name
    )
    Write-Host "Test-ValidateNotNull: $Name"
}
Test-ValidateNotNull -Name "Levi"
# this will generate error
# Test-ValidateNotNull -ComputerName "$null"

ValidateNotNullOrEmpty

The ValidateNotNullOrEmpty attribute specifies the parameter value cannot be null ($null) or an empty string (""). PowerShell will generate error if the parameter value is null or empty string. Example

function Test-ValidateNotNullOrEmpty {
    [Cmdletbinding()]
    Param (
        [Parameter(Mandatory=$true)]
        [ValidateNotNullOrEmpty()][String[]] $computerName
    )
    Write-Host "Test-validateNotNullOrEmpty: $computerName"
}
Test-ValidateNotNullOrEmpty -computerName "server01", "server02"
# Test-ValidateNotNullOrEmpty -computerName "" # this will generate error
# Test-ValidateNotNullOrEmpty -computerName "$null" # this will generate error

ValidateDrive

The ValidateDrive attribute specifies allowed drives as a value to represent the parameter path. PowerShell will generate an error if parameter value refers to unspecified drives. Example Example

function Test-ValidateDrive {
    [CmdletBinding()]
    Param (
        [Parameter()]
        [ValidateDrive('C','D')] [String] $Path
    )
    Write-Host "Test-ValidateDrive: $Path OK!"
}
Test-ValidateDrive -Path "C:\Users"
# Test-ValidateDrive -Path "E:\" # this will generate error

ValidateUserDrive

The ValidateUserDrive attribute specifies allowed User drive as a value to represent the parameter path. PowerShell will generate an error if parameter value referes to unspecified User drive. Example

function Test-ValidateUserDrive {
    [CmdletBinding()]
    Param (
        [Parameter()]
        [ValidateUserDrive()] [String] $Path
    )
    Write-Host "Test-ValidateUserDrive: $Path"
}
New-PSDrive -Name 'User' -PSProvider FileSystem -Root 'c:\temp'
Test-ValidateUserDrive -Path "User:\temp"

Switch

Switch parameters are parameters with no parameter value. Example

Function Test-Switch {
    [CmdletBinding()]
    Param (
        [Parameter()][Alias('P1')]
        [Switch] $Param1,

        [Parameter()][Alias('P2')]
        [Switch] $Param2
    )
    if ($Param1 -and $Param2) {
        Write-Host "It's P1 and P2"
    } ElseIf ($Param1) {
        Write-Host "It's P1"
    } ElseIf ($Param2) {
        Write-Host "It's P2"
    } Else {
        Write-Host "None of parameters were choosen"
    }
}
Test-Switch -P1 -P2
Test-Switch -P1
Test-Switch -P2
Test-Switch

That's all about advanced parameters in advanced functions, leave comments and feedback if you guys have any questions.

Source : Advanced Functions Advanced Parameters

Subscribe to receive free email updates:

0 Response to "PowerShell Advanced Functions Advanced Parameters"

Post a Comment