PowerShellの関数に引数を渡す:param・必須入力・型変換の使い分け

PowerShellの関数へ渡す引数を、名前指定、型と範囲の条件、配列とスイッチの三つの観点で整理した独自図解。

PowerShellの関数で、値の渡し方や入力エラーの理由に迷うことがあります。基本は、関数内のparamで値の受取り口を決め、呼出し側で名前を付けて値を渡す方法です。

名前付きの最小例から始め、既定値・型変換・必須入力・複数値の扱いを順に確認します。整数型でも小数を受け取る点など、間違えやすい挙動を出力と対応させ、必要な入力条件を選べるようにします。

対象はWindows PowerShell 5.1です。掲載結果は5.1.26100.9818の検証記録に基づきます。管理者起動やファイル作成は不要です。PowerShell 7系の実行結果は、この資料にはありません。

先に結論

  • まず名前付きで値を渡し、位置指定が必要な場合はPositionで受取り順を明示します。
  • 型変換と入力値の検証は別です。整数型を指定するだけでは、小数入力を拒否できません。
  • 必須入力を省くと、対話可能な画面では入力を求められます。自動実行では呼出し側で値を渡します。

名前付きで渡し、既定値と空文字を比べる

関数側でparamに受取り口を用意し、呼出し側では名前と値を指定します。

関数は、処理を名前で呼び出せるまとまりです。関数側の受取り口をパラメーター、呼出し側から渡す値を引数と呼びます。コードのfunctionは関数の定義、paramは受取り口の一覧を表します。

ドル記号で始まるLabelは、値を入れる変数です。stringは文字列、つまり文字の並びを受け取る型を指定します。型は値の種類です。等号の右側にある「未指定」は、引数を省いたときに使う既定値です。

呼出しでは、ハイフンを付けたLabelの後ろに値を置きます。空白を含む文字列は引用符で囲みます。一重引用符の内側は文字そのものを扱い、二重引用符の内側では変数名が値に置き換わります。

掲載例は現在の画面内に関数や変数を作ります。ファイル・権限・スクリプトの実行可否を決める実行ポリシーは変更しません。練習を終えて元に戻すには、練習用の画面を閉じます。

  1. WindowsのスタートメニューからWindows PowerShellを開きます。練習用に新しい画面を用意し、管理者としては起動しません。
  2. 入力欄へ $PSVersionTable.PSVersion.ToString() と入力してEnterを押し、PowerShellの版を確認します。掲載結果は5.1.26100.9818です。異なる版で同じ結果になることまでは確認していません。
  3. 各コード欄を先頭から末尾まで、1欄ずつ貼り付けます。関数定義の閉じかっこ後にある呼出しや、エラーを扱う部分も含めます。「実行結果」欄は貼り付けません。
  4. 貼り付けたコードをEnterで実行します。複数行入力の続きが表示される場合は、コード欄の末尾で改行してEnterを押します。

名前を指定する場合と省略する場合

function Get-StudyLabel {
    param([string]$Label = '未指定')
    "資料: $Label"
}
Get-StudyLabel -Label '設計 メモ'
Get-StudyLabel
Get-StudyLabel -Label ''

実行結果

資料: 設計 メモ
資料: 未指定
資料: 

結果は、1行目が「資料: 設計 メモ」、2行目が「資料: 未指定」です。3行目は空文字を明示して渡すため、「資料: 」だけになります。引数の省略と、文字を含まない値の指定は別の扱いです。

関数名と引数は空白で区切ります。別言語のように、関数名の直後をかっこで囲む書き方にはしません。途中の入力はCtrl+Cで取り消せます。値として受け取る外部の文字列を、命令として実行しないでください。

名前指定と位置指定で、値の受取り先を確認する

次の例ではPriceが単価、Countが個数です。名前付きなら、個数を先に書いても対応が分かります。intは整数を受け取る型の指定で、ここでは単価240と個数3を掛けます。型変換の注意は次の節で扱います。

Parameterは、受取り口へ条件を付ける属性です。属性は追加の指定を表します。ここではPositionで順番を決め、0を最初、1を次の受取り位置に割り当てています。位置指定では、呼出し時の引数名を省きます。

param内のカンマは、受取り口の宣言を区切ります。一方、呼出し側で単価と個数を別々に渡すときは空白で区切ります。見た目が似ていても、区切り方の役割は異なります。

名前で渡す場合と位置で渡す場合

function Get-StudyCost {
    param(
        [Parameter(Position=0)][int]$Price,
        [Parameter(Position=1)][int]$Count = 1
    )
    $Price * $Count
}
Get-StudyCost -Count 3 -Price 240
Get-StudyCost 240 3

実行結果

720
720

結果はどちらも720です。最初は名前で対応を決め、次は位置で単価240と個数3を受け取っています。Countの既定値は1ですが、掲載した2回の呼出しでは、どちらも個数3を明示しています。

位置指定では値の順番に意味があります。同じ計算結果だけを見て、単価と個数を逆順にしてよいとは判断しません。入力項目が増える場合は、まず名前付きで受取り先を確認すると読み取りやすくなります。

整数型でも、小数は拒否されず丸められる

整数型の指定は、元の入力が整数だったことを保証する条件ではありません。

intは、変換できる値を整数へ変換して受け取ります。数字を含む文字列も対象です。変換できない値は、関数本体の処理に入る前にエラーになります。最初のコード欄では、文字列の「6」と「六」を比べます。

tryは失敗する可能性がある処理を囲み、catchは発生したエラーを受け取る部分です。catch内の日本語は、この例で用意した案内です。PowerShellが出すエラー全文そのものではありません。

次のコード欄では、小数の2.5と3.5を整数型の受取り口へ渡します。文字列を変換できるかという問題と、小数がどう変換されるかという問題を分けて、二つの結果を読み取ります。

整数へ変換できる文字列と変換できない文字列

function Get-StudyDouble {
    param([int]$Count)
    $Count * 2
}
Get-StudyDouble -Count '6'
try {
    Get-StudyDouble -Count '六'
} catch {
    '整数へ変換できないため停止'
}

実行結果

12
整数へ変換できないため停止

整数型の指定だけでは小数入力を拒否しない

function Get-StudyInteger {
    param([int]$Count)
    $Count
}
Get-StudyInteger -Count 2.5
Get-StudyInteger -Count 3.5

実行結果

2
4

文字列の例では、「6」が整数6へ変換され、その後に2倍する処理で12になります。「六」は整数へ変換できず、「整数へ変換できないため停止」という案内が出ます。

小数の例では、2.5が2、3.5が4になります。整数への変換では近い整数へ丸め、ちょうど中間なら近い偶数を選びます。整数型だから小数がエラーになる、という動きではありません。

元の入力から小数を拒否したい場合は、変換前の値を確認する設計が必要です。掲載例には小数を拒否する処理を含めていないため、入力を制限する用途へそのまま流用しないでください。

ValidateRangeで受け取る値の範囲を絞る

型の指定と、値が範囲内かを確かめる検証は別の条件です。

ValidateRangeは、受取り口へ入力範囲の条件を付ける属性です。この例では部数を1から3までに制限し、両端の1と3を含みます。既定値には範囲内の1を設定しています。

呼出しは、省略、3の指定、0の指定の順です。最後の呼出しをtryとcatchで囲んでいるため、範囲外のエラーは用意した案内で読み取れます。条件を満たさない値は、関数本体へ進みません。

範囲を満たす値だけ本体で受け取る

function Get-StudyCopies {
    param([ValidateRange(1,3)][int]$Count = 1)
    "部数: $Count"
}
Get-StudyCopies
Get-StudyCopies -Count 3
try {
    Get-StudyCopies -Count 0
} catch {
    '範囲外のため停止'
}

実行結果

部数: 1
部数: 3
範囲外のため停止

結果は「部数: 1」「部数: 3」「範囲外のため停止」の順です。0を渡した呼出しでは、関数本体の部数表示は出ていません。これが、範囲外の入力を受け付けなかったことの確認点です。

既定値そのものは入力検証の対象ではないため、定義側で条件内の値を選びます。また、範囲指定は元の入力に小数が含まれないことまで保証しません。小数の拒否と範囲の制限を混同しないようにします。

必須入力を省いたときは、実行環境で挙動が変わる

自動実行では、画面での追加入力に頼らず、呼出し側で必須の値を渡します。

Mandatoryは、入力を必須にする属性の指定です。コード中のtrueは真を表し、ここでは必須の条件を有効にします。文字列を受け取るLabelを用意し、呼出し側で「設計」を渡しています。

この例のLabelは省略できません。省略した場合の動きは、その場で入力できる画面か、入力を受け付けない実行方法かで異なります。まず掲載コードで、必要な値を指定した呼出しを確認します。

必須の名前を指定して呼び出す

function Get-StudyRequired {
    param([Parameter(Mandatory=$true)][string]$Label)
    "受付: $Label"
}
Get-StudyRequired -Label '設計'

実行結果

受付: 設計

結果が「受付: 設計」なら、必須の値を渡せています。掲載コードは値を指定した正常な呼出しなので、省略時のエラーや入力要求を示す結果ではありません。

公式資料では、対話可能な画面で必須値を省くと入力を求められます。取り消す場合はCtrl+Cです。この入力要求の画面自体は、今回の検証記録では未確認です。

入力を受け付けない別起動のPowerShellによる検証記録では、必須値がないことを示すMissingMandatoryParameterという識別名のエラーで終了しています。自動実行では、呼出し側の指定漏れを確認します。

switchは指定の有無だけでなく値で判断する

スイッチ名を書いていても、偽を明示すれば無効になります。

switchは、機能の有効・無効を受け取る型です。この例のDetailedは、省略すると偽、指定すると真になります。真は有効、偽は無効に対応し、ifは真の場合、elseは偽の場合の処理を選びます。

3回目の呼出しでは、falseという偽を表す値を明示しています。スイッチが書かれているかだけで判断せず、受け取った値が真か偽かで表示を分ける点に注目します。

スイッチの省略・指定・明示的な無効化

function Get-StudyMode {
    param([switch]$Detailed)
    if ($Detailed) { '詳細表示' } else { '通常表示' }
}
Get-StudyMode
Get-StudyMode -Detailed
Get-StudyMode -Detailed:$false

実行結果

通常表示
詳細表示
通常表示

結果は「通常表示」「詳細表示」「通常表示」の順です。3回目もDetailedという名前は書かれていますが、値が偽なので通常表示になります。

無効を明示する呼出しでは、Detailedの直後をコロンでつなぎ、その後ろに偽の値を置いています。空白で偽の値を続ける書き方とは区別して、掲載コードの指定を確認してください。

配列で複数の値を一つの受取り口へ渡す

配列は、複数の値をひとまとめにしたものです。stringの後ろに付いた角かっこは、文字列の配列を受け取る指定を表します。次の例では二つの資料名をカンマで区切り、Labels一つへ渡します。

Labelsに続くCountは、配列に含まれる値の件数です。joinは、値を指定した区切り文字でつなぐための指定です。この例では、資料名の間を空白付きのスラッシュでつないで表示します。

配列を一つの引数へ渡す

function Get-StudyItems {
    param([string[]]$Labels)
    '件数: ' + $Labels.Count
    $Labels -join ' / '
}
Get-StudyItems -Labels '設計','試験'

実行結果

件数: 2
設計 / 試験

結果が「件数: 2」と「設計 / 試験」なら、二つの値が一つの受取り口へ届いています。最初の行は件数、次の行は配列の内容なので、両方を対応させて読み取れます。

ここでのカンマは配列を作ります。単価と個数を別々に渡した位置指定の空白とは役割が異なります。この説明はPowerShellの関数へ直接渡す場合であり、外部プログラムへの引数の扱いとは分けて考えます。

名前か番号の片方だけをパラメーターセットで選ぶ

名前と番号を別のセットに分け、両方の同時指定を受け付けない構成です。

パラメーターセットは、一度に選べる受取り口の組合せです。次の例には、Labelを受け取る名前用のByLabelと、Numberを受け取る番号用のByNumberがあります。呼出しでは片方を選びます。

CmdletBindingは、引数を細かく制御する高度な関数として扱う宣言です。ParameterSetNameは各受取り口の所属、DefaultParameterSetNameは入力だけではセットを決められない場合の既定を指定します。

関数内のPSCmdletは実行情報を参照する変数で、そのParameterSetNameが今回選ばれたセット名です。eqは値が等しいかを比べる指定で、ここでは名前用か番号用かによって出力を分けます。

名前指定と番号指定を使い分ける

function Get-StudyEntry {
    [CmdletBinding(DefaultParameterSetName='ByLabel')]
    param(
        [Parameter(Mandatory=$true,ParameterSetName='ByLabel')]
        [string]$Label,
        [Parameter(Mandatory=$true,ParameterSetName='ByNumber')]
        [int]$Number
    )
    if ($PSCmdlet.ParameterSetName -eq 'ByLabel') {
        "名前: $Label"
    } else {
        "番号: $Number"
    }
}
Get-StudyEntry -Label '設計'
Get-StudyEntry -Number 27
try {
    Get-StudyEntry -Label '設計' -Number 27
} catch {
    '二つの方式を同時には使えない'
}

実行結果

名前: 設計
番号: 27
二つの方式を同時には使えない

最初の2行は「名前: 設計」「番号: 27」です。両方を指定した最後の呼出しでは、「二つの方式を同時には使えない」というcatchの案内が出ます。一度に使えるセットは一つです。

既定のByLabelでもLabelは必須なので、既定セットの指定は「何も渡さず呼び出せる」という意味ではありません。また、この例は値を表示するだけで、実際のユーザー検索や設定変更は行いません。

スプラッティングで引数の名前と値をまとめる

スプラッティングは、複数の引数をまとめて渡す方法です。ハッシュテーブルは、名前と値を組にして保存する仕組みです。次の例では、アットマークと波かっこで囲んだ部分に3項目を用意します。

保存先はsettingsという変数で、Label、Count、Detailedの名前に対応する値を入れます。呼出しでは変数名の前をドル記号からアットマークに替え、名前ごとの引数へ展開します。Detailedには真を指定します。

名前と値をまとめて渡す

function Get-StudySummary {
    param([string]$Label,[int]$Count,[switch]$Detailed)
    "資料: $Label / 部数: $Count / 詳細: $Detailed"
}
$settings = @{
    Label = '設計'
    Count = 3
    Detailed = $true
}
Get-StudySummary @settings

実行結果

資料: 設計 / 部数: 3 / 詳細: True

「資料: 設計 / 部数: 3 / 詳細: True」なら、3項目が渡っています。最後のTrueは、有効を示す真の値の表示です。変数をそのまま一つの値として渡す方法とは区別します。

掲載例では、まとめた引数と同じ引数を呼出し側で重ねて指定していません。PowerShell 7.1以降の重複指定による上書きの扱いを、5.1でも利用できるとは考えないでください。

引数エラーは定義・名前・値・組合せの順に調べる

引数が届かないときは、関数側の受取り口と呼出し側の指定を順に照合します。表の掲載例名は各コード欄の見出しに対応しているため、目的や症状から該当する例へ戻れます。

最後のコード欄は、CmdletBindingを付けた関数に対して引数名を誤記する例です。定義したLabelに対し、呼出し側はLabalとなっています。この例では本体へ進む前にエラーになり、catchの案内が出ます。

  1. 関数が見つからない場合は、同じ画面で関数定義を実行したか確認します。別の画面では、掲載例の関数は未定義です。
  2. 引数名の綴りと、文字列を囲む引用符を確認します。受取り口の名前と呼出し側の名前を対応させます。
  3. 型へ変換できる値か、必須値を省いていないか、範囲内かを確認します。型変換と入力検証を分けて調べます。
  4. 名前と番号など、別セットに属する入力を同時に渡していないか確認します。
目的・症状 使う指定・掲載例 結果の見方
省略時の値を用意 名前を指定する場合と省略する場合 未指定と空文字を区別
名前を省いて渡す 名前で渡す場合と位置で渡す場合 両方が720
整数として受ける 整数へ変換できる文字列と変換できない文字列 6は12、六は変換エラー
小数を渡す 整数型の指定だけでは小数入力を拒否しない 2.5は2、3.5は4
範囲を制限 範囲を満たす値だけ本体で受け取る 0は本体へ進まない
必須入力を求める 必須の名前を指定して呼び出す 対話の入力要求と自動実行の失敗を区別
表示を切り替える スイッチの省略・指定・明示的な無効化 通常・詳細・通常
複数値を一つへ渡す 配列を一つの引数へ渡す 2件を一つのLabelsで受ける
名前か番号で選ぶ 名前指定と番号指定を使い分ける 両方同時には指定しない
入力項目をまとめる 名前と値をまとめて渡す @settingsで3項目を展開

宣言していない引数名をエラーとして見つける

function Get-StudyChecked {
    [CmdletBinding()]
    param([string]$Label)
    "資料: $Label"
}
try {
    Get-StudyChecked -Labal '設計'
} catch {
    '宣言していない引数名のため停止'
}

実行結果

宣言していない引数名のため停止

「宣言していない引数名のため停止」と出れば、この例では誤記をエラーとして見つけられています。案内はcatch内で用意した文です。エラーを無視して続ける前に、呼出し側の綴りを定義と照合します。

照合資料はPowerShell 7.6向けですが、掲載結果は冒頭の5.1環境の記録です。別のコマンドの出力を次の入力へ渡すパイプラインや、外部プログラムへの引数は、今回の実行確認に含めていません。