about_Parameters_Default_Values

  • [アーティクル]

適用対象: Windows PowerShell 3.0

トピック

about_Parameters_Default_Values

簡単な説明

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

詳細な説明

ユーザー設定変数 $PSDefaultParameterValues を使うと、あらゆるコマンドレットや高度な関数にカスタムの既定値を指定できます。コマンドレットや関数は、コマンドで別の値を指定しない限り、指定したカスタムの既定値を使用します。

コマンドレットと高度な関数の作成者は、それらのパラメータに標準の既定値を設定しています。通常、標準の既定値は便利ですが、すべての環境に適しているとは限りません。

この機能は、コマンドを使用するたび毎回のように同じ代替パラメーター値を指定する必要がある場合、または特定のパラメーターの値が、電子メール サーバー名またはプロジェクト GUID のように覚えにくい場合に特に便利です。

使用する既定値が規則正しく変化する場合は、スクリプト ブロックを指定してさまざまな条件に応じた異なる既定値を使用することができます。

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

構文

$PSDefaultParameterValues ユーザー設定変数の構文は次のとおりです。

       $PSDefaultParameterValues=@{"<CmdletName>:<ParameterName>"="<DefaultValue>"}

       $PSDefaultParameterValues=@{"<CmdletName>:<ParameterName>"={<ScriptBlock>}}

       $PSDefaultParameterValues["Disabled"]=$true | $false

CmdletName と ParameterName の値にはワイルドカード文字を使用することができます。

$PSDefaultParameterValues の値はSystem.Management.Automation.DefaultParameterDictionary という、キーの形式を検証するあるハッシュ テーブルで得られます。キーがコロン (:) で区切られたコマンドレット名とパラメーター名からなり、カスタムの既定値を値にとるハッシュ テーブルを指定してください。

$PSDefaultParameterValues からエントリを設定、変更、追加、または削除するには、標準的なハッシュ テーブルの編集に使用するメソッドを使用します。

<CmdletName> は、コマンドレットまたは CmdletBinding 属性を使用する高度な関数の名前である必要があります。$PSDefaultParameterValues を使用して、スクリプトまたは単純な関数の既定値を指定することはできません。

既定値にはオブジェクトまたはスクリプト ブロックを使用できます。値がスクリプト ブロックである場合、Windows PowerShell はスクリプト ブロックを評価してその結果をパラメータ値として使用します。指定したパラメーターがスクリプト ブロックの値を取る場合、スクリプト ブロックの値を次の様に中かっこで二重に囲みます。$PSDefaultParameterValues=@{ "Invoke-Command:ScriptBlock"={{Get-Process}} }

ハッシュ テーブルの詳細ついては、about_Hash_Tables を参照してください。スクリプト ブロックの詳細については、about_Script_Blocks を参照してください。ユーザー設定変数の詳細については、about_Preference_Variables を参照してください。

例

次のコマンドでは、Send-MailMessage コマンドレットの SmtpServer パラメーターをカスタムの既定値に設定します。

        $PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5"}

複数のパラメーターの既定値を設定するには、セミコロン (;) を使用してそれぞれの名前 = 値のペアを区切ります。次のコマンドは、Get-WinEvent コマンドレットの LogName パラメーターにカスタムの既定値を追加します。

        $PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5";
               "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational"}

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

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

パラメーターが複数の値 (配列) を取る場合は、既定値に複数の値を設定できます。次のコマンドでは、Invoke-command コマンドレットの ComputerName パラメーターの既定値を "Server01" と "Server02" に設定します。

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

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

ホスト プログラムが Windows PowerShell コンソールの場合、以下のコマンドは Format-Table コマンドレットの Autosize パラメータの既定値を $true に設定します。

        $PSDefaultParameterValues=@{"Format-Table:AutoSize"={if ($host.Name –eq "ConsoleHost"){$true}}}

パラメーターがスクリプト ブロックの値を取る場合、スクリプト ブロックを囲む中かっこを一組増やします。Windows PowerShell が外側のスクリプト ブロックを評価すると内側のスクリプト ブロックが生成され、それが既定パラメータ値として設定されます。

次のコマンドは、Invoke-command コマンドレットの ScriptBlock パラメーターの既定値を設定します。このスクリプト ブロックは、中かっこで二重に囲まれているため、中のスクリプト ブロックが Invoke-command コマンドレットに引き渡されます。

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

$PSDefaultParameterValues の設定方法

$PSDefaultParameterValues はユーザー設定変数のため、設定されたセッション内にのみ存在します。既定値はありません。

$PSDefaultParameterValues を設定するには、コマンド ラインで変数名と 1 つ以上のキーと値のペアを入力します。

別の $PSDefaultParameterValues コマンドを入力すると、元の値は新しいコマンドの値で置き換えられます。元のコマンドとその値は保持されません。

後のセッションのために $PSDefaultParameterValues を保存するには、$PSDefaultParameterValues コマンドを Windows PowerShell プロファイルに追加します。詳細については、about_Profiles を参照してください。

$PSDefaultParameterValues の取得方法

コマンドプロンプトで $PSDefaultParameterValues の値を取得するには、次の文字列を入力します:$PSDefaultParameterValues

たとえば、以下の1つ目のコマンドは $PSDefaultParameterValues の値を設定しています。2 番目のコマンドは、$PSDefaultParameterValues の値を取得します。

        PS C:\> $PSDefaultParameterValues = @{"Send-MailMessage:SmtpServer"="Server01AB234x5";
                "Get-WinEvent:LogName"="Microsoft-Windows-PrintService/Operational";
                "Get-*:Verbose"=$true}

        PS C:\> $PSDefaultParameterValues

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

<CmdletName:ParameterName> キーの値を取得するには、以下のコマンド構文を使用します。

       $PSDefaultParameterValues["<CmdletName:ParameterName>"]

使用例は、以下のとおりです。

       PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"]
       Server01AB234x5

$PSDefaultParameterValues に値を追加する方法

$PSDefaultParameterValues から値を追加または削除するには、標準的なハッシュ テーブルの編集に使用するメソッドを使用します。

たとえば、既存の値に影響を与えずに $PSDefaultParameterValues に値を追加するには、ハッシュ テーブルの Add メソッドを使用します。

Add メソッドの構文は次のとおりです。

        <HashTable>.Add(Key, Value)

Key には "<CmdletName>:<ParameterName>" という形式の文字列を、Value にはパラメータ値を入力します。

次のコマンド形式を使用して、$PSDefaultParameterValues の Add メソッドを呼び出します。キーと値を区切るにはにコンマ (,) を使用し、等号 (=) を使わないよう注意してください。

        $PSDefaultParameterValues.Add("<CmdletName>:<ParameterName>", "<ParameterValue>")

たとえば、次のコマンドでは Get-process コマンドレットの Name パラメーターの既定値として "PowerShell" を追加します。

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

次の例は、このコマンドの働きを表しています。

        PS C:\> $PSDefaultParameterValues

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

        PS C:\> $PSDefaultParameterValues.Add("Get-Process:Name", "PowerShell")

        PS C:\> $PSDefaultParameterValues

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

$PSDefaultParameterValues から値を削除する方法

$PSDefaultParameterValues から値を削除するには、ハッシュ テーブルの Remove メソッドを使用します。

Remove メソッドの構文は次のとおりです。

        <HashTable>.Remove(Key)

次のコマンド形式を使用して、$PSDefaultParameterValues の Remove メソッドを呼び出します。

        $PSDefaultParameterValues.Remove("<CmdletName>:<ParameterName>")

たとえば、次のコマンドは Get-process コマンドレットとその値の Name パラメーターを削除します。

        $PSDefaultParameterValues.Remove("Get-Process:Name")

次の例は、このコマンドの働きを表しています。

        PS C:\> $PSDefaultParameterValues

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

        PS C:\> $PSDefaultParameterValues.Remove("Get-Process:Name")

        PS C:\> $PSDefaultParameterValues

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

$PSDefaultParameterValues の値を変更する方法

$PSDefaultParameterValues 内の値を変更するには、次のコマンド形式を使用します。

        $PSDefaultParameterValues["CmdletName:ParameterName"]="<NewValue>"

次の例は、このコマンドの働きを表しています。

        PS C:\> $PSDefaultParameterValues

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

        PS C:\> $PSDefaultParameterValues["Send-MailMessage:SmtpServer"]="Server0000cabx5"
   
        PS C:\> $PSDefaultParameterValues

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

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

$PSDefaultParameterValues を一時的に無効化し、その後改めて有効化することができます。これは、異なる既定のパラメーター値を仮定することがあるスクリプトを実行している場合に便利です。

$PSDefaultParameterValues を無効にするには、$True を値に取る "Disabled" キーを追加します。

たとえば、

        $PSDefaultParameterValues.Add("Disabled", $true)

        - or -

        $PSDefaultParameterValues[Disabled]=$true

$PSDefaultParameterValues 内の他の値は保存されていますが有効ではありません。

        PS C:\> $PSDefaultParameterValues

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

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

        $PSDefaultParameterValues.Remove("Disabled")

- or -

        $PSDefaultParameterValues[Disabled]=$false

$PSDefaultParameterValues の以前の値が再度有効になります。

キーワード

about_PSDefaultParameterValues

about_Parameters_DefaultValues

about_DefaultValues

関連項目

about_Hash_Tables

about_Preference_Variables

about_Profiles

about_Script_Blocks