CommonParameters について

概要

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

詳細説明

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

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

共通パラメーターは、 CmdletBinding 属性または Parameter 属性を使用する高度な関数、およびすべてのワークフローでも使用できます。

いくつかの一般的なパラメーターは、PowerShell 基本設定変数を使用して設定したシステム既定値または基本設定をオーバーライドします。基本設定変数とは異なり、一般的なパラメーターは、それらが使用されているコマンドにのみ影響します。

一般的なパラメーターに加えて、多くのコマンドレットには WhatIf と Confirm のリスク軽減パラメーターが用意されています。システムまたはユーザーデータに対するリスクを伴うコマンドレットは、通常、これらのパラメーターを提供します。

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

デバッグ (db)
ErrorAction (ea)
ErrorVariable (ev)
InformationAction (infa)
情報変数 (iv)
アウト変数 (ov)
アウトバッファ (ob)
パイプライン変数 (PV)
詳細( vb)
WarningAction (wa)
警告変数 (wv)

リスク軽減パラメーターは次のとおりです。

もしも( ウィスコンシン)
確認 (cf)

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

一般的なパラメーターの説明

デバッグ

Debug のエイリアスは db です。

コマンドによって実行された操作に関するプログラマレベルの詳細を表示します。このパラメーターは、コマンドがデバッグメッセージを生成する場合にのみ機能します。たとえば、このパラメーターは、コマンドに Write-Debug コマンドレットが含まれている場合に機能します。

Debug パラメータは、現在のコマンドの $DebugPreference 変数の値を上書きし、$DebugPreference の値を Continue に設定します。 $DebugPreference変数のデフォルト値は SilentlyContinue であるため、デフォルトではデバッグメッセージは表示されません。

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

エラーアクション

ErrorAction のエイリアスは ea です。

コマンドから終了しないエラーにコマンドレットが応答する方法を決定します。このパラメーターは、コマンドが終了しないエラー ( Write-Error コマンドレットのエラーなど) を生成する場合にのみ機能します。

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 Core ではサポートされていません。

注

ErrorAction パラメータは、スクリプトまたは関数を実行するコマンドでパラメータが使用されるときに、$ErrorAction 設定変数の値を上書きしますが、置き換えるものではありません。

エラー変数

ErrorVariable のエイリアスは ev です。

ErrorVariable は、コマンドに関するエラーメッセージを、指定された変数と $Error 自動変数に格納します。詳細については、次のコマンドを入力します。

Get-Help about_Automatic_Variables

既定では、新しいエラーメッセージによって、変数に既に格納されているエラーメッセージが上書きされます。変数の内容にエラーメッセージを追加するには、変数名の前にプラス記号 (+) を入力します。

たとえば、次のコマンドは、 $a 変数を作成し、エラーを格納します。

Get-Process -Id 6 -ErrorVariable a

次のコマンドは、エラーメッセージを $a 変数に追加します。

Get-Process -Id 2 -ErrorVariable +a

次のコマンドは、 $aの内容を表示します。

$a

このパラメータを使用して、特定のコマンドからのエラーメッセージのみを含む変数を作成できます。 $Error自動変数には、セッション内のすべてのコマンドからのエラーメッセージが含まれています。 $a[0]や$error[1,2]などの配列表記を使用して、変数に格納されている特定のエラーを参照できます。

インフォメーションアクション

InformationAction のエイリアスは ia です。

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

-InformationAction:Stop は、 Write-Information コマンドの発生時にコマンドまたはスクリプトを停止します。

-InformationAction:Ignore は情報メッセージを抑制し、コマンドの実行を続行します。 SilentlyContinue とは異なり、Ignore は情報メッセージを完全に忘れます。情報メッセージは情報ストリームに追加されません。

-InformationAction:Inquire は、 Write-Information コマンドで指定した情報メッセージを表示し、続行するかどうかを確認します。

-InformationAction:Continue は情報メッセージを表示し、実行を続けます。

-InformationAction:Suspend は、ワークフローでのみ使用できるため、PowerShell Core ではサポートされていません。

-InformationAction:SilentlyContinue 情報メッセージが表示されない (既定) の場合、スクリプトは中断されずに続行されるため、効果はありません。

注

InformationAction パラメーターは、スクリプトまたは関数を実行するコマンドでパラメーターが使用されている場合、$InformationAction プリファレンス変数の値をオーバーライドしますが、置き換えるものではありません。

情報変数

InformationVariable のエイリアスは iv です。

PowerShell 5.0 で導入されました。それが使用されるコマンドまたはスクリプト内で、 InformationVariable 共通パラメータは、 Write-Information コマンドを追加して指定した文字列を変数に格納します。 Write-Information値は、InformationAction 共通パラメーターの値に応じて表示されます。InformationAction 共通パラメーターを追加しない場合、Write-Information 基本設定変数の値に応じて$InformationPreference文字列が表示されます。 $InformationPreferenceの詳細については、「about_Preference_Variables」を参照してください。

アウトバッファー

OutBuffer のエイリアスは ob で、System.Int32 値を受け取ります。

パイプラインを介してオブジェクトが送信される前にバッファーに蓄積するオブジェクトの数を決定します。このパラメーターを省略すると、オブジェクトは生成時に送信されます。

このリソース管理パラメーターは、上級ユーザー向けに設計されています。このパラメーターを使用すると、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 のエイリアスは ov です。

パイプラインに沿って出力を送信するだけでなく、指定した変数にコマンドからの出力オブジェクトを格納します。

変数に出力を追加するには、既に格納されている出力を置き換える代わりに、変数名の前にプラス記号 (+) を入力します。

たとえば、次のコマンドは、 $out 変数を作成し、その中にプロセスオブジェクトを格納します。

Get-Process PowerShell -OutVariable out

次のコマンドは、プロセスオブジェクトを $out 変数に追加します。

Get-Process iexplore -OutVariable +out

次のコマンドは、 $out 変数の内容を表示します。

$out

注

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

パイプライン変数

PipelineVariable のエイリアスは pv で、文字列値を受け取ります。

PipelineVariable は、パイプラインを通過する名前付きコマンドについて、現在のパイプライン要素の値を変数として格納します。

有効な値は文字列であり、変数名の場合と同じです。

PipelineVariable のしくみの例を次に示します。この例では、 PipelineVariable パラメーターを Foreach-Object コマンドに追加して、コマンドの結果を変数に格納します。 1 から 10 までの数値の範囲が最初の Foreach-Object コマンドにパイプされ、その結果は Left という名前の変数に格納されます。

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

3 番目の Foreach-Object コマンドでは、最初の 2 つの Foreach-Object パイプコマンド (変数 Left と Right で表される) の結果が乗算演算子を使用して処理されます。このコマンドは、 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 のエイリアスは vb です。

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

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

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

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

警告アクション

WarningAction のエイリアスは wa です。

コマンドレットがコマンドからの警告に応答する方法を決定します。 Continue が既定値です。このパラメーターは、コマンドによって警告メッセージが生成された場合にのみ機能します。たとえば、このパラメーターは、コマンドに Write-Warning コマンドレットが含まれている場合に機能します。

WarningAction パラメーターは、現在のコマンドの$WarningPreference変数の値をオーバーライドします。 $WarningPreference変数の既定値は Continue であるため、WarningAction パラメーターを使用しない限り、警告が表示され、実行が続行されます。

-WarningAction:Continue は警告メッセージを表示し、コマンドの実行を続行します。 Continue はデフォルト値です。

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

-WarningAction:SilentlyContinue は警告メッセージを抑制し、コマンドの実行を続行します。

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

注

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

警告変数

WarningVariable のエイリアスは wv です。

コマンドに関する警告を、指定した変数に格納します。

生成されたすべての警告は、警告がユーザーに表示されない場合でも、変数に保存されます。

変数コンテンツに警告を追加するには、既に保存されている可能性がある警告を置き換える代わりに、変数名の前にプラス記号 (+) を入力します。

たとえば、次のコマンドは、 $a 変数を作成し、その変数に警告を格納します。

Get-Process -Id 6 -WarningVariable a

次のコマンドは、 $a 変数に警告を追加します。

Get-Process -Id 2 -WarningVariable +a

次のコマンドは、 $aの内容を表示します。

$a

このパラメーターを使用すると、特定のコマンドからの警告のみを含む変数を作成できます。 $a[0]や$warning[1,2]などの配列表記を使用して、変数に格納されている特定の警告を参照できます。

注

WarningVariable パラメーターは、関数またはスクリプト内のネストされた呼び出しからの警告をキャプチャしません。

リスク管理パラメーターの説明

ホワット・イフ

WhatIf のエイリアスは wi です。

コマンドを実行する代わりに、コマンドの効果を説明するメッセージを表示します。

WhatIf パラメーターは、現在のコマンドの$WhatIfPreference変数の値をオーバーライドします。 $WhatIfPreference変数の既定値は 0 (無効) であるため、WhatIf の動作は WhatIf パラメーターなしでは実行されません。詳細については、次のコマンドを入力します。

Get-Help about_Preference_Variables

-WhatIf:$true は、 -WhatIfと同じ効果を持ちます。

-WhatIf:$false では、 $WhatIfPreference 変数の値が 1 の場合に発生する WhatIf の自動動作が抑制されます。

たとえば、次のコマンドでは、-WhatIf コマンドで Remove-Item パラメーターを使用します。

Remove-Item Date.csv -WhatIf

PowerShell では、アイテムを削除する代わりに、実行する操作と影響を受けるアイテムが一覧表示されます。このコマンドでは次の出力が生成されます。

What if: Performing operation "Remove File" on
Target "C:\ps-test\date.csv".

確認する

Confirm のエイリアスは cf です。

コマンドを実行する前に確認メッセージを表示します。

Confirm パラメータは、現在のコマンドの $ConfirmPreference 変数の値を上書きします。これは既定値は true です。詳細については、次のコマンドを入力します。

Get-Help about_Preference_Variables

-Confirm:$true は、 -Confirmと同じ効果を持ちます。

-Confirm:$false は、 $ConfirmPreference の値がコマンドレットの推定リスク以下である場合に発生する自動確認を抑制します。

たとえば、次のコマンドでは、コマンドで 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] オプションは次のとおりです。

[応答]	結果
はい (Y)	アクションを実行します。
すべてはい(A)	すべてのアクションを実行し、後続の Confirm クエリを抑制します
	このコマンドの場合。
いいえ (N):	アクションを実行しないでください。
すべてにいいえ(L):	アクションを実行せず、後続の確認を抑制します
	このコマンドのクエリ。
サスペンド (S):	コマンドを一時停止し、一時的なセッションを作成します。
ヘルプ (?)	これらのオプションのヘルプを表示します。

[中断] オプションを選択すると、コマンドが保留になり、一時的に入れ子になったセッションが作成され、確認オプションを選択する準備ができるまで作業できます。入れ子になったセッションのコマンドプロンプトには、元の親コマンドの子操作であることを示す追加のキャレット (>>) が 2 つあります。入れ子になったセッションでコマンドとスクリプトを実行できます。ネストされたセッションを終了し、元のコマンドの [確認] オプションに戻るには、「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

キーワード

about_Common_Parameters