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
があります。 既定のサイレント コンティニュ ではない場合$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:Continue
エラー メッセージが表示され、コマンドの実行が続行されます。 Continue
が既定値です。
-ErrorAction:Ignore
はエラー メッセージを抑制し、コマンドの実行を続行します。 SilentlyContinue とは異なり、Ignore はエラー メッセージを自動変数に$Error
追加しません。 無視 値は PowerShell 3.0 で導入されています。
-ErrorAction:Inquire
は、エラー メッセージを表示し、実行を続行する前に確認を求めます。 この値はほとんど使用しません。
-ErrorAction:SilentlyContinue
はエラー メッセージを抑制し、コマンドの実行を続行します。
-ErrorAction:Stop
はエラー メッセージを表示し、コマンドの実行を停止します。
-ErrorAction:Suspend
は、PowerShell 6 以降でサポートされていないワークフローでのみ使用できます。
注意
ErrorAction パラメーターはオーバーライドされますが、スクリプトまたは関数を実行するコマンドでパラメーターを使用する場合、変数の$ErrorActionPreference
値は置き換えされません。
-ErrorVariable
ErrorVariable は、指定された変数と自動変数にコマンドに関するエラー メッセージを $Error
格納します。 詳細については、「about_Automatic_Variables」を参照してください
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]
。
注意
カスタム エラー変数には、入れ子になった関数またはスクリプトへの呼び出しからのエラーを含む、コマンドによって生成されたすべてのエラーが含まれます。
-InformationAction
PowerShell 5.0 で導入されました。 使用されるコマンドまたはスクリプト内で、 InformationAction 共通パラメーターは基本設定変数の値を $InformationPreference
オーバーライドします。既定では 、SilentlyContinue に設定されます。 InformationAction のスクリプトで使用Write-Information
する場合、 Write-Information
InformationAction パラメーターの 値に応じて値が表示されます。 詳細については $InformationPreference
、「 about_Preference_Variables」を参照してください。
Type: ActionPreference
Aliases: ia
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:Stop
は、コマンドが発生した時点でコマンドまたはスクリプトを Write-Information
停止します。
-InformationAction:Ignore
は情報メッセージを抑制し、コマンドの実行を続行します。 SilentlyContinue とは異なり、Ignore は 情報メッセージを完全に忘れます。情報メッセージは情報ストリームに追加されません。
-InformationAction:Inquire
は、コマンドで指定した情報メッセージを Write-Information
表示し、続行するかどうかを尋ねるメッセージを表示します。
-InformationAction:Continue
は情報メッセージを表示し、実行を続行します。
-InformationAction:Suspend
は PowerShell 6 以降ではサポートされていません。これはワークフローでのみ使用できます。
-InformationAction:SilentlyContinue
情報メッセージが表示されない (既定) の場合、スクリプトは中断されずに続行されるため、効果はありません。
注意
InformationAction パラメーターはオーバーライドされますが、スクリプトまたは関数を$InformationAction
実行するコマンドでパラメーターを使用する場合、優先変数の値は置き換えされません。
-InformationVariable
PowerShell 5.0 で導入されました。 使用されるコマンドまたはスクリプト内で、 InformationVariable 共通パラメーターは、コマンドを追加して指定した文字列を変数に Write-Information
格納します。 Write-Information
値は 、InformationAction 共通パラメーターの値に応じて表示されます。 InformationAction 共通パラメーターを追加しない場合は、 Write-Information
ユーザー設定変数の値に応じて文字列が $InformationPreference
表示されます。 詳細については $InformationPreference
、「 about_Preference_Variables」を参照してください。
注意
情報変数には、入れ子になった関数またはスクリプトへの呼び出しからの情報メッセージを含む、コマンドによって生成されたすべての情報メッセージが含まれます。
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 は特定の一時変数よりも使いやすくなり、複数の場所に割り当てる必要がある場合があります。
PipelineVariable とは異なり$_
、または $PSItem
PipelineVariable を使用すると、パイプライン コマンドは、直前のコマンド以外のコマンドによって渡された (および保存された) パイプライン値にアクセスできます。 パイプライン コマンドは、パイプラインを通過する次の項目の処理中にパイプされた最後の値にアクセスできます。 これにより、コマンドはその出力を前のコマンド (またはそれ自体) に フィードバック できます。
注意
高度な関数には、次の 3 つのスクリプト ブロックを含めることができます。 begin``process``end
高度な関数で 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 is not 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:Continue
は警告メッセージを表示し、コマンドの実行を続行します。 Continue
が既定値です。
-WarningAction:Inquire
は警告メッセージを表示し、実行を続行する前に確認を求めます。 この値はほとんど使用しません。
-WarningAction:SilentlyContinue
は警告メッセージを抑制し、コマンドの実行を続行します。
-WarningAction: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
このパラメーターを使用して、特定のコマンドからの警告のみを含む変数を作成できます。 配列表記を使用できます。たとえば $a[0]
、変数に格納されている特定の警告を参照することもできます $warning[1,2]
。
注意
警告変数には、入れ子になった関数またはスクリプトへの呼び出しからの警告など、コマンドによって生成されたすべての警告が含まれます。
リスク管理パラメーターの説明
-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
抑制します。
たとえば、次のコマンドでは、コマンドでパラメーターを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を参照してください。
-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" と入力して入れ子になったプロンプトを終了し、クエリに対する [はい] (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
Keywords
about_Common_Parameters
関連項目
フィードバック
フィードバックの送信と表示