ja-JP/about_Parameters_Default_Values.help.txt
|
TOPIC about_Parameters_Default_Values 簡単な説明 コマンドレット、アドバンスト関数、スクリプトのパラメーターに対して 独自の既定値を設定する方法について説明します。 (PSHelpJaJP 日本語パッチ版) 詳細な説明 $PSDefaultParameterValues 設定変数を使うと、CmdletBinding 属性を 使用する任意のコマンドレット、アドバンスト関数、スクリプトに対して、 独自のパラメーター既定値を指定できます。定義した値は、コマンド ラインで別の値を指定しない限り使用されます。 この機能は、次のような場面で役立ちます。 - コマンドを使うたびに毎回同じパラメーター値を指定する場合 - 電子メールサーバー名やプロジェクトの GUID など、覚えにくい 特定のパラメーター値を指定する場合 $PSDefaultParameterValues 変数には既定値がありません。設定を今後の セッションでも使うには、この変数への代入を PowerShell プロファイル に追加してください。 $PSDefaultParameterValues は PowerShell 3.0 で導入されました。 構文 $PSDefaultParameterValues 変数は、 System.Management.Automation.DefaultParameterDictionary 型の オブジェクトです。DefaultParameterDictionary 型は、キーの形式に 関する追加の検証を備えたハッシュテーブルです。このハッシュテーブル には、次のようなキーと値のペアが格納されます。 - キーは CommandName:ParameterName という形式です - 値は、パラメーターの既定値、または既定値を返す ScriptBlock です キーにおいて、CommandName は、CmdletBinding 属性を使用する コマンドレット、アドバンスト関数、またはスクリプトファイルの名前で なければなりません。スクリプト名は、 (Get-Command -Name .\script.ps1).Name で報告される名前と一致する 必要があります。 メモ: PowerShell では、CommandName にエイリアスを指定することを 妨げません。ただし、その定義が無視されたり、エラーの原因に なったりする場合があります。コマンドのエイリアスに対して既定値を 定義するのは避けてください。 値には、パラメーターと互換性のある型のオブジェクト、または そのような値を返す 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' } コマンドレット名とパラメーター名にはワイルドカード文字を 使用できます。Verbose などの [switch] パラメーターに値を 設定するには $true と $false を使います。次の例では、共通 パラメーター 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 キーは、その [switch] パラメーターの 既定値を $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 を無効化するには、値が $true の Disabled キーを追加します。$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 ---- 原文: PowerShell-Docs (CC BY 4.0) の翻訳 / PSHelpJaJP |