HOWTO · PowerShell
PowerShell 関数から複数のアイテムを返す方法
このチュートリアルでは、PowerShell 関数から複数の値を返す方法を教えます。
このページの内容
PowerShell 関数は、成功ストリームを通じて複数の値を出力できます。関連する値には配列、キーで検索する値にはハッシュテーブル、名前付きプロパティを持つレコードには [PSCustomObject] を使います。呼び出し元では、関数呼び出しを変数に代入して出力を受け取ります。
return キーワードは現在の関数スコープを終了し、値を出力できますが、出力するために必須ではありません。また、複数の式を1つの結果にまとめるものでもありません。関数が終了する前に成功ストリームへ出力された値は、すべて関数の出力に含まれます。呼び出し元が明確なコレクションやレコードを受け取れるよう、以下のいずれかの形式を使いましょう。
PowerShell 関数が出力を返す仕組み
PowerShell 関数は、成功ストリームの出力を呼び出し元に送ります。Write-Output のようなコマンドは値を出力し、関数内に置かれた式も同じストリームに書き込みます。呼び出し元では、たとえば $result = Get-Data のように代入して出力を受け取れます。
return $value は $value を出力して関数を終了します。特定の位置で処理を終えたいときに便利ですが、複数の値をまとめる特別なコンテナーではありません。呼び出し元がデータオブジェクトだけを想定している場合は、ステータス文字列などの意図しない成功ストリーム出力を避けてください。その出力も関数の結果に含まれます。
複数の値を配列として返す
呼び出し元がまとめて処理する順序付きの値の並びには、配列を使います。PowerShell は配列の要素を成功ストリームに出力します。関数が後で1つの要素だけを返す場合でも変数を配列のまま保持したいときは、関数呼び出しを @(...) で囲んで受け取ります。
次の例を実行します。
このセクションのコードと表示されるラベルや出力は英語のままです。
function Get-Colors {
return @('red', 'green', 'blue')
}
$colors = @(Get-Colors)
foreach ($color in $colors) {
Write-Output $color
}
呼び出し元は3つの文字列を受け取り、それらをループ処理したり、別のコマンドに渡したりできます。配列では値の順序が保たれますが、各値に説明的な名前は付きません。呼び出し元が値の役割を識別する必要がある場合は、キーまたはプロパティで参照できる形式を使います。
名前付きの値をハッシュテーブルで返す
ハッシュテーブルは、値を一意のキーに関連付けてまとめます。呼び出し元が既知のキーを使って値を取得する場合、特に位置に依存する並びよりキーの集合のほうが便利な場合に適しています。
このセクションのコードと表示されるラベルや出力は英語のままです。
function Get-UserRecord {
return @{
Name = 'Rohan'
Age = 21
Address = 'UK'
}
}
$user = Get-UserRecord
Write-Output "$($user['Name']) is $($user['Age']) and lives in $($user['Address'])."
呼び出し元は $user['Name'] でエントリを取得できます。また、PowerShell では $user.Name のようなプロパティ形式のアクセスも可能です。キーに空白が含まれる場合や、メンバー名と紛らわしい場合は、角かっこ表記を使うとよいでしょう。ハッシュテーブルはキーによる検索に便利ですが、キーは宣言済みのレコードスキーマではありません。
[PSCustomObject] で構造化オブジェクトを返す
名前付きプロパティを持つ1件のレコードには、[PSCustomObject] を使います。呼び出し元は1つのオブジェクトを受け取り、各フィールドに直接アクセスできます。プロパティ名から、それぞれの値の意味も分かります。
このセクションのコードと表示されるラベルや出力は英語のままです。
function Get-UserRecord {
return [PSCustomObject]@{
Name = 'Rohan'
Age = 21
Address = 'UK'
}
}
$user = Get-UserRecord
Write-Output "Name: $($user.Name)"
Write-Output "Age: $($user.Age)"
Write-Output "Address: $($user.Address)"
フィールドには $user.Name のようにアクセスできます。また、Format-List などのコマンドで内容を確認できます。$user を反復処理しても、そのプロパティが列挙されるわけではありません。レコードがオブジェクトとして扱われます。フィールド自体を処理するには、たとえば $user.PSObject.Properties のように、プロパティへ明示的にアクセスします。
用途に合った戻り値の形式を選ぶ
呼び出し元が反復処理、並べ替え、またはパイプラインへの受け渡しを行う順序付きリストには、配列を使います。キーによる検索が必要で、キーと値の組を軽量にまとめれば十分な場合は、ハッシュテーブルを選びます。出力が、呼び出し元が参照または表示する名前付きフィールドを持つ1件のレコードなら、[PSCustomObject] を使います。
どの形式を選ぶ場合も、関数の成功ストリームには意図した結果だけを出力するようにします。関数呼び出しの結果を一度受け取り、その形式に応じて配列の反復処理、キーによる検索、またはプロパティへのアクセスを行います。こうすることで関数の契約が明確になり、意図しないメッセージが戻り値と誤解されるのを防げます。