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 は、次の値を持つ列挙体です。
名前 | 値 |
---|---|
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
Inquire に設定します。
非対話型モードでは、パラメーターはDebug現在のコマンドの変数の値を$DebugPreference
オーバーライドし、値$DebugPreference
を Continue に設定します。
-Debug:$true
と同じ効果 -Debug
があります。 既定の SilentlyContinue でない場合$DebugPreference
に、デバッグ メッセージの表示を抑制するために使用-Debug:$false
します。
-ErrorAction
コマンドから終了しないエラーにコマンドレットが応答する方法を決定します。
このパラメーターは、コマンドが終了しないエラー (コマンドレットからのエラーなど) を生成する Write-Error
場合にのみ機能します。
Type: ActionPreference
Aliases: ea
Accepted values: 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
値をオーバーライドします。 変数の$ErrorActionPreference
既定値は Continue であるため、ErrorAction パラメーターを使用しない限り、エラー メッセージが表示され、実行が続行されます。
ErrorAction パラメーターは、コマンドの正常な完了を妨げるエラー (データの不足、無効なパラメーター、アクセス許可の不十分など) の終了には影響しません。
-ErrorAction:Break
エラーが発生したとき、または例外が発生したときにデバッガーを入力します。-ErrorAction:Continue
はエラー メッセージを表示し、コマンドの実行を続行します。Continue
は既定値です。-ErrorAction:Ignore
は、エラー メッセージを抑制し、コマンドの実行を続行します。 SilentlyContinue とは異なり、Ignore はエラー メッセージを自動変数に$Error
追加しません。 無視値は PowerShell 3.0 で導入されています。-ErrorAction:Inquire
はエラー メッセージを表示し、実行を続行する前に確認を求められます。 この値はほとんど使用しません。-ErrorAction:SilentlyContinue
は、エラー メッセージを抑制し、コマンドの実行を続行します。-ErrorAction:Stop
はエラー メッセージを表示し、コマンドの実行を停止します。-ErrorAction:Suspend
は、PowerShell 6 以降でサポートされていないワークフローでのみ使用できます。
Note
ErrorAction パラメーターはオーバーライドされますが、スクリプトまたは関数を実行するコマンドでパラメーターを使用する場合、変数の$ErrorActionPreference
値は置き換えられません。
-ErrorVariable
エラー レコードは自動変数に自動的に $Error
格納されます。 詳細については、「about_Automatic_Variables」を参照してください。
コマンドで ErrorVariable パラメーターを使用すると、PowerShell では、コマンドによって出力されたエラー レコードも、パラメーターで指定された変数に格納されます。
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]
配列表記を使用できます。
Note
カスタム エラー変数には、入れ子になった関数またはスクリプトの呼び出しからのエラーを含め、コマンドによって生成されたすべてのエラーが含まれます。
-InformationAction
PowerShell 5.0 で導入されました。 使用されるコマンドまたはスクリプト内で、InformationAction 共通パラメーターは基本設定変数の$InformationPreference
値をオーバーライドします。既定では SilentlyContinue に設定されています。 InformationAction でスクリプトで使用Write-Information
する場合、 Write-Information
InformationAction パラメーターの値に応じて値が表示されます。 $InformationPreference
の詳細については、「about_Preference_Variables」を参照してください。
Type: ActionPreference
Aliases: infa
Accepted values: Suspend, Ignore, Inquire, Continue, Stop, SilentlyContinue
Required: False
Position: Named
Default value: Depends on preference variable
Accept pipeline input: False
Accept wildcard characters: False
-InformationAction:Break
コマンドが発生した時点でデバッガーをWrite-Information
入力します。-InformationAction:Stop
は、コマンドが発生した時点でコマンドまたはスクリプトをWrite-Information
停止します。-InformationAction:Ignore
は情報メッセージを抑制し、コマンドの実行を続行します。 SilentlyContinue とは異なり、Ignore は情報メッセージを完全に忘れます。情報メッセージは情報ストリームに追加されません。-InformationAction:Inquire
コマンドでWrite-Information
指定した情報メッセージが表示され、続行するかどうかを確認するメッセージが表示されます。-InformationAction:Continue
は情報メッセージを表示し、実行を続けます。-InformationAction:Suspend
は PowerShell 6 以降ではサポートされていません。これはワークフローでのみ使用できます。-InformationAction:SilentlyContinue
情報メッセージが表示されない (既定) の場合、スクリプトは中断されずに続行されるため、効果はありません。
Note
InformationAction パラメーターはオーバーライドされますが、スクリプトまたは関数を$InformationAction
実行するコマンドでパラメーターを使用する場合、基本設定変数の値は置き換えられません。
-InformationVariable
PowerShell 5.0 で導入されました。 InformationVariable 共通パラメーターを使用すると、情報レコードはパラメーターで指定された変数に格納されます。 また、PowerShell コマンドレットは情報レコードを情報ストリームに書き込むことができます。 コマンドレットを Write-Information
使用して情報レコードを書き込むこともできます。
情報レコードは、既定でコンソールにメッセージとして表示されます。 InformationAction 共通パラメーターを使用して、情報レコードの表示を制御できます。 基本設定変数を使用して動作を $InformationPreference
変更することもできます。 $InformationPreference
の詳細については、「about_Preference_Variables」を参照してください。
Note
情報変数には、入れ子になった関数またはスクリプトへの呼び出しからの情報メッセージを含め、コマンドによって生成されるすべての情報メッセージが含まれます。
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
Note
OutVariable パラメーターによって作成される変数は、[System.Collections.ArrayList]
-PipelineVariable
PipelineVariable を使用すると、このパラメーターを使用するコマンドによって、次のパイプライン セグメントに渡される最新の値にアクセスできます。 パイプライン内のすべてのコマンドは、名前付き PipelineVariable を使用して値にアクセスできます。 値は、次のパイプライン セグメントに渡されるときに変数に割り当てられます。 これにより、PipelineVariable は特定の一時変数よりも使いやすくなり、複数の場所に割り当てる必要がある場合があります。
PipelineVariable とは異なり$_
、または $PSItem
PipelineVariable を使用すると、パイプライン コマンドは、直前のコマンド以外のコマンドによって渡された (および保存された) パイプライン値にアクセスできます。 パイプライン コマンドは、パイプラインを通過する次の項目の処理中にパイプされた最後の値にアクセスできます。 これにより、コマンドはその出力を 前のコマンド (またはそれ自体) にフィードバック できます。
Note
高度な関数には、最大 3 つのスクリプト ブロックをprocess
end
含めることができます。 begin
高度な関数で 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
Get-Variable : Cannot find a variable with the name 'temp'.
At line:1 char:1
+ Get-Variable temp
+ ~~~~~~~~~~~~~~~~~
+ CategoryInfo : ObjectNotFound: (temp:String) [Get-Variable], ItemNotFoundException
+ FullyQualifiedErrorId : VariableNotFound,Microsoft.PowerShell.Commands.GetVariableCommand
-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: 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 パラメーターを使用しない限り、警告が表示され、実行が続行されます。
-WarningAction:Break
は、警告が発生したときにデバッガーに入ります。-WarningAction:Continue
は警告メッセージを表示し、コマンドの実行を続行します。Continue
は既定値です。-WarningAction:Inquire
は警告メッセージを表示し、実行を続行する前に確認を求められます。 この値はほとんど使用しません。-WarningAction:SilentlyContinue
は警告メッセージを抑制し、コマンドの実行を続行します。-WarningAction:Stop
は警告メッセージを表示し、コマンドの実行を停止します。
Note
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
このパラメーターを使用すると、特定のコマンドからの警告のみを含む変数を作成できます。 変数に格納されている特定の警告など$a[0]
$warning[1,2]
、配列表記を使用できます。
Note
警告変数には、入れ子になった関数またはスクリプトへの呼び出しからの警告を含め、コマンドによって生成されたすべての警告が含まれます。
リスク管理パラメーターの説明
-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」を参照してください。
-WhatIf:$true
と同じ効果-WhatIf
があります。-WhatIf:$false
は、変数の値が 1 の場合に発生する自動 WhatIf 動作を$WhatIfPreference
抑制します。
たとえば、次のコマンドでは、コマンドでパラメーターを-WhatIf
Remove-Item
使用します。
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」を参照してください。
-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"):
応答オプションは Confirm 次のとおりです。
回答 | 結果 |
---|---|
Yes (Y ) |
アクションを実行します。 |
Yes to All (A ) |
すべてのアクションを実行し、後続のアクションを抑制する Confirm |
このコマンドのクエリ。 | |
No (N ): |
アクションを実行しないでください。 |
No to All (L ): |
アクションを実行せず、後続の操作を抑制する |
Confirm このコマンドのクエリ。 | |
Suspend (S ): |
コマンドを一時停止し、一時的なセッションを作成します。 |
Help (? ) |
これらのオプションのヘルプを表示します。 |
Suspend オプションは、コマンドを保留にし、オプションを選択する準備ができるまで作業できる一時的な入れ子になったセッションを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
関連項目
PowerShell
フィードバック
https://aka.ms/ContentUserFeedback」を参照してください。
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「フィードバックの送信と表示