Windows PowerShellのFunction入門 (Paramキィワード、Parameter属性編)

Windows PowerShell

この記事はWindows PowerShellのFunctionのParamキィワードの基本的な説明とParameter属性の話です

値の指定 (AllowNullとか) などは出てきませんので予めご了承ください

PowerShellに名前付きで引数を設定するには、関数名の後ろに "()" で記述する方法と、関数内にParamキィワードで記述する方法の2種類ががあります

いずれの場合も宣言した変数名の$を-に変えたものがパラメータ名になります

Function SampleFunction1 ($InputString) {
    Write-Host $InputString;
}

Function SampleFunction2 {
    Param(
        $InputString
    )
    Write-Host $InputString;
}

PS> SampleFunction1 -InputString "Hello";
Hello
PS> SampleFunction2 -InputString "World";
World
````

上記のどちらの書き方でも結果は同じ為、本記事では以下<code>param</code>キィワードを使う書き方で説明します

---

パラメータは変数宣言と同じように型名を付けて宣言することが出来ます

また、複数の引数を設定する場合、',' 区切りで記述します

Function SampleFunction3 { Param( [String] $InputString1, [String] $InputString2 ) Write-Host (($InputString1, $InputString2) -join ' '); }

PS> SampleFunction3 -InputString1 "Hello" -InputString2 "World"; Hello World ````

パラメータ用の特殊な型としてSwitchがあります

Switchはパラメータとして記述されると$True、なければ$falseになります

Function SampleFunction4 {
    Param(
        [Switch] $Switch1,
        [Switch] $Switch2
    )
    Write-Host (('Switch1 is', $Switch1) -join ' ');
    Write-Host (('Switch2 is', $Switch2) -join ' ');
}

PS> SampleFunction4 -Switch1;
Switch1 is True
Switch2 is False

パラメータにデフォルト値を付けたい場合、$変数名 = デフォルト値の形で記述します

Function SampleFunction5 {
    Param(
        [String] $String = 'Hello World'
    )
    Write-Host ($String);
}

PS> SampleFunction5;
Hello World

各引数には個別にParameter属性を記述することで、必須属性かどうか、パイプラインから値を受け取るかなどの設定を行う事ができます

主なParameter属性のオプションは以下の通りです

HelpMessage
パラメーターの簡単な説明文を String 型で指定。必須パラメーターの入力がない場合に使用されますが、使用方法は実装依存
Mandatory
必須かどうかを Boolean 値で指定
ParameterSetName
パラメーターのセット名を設定します。非常に長くなる為、本記事では割愛します
Position
パラメータ名がない引数の位置 (昇順) をInt型で指定。なお、関数内のすべてのパラメータがPositionを持たない場合、記述順で解釈される
ValueFromPipeline
パイプラインオブジェクトからの入力を受け入れるかどうかを Boolean 型で指定
ValueFromPipelineByPropertyName
同じ名前または同じエイリアスを持つパイプラインオブジェクトのプロパティから、その値を取得するかどうかを Boolean型で指定。ValueFromPipelineByPropertyNameが$trueの場合、ValueFromPipelineを併せて書く必要はない
ValueFromRemainingArguments
バインドされていない (パラメーター名つきなく、位置からも特定できない) 残りの引数を受け入れるかどうかを Boolean型で指定。記述がない場合は $false

以下サンプルコードです

# HelpMessage と Mandatory
Function SampleFunction6{
    Param(
        [Parameter(Mandatory=$true,HelpMessage='年齢を入力してください')]
        [String] $Age;
    )
}

PS> SampleFunction6
コマンド パイプライン位置 1 のコマンドレット SampleFunction6
次のパラメーターに値を指定してください:
(ヘルプを表示するには、「!?」と入力してください。)
Age: !?
年齢を入力してください
Age: 
# Position
Function SampleFunction7{
    Param(
        [Parameter(Position=3)]
        [Int] $C,
        [Parameter(Position=1)]
        [Int] $A,
        [Parameter(Position=2)]
        [Int] $B
    )
    Write-Host '$A is ' $A;
    Write-Host '$B is ' $B;
    Write-Host '$C is ' $C;
}

PS> SampleFunction7 1 2 3
$A is  1
$B is  2
$C is  3
# ValueFromPipeline
Function SampleFunction8{
    Param(
        [Parameter(ValueFromPipeline=$true)]
        [DateTime] $DateTime,
        [int] $AddDays = 0
    )
    $DateTime.AddDays($AddDays);
}

PS> Get-Date;
2017年12月27日 21:00:00
PS> Get-Date | SampleFunction8 -AddDate 3;
2017年12月30日 21:00:00
# ValueFromPipelineByPropertyName
Function SampleFunction9{
    Param(
        [Parameter(ValueFromPipelineByPropertyName=$true)]
        [Int] $Year,
        [Parameter(ValueFromPipelineByPropertyName=$true)]
        [Int] $Month,
        [Parameter(ValueFromPipelineByPropertyName=$true)]
        [Int] $Day
    )
    $Year;
    $Month;
    $Day;
}

Get-Date | SampleFunction9;
# ValueFromRemainingArguments
Function SampleFunction10{
    param (
        [int] $p1,
        [parameter(Position = 2)]
        [int] $p2,
        [parameter(ValueFromRemainingArguments=$true)]
        [Int[]] $others
    )
    $others;
}

PS> SampleFunction10 -p1 1 2 3 4 5
3
4
5

こんな感じで一つ