about_CommonParameters

適用対象: Windows PowerShell 2.0, Windows PowerShell 3.0, Windows PowerShell 4.0

概要をここに挿入してください。

トピック

about_CommonParameters

概要

コマンドレットと共に使用できるパラメーターについて説明します。

詳細説明

共通パラメーターは、任意のコマンドレットで使用できる一連のコマンドレット パラメーターです。これらは、コマンドレット開発者ではなく Windows PowerShell® によって実装され、自動的にすべてのコマンドレットで使用可能です。

共通パラメーターは任意のコマンドレットで使用できますが、コマンドレットによっては効果がない場合もあります。たとえば、コマンドレットが詳細な出力を生成しない場合は、Verbose 共通パラメーターを使用しても効果はありません。

共通パラメーターは、CmdletBinding 属性または Parameter 属性を使用する高度な関数や、すべてのワークフローでも使用可能です。

いくつかの共通パラメーターは、Windows PowerShell のユーザー設定変数を使用して設定されたシステムの既定値やユーザー設定を上書きします。ユーザー設定変数とは異なり、共通パラメーターはそれが使用されたコマンドのみに影響します。

共通パラメーターに加えて、多くのコマンドレットにはリスク軽減パラメーター WhatIf と Confirm が用意されています。これらのパラメーターは、通常、システムまたはユーザー データに対するリスクを伴うコマンドレットに用意されています。

次の一覧に、共通パラメーターを示します。かっこの中は、それぞれのエイリアスを示しています。

       -Debug (db)
       -ErrorAction (ea)
       -ErrorVariable (ev)
       -OutVariable (ov)
       -OutBuffer (ob)
       -PipelineVariable (pv)
       -Verbose (vb) 
       -WarningAction (wa)
       -WarningVariable (wv

リスク軽減パラメーターは、次のとおりです。

-WhatIf (wi)
       -Confirm (cf)

ユーザー設定変数の詳細については、次のように入力してください。

help about_Preference_Variables

共通パラメーターの説明

-DEBUG[:{$TRUE | $FALSE}]

エイリアス:db

コマンドによって実行される操作に関するプログラマ向けの詳細情報を表示します。このパラメーターは、コマンドがデバッグ メッセージを生成する場合にのみ機能します。このパラメーターは、たとえば、コマンドに Write-Debug コマンドレットが含まれている場合に機能します。

Debug パラメーターは、現在のコマンドの $DebugPreference 変数の値を上書きして、$DebugPreference の値を Inquire に設定します。$DebugPreference 変数の既定値は SilentlyContinue なので、既定ではデバッグ メッセージは表示されません。

有効な値:

$true (-Debug:$true). Has the same effect as -Debug.

$false (-Debug:$false). Suppresses the display of debugging
            messages when the value of the $DebugPreference is not
            SilentlyContinue (the default).

-ERRORACTION[:{CONTINUE | IGNORE | INQUIRE | SILENTLYCONTINUE | STOP |SUSPEND }]

エイリアス:ea

コマンドを終了させないエラーに対するコマンドレットの応答方法を決定します。このパラメーターは、コマンドを終了させないエラー (Write-Error コマンドレットのエラーなど) を生成した場合にのみ機能します。

ErrorAction パラメーターは、現在のコマンドの $ErrorActionPreference 変数の値に優先します。$ErrorActionPreference 変数の既定値は Continue なので、ErrorAction パラメーターを使用しなかった場合はエラー メッセージが表示され、実行が続行されます。

ErrorAction パラメーターは、コマンドが正常に完了しない終了エラー (データの消失、無効なパラメーター、不十分なアクセス許可など) には効果がありません。

有効な値:

Continue。エラー メッセージを表示し、コマンドの実行を続行します。既定値は "Continue" です。

Ignore。エラー メッセージを表示せず、コマンドの実行を続けます。SilentlyContinue とは異なり、Ignore ではエラー メッセージが $Error 自動変数に追加されません。値 Ignore は Windows PowerShell 3.0 で導入されました。

Inquire。エラー メッセージを表示し、実行を続ける前に確認メッセージを表示します。この値はほとんど使用しません。

SilentlyContinue。エラー メッセージを表示せず、コマンドの実行を続けます。

Stop。エラー メッセージを表示し、コマンドの実行を停止します。

Suspend。この値は、Windows PowerShell のワークフローでのみ使用可能です。この操作設定では、ワークフローで終了エラーが発生したときにジョブが自動的に中断され、詳しい調査が可能になります。調査の後で、ワークフローを再開できます。

-ERRORVARIABLE [+]<VARIABLE-NAME>

エイリアス:ev

コマンドに関するエラー メッセージを、指定された変数および $Error 自動変数に格納します。詳細については、次のコマンドを入力してください。

get-help about_Automatic_Variables

既定では、新しいエラー メッセージが変数に既に保存されているエラー メッセージを上書きします。エラー メッセージを変数の内容に追加するには、変数名の前にプラス記号 (+) を入力します。

たとえば、次のコマンドは変数 $a を作成し、その中にエラーを格納します。

Get-Process -Id 6 -ErrorVariable a

次のコマンドは、変数 $a にエラー メッセージを追加します。

Get-Process -Id 2 -ErrorVariable +a

次のコマンドは、$a の内容を表示します。

$a

このパラメーターを使用して、特定のコマンドのエラー メッセージのみを格納する変数を作成できます。$Error 自動変数には、セッション内のすべてのコマンドのエラー メッセージが格納されます。$a[0] や $error[1,2] などの配列表記を使用して、変数に格納されている特定のエラーを参照できます。

-OUTBUFFER <INT32>

エイリアス:ob

パイプラインを介して送信する前にバッファーに蓄積するオブジェクトの数を決定します。このパラメーターを省略すると、オブジェクトは生成されると同時に送信されます。

このリソース管理パラメーターは、上級ユーザー向けに設計されています。このパラメーターを使用すると、生成されたオブジェクトの数が OutBuffer + 1 になるまで Windows PowerShell によってパイプラインの次のコマンドレットが呼び出されません。その後は、すべてのオブジェクトが生成されると同時に送信されます。

-OUTVARIABLE [+]<VARIABLE-NAME>

エイリアス:ov

コマンドからの出力オブジェクトを指定された変数に格納し、それをコマンド ラインに表示します。

変数に既に格納されている出力を置換せずに、出力を変数に追加するには、変数名の前にプラス記号 (+) を入力します。

たとえば、次のコマンドは変数 $out を作成し、その中にプロセス オブジェクトを格納します。

Get-Process PowerShell -OutVariable out

次のコマンドは、変数 $out にプロセス オブジェクトを追加します。

Get-Process iexplore -OutVariable +out

次のコマンドは、変数 $out の内容を表示します。

$out

-PIPELINEVARIABLE <STRING>

エイリアス:pv

PipelineVariable は、パイプラインを通過する名前付きコマンドのために、現在のパイプライン要素の値を変数として格納します。

有効な値は、変数名の場合と同様の文字列です。

PipelineVariable の動作の例を次に示します。この例では、コマンドの結果を変数に格納するため、Foreach-Object コマンドに PipelineVariable パラメーターが追加されています。数値範囲 1 ～ 10 が最初の Foreach-Object コマンドにパイプを介して渡され、その結果が Left という名前の変数に格納されます。

最初の Foreach-Object コマンドの結果が 2 番目の Foreach-Object コマンドにパイプを介して渡され、最初の Foreach-Object コマンドによって返されたオブジェクトがフィルター処理されます。2 番目のコマンドの結果が Right という名前の変数に格納されます。

3 番目の Foreach-Object コマンドで、パイプ処理された最初の 2 つの Foreach-Object コマンドの結果 (変数 Left および Right で表されたもの) が乗算演算子を使用して処理されます。このコマンドは、変数 Left および Right に格納されているオブジェクトを乗算し、その結果を「Left の範囲メンバー * Right の範囲メンバー = 乗算結果」として表示するように指示しています。

1..10 | Foreach-Object -PipelineVariable Left -Process { $_ } |
              >>    Foreach-Object -PV Right -Process { 1..10 } |
              >>    Foreach-Object -Process { "$Left * $Right = " + ($Left * $Right) }
              >>
              1 * 1 = 1
              1 * 2 = 2
              1 * 3 = 3
              1 * 4 = 4
              1 * 5 = 5

-VERBOSE[:{$TRUE | $FALSE}]

エイリアス:vb

コマンドによって実行された操作の詳細情報を表示します。この情報は、トレースやトランザクション ログに含まれる情報に似ています。このパラメーターは、コマンドが詳細メッセージを生成する場合にのみ機能します。このパラメーターは、たとえば、コマンドに Write-Verbose コマンドレットが含まれている場合に機能します。

Verbose パラメーターは、現在のコマンドの $VerbosePreference 変数の値に優先します。$VerbosePreference 変数の既定値は SilentlyContinue なので、既定では詳細メッセージは表示されません。

有効な値:

$true (-Verbose:$true) has the same effect as -Verbose.

$false (-Verbose:$false) suppresses the display of verbose
            messages. Use this parameter when the value of $VerbosePreference
            is not SilentlyContinue (the default).

-WARNINGACTION[:{CONTINUE | INQUIRE | SILENTLYCONTINUE | STOP}]

エイリアス:wa

コマンドレットがコマンドの警告に応答する方法を決定します。既定値は "Continue" です。このパラメーターは、コマンドが警告メッセージを生成する場合にのみ機能します。このパラメーターは、たとえば、コマンドに Write-Warning コマンドレットが含まれている場合に機能します。

WarningAction パラメーターは、現在のコマンドの $WarningPreference 変数の値に優先します。$WarningPreference 変数の既定値は Continue なので、WarningAction パラメーターを使用しなかった場合は警告が表示され、実行が続行されます。

有効な値:

Continue。警告メッセージを表示し、コマンドの実行を続行します。既定値は "Continue" です。

Inquire。警告メッセージを表示し、実行を続ける前に確認メッセージを表示します。この値はほとんど使用しません。

SilentlyContinue。警告メッセージを表示せず、コマンドの実行を続けます。

Stop。警告メッセージを表示し、コマンドの実行を停止します。

注記:コマンド内でスクリプトまたは関数を実行するためにこのパラメーターが使用された場合、WarningAction パラメーターは $WarningAction ユーザー設定変数の値に優先しません。

-WARNINGVARIABLE [+]<VARIABLE-NAME>

エイリアス:wv

コマンドに関する警告を、指定された変数に格納します。

ユーザーに対して警告が表示されない場合でも、生成されたすべての警告が変数に保存されます。

変数に既に格納されている警告を置換せずに、警告を変数の内容に追加するには、変数名の前にプラス記号 (+) を入力します。

たとえば、次のコマンドは変数 $a を作成し、その中に警告を格納します。

Get-Process -Id 6 -WarningVariable a

次のコマンドは、変数 $a に警告を追加します。

Get-Process -Id 2 -WarningVariable +a

次のコマンドは、$a の内容を表示します。

$a

このパラメーターを使用して、特定のコマンドの警告のみを格納する変数を作成できます。$a[0] や $warning[1,2] などの配列表記を使用して、変数に格納されている特定の警告を参照できます。

注記:WarningVariable パラメーターは、関数またはスクリプト内の入れ子になった呼び出しの警告をキャプチャしません。

リスク管理パラメーターの説明

-WHATIF[:{$TRUE | $FALSE}]

エイリアス:wi

コマンドを実行せずに、コマンドの効果を説明するメッセージを表示します。

WhatIf パラメーターは、現在のコマンドの $WhatIfPreference 変数の値を上書きします。$WhatIfPreference 変数の既定値は 0 (無効) なので、WhatIf パラメーターを指定しないと WhatIf の動作は実行されません。詳細については、次のコマンドを入力してください。

Get-Help about_Preference_Variables

有効な値:

$true (-WhatIf:$true). Has the same effect as -WhatIf.

$false (-WhatIf:$false). Suppresses the automatic WhatIf behavior
            that results when the value of the $WhatIfPreference variable 
            is 1.

たとえば、次のコマンドは Remove-Item コマンドで WhatIf パラメーターを使用しています。

PS> Remove-Item Date.csv -WhatIf

項目を削除する代わりに、Windows PowerShell は、実行される操作と影響を受ける項目を一覧表示します。このコマンドによって次の出力が生成されます。

What if: Performing operation "Remove File" on 
            Target "C:\ps-test\date.csv".

-CONFIRM[:{$TRUE | $FALSE}]

エイリアス:cf

コマンドを実行する前に確認メッセージを表示します。

Confirm パラメーターは、現在のコマンドの $ConfirmPreference 変数の値を上書きします。既定値は High です。詳細については、次のコマンドを入力してください。

Get-Help about_Preference_Variables

有効な値:

$true (-Confirm:$true). Has the same effect as -Confirm.

$false(-Confirm:$false). Suppresses automatic confirmation,
            which occurs when the value of $ConfirmPreference is less than
            or equal to the estimated risk of the cmdlet.

たとえば、次のコマンドは Remove-Item コマンドで Confirm パラメーターを使用しています。Windows PowerShell は、項目を削除する前に実行される操作と影響を受ける項目を一覧表示し、承認を求めます。

PS C:\ps-test> Remove-Item tmp*.txt -Confirm

このコマンドによって次の出力が生成されます。

Confirm
            Are you sure you want to perform this action?
            Performing operation "Remove File" on Target " C:\ps-test\tmp1.txt
            [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  
            [?] Help (default is "Y"):

Confirm の応答オプションは次のとおりです。

Yes (Y)         Perform the action.
            Yes to All (A)  Perform all actions and suppress subsequent
                            Confirm queries for this command.
            No (N):         Do not perform the action.
            No to All (L):  Do not perform any actions and suppress subsequent
                            Confirm queries for this command.
            Suspend (S):    Pause the command and create a temporary session.
            Help (?)        Display help for these options.

Suspend オプションは、コマンドの実行を保留し、一時的な入れ子のセッションを作成します。ユーザーは、Confirm のオプションを選択できるようになるまでこのセッション内で作業できます。入れ子のセッションのコマンド プロンプトには、元の親コマンドの子の操作であることを示す 2 つのキャレット (>>) が追加されます。入れ子のセッションでは、コマンドやスクリプトを実行できます。入れ子のセッションを終了して元のコマンドの Confirm オプションに戻るには、「exit」を入力します。

次の例では、Suspend オプション (S) を使用してコマンドを一時的に停止している間に、ユーザーがコマンド パラメーターのヘルプを確認しています。必要な情報を入手した後、ユーザーは「exit」を入力して入れ子のプロンプトを終了し、はい (y) を選択して Confirm の問い合わせに応答します。

PS C:\ps-test> New-Item -ItemType File -Name Test.txt -Confirm

            Confirm
            Are you sure you want to perform this action?
            Performing operation "Create File" on Target "Destination: C:\ps-test\test.txt".
            [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): s

            PS C:\ps-test>>> Get-Help New-Item -Parameter ItemType

            -ItemType <string>
                Specifies the provider-specified type of the new item.

                Required?                    false
                Position?                    named
                Default value
                Accept pipeline input?       true (ByPropertyName)
                Accept wildcard characters?  false


            PS C:\ps-test>>> exit

            Confirm
            Are you sure you want to perform this action?
            Performing operation "Create File" on Target "Destination: C:\ps-test\test.txt".
            [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "Y"): y


                Directory: C:\ps-test
            

            Mode                LastWriteTime     Length Name
            ----                -------------     ------ ----
            -a---         8/27/2010   2:41 PM          0 test.txt

キーワード

about_Common_Parameters

関連項目

about_Preference_Variables

Write-Debug

Write-Warning

Write-Error

Write-Verbose