about_CommonParameters

簡単な説明

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

長い説明

共通パラメーターは、すべてのコマンドレットで使用できるコマンドレットパラメーターのセットです。 これらは、コマンドレットの開発者ではなく、PowerShell によって実装され、任意のコマンドレットで自動的に使用できるようになります。

共通パラメーターは任意のコマンドレットと共に使用できますが、すべてのコマンドレットに影響を与えない場合があります。 たとえば、コマンドレットで詳細出力が生成されない場合、共通パラメーターを使用しても Verbose 効果はありません。

一般的なパラメーターは、表示可能な バインド 属性または Parameter 属性を使用する高度な関数でも使用できます。

いくつかの一般的なパラメーターでは、システムの既定値や、PowerShell ユーザー設定変数を使用して設定した設定を上書きします。 ユーザー設定変数とは異なり、共通パラメーターは、使用されるコマンドにのみ影響します。

詳細については、「 about_Preference_Variables」を参照してください。

共通パラメーターの一覧を次に示します。 これらのエイリアスは、かっこで囲まれています。

  • Debug db-9
  • Erroraction (ea)
  • Errorvariable (ev)
  • Informationaction (infa)
  • Informationvariable (iv)
  • Outvariable (ov-es)
  • Outbuffer (ob)
  • PipelineVariable (pv)
  • Verbose (vb)
  • WarningAction (wa)
  • WarningVariable (wv)

Action パラメーターActionPreference 型の 値です。 ActionPreference は 、次の値を持つ列挙体です。

Name
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 $DebugPreference $DebugPreference 設定 します

-Debug:$true と同じ効果があります -Debug-Debug:$false $DebugPreferenceSilentlyContinue ではない場合 (既定)、を使用して、デバッグメッセージの表示を抑制します。

-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続行 されるため、 erroraction パラメーターを使用しない限り、エラーメッセージが表示され、実行が続行されます。

Erroraction パラメーターは、コマンドが正常に完了しないようにする、不足しているデータ、無効なパラメーター、権限の不足などの終了エラーには影響しません。

-ErrorAction:Continue エラーメッセージを表示し、コマンドの実行を続行します。 Continue が既定値です。

-ErrorAction:Ignore エラーメッセージを表示せずに、コマンドの実行を続行します。 SilentlyContinue とは異なり、 Ignore ではエラーメッセージが自動変数に追加されません $ErrorIgnore 値は、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 変数には、セッション内のすべてのコマンドからのエラー メッセージが含まれています。 や などの配列表記を使用して $a[0]$error[1,2] 変数に格納されている特定のエラーを参照できます。

注意

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

-InformationAction

PowerShell 5.0 で導入されました。 使用されるコマンドまたはスクリプト内では 、InformationAction 共通パラメーターによって基本設定変数の値がオーバーライドされます。既定では $InformationPreference 、SilentlyContinue に設定されますWrite-InformationInformationAction を使用するスクリプトで を使用すると、InformationAction パラメーターの値に応じて値 Write-Information が表示 されます。 の詳細については、「」 $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 Coreでサポートされていません。

-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 し、その中に process オブジェクトを格納します。

Get-Process PowerShell -OutVariable out

次のコマンドを実行すると、process オブジェクトが変数に追加され $out ます。

Get-Process iexplore -OutVariable +out

次のコマンドを実行すると、変数の内容が表示され $out ます。

$out

注意

Outvariable パラメーターによって作成された変数は [System.Collections.ArrayList] です。

-PipelineVariable

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 パラメーターをコマンドに追加して、コマンドの結果を変数 Foreach-Object に格納します。 1 ~ 10 の範囲の数値は、最初のコマンドにパイプされ、その結果は Left という名前の Foreach-Object 変数に格納 されます

最初のコマンドの結果は 2 番目のコマンドにパイプされ、最初のコマンドによって返されたオブジェクト Foreach-Object Foreach-Object がフィルター処理 Foreach-Object されます。 2 番目のコマンドの結果は、Right という名前の変数に 格納されます

3 番目のコマンドでは、左と右の変数で表される最初の 2 つのパイプコマンドの結果は、乗算演算子を使用して Foreach-Object Foreach-Object 処理されます。 このコマンドは 、Left 変数と Right 変数に格納されているオブジェクトに乗算するように指示し、結果を "Left range member * Right range member = product" として表示するように指定します。

1..10 | Foreach-Object -PipelineVariable Left -Process { $_ } |
  Foreach-Object -PV Right -Process { 1..10 } |
  Foreach-Object -Process { "$Left * $Right = " + ($Left*$Right) }
1 * 1 = 1
1 * 2 = 2
1 * 3 = 3
1 * 4 = 4
1 * 5 = 5
...

-Verbose

コマンドによって実行される操作に関する詳細情報を表示します。 この情報は、トレースまたはトランザクション ログ内の情報に似た情報です。 このパラメーターは、コマンドによって詳細メッセージが生成された場合にのみ機能します。 たとえば、このパラメーターは、コマンドに コマンドレットが含まれている場合に機能 Write-Verbose します。

Type: SwitchParameter
Aliases: vb

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

パラメーター Verbose は、現在のコマンドの $VerbosePreference 変数の値をオーバーライドします。 変数の既定値 $VerbosePreferenceSilentlyContinue であるため、詳細メッセージは既定では表示されません。

-Verbose:$true と同じ効果があります。 -Verbose

-Verbose:$false 詳細メッセージの表示を抑制します。 の値が SilentlyContinue (既定値) でない場合に、このパラメーターを使用し $VerbosePreference ます。

-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

Warnings action パラメーターは、現在のコマンドの変数の値よりも優先され $WarningPreference ます。 変数の既定値 $WarningPreferenceContinue であるため、 warnings action パラメーターを使用しない限り、警告が表示され、実行が続行されます。

-WarningAction:Continue 警告メッセージを表示し、コマンドの実行を続行します。 Continue が既定値です。

-WarningAction:Inquire 警告メッセージを表示し、実行を続行する前に確認メッセージを表示します。 この値はほとんど使用されません。

-WarningAction:SilentlyContinue 警告メッセージを表示せずに、コマンドの実行を続行します。

-WarningAction:Stop 警告メッセージを表示し、コマンドの実行を停止します。

注意

警告動作 パラメーターはをオーバーライドしますが、 $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 変数の値をオーバーライドします。 変数の既定値は 0 (無効) なので、WhatIf の動作は $WhatIfPreference 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 (?) これらのオプションのヘルプを表示します。

Suspend オプションを指定すると、コマンドが保留状態になり、一時的な入れ子になったセッションが作成されます。このセッションでは、オプションを選択する準備ができてい Confirm ます。 入れ子になったセッションのコマンドプロンプトには、元の親コマンドの子操作であることを示すために、2つの追加のキャレット (>>) があります。 入れ子になったセッションでは、コマンドとスクリプトを実行できます。 入れ子になったセッションを終了し、 Confirm 元のコマンドのオプションに戻るには、「exit」と入力します。

次の例では、ユーザーがコマンドパラメーターのヘルプを確認している間に、 Suspend オプションを使用してコマンドを一時的に停止しています。 ユーザーは必要な情報を取得した後、"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

こちらもご覧ください

about_Preference_Variables

企画Debug

Write-Warning

Write-Error

企画Verbose