CommonParameters について
概要
任意のコマンドレットで使用できるパラメーターについて説明します。
詳細説明
共通パラメーターは、任意のコマンドレットで使用できるコマンドレット パラメーターのセットです。 これらは、コマンドレット開発者ではなく PowerShell によって実装され、任意のコマンドレットで自動的に使用できます。
共通パラメーターは任意のコマンドレットで使用できますが、すべてのコマンドレットに影響を及ぼすとは限りません。 たとえば、コマンドレットで詳細な出力が生成されない場合、 Verbose 共通パラメーターを使用しても効果はありません。
共通パラメーターは、 CmdletBinding 属性または Parameter 属性を使用する高度な関数、およびすべてのワークフローでも使用できます。
いくつかの一般的なパラメーターは、PowerShell 基本設定変数を使用して設定したシステムの既定値または基本設定をオーバーライドします。 基本設定変数とは異なり、共通パラメーターは、それらが使用されているコマンドにのみ影響します。
一般的なパラメーターに加えて、多くのコマンドレットでは 、WhatIf と Confirm のリスク軽減パラメーターが提供されています。 システムまたはユーザー データに対するリスクを伴うコマンドレットは、通常、これらのパラメーターを提供します。
次の一覧には、共通パラメーターが表示されます。 エイリアスはかっこで囲んで表示されます。
- Debug (db)
- ErrorAction (ea)
- ErrorVariable (ev)
- InformationAction (infa)
- InformationVariable (iv)
- OutVariable (ov)
- OutBuffer (ob)
- PipelineVariable (pv)
- Verbose (vb)
- WarningAction (wa)
- WarningVariable (wv)
リスク軽減パラメーターは次のとおりです。
- WhatIf (wi)
- 確認 (cf)
詳細については、「 about_Preference_Variables」を参照してください。
一般的なパラメーターの説明
デバッグ
Debug のエイリアスは db です。
コマンドによって実行された操作に関するプログラマ レベルの詳細を表示します。 このパラメーターは、コマンドがデバッグ メッセージを生成する場合にのみ機能します。 たとえば、このパラメーターは、コマンドに コマンドレットが含まれている場合に Write-Debug 機能します。
Debug パラメーターは、現在のコマンドの変数の値を$DebugPreferenceオーバーライドし、 の$DebugPreference値を Continue に設定します。 変数の $DebugPreference 既定値は SilentlyContinue であるため、デバッグ メッセージは既定では表示されません。
-Debug:$true は と同じ効果 -Debugを持ちます。 が SilentlyContinue でない場合$DebugPreferenceのデバッグ メッセージの表示を抑制する場合に使用-Debug:$falseします。これは既定です。
ErrorAction
ErrorAction のエイリアスは ea です。
コマンドから終了しないエラーに対するコマンドレットの応答方法を決定します。
このパラメーターは、コマンドが終了しないエラー (コマンドレットからのエラーなど) を生成する Write-Error 場合にのみ機能します。
ErrorAction パラメーターは、現在のコマンドの変数の$ErrorActionPreference値をオーバーライドします。 変数の既定値は Continue であるため、ErrorAction パラメーターを$ErrorActionPreference使用しない限り、エラー メッセージが表示され、実行が続行されます。
ErrorAction パラメーターは、コマンドの正常な完了を妨げるエラー (データの欠落、無効なパラメーター、アクセス許可の不十分など) の終了には影響しません。
-ErrorAction:Continue エラー メッセージを表示し、コマンドの実行を続行します。 Continue は既定値です。
-ErrorAction:Ignore はエラー メッセージを抑制し、コマンドの実行を続行します。 SilentlyContinue とは異なり、Ignore は自動変数にエラー メッセージを$Error追加しません。 Ignore 値は PowerShell 3.0 で導入されています。
-ErrorAction:Inquire はエラー メッセージを表示し、実行を続行する前に確認を求めます。 この値はほとんど使用しません。
-ErrorAction:SilentlyContinue はエラー メッセージを抑制し、コマンドの実行を続行します。
-ErrorAction:Stop はエラー メッセージを表示し、コマンドの実行を停止します。
-ErrorAction:Suspend は PowerShell Core ではサポートされていません。これはワークフローでのみ使用できます。
注意
ErrorAction パラメーターはオーバーライドされますが、パラメーターをコマンドで使用してスクリプトまたは関数を$ErrorAction実行する場合、ユーザー設定変数の値は置き換えられません。
ErrorVariable
ErrorVariable のエイリアスは ev です。
ErrorVariable は、指定した変数と自動変数にコマンドに関するエラー メッセージを $Error 格納します。 詳細については、次のコマンドを入力します。
Get-Help about_Automatic_Variables
既定では、新しいエラー メッセージによって、変数に既に格納されているエラー メッセージが上書きされます。 エラー メッセージを変数コンテンツに追加するには、変数名の前にプラス記号 (+) を入力します。
たとえば、次のコマンドは 変数を $a 作成し、その中にエラーを格納します。
Get-Process -Id 6 -ErrorVariable a
次のコマンドは、エラー メッセージを変数に $a 追加します。
Get-Process -Id 2 -ErrorVariable +a
次のコマンドは、 の内容 $aを表示します。
$a
このパラメーターを使用すると、特定のコマンドからのエラー メッセージのみを含む変数を作成できます。 $Error自動変数には、セッション内のすべてのコマンドからのエラー メッセージが含まれています。 や $error[1,2] などの$a[0]配列表記を使用して、変数に格納されている特定のエラーを参照できます。
InformationAction
InformationAction のエイリアスは ia です。
PowerShell 5.0 で導入されました。 使用されるコマンドまたはスクリプト内で、 InformationAction 共通パラメーターはユーザー設定変数の $InformationPreference 値をオーバーライドします。既定では、 SilentlyContinue に設定されます。 InformationAction を使用してスクリプトでを使用Write-Informationすると、 Write-InformationInformationAction パラメーターの値に応じて値が表示されます。 の詳細については $InformationPreference、「 about_Preference_Variables」を参照してください。
-InformationAction:Stop は、コマンドが発生した時点でコマンドまたはスクリプトを Write-Information 停止します。
-InformationAction:Ignore は情報メッセージを抑制し、コマンドの実行を続行します。 SilentlyContinue とは異なり、Ignore は情報メッセージを完全に忘れてしまいます。情報メッセージは情報ストリームに追加されません。
-InformationAction:Inquire は、コマンドで指定した情報メッセージを Write-Information 表示し、続行するかどうかを確認します。
-InformationAction:Continue は情報メッセージを表示し、実行を続けます。
-InformationAction:Suspend は PowerShell Core ではサポートされていません。これはワークフローでのみ使用できます。
-InformationAction:SilentlyContinue 情報メッセージが表示されない (既定) の場合、スクリプトは中断することなく続行されます。
注意
InformationAction パラメーターはオーバーライドされますが、パラメーターをコマンドで使用してスクリプトまたは関数を実行する場合、ユーザー設定変数の値$InformationActionは置き換えられません。
InformationVariable
InformationVariable のエイリアスは iv です。
PowerShell 5.0 で導入されました。 使用されるコマンドまたはスクリプト内で、 InformationVariable 共通パラメーターは、コマンドを追加して指定した文字列を変数に Write-Information 格納します。 Write-Information 値は、 InformationAction 共通パラメーターの値に応じて表示されます。 InformationAction 共通パラメーターを追加しない場合は、 Write-Information ユーザー設定変数の値に応じて文字列が $InformationPreference 表示されます。 の詳細については $InformationPreference、「 about_Preference_Variables」を参照してください。
OutBuffer
OutBuffer のエイリアスは ob で、System.Int32 値を受け取ります。
パイプラインを介してオブジェクトが送信される前にバッファーに蓄積するオブジェクトの数を決定します。 このパラメーターを省略すると、オブジェクトは生成時に送信されます。
このリソース管理パラメーターは、上級ユーザー向けに設計されています。 このパラメーターを使用すると、PowerShell は のバッチで次のコマンドレットにデータを OutBuffer + 1送信します。
次の例では、 コマンドレットを使用するプロセス ブロック間 ForEach-Object の代替表示を Write-Host 示します。 表示は、2 または OutBuffer + 1のバッチで代替されます。
1..4 | ForEach-Object {
Write-Host "$($_): First"; $_
} -OutBuffer 1 | ForEach-Object {
Write-Host "$($_): Second" }
1: First
2: First
1: Second
2: Second
3: First
4: First
3: Second
4: Second
OutVariable
OutVariable のエイリアスは ov です。
パイプラインに沿って出力を送信するだけでなく、指定した変数に コマンドからの出力オブジェクトを格納します。
出力を変数に追加するには、そこに既に格納されている出力を置き換える代わりに、変数名の前にプラス記号 (+) を入力します。
たとえば、次のコマンドは 変数を $out 作成し、その中にプロセス オブジェクトを格納します。
Get-Process PowerShell -OutVariable out
次のコマンドは、プロセス オブジェクトを変数に $out 追加します。
Get-Process iexplore -OutVariable +out
次のコマンドは、変数の内容を $out 表示します。
$out
注意
OutVariable パラメーターによって作成される変数は です[System.Collections.ArrayList]。
PipelineVariable
PipelineVariable のエイリアスは pv で、文字列値を受け取ります。
PipelineVariable は、パイプライン内を流れる任意の名前付きコマンドに対して、現在のパイプライン要素の値を変数として格納します。
有効な値は、任意の変数名の場合と同じ文字列です。
PipelineVariable のしくみの例を次に示します。 この例では、 PipelineVariable パラメーターをコマンドに追加して Foreach-Object 、コマンドの結果を変数に格納します。 1 ~ 10 の数値の範囲は、最初 Foreach-Object のコマンドにパイプ処理され、その結果は Left という名前の変数に格納されます。
最初 Foreach-Object のコマンドの結果は、2 番目 Foreach-Object のコマンドにパイプ処理され、最初 Foreach-Object のコマンドによって返されたオブジェクトがフィルター処理されます。 2 番目のコマンドの結果は、 Right という名前の変数に格納されます。
3 番目Foreach-Objectのコマンドでは、左と右の変数で表される最初の 2 つのForeach-Objectパイプコマンドの結果は、乗算演算子を使用して処理されます。 このコマンドは、 Left 変数と Right 変数に格納されているオブジェクトに乗算するように指示し、結果を "Left range member * Right range member = product" として表示するように指定します。
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 のエイリアスは vb です。
コマンドによって実行された操作に関する詳細情報を表示します。 この情報は、トレースまたはトランザクション ログ内の情報に似ています。 このパラメーターは、コマンドが詳細メッセージを生成する場合にのみ機能します。 たとえば、このパラメーターは、コマンドに コマンドレットが含まれている場合に Write-Verbose 機能します。
Verbose パラメーターは、現在のコマンドの変数の$VerbosePreference値をオーバーライドします。 変数の $VerbosePreference 既定値は SilentlyContinue であるため、詳細メッセージは既定では表示されません。
-Verbose:$true と同じ効果があります。 -Verbose
-Verbose:$false は、詳細メッセージの表示を抑制します。 の値 $VerbosePreference が SilentlyContinue (既定値) でない場合は、このパラメーターを使用します。
WarningAction
WarningAction のエイリアスは wa です。
コマンドからの警告に対するコマンドレットの応答方法を決定します。 Continue が既定値です。 このパラメーターは、コマンドが警告メッセージを生成する場合にのみ機能します。 たとえば、このパラメーターは、コマンドに コマンドレットが含まれている場合に Write-Warning 機能します。
WarningAction パラメーターは、現在のコマンドの変数の$WarningPreference値をオーバーライドします。 変数の $WarningPreference 既定値は Continue であるため、 WarningAction パラメーターを使用しない限り、警告が表示され、実行が続行されます。
-WarningAction:Continue は警告メッセージを表示し、コマンドの実行を続行します。 Continue は既定値です。
-WarningAction:Inquire は警告メッセージを表示し、実行を続行する前に確認を求めます。 この値はほとんど使用しません。
-WarningAction:SilentlyContinue は警告メッセージを抑制し、コマンドの実行を続行します。
-WarningAction:Stop は警告メッセージを表示し、コマンドの実行を停止します。
注意
WarningAction パラメーターはオーバーライドされますが、スクリプトまたは関数を$WarningAction実行するコマンドで パラメーターを使用する場合、ユーザー設定変数の値は置き換えされません。
WarningVariable
WarningVariable のエイリアスは wv です。
指定した変数にコマンドに関する警告を格納します。
生成されたすべての警告は、警告がユーザーに表示されない場合でも、変数に保存されます。
変数コンテンツに警告を追加するには、そこに既に格納されている可能性のある警告を置き換える代わりに、変数名の前にプラス記号 (+) を入力します。
たとえば、次のコマンドは 変数を $a 作成し、その変数に警告を格納します。
Get-Process -Id 6 -WarningVariable a
次のコマンドは、変数に警告を $a 追加します。
Get-Process -Id 2 -WarningVariable +a
次のコマンドは、 の内容 $aを表示します。
$a
このパラメーターを使用して、特定のコマンドからの警告のみを含む変数を作成できます。 や $warning[1,2] などの$a[0]配列表記を使用して、変数に格納されている特定の警告を参照できます。
注意
WarningVariable パラメーターは、関数またはスクリプトの入れ子になった呼び出しからの警告をキャプチャしません。
リスク管理パラメーターの説明
WhatIf
WhatIf のエイリアスは wi です。
コマンドを実行する代わりに、コマンドの効果を説明するメッセージを表示します。
WhatIf パラメーターは、現在のコマンドの変数の$WhatIfPreference値をオーバーライドします。 変数の $WhatIfPreference 既定値は 0 (無効) であるため 、WhatIf の動作は WhatIf パラメーターなしでは実行されません。 詳細については、次のコマンドを入力します。
Get-Help about_Preference_Variables
-WhatIf:$true は と同じ効果 -WhatIfを持ちます。
-WhatIf:$false は、変数の値が 1 の場合に発生する WhatIf の自動動作を $WhatIfPreference 抑制します。
たとえば、次のコマンドでは、 コマンドで パラメーターをRemove-Item使用-WhatIfします。
Remove-Item Date.csv -WhatIf
PowerShell では、アイテムを削除する代わりに、実行する操作と影響を受けるアイテムが一覧表示されます。 このコマンドでは次の出力が生成されます。
What if: Performing operation "Remove File" on
Target "C:\ps-test\date.csv".
Confirm
Confirm のエイリアスは cf です。
コマンドを実行する前に確認メッセージを表示します。
Confirm パラメーターは、現在のコマンドの変数の$ConfirmPreference値をオーバーライドします。 既定値は、true です。 詳細については、次のコマンドを入力します。
Get-Help about_Preference_Variables
-Confirm:$true は と同じ効果 -Confirmを持ちます。
-Confirm:$false は自動確認を抑制します。これは、 の値がコマンドレットの $ConfirmPreference 推定リスク以下の場合に発生します。
たとえば、次のコマンドでは、 Confirm パラメーターをコマンドと共に Remove-Item 使用します。 アイテムを削除する前に、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"):
[応答の確認] オプションは次のとおりです。
| Response | 結果 |
|---|---|
| はい (Y) | アクションを実行します。 |
| [すべてにはい] (A) | すべてのアクションを実行し、後続の確認クエリを抑制する |
| このコマンドの 場合は 。 | |
| いいえ (N): | アクションを実行しないでください。 |
| [すべていいえ] (L): | アクションを実行せず、後続の確認を抑制する |
| このコマンドのクエリ。 | |
| Suspend (S): | コマンドを一時停止し、一時的なセッションを作成します。 |
| ヘルプ (?) | これらのオプションのヘルプを表示します。 |
[中断] オプションを選択すると、コマンドが保留になり、一時的な入れ子になったセッションが作成されます。このセッションは、確認オプションを選択する準備ができるまで作業できます。 入れ子になったセッションのコマンド プロンプトには、元の親コマンドの子操作であることを示す 2 つの余分なキャレット (>>) があります。 入れ子になったセッションでコマンドとスクリプトを実行できます。 入れ子になったセッションを終了し、元のコマンドの [確認] オプションに戻すには、「exit」と入力します。
次の例では、 Suspend オプション (S) を使用してコマンドを一時的に停止し、ユーザーがコマンド パラメーターのヘルプを確認します。 必要な情報を取得した後、ユーザーは "exit" と入力して入れ子になったプロンプトを終了し、Confirm クエリに対する Yes (y) 応答を選択します。
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 (defau
lt is "Y"): y
Directory: C:\ps-test
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a--- 8/27/2010 2:41 PM 0 test.txt
キーワード
about_Common_Parameters