about_CommonParameters
簡単な説明
任意のコマンドレットで使用できるパラメーターについて説明します。
長い説明
共通パラメーターは、任意のコマンドレットで使用できるコマンドレット パラメーターのセットです。 これらは、コマンドレット開発者ではなく PowerShell によって実装され、任意のコマンドレットで自動的に使用できます。
共通パラメーターは任意のコマンドレットで使用できますが、すべてのコマンドレットに影響を及ぼすとは限りません。 たとえば、コマンドレットで詳細な出力が生成されない場合、共通パラメーターを Verbose 使用しても効果はありません。
共通パラメーターは、 CmdletBinding 属性または Parameter 属性を使用する高度な関数でも使用できます。
いくつかの一般的なパラメーターは、PowerShell 基本設定変数を使用して設定したシステムの既定値または基本設定をオーバーライドします。 基本設定変数とは異なり、共通パラメーターは、それらが使用されているコマンドにのみ影響します。
詳細については、「 about_Preference_Variables」を参照してください。
次の一覧には、共通パラメーターが表示されます。 エイリアスはかっこで囲んで表示されます。
- Debug (db)
- ErrorAction (ea)
- ErrorVariable (ev)
- InformationAction (infa)
- InformationVariable (iv)
- OutVariable (ov)
- OutBuffer (ob)
- PipelineVariable (pv)
- Verbose (vb)
- WarningAction (wa)
- WarningVariable (wv)
Action パラメーターは、ActionPreference 型の値です。 ActionPreference は、次の値を持つ列挙体です。
名前 | 値 |
---|---|
Break |
6 |
Suspend |
5 |
Ignore |
4 |
Inquire |
3 |
Continue |
2 |
Stop |
1 |
SilentlyContinue |
0 |
パラメーターには、名前または値を使用できます。
一般的なパラメーターに加えて、多くのコマンドレットではリスク軽減パラメーターが提供されています。 システムまたはユーザー データに対するリスクを伴うコマンドレットは、通常、これらのパラメーターを提供します。
リスク軽減パラメーターは次のとおりです。
- WhatIf (wi)
- Confirm (cf)
一般的なパラメーターの説明
-Debug
コマンドによって実行された操作に関するプログラマ レベルの詳細を表示します。 このパラメーターは、コマンドがデバッグ メッセージを生成する場合にのみ機能します。 たとえば、このパラメーターは、コマンドに コマンドレットが含まれている場合に Write-Debug
機能します。
Type: SwitchParameter
Aliases: db
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
既定では、変数の値が SilentlyContinue であるため、$DebugPreference
デバッグ メッセージは表示されません。
パラメーターは Debug 、現在のコマンドの変数の値を $DebugPreference
オーバーライドし、 の $DebugPreference
値を Continue に設定します。
-Debug:$true
は と同じ効果 -Debug
を持ちます。 が SilentlyContinue でない場合$DebugPreference
のデバッグ メッセージの表示を抑制する場合に使用-Debug:$false
します。これは既定です。
-ErrorAction
コマンドから終了しないエラーに対するコマンドレットの応答方法を決定します。
このパラメーターは、コマンドが終了しないエラー (コマンドレットからのエラーなど) を生成する Write-Error
場合にのみ機能します。
Type: ActionPreference
Aliases: ea
Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False
ErrorAction パラメーターは、現在のコマンドの変数の$ErrorActionPreference
値をオーバーライドします。 変数の既定値は Continue であるため、ErrorAction パラメーターを$ErrorActionPreference
使用しない限り、エラー メッセージが表示され、実行が続行されます。
ErrorAction パラメーターは、コマンドの正常な完了を妨げるエラー (データの欠落、無効なパラメーター、アクセス許可の不十分など) の終了には影響しません。
Break
エラーが発生したとき、または例外が発生したときにデバッガーに入ります。Continue
はエラー メッセージを表示し、コマンドの実行を続行します。Continue
は既定値です。Ignore
はエラー メッセージを抑制し、コマンドの実行を続行します。 SilentlyContinue とは異なり、Ignore は自動変数にエラー メッセージを$Error
追加しません。 Ignore 値は PowerShell 3.0 で導入されています。Inquire
はエラー メッセージを表示し、実行を続行する前に確認を求めます。 この値はほとんど使用しません。SilentlyContinue
はエラー メッセージを抑制し、コマンドの実行を続行します。Stop
はエラー メッセージを表示し、コマンドの実行を停止します。Suspend
は、PowerShell 6 以降ではサポートされていないワークフローでのみ使用できます。
注意
ErrorAction パラメーターはオーバーライドされますが、スクリプトまたは関数を$ErrorActionPreference
実行するコマンドでパラメーターを使用する場合、変数の値は置き換えられません。
-ErrorVariable
エラー レコードは自動変数に自動的に $Error
格納されます。 詳細については、「about_Automatic_Variables」を参照してください。
コマンドで ErrorVariable パラメーターを使用すると、コマンドによって出力されたエラー レコードも パラメーターで指定された変数に格納されます。
Type: String
Aliases: ev
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
既定では、新しいエラー メッセージによって、変数に既に格納されているエラー メッセージが上書きされます。 エラー メッセージを変数コンテンツに追加するには、変数名の前にプラス記号 (+
) を付けます。
たとえば、次のコマンドは 変数を $a
作成し、その中にエラーを格納します。
Get-Process -Id 6 -ErrorVariable a
次のコマンドは、エラー メッセージを変数に $a
追加します。
Get-Process -Id 2 -ErrorVariable +a
次のコマンドは、 の内容 $a
を表示します。
$a
このパラメーターを使用すると、特定のコマンドからのエラー メッセージのみを含み、自動変数の動作に影響しない変数を $Error
作成できます。 $Error
自動変数には、セッション内のすべてのコマンドからのエラー メッセージが含まれています。 や $error[1,2]
などの$a[0]
配列表記を使用して、変数に格納されている特定のエラーを参照できます。
注意
カスタム エラー変数には、入れ子になった関数またはスクリプトの呼び出しからのエラーを含め、コマンドによって生成されたすべてのエラーが含まれます。
-InformationAction
PowerShell 5.0 で導入されました。 使用されるコマンドまたはスクリプト内で、 InformationAction 共通パラメーターはユーザー設定変数の $InformationPreference
値をオーバーライドします。既定では、 SilentlyContinue に設定されます。 InformationAction を使用してスクリプトでを使用Write-Information
すると、 Write-Information
InformationAction パラメーターの値に応じて値が表示されます。 の詳細については $InformationPreference
、「 about_Preference_Variables」を参照してください。
Type: ActionPreference
Aliases: infa
Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False
Break
コマンドが発生した時点でデバッガーをWrite-Information
入力します。Stop
は、コマンドが発生した時点でコマンドまたはスクリプトをWrite-Information
停止します。Ignore
は情報メッセージを抑制し、コマンドの実行を続行します。 SilentlyContinue とは異なり、Ignore は情報メッセージを完全に忘れてしまいます。情報メッセージは情報ストリームに追加されません。Inquire
は、コマンドで指定した情報メッセージをWrite-Information
表示し、続行するかどうかを確認します。Continue
は情報メッセージを表示し、実行を続けます。Suspend
は、ワークフローでのみ使用できる PowerShell 6 以降ではサポートされていません。SilentlyContinue
情報メッセージが表示されない (既定) の場合、スクリプトは中断することなく続行されます。
注意
InformationAction パラメーターはオーバーライドされますが、パラメーターをコマンドで使用してスクリプトまたは関数を$InformationAction
実行する場合、ユーザー設定変数の値は置き換えられません。
-InformationVariable
PowerShell 5.0 で導入されました。 InformationVariable 共通パラメーターを使用すると、 パラメーターで指定された変数に情報レコードが格納されます。 PowerShell コマンドレットでは、情報レコードを Information ストリームに書き込むことができます。 コマンドレットを使用して Write-Information
情報レコードを書き込むこともできます。
情報レコードは、既定でコンソールにメッセージとして表示されます。 InformationAction 共通パラメーターを使用して、情報レコードの表示を制御できます。 ユーザー設定変数を使用して動作を $InformationPreference
変更することもできます。 の詳細については $InformationPreference
、「 about_Preference_Variables」を参照してください。
注意
information 変数には、入れ子になった関数またはスクリプトへの呼び出しからの情報メッセージを含む、コマンドによって生成されたすべての情報メッセージが含まれます。
Type: String
Aliases: iv
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
既定では、新しい情報レコードは、変数に既に格納されている値を上書きします。 エラー メッセージを変数コンテンツに追加するには、変数名の前にプラス記号 (+
) を付けます。
-OutBuffer
パイプラインを介してオブジェクトが送信される前に、バッファーに累積するオブジェクトの数を決定します。 このパラメーターを省略すると、オブジェクトは生成時に送信されます。
Type: Int32
Aliases: ob
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
このリソース管理パラメーターは、上級ユーザー向けに設計されています。 このパラメーターを使用すると、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
パイプラインに沿って出力を送信するだけでなく、指定した変数に コマンドからの出力オブジェクトを格納します。
Type: String
Aliases: ov
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
出力を変数に追加するには、そこに既に格納されている出力を置き換える代わりに、変数名の前にプラス記号 (+
) を入力します。
たとえば、次のコマンドは 変数を $out
作成し、その中にプロセス オブジェクトを格納します。
Get-Process PowerShell -OutVariable out
次のコマンドは、プロセス オブジェクトを変数に $out
追加します。
Get-Process iexplore -OutVariable +out
次のコマンドは、変数の内容を $out
表示します。
$out
注意
OutVariable パラメーターによって作成される変数は です[System.Collections.ArrayList]
。
-PipelineVariable
PipelineVariable を使用すると、このパラメーターを使用するコマンドによって、次のパイプライン セグメントに渡される最新の値にアクセスできます。 パイプライン内のすべてのコマンドは、名前付きの PipelineVariable を使用して値にアクセスできます。 値は、次のパイプライン セグメントに渡されるときに変数に割り当てられます。 これにより、 PipelineVariable は特定の一時変数よりも使いやすくなり、複数の場所に割り当てる必要がある場合があります。
または $PSItem
とは異なり$_
、PipelineVariable を使用すると、パイプライン コマンドは、直前のコマンド以外のコマンドによって渡された (および保存された) パイプライン値にアクセスできます。 パイプライン コマンドは、パイプラインを通過する次の項目の処理中に、 からパイプされた最後の値にアクセスできます。 これにより、コマンドは、その出力を前のコマンド (またはそれ自体) に フィード バック できます。
注意
高度な関数には、、、および end
の 3 つのスクリプト ブロックbegin
process
を含めることができます。 高度な関数で PipelineVariable パラメーターを使用する場合、関数の実行時に最初に定義されたスクリプト ブロックの値のみが変数に割り当てられます。 詳細については、「 高度な関数」を参照してください。 PowerShell 7.2 では、この動作が修正されます。
Type: String
Aliases: pv
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
有効な値は、任意の変数名の場合と同じ文字列です。
注意事項
PipelineVariable のスコープは、それが呼び出されるパイプラインです。 パイプラインの外部にある変数 (同じ名前を使用) は、パイプラインが実行される前にクリアされます。 パイプラインが終了すると、 PipelineVariable はスコープ外になります。 パイプライン内の複数のコマンドで同じ PipelineVariable が指定されている場合、共有変数は 1 つだけです。 その変数は、変数を指定するコマンドからの最新のパイプ出力で更新されます。
一部の ブロック コマンドでは、出力を生成する前にすべてのパイプライン項目 (例: Sort-Object
または Select-Object -Last
) が収集されます。 このようなブロッキング コマンドの前にコマンドで割り当てられた PipelineVariable には、ブロッキング コマンドの後のコマンドで使用される場合、常に前のコマンドの最後のパイプされた項目が含まれます。
PipelineVariable のしくみの例を次に示します。 この例では、 PipelineVariable パラメーターをコマンドに追加して Foreach-Object
、コマンドの結果を変数に格納します。 1 ~ 5 の数値の範囲は、最初 Foreach-Object
のコマンドにパイプ処理され、その結果は という名前 $temp
の変数に格納されます。
最初Foreach-Object
のコマンドの結果は、2 番目Foreach-Object
のコマンドにパイプ処理され、 と $_
の現在の$temp
値が表示されます。
# Create a variable named $temp
$temp=8
Get-Variable temp
# Note that the variable just created isn't available on the
# pipeline when -PipelineVariable creates the same variable name
1..5 | ForEach-Object -PipelineVariable temp -Begin {
Write-Host "Step1[BEGIN]:`$temp=$temp"
} -Process {
Write-Host "Step1[PROCESS]:`$temp=$temp - `$_=$_"
Write-Output $_
} | ForEach-Object {
Write-Host "`tStep2[PROCESS]:`$temp=$temp - `$_=$_"
}
# The $temp variable is deleted when the pipeline finishes
Get-Variable temp
Name Value
---- -----
temp 8
Step1[BEGIN]:$temp=
Step1[PROCESS]:$temp= - $_=1
Step2[PROCESS]:$temp=1 - $_=1
Step1[PROCESS]:$temp=1 - $_=2
Step2[PROCESS]:$temp=2 - $_=2
Step1[PROCESS]:$temp=2 - $_=3
Step2[PROCESS]:$temp=3 - $_=3
Step1[PROCESS]:$temp=3 - $_=4
Step2[PROCESS]:$temp=4 - $_=4
Step1[PROCESS]:$temp=4 - $_=5
Step2[PROCESS]:$temp=5 - $_=5
Name Value
---- -----
temp
-Verbose
コマンドによって実行された操作に関する詳細情報を表示します。 この情報は、トレースまたはトランザクション ログ内の情報に似ています。 このパラメーターは、コマンドが詳細メッセージを生成する場合にのみ機能します。 たとえば、このパラメーターは、コマンドに コマンドレットが含まれている場合に Write-Verbose
機能します。
Type: SwitchParameter
Aliases: vb
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
パラメーターは Verbose 、現在のコマンドの変数の $VerbosePreference
値をオーバーライドします。 変数の $VerbosePreference
既定値は SilentlyContinue であるため、詳細メッセージは既定では表示されません。
-Verbose:$true
と同じ効果があります。-Verbose
-Verbose:$false
は、詳細メッセージの表示を抑制します。 の値$VerbosePreference
が SilentlyContinue (既定値) でない場合は、このパラメーターを使用します。
-WarningAction
コマンドからの警告に対するコマンドレットの応答方法を決定します。 Continue が既定値です。 このパラメーターは、コマンドが警告メッセージを生成する場合にのみ機能します。 たとえば、このパラメーターは、コマンドに コマンドレットが含まれている場合に Write-Warning
機能します。
Type: ActionPreference
Aliases: wa
Accepted values: Break, Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False
WarningAction パラメーターは、現在のコマンドの変数の$WarningPreference
値をオーバーライドします。 変数の $WarningPreference
既定値は Continue であるため、 WarningAction パラメーターを使用しない限り、警告が表示され、実行が続行されます。
Break
は、警告が発生したときにデバッガーに入ります。Continue
は警告メッセージを表示し、コマンドの実行を続行します。Continue
は既定値です。Inquire
は警告メッセージを表示し、実行を続行する前に確認を求めます。 この値はほとんど使用しません。SilentlyContinue
は警告メッセージを抑制し、コマンドの実行を続行します。Stop
は警告メッセージを表示し、コマンドの実行を停止します。
注意
WarningAction パラメーターはオーバーライドされますが、パラメーターがスクリプトまたは関数を$WarningAction
実行するためにコマンドで使用されている場合、ユーザー設定変数の値は置き換えられません。
-WarningVariable
指定した変数にコマンドに関する警告レコードを格納します。
Type: String
Aliases: wv
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
生成されたすべての警告は、警告がユーザーに表示されない場合でも、変数に保存されます。
変数コンテンツに警告を追加するには、そこに既に格納されている可能性のある警告を置き換える代わりに、変数名の前にプラス記号 (+
) を入力します。
たとえば、次のコマンドは 変数を $a
作成し、その変数に警告を格納します。
Get-Process -Id 6 -WarningVariable a
次のコマンドは、変数に警告を $a
追加します。
Get-Process -Id 2 -WarningVariable +a
次のコマンドは、 の内容 $a
を表示します。
$a
このパラメーターを使用して、特定のコマンドからの警告のみを含む変数を作成できます。 や $warning[1,2]
などの$a[0]
配列表記を使用して、変数に格納されている特定の警告を参照できます。
注意
警告変数には、入れ子になった関数またはスクリプトの呼び出しからの警告を含め、コマンドによって生成されたすべての警告が含まれます。
リスク管理パラメーターの説明
-WhatIf
コマンドを実行する代わりに、コマンドの効果を説明するメッセージを表示します。
Type: SwitchParameter
Aliases: wi
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
WhatIf パラメーターは、現在のコマンドの変数の$WhatIfPreference
値をオーバーライドします。 変数の $WhatIfPreference
既定値は 0 (無効) であるため 、WhatIf の動作は WhatIf パラメーターなしでは実行されません。 詳細については、「 about_Preference_Variables」を参照してください。
$true
は と同じ効果-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
コマンドを実行する前に確認メッセージを表示します。
Type: SwitchParameter
Aliases: cf
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False
パラメーターは Confirm 、現在のコマンドの変数の $ConfirmPreference
値をオーバーライドします。 既定値は、true です。 詳細については、「 about_Preference_Variables」を参照してください。
$true
は と同じ効果-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"):
応答オプションは Confirm 次のとおりです。
Response | 結果 |
---|---|
Yes (Y ) |
アクションを実行します。 |
Yes to All (A ) |
すべてのアクションを実行し、後続のアクションを抑制する Confirm |
このコマンドのクエリ。 | |
No (N ): |
アクションを実行しないでください。 |
No to All (L ): |
アクションを実行せず、後続のアクションを抑制する |
Confirm このコマンドのクエリ。 | |
Suspend (S ): |
コマンドを一時停止し、一時的なセッションを作成します。 |
Help (? ) |
これらのオプションのヘルプを表示します。 |
[中断] オプションを選択すると、コマンドが保留になり、一時的に入れ子になったセッションが作成されます。このセッションでは、オプションを選択Confirmする準備ができるまで作業できます。 入れ子になったセッションのコマンド プロンプトには、元の親コマンドの子操作であることを示す 2 つの余分なキャレット (>>) があります。 入れ子になったセッションでコマンドとスクリプトを実行できます。 入れ子になったセッションを終了し、元のコマンドの Confirm オプションに戻すには、「exit」と入力します。
次の例では、 Suspend オプション (S) を使用してコマンドを一時的に停止し、ユーザーがコマンド パラメーターのヘルプを確認します。 必要な情報を取得した後、ユーザーは入れ子になったプロンプトを終了するために「exit」と入力し、クエリに対する Yes (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 (defau
lt is "Y"): y
Directory: C:\ps-test
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a--- 8/27/2010 2:41 PM 0 test.txt