about_Parameters_Default_Values

簡単な説明

コマンドレット パラメーター、高度な関数、スクリプトのカスタム既定値を設定する方法について説明します。

長い説明

$PSDefaultParameterValues 基本設定変数を使用すると、CmdletBinding 属性を使用するすべてのコマンドレット、高度な関数、またはスクリプトにカスタムの既定のパラメーター値を指定できます。 定義された値は、コマンド ラインで他の値を指定しない限り使用されます。

この機能は、次のシナリオで役立ちます。

• コマンドを使用するたびに同じパラメーター値を指定する
• 電子メール サーバー名やプロジェクト GUID など、覚えにくい特定のパラメーター値を指定する

$PSDefaultParameterValues 変数には既定値がありません。 今後のセッションで使用する設定を保存するには、変数の割り当てを PowerShell プロファイルに追加します。

$PSDefaultParameterValues は PowerShell 3.0 で導入されました。

構文

変数は、System.Management.Automation.DefaultParameterDictionaryオブジェクト型です。 DefaultParameterDictionary 型はハッシュテーブルであり、キーの形式に対して追加の検証が行われます。 ハッシュテーブルにはキーと値のペアが含まれています。

• キー の形式は CommandName:ParameterName
• パラメーターの既定値としての値、または既定値を返す ScriptBlock

キーの場合、CommandName は、CmdletBinding 属性を使用するコマンドレット、高度な関数、またはスクリプト ファイルの名前である必要があります。 スクリプト名は、(Get-Command -Name .\script.ps1).Nameによって報告された名前と一致する必要があります。

値 には、パラメーターと互換性のある型のオブジェクト、またはそのような値を返す ScriptBlock を指定できます。 値がスクリプト ブロックの場合、PowerShell はスクリプト ブロックを評価し、パラメーター値の結果を使用します。 指定したパラメーターで ScriptBlock 型が必要な場合は、値を別の中かっこで囲む必要があります。 PowerShell が外部の ScriptBlockを評価すると、結果は内部 ScriptBlockになります。 内部 ScriptBlock が新しい既定のパラメーター値になります。

例えば：

$PSDefaultParameterValues = @{
    'Invoke-Command:ScriptBlock' = { {Get-Process} }
}

例示

Add() メソッドと Remove() メソッドを使用して、他の既存のキーと値のペアを上書きせずに、特定のキーと値のペアを $PSDefaultParameterValues に追加または削除します。

$PSDefaultParameterValues.Add('CmdletName:ParameterName', 'DefaultValue')
$PSDefaultParameterValues.Remove('CmdletName:ParameterName')

既存のキーと値のペアの値を変更するには、インデックス作成またはメンバー アクセスを使用します。 例えば：

$PSDefaultParameterValues.'CommandName:ParameterName'='DefaultValue2'
$PSDefaultParameterValues['CommandName:ParameterName']='DefaultValue1'

$PSDefaultParameterValues に値を割り当てる

コマンドレット パラメーターの既定値を定義するには、適切なキーと値のペアを含むハッシュテーブルを $PSDefaultParameterValues 変数に割り当てます。 ハッシュテーブルには、複数のキーと値のペアを含めることができます。 次の使用例は、Send-MailMessage:SmtpServer キーと Get-WinEvent:LogName キーの既定値を設定します。

$PSDefaultParameterValues = @{
  'Send-MailMessage:SmtpServer'='Server123'
  'Get-WinEvent:LogName'='Microsoft-Windows-PrintService/Operational'
}

コマンドレットとパラメーター名には、ワイルドカード文字を含めることができます。 $trueと$falseを使用して、Verbose などのスイッチ パラメーターの値を設定します。 次の使用例は、すべてのコマンドの共通パラメーター Verbose を $true に設定します。

$PSDefaultParameterValues = @{'*:Verbose'=$true}

パラメーターが複数の値を受け入れる場合は、配列を使用して複数の既定値を指定できます。 次の使用例は、Invoke-Command:ComputerName キーの既定値を、Server01 および Server02文字列値を含む配列に設定します。

$PSDefaultParameterValues = @{
  'Invoke-Command:ComputerName' = 'Server01', 'Server02'
}

定義された値を表示する

$PSDefaultParameterValuesの次の定義について考えてみましょう。

$PSDefaultParameterValues = @{
  'Send-MailMessage:SmtpServer' = 'Server123'
  'Get-WinEvent:LogName' = 'Microsoft-Windows-PrintService/Operational'
  'Get-*:Verbose' = $true
}

コマンド プロンプトで「$PSDefaultParameterValues」と入力すると、定義された値を表示できます。

PS> $PSDefaultParameterValues

Name                           Value
----                           -----
Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
Get-*:Verbose                  True
Send-MailMessage:SmtpServer    Server123

インデックス作成またはメンバー アクセスを使用して、特定の値を取得できます。

PS> $PSDefaultParameterValues['Send-MailMessage:SmtpServer'] # index notation
Server123
PS> $PSDefaultParameterValues.'Get-*:Verbose' # member access notation
True

既定値にスクリプト ブロックを使用する

スクリプト ブロックを使用すると、さまざまな条件下でパラメーターに異なる既定値を指定できます。 PowerShell はスクリプト ブロックを評価し、その結果を既定のパラメーター値として使用します。

Format-Table:AutoSize キーは、パラメーターを既定値 $true に設定します。if ステートメントには、$Host.Name を ConsoleHostする必要がある条件が含まれています。

$PSDefaultParameterValues = @{
  'Format-Table:AutoSize' = { if ($Host.Name -eq 'ConsoleHost'){$true} }
}

パラメーターが ScriptBlock 値を受け取る場合は、ScriptBlock を別の中かっこで囲みます。 PowerShell が外部の ScriptBlockを評価すると、結果は内部 ScriptBlockになります。 内部 ScriptBlock が新しい既定のパラメーター値になります。

$PSDefaultParameterValues = @{
  'Invoke-Command:ScriptBlock' = { {Get-EventLog -Log System} }
}

既存の $PSDefaultParameterValues 変数に値を追加する

$PSDefaultParameterValuesに値を追加するには、Add() メソッドを使用します。 値を追加しても、ハッシュテーブルの既存の値には影響しません。 コンマ (,) を使用して、キー を 値区切ります。

$PSDefaultParameterValues.Add('Get-Process:Name', 'PowerShell')

前の例で作成したハッシュテーブルは、新しいキーと値のペアで更新されます。

PS> $PSDefaultParameterValues

Name                           Value
----                           -----
Get-Process:Name               PowerShell
Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
Get-*:Verbose                  True
Send-MailMessage:SmtpServer    Server123

$PSDefaultParameterValues から値を削除する

$PSDefaultParameterValuesから値を削除するには、Remove() メソッドを使用します。 値を削除しても、ハッシュテーブルの既存の値には影響しません。

この例では、前の例で追加したキーと値のペアを削除します。

PS> $PSDefaultParameterValues.Remove('Get-Process:Name')
PS> $PSDefaultParameterValues

Name                           Value
----                           -----
Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
Get-*:Verbose                  True
Send-MailMessage:SmtpServer    Server123

$PSDefaultParameterValues の値を変更する

既存のキーと値のペアの既定値を変更するには、インデックス作成またはメンバー アクセスを使用します。 この例では、Send-MailMessage:SmtpServer キーの既定値が新しい値 ServerXYZに変更されています。

PS> $PSDefaultParameterValues['Send-MailMessage:SmtpServer']='ServerXYZ'
PS> $PSDefaultParameterValues

Name                           Value
----                           -----
Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
Get-*:Verbose                  True
Send-MailMessage:SmtpServer    ServerXYZ

$PSDefaultParameterValues を無効または再度有効にする

一時的に無効にしてから、 $PSDefaultParameterValuesを再度有効にすることができます。 $PSDefaultParameterValuesを無効にすると、異なる既定のパラメーター値を必要とするスクリプトを実行する場合に便利です。

$PSDefaultParameterValuesを無効にするには、Disabledの値を持つ $true のキーを追加します。 $PSDefaultParameterValues の値は保持されますが、使用されません。

PS> $PSDefaultParameterValues.Add('Disabled', $true)
PS> $PSDefaultParameterValues

Name                           Value
----                           -----
Disabled                       True
Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
Get-*:Verbose                  True
Send-MailMessage:SmtpServer    ServerXYZ

$PSDefaultParameterValuesを再度有効にするには、Disabled キーを削除するか、Disabled キーの値を $falseに変更します。

PS> $PSDefaultParameterValues.Disabled = $false
PS> $PSDefaultParameterValues

Name                           Value
----                           -----
Disabled                       False
Get-WinEvent:LogName           Microsoft-Windows-PrintService/Operational
Get-*:Verbose                  True
Send-MailMessage:SmtpServer    ServerXYZ

こちらも参照ください

• about_CommonParameters
• about_Functions_Advanced
• about_Functions_CmdletBindingAttribute
• about_Hash_Tables
• about_Preference_Variables
• about_Profiles
• about_Script_Blocks