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
0 Response to "PowerShell Advanced Functions Advanced Parameters"
Post a Comment