PowerShellの関数で、値の渡し方や入力エラーの理由に迷うことがあります。基本は、関数内のparamで値の受取り口を決め、呼出し側で名前を付けて値を渡す方法です。
名前付きの最小例から始め、既定値・型変換・必須入力・複数値の扱いを順に確認します。整数型でも小数を受け取る点など、間違えやすい挙動を出力と対応させ、必要な入力条件を選べるようにします。
対象はWindows PowerShell 5.1です。掲載結果は5.1.26100.9818の検証記録に基づきます。管理者起動やファイル作成は不要です。PowerShell 7系の実行結果は、この資料にはありません。
先に結論
- まず名前付きで値を渡し、位置指定が必要な場合はPositionで受取り順を明示します。
- 型変換と入力値の検証は別です。整数型を指定するだけでは、小数入力を拒否できません。
- 必須入力を省くと、対話可能な画面では入力を求められます。自動実行では呼出し側で値を渡します。
名前付きで渡し、既定値と空文字を比べる
関数側でparamに受取り口を用意し、呼出し側では名前と値を指定します。
関数は、処理を名前で呼び出せるまとまりです。関数側の受取り口をパラメーター、呼出し側から渡す値を引数と呼びます。コードのfunctionは関数の定義、paramは受取り口の一覧を表します。
ドル記号で始まるLabelは、値を入れる変数です。stringは文字列、つまり文字の並びを受け取る型を指定します。型は値の種類です。等号の右側にある「未指定」は、引数を省いたときに使う既定値です。
呼出しでは、ハイフンを付けたLabelの後ろに値を置きます。空白を含む文字列は引用符で囲みます。一重引用符の内側は文字そのものを扱い、二重引用符の内側では変数名が値に置き換わります。
掲載例は現在の画面内に関数や変数を作ります。ファイル・権限・スクリプトの実行可否を決める実行ポリシーは変更しません。練習を終えて元に戻すには、練習用の画面を閉じます。
- WindowsのスタートメニューからWindows PowerShellを開きます。練習用に新しい画面を用意し、管理者としては起動しません。
- 入力欄へ $PSVersionTable.PSVersion.ToString() と入力してEnterを押し、PowerShellの版を確認します。掲載結果は5.1.26100.9818です。異なる版で同じ結果になることまでは確認していません。
- 各コード欄を先頭から末尾まで、1欄ずつ貼り付けます。関数定義の閉じかっこ後にある呼出しや、エラーを扱う部分も含めます。「実行結果」欄は貼り付けません。
- 貼り付けたコードを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の案内が出ます。
- 関数が見つからない場合は、同じ画面で関数定義を実行したか確認します。別の画面では、掲載例の関数は未定義です。
- 引数名の綴りと、文字列を囲む引用符を確認します。受取り口の名前と呼出し側の名前を対応させます。
- 型へ変換できる値か、必須値を省いていないか、範囲内かを確認します。型変換と入力検証を分けて調べます。
- 名前と番号など、別セットに属する入力を同時に渡していないか確認します。
| 目的・症状 | 使う指定・掲載例 | 結果の見方 |
|---|---|---|
| 省略時の値を用意 | 名前を指定する場合と省略する場合 | 未指定と空文字を区別 |
| 名前を省いて渡す | 名前で渡す場合と位置で渡す場合 | 両方が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環境の記録です。別のコマンドの出力を次の入力へ渡すパイプラインや、外部プログラムへの引数は、今回の実行確認に含めていません。
