PowerShell Advanced Functions Parameter Attributes

Advanced functions allow you to write functions that can perform like cmdlets. Advanced functions are very useful when you want to write a function without having a compiled code cmdlet using a Microsoft .NET Framework language.

Advanced functions use the [CmdletBinding()] attribute or [parameter()] arguments, or both to identify them as functions that can perform like cmdlets.

In this tutorial we're going to talk about parameter arguments. The following are arguments that is used with [Parameter()].

Mandatory
Position
ParameterSetName
ValueFromPipeline
ValueFromPipelineByPropertyName
ValueFromRemainingArguments
HelpMessage

Mandatory

Mandatory has boolean value. When the value is true you need to pass a value for mandatory parameter, but if you don't, powerShell will prompt for the value. Example

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

The result will be like this

PS D:\> .\script.ps1
Test-Mandatory: server01 server02 server03

So instead of passing values for mandatory parameter, powerShell will prompt for the value.

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

Here it is. When the prompt reached ComputerName[3], hit Esc key then hit Enter when you done entering the values.

PS D:\> .\script.ps1

cmdlet Test-Mandatory at command pipeline position 1
Supply values for the following parameters:
ComputerName[0]: server01
ComputerName[1]: server02
ComputerName[2]: server03
ComputerName[3]:
Test-Mandatory: server01 server02 server03

Position

Actually by default powerShell gives each parameter a position number in the order declared start from 0. Example

function Get-Position {
    [CmdletBinding()]
    Param (
        [Parameter(Position=0)]
        [String] $pos1,
        [Parameter(Position=1)]
        [String] $pos2
    )
    Write-Host "Pos1: $pos1, Pos2: $pos2"
}
Get-Position -pos1 "1" -pos2 "2" # this work
Get-Position -pos2 "2" -pos1 "1" # this work too even you swap them 

The script produces this output.

PS D:\> .\script.ps1
Pos1: 1, Pos2: 2
Pos1: 1, Pos2: 2

ParameterSetName

This will allow a function to have different set of parameters for different task. Example

function Test-ParameterSetName {
    [Cmdletbinding()]
    Param (
        [Parameter(ParameterSetName="one")][String]$Computer,
        [Parameter(ParameterSetName="two")][String]$User
    )
    Switch ($PSCmdlet.ParameterSetName) {
        "one" { Write-Host "Computer: $Computer"; break }
        "two" { Write-Host "User : $User "; break }
    }
}
Test-ParameterSetName -Computer "CodeGeekStuff-137"
Test-ParameterSetName -User "CodeGeekStuff"

The script produces this output.

PS D:\> .\script.ps1
Computer: CodeGeekStuff-137
User : CodeGeekStuff

ValueFromPipeline

This attiribute allows you to pass values via pipeline. Example

function Test-Valuefrompipeline {
    [CmdletBinding()]
    Param (
        [Parameter(Mandatory=$true, ValueFromPipeline=$true)]
        [String] $Name
    )
    Begin {
        Write-Host "This is begin block."
    }
    Process {
        Write-Host "Processing Test-ValueFromPipeline: $_"
    }
    End {
        Write-Host "This is end block."
    }
}
"code", "geek", "stuff" | Test-Valuefrompipeline

The script produces this output.

PS D:\> .\script.ps1
This is begin block.
Processing Test-ValueFromPipeline: code
Processing Test-ValueFromPipeline: geek
Processing Test-ValueFromPipeline: stuff
This is end block.

ValueFromPipelineByPropertyName

Besides you can running (Get-ChildItem).Name command or (Get-Process).Name command and etc, here we can use ValueFromPipelineByPropertyName. Example

function Test-ValueFromPipelineByPropertyName {
    [CmdletBinding()]
    Param (
        [Parameter(
            ValueFromPipeline=$true,
            ValueFromPipelineByPropertyName=$true
         )] [String[]] $Names
    )
    Begin {
        Write-Host "The begin is block"
    }
    Process {
        Write-Host "Processing:Test-ValueFromPipelineByPropertyName: $Names"
    }
    End {
        write-host "The is end block"
    }
}
Get-ChildItem | Select-Object -First 5 | Test-ValueFromPipelineByPropertyName

The script produces this output.

PS C:\Windows\System32> .\script.ps1
The begin is block
Processing:Test-ValueFromPipelineByPropertyName: 0409
Processing:Test-ValueFromPipelineByPropertyName: 1033
Processing:Test-ValueFromPipelineByPropertyName: AdvancedInstallers
Processing:Test-ValueFromPipelineByPropertyName: af-ZA
Processing:Test-ValueFromPipelineByPropertyName: am-ET
The is end block

Notice that I run the script in C:\Windows\System32 directory.

ValueFromRemainingArguments

This makes your parameter to catch all what’s left after all other parameters were bound. The idea is to let PowerShell bind everything then dump unused values to the dummy parameter.

function Test-ValueFromRemainingArguments {
    [CmdletBinding()]
    Param (
        [Parameter(Mandatory = $true)]
        [string]$defined,
 
        [Parameter(ValueFromRemainingArguments = $true)]
        $dummy
    )
    Write-Host "Test-ValueFromRemainingArguments: Defined: $defined"
    Write-Host "Test-ValueFromRemainingArguments: Unused: $dummy"
}
Test-ValueFromRemainingArguments -defined "Defined Value" "dummy1" "dummy2"

The script produces this output

PS D:\> .\script.ps1
Test-ValueFromRemainingArguments: Defined: Defined Value
Test-ValueFromRemainingArguments: Unused: dummy1 dummy2

HelpMessage

Okey the last is HelpMessage, it's a custom prompt message for mandatory parameter. Example

function Test-HelpMessage {
    [Cmdletbinding()]
    Param (
        [Parameter(Mandatory=$true, 
        HelpMessage="Enter one or more computers!")]
        [String[]]$ComputerName
    )
    Write-Host "Test-HelpMessage : $computerName"
}
Test-HelpMessage

The script will produce this.

cmdlet Test-HelpMessage at command pipeline position 1
Supply values for the following parameters:
(Type !? for Help.)
ComputerName[0]: !?
Enter one or more computers!
ComputerName[0]: server01
ComputerName[1]: server02
ComputerName[2]:
Test-HelpMessage : server01 server02