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] を使います。

どの形式を選ぶ場合も、関数の成功ストリームには意図した結果だけを出力するようにします。関数呼び出しの結果を一度受け取り、その形式に応じて配列の反復処理、キーによる検索、またはプロパティへのアクセスを行います。こうすることで関数の契約が明確になり、意図しないメッセージが戻り値と誤解されるのを防げます。