about_CommonParameters
簡単な説明
任意のコマンドレットで使用できるパラメーターについて説明します。
詳細な説明
一般的なパラメーターは、任意のコマンドレットで使用できる一連のコマンドレット パラメーターです。 これらはコマンドレット開発者ではなく PowerShell によって実装され、任意のコマンドレットで自動的に使用できます。
共通パラメーターは任意のコマンドレットで使用できますが、すべてのコマンドレットに影響を与えるわけではありません。 たとえば、コマンドレットで verbose 出力が生成されない場合、 Verbose 共通パラメーターを使用しても効果はありません。
共通パラメーターは、 CmdletBinding
属性または Parameter
属性を使用する高度な関数でも使用できます。 これらの属性を使用すると、PowerShell によって共通パラメーターが自動的に追加されます。 共通パラメーターと同じ名前を使用するパラメーターは作成できません。
いくつかの一般的なパラメーターは、PowerShell 基本設定変数を使用して設定したシステムの既定値または基本設定をオーバーライドします。 基本設定変数とは異なり、一般的なパラメーターは、それらが使用されているコマンドにのみ影響します。
詳細については、「 about_Preference_Variables」を参照してください。
次の一覧に共通パラメーターが表示されます。 それらのエイリアスはかっこで囲まれています。
- Debug (db)
- ErrorAction (ea)
- ErrorVariable (ev)
- InformationAction (infa)
- InformationVariable (iv)
- OutVariable (ov)
- OutBuffer (ob)
- PipelineVariable (pv)
- ProgressAction (proga)
- 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
既定では、 $DebugPreference
変数の値が SilentlyContinue であるため、デバッグ メッセージは表示されません。
Debug パラメーターは、現在のコマンドの$DebugPreference
変数の値をオーバーライドし、$DebugPreference
の値を Continue に設定します。
-Debug:$true
は、 -Debug
と同じ効果を持ちます。 -Debug:$false
を使用して、$DebugPreference
が既定SilentlyContinueでない場合に、デバッグ メッセージの表示を抑制します。
-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
変数の値をオーバーライドします。 $ErrorActionPreference
変数の既定値は Continue であるため、ErrorAction パラメーターを使用しない限り、エラー メッセージが表示され、実行が続行されます。
ErrorAction パラメーターは、コマンドの正常な完了を妨げるエラー (データの不足、無効なパラメーター、アクセス許可の不十分など) の終了には影響しません。
Break
エラーが発生したとき、または例外が発生したときにデバッガーを入力します。Continue
はエラー メッセージを表示し、コマンドの実行を続行します。Continue
は既定値です。Ignore
は、エラー メッセージを抑制し、コマンドの実行を続行します。 SilentlyContinueとは異なり、Ignoreはエラー メッセージを$Error
自動変数に追加しません。 Ignore 値は PowerShell 3.0 で導入されています。Inquire
はエラー メッセージを表示し、実行を続行する前に確認を求められます。 この値はほとんど使用しません。SilentlyContinue
は、エラー メッセージを抑制し、コマンドの実行を続行します。Stop
はエラー メッセージを表示し、コマンドの実行を停止します。Suspend
は、PowerShell 6 以降でサポートされていないワークフローでのみ使用できます。
Note
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
自動変数には、セッション内のすべてのコマンドからのエラー メッセージが含まれています。 $a[0]
や$error[1,2]
などの配列表記を使用して、変数に格納されている特定のエラーを参照できます。
Note
カスタム エラー変数には、入れ子になった関数またはスクリプトの呼び出しからのエラーを含め、コマンドによって生成されたすべてのエラーが含まれます。
-InformationAction
PowerShell 5.0 で導入されました。 使用されるコマンドまたはスクリプト内で、InformationAction 共通パラメーターは、既定で SilentlyContinue に設定されている$InformationPreference
基本設定変数の値をオーバーライドします。 InformationAction のスクリプトでWrite-Information
を使用すると、InformationAction パラメーターの値に応じてWrite-Information
値が表示されます。 $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
情報メッセージが表示されない (既定) の場合、スクリプトは中断されずに続行されるため、効果はありません。
Note
InformationAction パラメーターはオーバーライドされますが、スクリプトまたは関数を実行するコマンドでパラメーターを使用する場合、$InformationAction
基本設定変数の値は置き換えられません。
-InformationVariable
PowerShell 5.0 で導入されました。 InformationVariable共通パラメーターを使用すると、情報レコードはパラメーターで指定された変数に格納されます。 また、PowerShell コマンドレットは、 Information ストリームに情報レコードを書き込むことができます。 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
のバッチで次のコマンドレットにデータを送信します。
次の例では、Write-Host
コマンドレットを使用するプロセス ブロック間ForEach-Object
表示します。 表示は、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 特定の一時変数よりも使いやすくなり、複数の場所に割り当てる必要がある場合があります。
$_
や$PSItem
とは異なり、PipelineVariable を使用すると、パイプライン コマンドは直前のコマンド以外のコマンドによって渡された (保存された) パイプライン値にアクセスできます。 パイプライン コマンドは、パイプラインを通過する次の項目の処理中にパイプされた最後の値にアクセスできます。 これにより、コマンドは前のコマンド (またはそれ自体) に出力戻できます。
Note
高度な関数には、最大 3 つのスクリプト ブロック ( begin
、 process
、および end
) を含めることができます。 高度な関数で PipelineVariable パラメーターを使用すると、関数の実行時に最初に定義されたスクリプト ブロックの値のみが変数に割り当てられます。 詳細については、「 Advanced 関数」を参照してください。 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
-ProgressAction
スクリプト、コマンドレット、またはプロバイダーによって生成された進行状況の更新 ( Write-Progress コマンドレットによって生成された進行状況バーなど) に対する PowerShell の応答方法を決定します。 Write-Progress
コマンドレットは、コマンドの状態を示す進行状況バーを作成します。 ProgressAction パラメーターが PowerShell 7.4 で追加されました。
ProgressAction パラメーターは、SilentlyContinue
、Stop
、Continue
、Inquire
、Ignore
、Suspend
、またはBreak
のいずれかのActionPreference
列挙値を受け取ります。
有効な値は次のとおりです。
Break
Write-Progress
コマンドが発生した時点でデバッガーを入力します。Stop
: 進行状況バーは表示されません。 代わりに、エラー メッセージが表示され、実行が停止されます。Inquire
: 進行状況バーは表示されません。 続行するアクセス許可を求めるメッセージが表示されます。Y
またはA
で返信すると、進行状況バーが表示されます。Continue
: (既定値) 進行状況バーが表示され、実行が続行されます。SilentlyContinue
: コマンドを実行しますが、進行状況バーは表示されません。
Type: ActionPreference
Aliases: proga
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
-Verbose
コマンドによって実行された操作に関する詳細情報を表示します。 この情報は、トレースまたはトランザクション ログ内の情報に似ています。 このパラメーターは、コマンドが 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 メッセージは既定では表示されません。
-Verbose:$true
と同じ効果があります。-Verbose
-Verbose:$false
は、 verbose メッセージの表示を抑制します。 このパラメーターは、$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
は警告メッセージを表示し、コマンドの実行を停止します。
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」を参照してください。
$true
は、-WhatIf
と同じ効果を持ちます。$false
では、$WhatIfPreference
変数の値が 1 の場合に発生する WhatIf の自動動作が抑制されます。
たとえば、次のコマンドでは、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
の値がコマンドレットの推定リスク以下である場合に発生する自動確認を抑制します。
たとえば、次のコマンドでは、Remove-Item
コマンドで Confirm パラメーターを使用します。 アイテムを削除する前に、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" を入力して入れ子になったプロンプトを終了し、 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
関連項目
PowerShell