PowerShellの関数で戻り値が増える原因とスコープの調べ方

関数の結果を受け取る、returnで処理を終了する、スコープの範囲を確認するという3つの観点を並べた独自図解

PowerShellの関数で、5だけを返すつもりなのに結果が2件になったり、関数内で変えた変数が外側に反映されなかったりすると、修正箇所に迷います。まず、関数から出る値と、変数を参照・変更できる範囲を分けて確認します。

通常の関数では、returnより前に出た値も結果へ残ります。また、変数への代入と共有データの中身の変更では、影響する範囲が異なります。Windows PowerShell 5.1を用意し、10の短い例で余分な出力の原因と変更範囲を順に確認できます。

先に結論

  • returnは関数を終了しますが、それより前の成功出力を取り消しません。
  • 呼出し側で結果を@(…)に入れると、0件・1件・複数件を配列として受け取り、Countで件数を確認できます。
  • 通常関数での同名変数への代入と、共有データの中身の更新では、外側へ残る変更が異なります。

Windows PowerShell 5.1の新しい画面で準備する

各例は通常権限の新しい画面で、コード欄の末尾まで実行します。

関数は、複数の処理に名前を付け、その名前で実行できるようにしたものです。変数は値を保存する名前で、PowerShellでは先頭に$を付けます。画面へ変数名だけを入力してEnterを押すと、その値を表示できます。

根拠となる実行記録は、Windows PowerShell 5.1.26100.9818の新しいプロセスでの10例です。仕様の照合にはMicrosoftのPowerShell 7.6向け資料なども含みますが、7系で実行した記録ではありません。

  1. WinキーとRキーで「ファイル名を指定して実行」を開きます。powershell.exeの後に半角空白と-NoProfileを付けて入力し、Enterを押します。-NoProfileは個人設定を読み込まない指定です。管理者権限は不要です。
  2. 開いた画面で、バージョン情報を持つ変数$PSVersionTableを表示し、PSVersionの行が5.1で始まることを確認します。末尾の版番号はWindows更新などで異なります。
  3. 各例は新しい画面へ、コード欄の最初から末尾まで貼り付けて実行します。閉じ波括弧の後にある呼出しや表示の行も含め、Enterで確定します。実行結果の欄は入力しません。
  4. 入力途中の状態が続く場合は、閉じ括弧や引用符が欠けていないか確認します。やり直す場合は画面を閉じ、新しい画面へコード欄全体を入力します。

各例が扱うのは計算と画面内の学習用データです。練習をやり直すときは画面を閉じ、新しく開けば、そこで作った関数や変数を残さずに始められます。ファイル、実行ポリシー、管理者設定を変更する操作は含みません。

関数を定義して25を受け取る

functionの後に関数名を書き、波括弧で処理を囲みます。次の例ではGet-StudyTotalが関数名です。定義だけでは計算結果は表示されず、その後に関数名を指定した行で処理が実行されます。

$resultは結果を受け取る変数です。=は右側の値を左側の変数へ入れ、+はここでは18と7を足します。最後の$resultが受け取った値を表示します。通常関数では、returnを書かなくても式の結果を呼出し元へ渡せます。

定義してから関数名を入力し、25を受け取る

function Get-StudyTotal {
    18 + 7
}
$result = Get-StudyTotal
$result

実行結果

25

25が表示されれば、定義、呼出し、結果の受取りまで進めています。「認識されません」というエラーが出た場合は、同じ画面で関数の定義から実行したか、定義した名前と呼出し側の綴りが一致するか確認してください。

returnを書いたのに2件返る理由を確かめる

returnは関数を終えますが、それまでに出た値を取り消しません。

通常の関数では、式やコマンドが出した値も呼出し元へ渡ります。この結果を受け取る経路を成功出力と呼びます。returnに値を付けると、その値を成功出力へ出して関数を終えますが、すでに出た値は残ります。

次の例の@(…)は、中から出た値を配列としてまとめて受け取る書き方です。配列は複数の値を順番にまとめたもので、.Countは件数を調べる指定です。文字列から始まる表示行の+は、案内文と件数をつないでいます。

最初の例は、1を出した後にreturnで5を出します。次の例は、「開始」を出した後に値を付けないreturnで終了します。値を付けない場合も、それ以前の出力が残るかを比べてください。

returnより前の1とreturnの5が両方残る

function Get-StudyMixed {
    1
    return 5
    2
}
$result = @(Get-StudyMixed)
'件数: ' + $result.Count
$result

実行結果

件数: 2
1
5

値を付けないreturnも、それ以前の出力は取り消さない

function Get-StudyStop {
    '開始'
    return
    '終了後'
}
$result = @(Get-StudyStop)
'件数: ' + $result.Count
$result

実行結果

件数: 1
開始

数値の例は「件数: 2」に続いて1と5が表示されます。returnより後の2は実行されません。5だけを返したつもりでも、その前の1が成功出力へ出ているため、結果は2件になります。

文字列の例は「件数: 1」と「開始」だけが表示されます。値を付けないreturn自体は新しい値を加えず、「終了後」の行にも進みません。出力した値と、処理が止まる位置を分けて確認できます。

案内は表示し、計算結果には含めない

画面に見える案内と、変数で受け取る成功出力は分けられます。

関数内へ文字列を単独で書いたり、Write-Outputで文章を出したりすると、その文章も成功出力へ流れます。画面向けの案内として追加した文章が、数値と一緒に結果変数へ入る原因になります。

情報ストリームは、案内などを送る別の出力経路です。Write-Informationはこの経路へ情報を送り、-InformationAction Continueは案内を表示して処理を続ける指定です。PowerShell 5.0以降で利用できます。

案内メッセージと計算結果を別の経路へ分ける

function Get-StudyNotice {
    Write-Information '計算の案内' -InformationAction Continue
    return (18 + 7)
}
$result = @(Get-StudyNotice)
'結果の件数: ' + $result.Count
$result

実行結果

計算の案内
結果の件数: 1
25

画面には「計算の案内」も表示されますが、結果の件数は1で、中身は25です。画面に表示されたすべての行が、結果変数へ入るわけではありません。

出力経路を結合する指定を加えた場合は、案内も成功出力へ混ざることがあります。この例は経路を結合せず、案内の表示と計算結果の受取りを分けた条件です。

結果に0が混ざるときはAddの戻り値を調べる

ArrayListのAddが返す0は、追加した位置を示す番号です。

メソッドは、データに対して実行できる名前付きの操作です。次の例では、New-Objectで要素を追加できる入れ物のArrayListを作り、Addで「資料」を加えます。New-Objectは指定した種類のデータを作るコマンドです。

ArrayListのAddは、追加した位置の番号も返します。先頭の位置は0なので、その戻り値を受け取らずに呼ぶと、0も関数の成功出力へ流れます。最初の例と、不要な位置番号だけを捨てる次の例を比較します。

Addの戻り値0も結果に混ざる

function Get-StudyBuffer {
    $buffer = New-Object System.Collections.ArrayList
    $buffer.Add('資料')
    return $buffer
}
$result = @(Get-StudyBuffer)
'件数: ' + $result.Count
$result

実行結果

件数: 2
0
資料

追加位置の数値だけを捨て、資料を残す

function Get-StudyBuffer {
    $buffer = New-Object System.Collections.ArrayList
    $null = $buffer.Add('資料')
    return $buffer
}
$result = @(Get-StudyBuffer)
'件数: ' + $result.Count
$result

実行結果

件数: 1
資料

最初の例は「件数: 2」と表示され、0と「資料」が残ります。この0は失敗を示す終了コードではありません。次の例は位置番号を$nullへ代入して捨てるため、「資料」の1件になります。$nullは値がないことを表す特別な値です。

位置番号を捨てても、「資料」を追加する処理は行われます。別のメソッドを利用する場合は、その仕様で戻り値の有無と意味を確認してください。必要な結果まで捨てないよう、抑える行を限定します。

0件でも1件でも同じ形で件数を調べる

呼出し側で@(…)を使うと、出力件数が変わっても配列として受け取れます。

出力が1件だけの場合、単純な代入ではその1個のデータを受け取ります。今回の文字列1件の種類はSystem.Stringです。受取側を@(…)で囲むと、0件・1件・複数件を配列の形にそろえて件数を調べられます。

次の例は、0件、1件、2件の関数を定義し、それぞれのCountを表示します。末尾ではデータの種類も比較します。GetTypeは種類を調べるメソッド、FullNameはその正式名を読む指定です。System.Object[]は、さまざまな種類の値を入れられる配列を表します。

通常、関数から配列を出すと、その要素が順に出力されます。直前のArrayListの例でも、返した入れ物の中身である「資料」が結果へ出ています。受取側で配列にまとめる操作と、関数から何が出るかを分けて見てください。

成功出力の件数 配列として受けたCount 囲まず受けた今回の1件の型
0件 0 該当なし
1件 1 System.String
2件 2 該当なし

出力0件・1件・2件を同じ配列の形で受け取る

function Get-StudyEmpty { return }
function Get-StudyOne { '資料A' }
function Get-StudyPair { '資料A'; '資料B' }
$empty = @(Get-StudyEmpty)
$one = @(Get-StudyOne)
$pair = @(Get-StudyPair)
'0件のCount: ' + $empty.Count
'1件のCount: ' + $one.Count
'2件のCount: ' + $pair.Count
$single = Get-StudyOne
'囲まない1件の型: ' + $single.GetType().FullName
'囲んだ1件の型: ' + $one.GetType().FullName

実行結果

0件のCount: 0
1件のCount: 1
2件のCount: 2
囲まない1件の型: System.String
囲んだ1件の型: System.Object[]

Countは順に0、1、2になります。1件を囲まずに受けた種類はSystem.String、囲んで受けた種類はSystem.Object[]です。コード欄末尾の種類を表示する行まで実行して比較します。

0件の配列と$nullは別のデータです。また、ここでの目的は受取側の形と件数をそろえることです。配列そのものを分割せず、1個の値として返す設計とは区別してください。

外側の変数が変わらないときは代入先を見る

親の変数を参照できても、通常の代入は関数内の変数に作用します。

スコープは、変数や関数の名前を参照・変更できる範囲です。通常の関数を呼ぶと、その呼出し用の子スコープが作られます。呼出し元は親スコープに当たり、関数内からは、特別に隠されていない親の変数を参照できます。

次の例では、親の$studyLabelを関数内から読み、その後に同名の変数へ別の文字列を代入します。範囲を指定しない通常の代入は子スコープへ作用するため、親の変数そのものは書き換わりません。

外側を参照できても、関数内の代入は外側の変数を書き換えない

$studyLabel = '外側'
function Show-StudyScope {
    '関数内の参照: ' + $studyLabel
    $studyLabel = '内側'
    '関数内の代入後: ' + $studyLabel
}
Show-StudyScope
'呼出後の外側: ' + $studyLabel

実行結果

関数内の参照: 外側
関数内の代入後: 内側
呼出後の外側: 外側

表示される値は順に「外側」「内側」「外側」です。最初は親の値を参照でき、代入後は関数内の値が変わりますが、呼出し後の親の値は残っています。

親の変数が見えることと、親の変数を書き換えることは別です。モジュール内の関数には独自の状態があるため、この例は画面で定義する通常関数の説明として読んでください。

未定義の変数は常にエラーになるわけではない

今回の新しい画面では、関数内だけの変数を外側から参照すると$nullになります。

次の例は、関数内でだけ$studyOnlyInsideを作成します。関数の実行中はその値を出力できますが、呼出しが終わっても外側に同じ変数は作られません。例ごとに新しい画面を開き、同名変数が残っていない条件で進めます。

StrictModeは、未定義変数の参照などを厳しく検査する設定です。今回の新しい画面では無効で、外側の未定義変数の参照は$nullになります。-eqは左右が等しいかを調べる記号で、Trueは比較が成り立つことを示します。

新しい画面で、関数内だけの変数を外から調べる

function Get-StudyLocal {
    $studyOnlyInside = '内側だけ'
    $studyOnlyInside
}
Get-StudyLocal
'外側ではnull: ' + ($null -eq $studyOnlyInside)

実行結果

内側だけ
外側ではnull: True

「内側だけ」の後に「外側ではnull: True」と表示されます。今回の条件では、関数内の値を出力できても、外側にはその変数が作られていないことを確認できます。

StrictModeが有効な環境では、未定義参照がエラーになる場合があります。外側に同名変数があれば、その値を読む点にも注意してください。業務環境の検査設定を無効にして、エラーを回避するための手順ではありません。

外側のデータが変わるときは中身の更新を見る

同じハッシュテーブルの中身を変えると、呼出し元にも変更が残ります。

ハッシュテーブルは、名前と値を組にして保存する入れ物です。次の例では、Stateという項目名に「未着手」を対応させます。角括弧の中で項目名を指定し、その値を読み書きします。

関数内の$studyBoxは、親と同じ入れ物を参照しています。そのため、Stateの値を書き換えると外側にも変更が見えます。変数へ別の値を代入する操作と、同じ入れ物の中身を更新する操作の違いを、コードと比較表で確認してください。

操作 関数内の結果 呼出し後の外側
親の文字列を参照後、同名変数へ代入 外側 → 内側 外側のまま
関数内だけで変数を作成 内側だけ 今回の新規画面ではnull
親のハッシュテーブル内のStateを更新 出力なし 完了へ変わる

共有オブジェクトの中身の変更は外側にも見える

$studyBox = @{ State = '未着手' }
function Set-StudyBox {
    $studyBox['State'] = '完了'
}
Set-StudyBox
$studyBox['State']

実行結果

完了

呼出し後は「完了」と表示されます。関数が終了しても、中身の更新は取り消されません。比較表では、文字列への代入、関数内だけの変数、共有データの更新で、外側に残る結果が異なることを確認できます。

この例はメモリ上の学習用データだけを変更し、ファイルには保存していません。練習を戻すには画面を閉じます。外側へ変更を残す必要がなければ、関数から結果を返し、呼出し元で採用する形を検討できます。

結果の件数と変更範囲を順に切り分ける

出力する行を確認してから、変数への代入と共有データの更新を分けます。

スコープの指定にはlocal、script、globalがあります。localは現在の範囲、scriptはスクリプトファイルの範囲、globalはそのPowerShellセッションの基点です。globalは、別のPowerShell画面まで値を共有する意味ではありません。

画面へ直接入力する場合と、スクリプトファイルから実行する場合では、現在の範囲が異なります。原因が分からないままglobalへ変更すると、同名の変数や関数への影響が広がるため、まず以下の順で確認します。

比較表は、ここまでの例で成功出力へ残る値を整理したものです。案内が画面へ表示されることと、結果変数へ入ることを分けて読み返してください。件数が合わなければ、該当する例へ戻って出力する行を確認できます。

  1. 呼出しと同じ画面で、関数の定義からコード欄の末尾まで実行したか確認します。最後の呼出しや表示の行も対象です。
  2. 結果を@(…)で受けてCountを調べます。文字列の単独出力、Write-Output、受け取らずに残したメソッドの戻り値を確認します。
  3. returnより前と後を分けて追います。前に出た値は残り、returnより後の行は実行されないことを確認します。
  4. 変数への代入か、共有データの中身の更新かを分けます。同名変数が外側に残っていないか、StrictModeの設定が例と異ならないかも確認します。
対応する掲載例 結果に残る値 実行されない箇所
returnより前の1とreturnの5が両方残る 1 と 5 の2件 returnより後の2
値を付けないreturnも、それ以前の出力は取り消さない 開始の1件 returnより後の終了後
案内メッセージと計算結果を別の経路へ分ける 25の1件。案内は別表示 なし
Addの戻り値0も結果に混ざる 0 と 資料の2件 なし
追加位置の数値だけを捨て、資料を残す 資料の1件 なし

10例の実行記録は、StrictModeが無効なWindows PowerShell 5.1の新しい画面での結果です。PowerShell 7系、クラスのメソッド、モジュール、ジョブ、再帰、遠隔実行、外部入力や業務データへの適用は実行確認の範囲外です。