about_CommonParameters

[アーティクル]
05/09/2024

簡単な説明

任意のコマンドレットで使用できるパラメーターについて説明します。

長い説明

一般的なパラメーターは、任意のコマンドレットで使用できるコマンドレットパラメーターのセットです。これらは、コマンドレット開発者ではなく 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 値を Inquire に設定します。

非対話型モードでは、パラメーターは 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値をオーバーライドします。変数の $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 以降でサポートされていないワークフローでのみ使用できます。

注意

ErrorAction パラメーターはオーバーライドされますが、スクリプトまたは関数を$ErrorAction実行するコマンドでパラメーターを使用する場合、ユーザー設定変数の値は置き換えされません。

-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 、セッション内のすべてのコマンドからのエラーメッセージが含まれています。や $error[1,2] などの$a[0]配列表記を使用して、変数に格納されている特定のエラーを参照できます。

注意

カスタムエラー変数には、入れ子になった関数またはスクリプトの呼び出しからのエラーを含め、コマンドによって生成されたすべてのエラーが含まれます。

-InformationAction

PowerShell 5.0 で導入されました。使用されるコマンドまたはスクリプト内で、 InformationAction 共通パラメーターはユーザー設定変数の値を $InformationPreference オーバーライドします。この値は既定で SilentlyContinue に設定されます。 InformationAction を含むスクリプトでを使用Write-Informationすると、 Write-InformationInformationAction パラメーターの値に応じて値が表示されます。の詳細については $InformationPreference、「 about_Preference_Variables」を参照してください。

Type: ActionPreference
Aliases: ia
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

-InformationAction:Break コマンドが発生した時点でデバッガーを Write-Information 入力します。

-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」を参照してください。

注意

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 つのスクリプトブロックbeginprocessを含めることができます。 高度な関数で 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'.

-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値をオーバーライドします。変数の既定値は Continue であるため、WarningAction パラメーターを$WarningPreference使用しない限り、警告が表示され、実行が続行されます。

-WarningAction:Break は、警告が発生したときにデバッガーに入ります。

-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

このパラメーターを使用すると、特定のコマンドからの警告のみを含む変数を作成できます。や $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」を参照してください。

-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 次のとおりです。

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

キーワード

about_Common_Parameters

Share via