about_Functions_Advanced_Parameters

簡単な説明

高度な関数にパラメーターを追加する方法について説明します。

長い説明

記述する高度な関数にパラメーターを追加し、パラメーターの属性と引数を使用して、関数ユーザーがパラメーターと共に送信するパラメーター値を制限できます。

CmdletBinding属性を使用すると、PowerShell によって共通パラメーターが自動的に追加されます。共通パラメーターと同じ名前を使用するパラメーターは作成できません。詳細については、「about_CommonParameters」を参照してください。

PowerShell 3.0 以降では、 @args でスプラッティングを使用して、コマンド内のパラメーターを表すことができます。スプラッティングは、シンプルで高度な機能で有効です。詳細については、「 about_Functions と about_Splatting」を参照してください。

パラメーターの宣言

パラメーターは、関数または scriptblock の param() ステートメントで宣言された変数です。省略可能な [Parameter()] 属性を単独で使用することも、[Alias()] 属性またはその他のパラメーター検証属性と組み合わせて使用することもできます。

パラメーター名は変数名の規則に従います。パラメーター名は、10 進数、アルファベット文字、およびアンダースコアで構成されます。命名規則の完全な一覧については、about_Variablesを参照してください。

重要

10 進数字で始まるパラメーターを定義できます。 PowerShell では位置指定パラメーターとして渡される文字列値として扱われるため、数字でパラメーター名を開始することはお勧めしません。

次に例を示します。

function TestFunction {
    param (
        [switch] $100,
        [string] $200
    )

    "100: $100"
    "200: $200"
}

パラメーターを使用しようとすると、PowerShell はそれらを位置指定パラメーターとして渡された文字列として解釈します。

PS> TestFunction -100 -200 Hello
100: False
200: -100
$args: -200 Hello

出力結果では、PowerShell が -100 値を $200 パラメーター変数にバインドしたことを示しています。残りの位置値は、$argsにバインドされます。この問題を回避するには、スプラッティングを利用してパラメーター値を渡すことができます。

PS> $ht = @{100 = $true; 200 = 'Hello'}
PS> TestFunction @ht
100: True
200: Hello
$args:

詳しくは、about_Splattingを参照してください。

パラメーター値の型変換

異なる型を想定するパラメーターに文字列を引数として指定すると、PowerShell は文字列をパラメーターターゲット型に暗黙的に変換します。高度な関数は、パラメーター値のカルチャに依存しない解析を実行します。

これに対し、カルチャに依存する変換は、コンパイルされたコマンドレットのパラメーターバインド中に実行されます。

この例では、 [datetime] パラメーターを受け取るコマンドレットとスクリプト関数を作成します。現在のカルチャは、ドイツ語の設定を使用するように変更されます。ドイツ語形式の日付がパラメーターに渡されます。

# Create a cmdlet that accepts a [datetime] argument.
Add-Type @'
  using System;
  using System.Management.Automation;
  [Cmdlet("Get", "Date_Cmdlet")]
  public class GetFooCmdlet : Cmdlet {

    [Parameter(Position=0)]
    public DateTime Date { get; set; }

    protected override void ProcessRecord() {
      WriteObject(Date);
    }
  }
'@ -PassThru | % Assembly | Import-Module

[cultureinfo]::CurrentCulture = 'de-DE'
$dateStr = '19-06-2018'

Get-Date_Cmdlet $dateStr

Dienstag, 19. Juni 2018 00:00:00

上記のように、コマンドレットはカルチャに依存する解析を使用して文字列を変換します。

# Define an equivalent function.
function Get-Date_Func {
  param(
    [datetime] $Date
  )
  process {
    $Date
  }
}

[cultureinfo]::CurrentCulture = 'de-DE'

# This German-format date string doesn't work with the invariant culture.
# E.g., [datetime] '19-06-2018' breaks.
$dateStr = '19-06-2018'

Get-Date_Func $dateStr

高度な関数では、カルチャに依存しない解析が使用されるため、次のエラーが発生します。

Get-Date_Func: Cannot process argument transformation on parameter 'Date'.
Cannot convert value "19-06-2018" to type "System.DateTime". Error:
"String '19-06-2018' was not recognized as a valid DateTime."

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

静的パラメーター

静的パラメーターは、関数で常に使用できるパラメーターです。 PowerShell コマンドレットとスクリプトのほとんどのパラメーターは静的パラメーターです。

次の例は、次の特性を持つ ComputerName パラメーターの宣言を示しています。

必須です (必須)。
パイプラインから入力を受け取ります。
文字列の配列を入力として受け取ります。

param(
    [Parameter(Mandatory=$true, ValueFromPipeline=$true)]
    [string[]]$ComputerName
)

パラメーターの切り替え

スイッチパラメーターは、パラメーター値を受け取っていないパラメーターです。代わりに、ブール型の true または false の値が存在するか、存在しないかを伝えます。そのため、switch パラメーターが存在する場合は true 値を持ち、存在しない場合は false 値になります。

たとえば、の Get-ChildItem パラメーターは switch パラメーターです。

関数に switch パラメーターを作成するには、パラメーター定義で [switch] 型を指定します。次の例は、データをバイト配列として出力するオプションを提供するために使用できる switch パラメーターの定義を示しています。

param([switch]$AsByteArray)

スイッチパラメーターは使いやすく、PowerShell の構文があまり自然でないブール型パラメーターよりも優先されます。

switch パラメーターを使用するには、コマンドにパラメーターを含めます。次に例を示します。

-IncludeAll

Boolean パラメーターを使用するには、パラメーターとブール値を指定する必要があります。

-IncludeAll $true

スイッチパラメーターを作成するときは、パラメーター名を慎重に選択します。パラメーター名がパラメーターの効果をユーザーに伝えるようにしてください。 Filter や Maximum など、値が必要であることを意味するあいまいな用語は避けてください。

スイッチパラメーターの設計に関する考慮事項

スイッチパラメーターの既定値を設定しないでください。 Switch パラメーターは常に既定で false に設定されます。
スイッチパラメーターを位置指定しないでください。既定では、スイッチパラメーターは位置指定パラメーターから除外されます。 Parameter 属性でそれをオーバーライドが、ユーザーを混乱させる可能性があります。
パラメーターを使用してコマンドの既定の動作をあまり一般的ではない、または複雑なモードに変更するようにスイッチパラメーターを設計します。コマンドの最も簡単な動作は、スイッチパラメーターを使用する必要のない既定の動作です。
スイッチパラメーターを必須にしないでください。 switch パラメーターを必須にすることが役立つ唯一のケースは、パラメーターセットを区別する必要がある場合です。
switch パラメーター変数は、条件式で直接使用します。 SwitchParameter 型は、暗黙的にブール型に変換されます。次に例を示します。
```
if ($MySwitch) { ... }
```
常にスイッチによって制御される動作は、パラメーターの存在ではなく、スイッチの値に基づいて行います。スイッチパラメーターの有無をテストするには、いくつかの方法があります。
- スイッチパラメーター名をキーとして含む $PSBoundParameters
- スイッチパラメーター名をキーとして含む $MyInvocation.BoundParameters
- スイッチが一意のパラメーターセットを定義する場合の $PSCmdlet.ParameterSetName
たとえば、-MySwitch:$false またはスプラッティングを使用して、スイッチに明示的な値を指定できます。パラメーターの有無のみをテストする場合、コマンドはスイッチ値が $trueではなく $false かのように動作します。

動的パラメーター

動的パラメーターは、特定の条件下でのみ使用できるコマンドレット、関数、またはスクリプトのパラメーターです。

たとえば、いくつかのプロバイダーコマンドレットには、プロバイダードライブまたはプロバイダードライブの特定のパスでコマンドレットが使用されている場合にのみ使用できるパラメーターがあります。たとえば、 Encoding パラメーターは、ファイルシステムドライブで使用されている場合にのみ、 Add-Content、 Get-Content、および Set-Content コマンドレットで使用できます。

関数コマンドで別のパラメーターが使用されている場合、または別のパラメーターに特定の値がある場合にのみ表示されるパラメーターを作成することもできます。

動的パラメーターは便利ですが、ユーザーが検出するのが困難な場合があるため、必要な場合にのみ使用します。動的パラメーターを検索するには、ユーザーがプロバイダーパスに存在するか、コマンドレットの Get-Command パラメーターを使用するか、の Get-Help パラメーターを使用する必要があります。

関数またはスクリプトの動的パラメーターを作成するには、 dynamicparam キーワードを使用します。

構文は次のとおりです。

dynamicparam {<statement-list>}

ステートメントの一覧で、 if ステートメントを使用して、関数でパラメーターを使用できる条件を指定します。

次の例は、 Name および Path という名前の標準パラメーターを持つ関数と、 KeyCount という名前の省略可能な動的パラメーターを示しています。 KeyCount パラメーターは、ByRegistryPath パラメーターセット内にあり、Int32の型を持っています。 KeyCount パラメーターは、Get-Sample パラメーターの値がで始まり、HKLM: レジストリドライブで使用されていることを示す場合にのみ、HKEY_LOCAL_MACHINE関数で使用できます。

function Get-Sample {
  [CmdletBinding()]
  param([string]$Name, [string]$Path)

  dynamicparam
  {
    if ($Path.StartsWith("HKLM:"))
    {
      $parameterAttribute = [System.Management.Automation.ParameterAttribute]@{
          ParameterSetName = "ByRegistryPath"
          Mandatory = $false
      }

      $attributeCollection = [System.Collections.ObjectModel.Collection[System.Attribute]]::new()
      $attributeCollection.Add($parameterAttribute)

      $dynParam1 = [System.Management.Automation.RuntimeDefinedParameter]::new(
        'KeyCount', [int32], $attributeCollection
      )

      $paramDictionary = [System.Management.Automation.RuntimeDefinedParameterDictionary]::new()
      $paramDictionary.Add('KeyCount', $dynParam1)
      return $paramDictionary
    }
  }
}

詳細については、 RuntimeDefinedParameter 型のドキュメントを参照してください。

パラメーターの属性

このセクションでは、関数パラメーターに追加できる属性について説明します。

すべての属性は省略可能です。ただし、 CmdletBinding 属性を省略し、高度な関数として認識するには、 Parameter 属性を含める必要があります。

各パラメーター宣言には、1 つまたは複数の属性を追加できます。パラメーター宣言に追加できる属性の数に制限はありません。

パラメーター属性

Parameter 属性は、関数パラメーターの属性を宣言するために使用されます。

Parameter 属性は省略可能であり、関数のどのパラメーターにも属性が必要ない場合は省略できます。ただし、単純な関数ではなく高度な関数として認識するには、関数に CmdletBinding 属性または Parameter 属性、またはその両方が必要です。

Parameter属性には、パラメーターが必須か省略可能かなど、パラメーターの特性を定義する引数があります。

Parameter属性、引数、および引数値を宣言するには、次の構文を使用します。引数とその値を囲むかっこは、 Parameter の後にスペースを入れてはなりません。

param(
    [Parameter(Argument=value)]
    $ParameterName
)

かっこ内の引数を区切るには、コンマを使用します。 Parameter 属性の 2 つの引数を宣言するには、次の構文を使用します。

param(
    [Parameter(Argument1=value1, Argument2=value2)]
    $ParameterName
)

Parameter 属性から省略すると、Parameter 属性のブール型は既定で False になります。引数の値を $true に設定するか、単に名前で引数を一覧表示します。たとえば、次の Parameter 属性は同等です。

param(
    [Parameter(Mandatory=$true)]
)

# Boolean arguments can be defined using this shorthand syntax

param(
    [Parameter(Mandatory)]
)

引数を指定せずに Parameter 属性を使用する場合は、 CmdletBinding 属性の後に続くかっこが必要です。

param(
    [Parameter()]
    $ParameterName
)

必須引数

Mandatory引数は、パラメーターが必要であることを示します。この引数が指定されていない場合、パラメーターは省略可能です。

次の例では、 ComputerName パラメーターを宣言します。 Mandatory引数を使用して、パラメーターを必須にします。

param(
    [Parameter(Mandatory)]
    [string[]]$ComputerName
)

引数 Position

Position引数は、パラメーターをコマンドで使用するときにパラメーター名が必要かどうかを決定します。パラメーター宣言に Position 引数が含まれている場合は、パラメーター名を省略でき、PowerShell は、コマンド内の名前のないパラメーター値のリスト内の位置 (順序) によって、名前のないパラメーター値を識別します。

Position引数が指定されていない場合、パラメーター名、またはパラメーター名の別名または省略形は、パラメーターがコマンドで使用されるたびにパラメーター値の前に置く必要があります。

既定では、すべての関数パラメーターは位置指定です。 PowerShell では、関数でパラメーターが宣言された順序で、パラメーターに位置番号が割り当てられます。この機能を無効にするには、PositionalBinding 属性の引数の値を$falseに設定します。 Position引数は、PositionalBinding 属性の引数の値よりも優先されます。詳細については、PositionalBindingのを参照してください。

Position引数の値は整数として指定されます。 0 の位置値コマンドの最初の位置を表し、1 の位置の値コマンド内の 2 番目の位置などを表します。

関数に位置指定パラメーターがない場合、PowerShell はパラメーターが宣言されている順序に基づいて各パラメーターに位置を割り当てます。ただし、ベストプラクティスとして、この割り当てには依存しないでください。パラメーターを位置指定する場合は、 Position 引数を使用します。

次の例では、 ComputerName パラメーターを宣言します。値が Position の引数を使用します。その結果、コマンドから -ComputerName を省略した場合、その値はコマンドの最初のパラメーター値または唯一の名前のないパラメーター値である必要があります。

param(
    [Parameter(Position=0)]
    [string[]]$ComputerName
)

ParameterSetName 引数

ParameterSetName引数は、パラメーターが属するパラメーターセットを指定します。パラメーターセットが指定されていない場合、パラメーターは関数によって定義されているすべてのパラメーターセットに属します。一意にするには、各パラメーターセットに、他のパラメーターセットのメンバーではないパラメーターが少なくとも 1 つ必要です。

Note

コマンドレットまたは関数の場合、パラメーターセットは 32 個に制限されています。

次の例では、パラメーターセットの Computer パラメーター、パラメーターセットの User パラメーター、および両方のパラメーターセットの Summary パラメーターを宣言します。

param(
    [Parameter(Mandatory, ParameterSetName="Computer")]
    [string[]]$ComputerName,

    [Parameter(Mandatory, ParameterSetName="User")]
    [string[]]$UserName,

    [Parameter()]
    [switch]$Summary
)

各引数には 1 つのParameterSetName値のみを指定でき、各ParameterSetName属性には 1 つの引数のみを指定できます。複数のパラメーターセットにパラメーターを含めるには、 Parameter 属性を追加します。

次の例では、 Summary パラメーターを Computer および User パラメーターセットに明示的に追加します。 Summary パラメーターは、Computer パラメーターセットでは省略可能で、User パラメーターセットでは必須です。

param(
    [Parameter(Mandatory, ParameterSetName="Computer")]
    [string[]]$ComputerName,

    [Parameter(Mandatory, ParameterSetName="User")]
    [string[]]$UserName,

    [Parameter(ParameterSetName="Computer")]
    [Parameter(Mandatory, ParameterSetName="User")]
    [switch]$Summary
)

パラメーターセットの詳細については、「 About パラメーターセット」を参照してください。

ValueFromPipeline 引数

ValueFromPipeline引数は、パラメーターがパイプラインオブジェクトからの入力を受け入れることを示します。関数がオブジェクトのプロパティだけでなく、オブジェクト全体を受け入れる場合は、この引数を指定します。

次の例では、必須の ComputerName パラメーターを宣言し、パイプラインから関数に渡されるオブジェクトを受け入れます。

param(
    [Parameter(Mandatory, ValueFromPipeline)]
    [string[]]$ComputerName
)

ValueFromPipelineByPropertyName 引数

ValueFromPipelineByPropertyName引数は、パラメーターがパイプラインオブジェクトのプロパティからの入力を受け入れることを示します。オブジェクトプロパティには、パラメーターと同じ名前またはエイリアスが必要です。

たとえば、関数に ComputerName パラメーターがあり、パイプされたオブジェクトに ComputerName プロパティがある場合、 ComputerName プロパティの値は関数の ComputerName パラメーターに割り当てられます。

次の例では、必須の ComputerName パラメーターを宣言し、パイプラインを介して関数に渡されるオブジェクトの ComputerName プロパティからの入力を受け入れます。

param(
    [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
    [string[]]$ComputerName
)

次の引数を使用して関数を実装することを検討してください。

function Test-ValueFromPipelineByPropertyName{
  param(
      [Parameter(Mandatory, ValueFromPipelineByPropertyName)]
      [string[]]$ComputerName
  )
  Write-Output -InputObject "Saw that ComputerName was '$ComputerName'"
}

次に、 ComputerName プロパティを使用してオブジェクトをパイプ処理する例を次に示します。

[pscustomobject]@{ ComputerName = "HelloWorld" } |
    Test-ValueFromPipelineByPropertyName

Saw that ComputerName was 'HelloWorld'

Note

パイプライン入力 (by Value) または (by PropertyName) を受け入れる型指定されたパラメーターを使用すると、パラメーターで 遅延バインド スクリプトブロックを使用できます。

遅延バインド スクリプトブロックは、ParameterBinding 中に自動的に実行されます。結果はパラメーターにバインドされます。遅延バインディングは、型 ScriptBlock または System.Object として定義されているパラメーターでは機能しません。 scriptblock は呼び出 されず に渡されます。 遅延バインド スクリプトブロックの詳細については、about_Script_Blocksを参照してください。

ValueFromRemainingArguments 引数

ValueFromRemainingArguments引数は、パラメーターが、関数の他のパラメーターに割り当てられていないコマンド内のすべてのパラメーター値を受け入れることを示します。

次の例では、必須の Value パラメーターと、関数に送信される残りのパラメーター値をすべて受け取る Remaining パラメーターを宣言します。

function Test-Remainder {
    param(
        [Parameter(Mandatory, Position=0)]
        [string]$Value,

        [Parameter(Position=1, ValueFromRemainingArguments)]
        [string[]]$Remaining
    )

    "Found $($Remaining.Count) elements"

    for ($i = 0; $i -lt $Remaining.Count; $i++) {
        "${i}: $($Remaining[$i])"
    }
}
Test-Remainder first one, two

Found 2 elements
0: one
1: two

HelpMessage 引数

HelpMessage引数は、パラメーターまたはその値の簡単な説明を含む文字列を指定します。必須パラメーターを指定せずにコマンドを実行すると、PowerShell によって入力が求められます。ヘルプメッセージを表示するには、プロンプトで「 !? 」と入力し、 Enter キーを押します。

次の例では、必須の ComputerName パラメーターと、予期されるパラメーター値を説明するヘルプメッセージを宣言します。

param(
    [Parameter(Mandatory,
    HelpMessage="Enter one or more computer names separated by commas.")]
    [string[]]$ComputerName
)

出力例:

cmdlet  at command pipeline position 1
Supply values for the following parameters:
(Type !? for Help.)
ComputerName[0]: !?
Enter one or more computer names separated by commas.
ComputerName[0]: localhost
ComputerName[1]:

関数にコメントベースのヘルプがない場合このメッセージは Get-Help -Full 出力に表示されます。

この引数は省略可能なパラメーターには影響しません。

DontShow 引数

通常、DontShow 値は、古いパラメーターを削除できないコマンドの下位互換性を支援するために使用されます。 DontShow を True に設定すると、タブ展開と IntelliSense のパラメーターがユーザーに表示されなくなります。

PowerShell v7 (以降) では、DontShow を使用して、次の古いパラメーターを非表示にします。

と ConvertTo-Csv の Export-Csv パラメーター
の Format-Hex パラメーター
と Invoke-RestMethod の Invoke-WebRequest パラメーター

DontShow 引数には、次の副作用があります。

DontShow が使用されていないパラメーターセットがある場合でも、関連付けられているパラメーターのすべてのパラメーターセットに影響します。
タブ補完と IntelliSense から共通パラメーターを非表示にします。では、オプションの一般的なパラメーター (WhatIf、の確認、UseTransactionの ) は非表示になりません。

Alias 属性

Alias 属性は、パラメーターの代替名を確立します。パラメーターに割り当てることができるエイリアスの数に制限はありません。

次の例は、必須の ComputerName パラメーターに CN および MachineName エイリアスを追加するパラメーター宣言を示しています。

param(
    [Parameter(Mandatory)]
    [Alias("CN","MachineName")]
    [string[]]$ComputerName
)

Credential 属性

Credential 属性は、パラメーターが資格情報を受け入れることを示すために使用されます。次の例は、 Credential 属性を使用するパラメーター宣言を示しています。

param(
    [Parameter()]
    [System.Management.Automation.Credential()]
    [PSCredential]$Credential
)

試験段階の属性

Experimental 属性を使用して、一部のコードを試験段階として宣言します。属性の詳細については、 about_Experimental_Featuresを参照してください。

PSDefaultValue 属性

PSDefaultValue スクリプト内のコマンドパラメーターの既定値を指定します。この情報は、 Get-Help コマンドレットによって表示されます。既定値の情報を表示するには、関数にコメントベースのヘルプを含める必要があります。次に例を示します。

<#
    .SYNOPSIS
     This is a test script that has a parameter with a default value.
#>
function TestDefaultValue {
    param(
        [PSDefaultValue(Help='Current directory')]
        [string]$Name = $PWD.Path
    )

    $Name
}

既定値の情報を表示するには、 Get-Help を使用します。

Get-Help TestDefaultValue -Parameter Name

-Name <String>

    Required?                    false
    Position?                    1
    Default value                Current directory
    Accept pipeline input?       false
    Accept wildcard characters?  false

PSDefaultValue 属性の引数

PSDefaultValue 属性には、次の 2 つの引数があります。

ヘルプ - 既定値を記述する文字列。この情報は、 Get-Help コマンドレットによって表示されます。
値 - パラメーターの既定値。

どちらの引数も省略可能です。引数を指定しない場合は、パラメーターに割り当てられた値 Get-Help 表示されます。

PSTypeName 属性

型宣言で拡張型名を使用することはできません。 PSTypeName* 属性を使用すると、パラメーターの型を拡張型に制限できます。

この例では、 Test-Connection コマンドレットは拡張型を返します。 PSTypeName 属性を使用して、パラメーターの型を拡張型に制限できます。

function TestType {
    param(
        [PSTypeName('Microsoft.PowerShell.Commands.TestConnectionCommand+PingMtuStatus')]
        [psobject]$MtuStatus
    )

    $MtuStatus
}

$mtu = Test-Connection -TargetName bing.com -MtuSize
TestType $mtu

System.Obsolete 属性

System.Obsolete 属性を使用して、サポートされなくなったパラメーターをマークします。これは、関数からパラメーターを削除するが、関数を使用する既存のスクリプトを中断したくない場合に便利です。

たとえば、型情報を出力に含めるかどうかを制御する NoTypeInformation スイッチパラメーターを持つ関数を考えてみましょう。その動作を既定値にし、関数からパラメーターを削除します。ただし、関数を使用する既存のスクリプトを中断する必要はありません。パラメーターを古い形式としてマークし、変更を説明するメッセージを追加できます。

param(
    [System.Obsolete("The NoTypeInformation parameter is obsolete.")]
    [SwitchParameter]$NoTypeInformation
)

SupportsWildcards 属性

SupportsWildcards 属性は、パラメーターがワイルドカード値を受け入れることを示すために使用されます。次の例は、ワイルドカード値をサポートする必須の Path パラメーターのパラメーター宣言を示しています。

param(
    [Parameter(Mandatory)]
    [SupportsWildcards()]
    [string[]]$Path
)

この属性を使用しても、ワイルドカードのサポートは自動的に有効になりません。コマンドレット開発者は、ワイルドカード入力を処理するコードを実装する必要があります。サポートされるワイルドカードは、基になる API または PowerShell プロバイダーによって異なる場合があります。詳細については、「 about_Wildcards」を参照してください。

引数の入力候補属性

ArgumentCompletions 属性

ArgumentCompletions 属性を使用すると、タブ補完値を特定のパラメーターに追加できます。 ArgumentCompletions 属性は、タブ補完が必要なパラメーターごとに定義する必要があります。 ArgumentCompletions 属性は、ValidateSet に似ています。どちらの属性も、ユーザーがパラメーター名の後に Tab を押したときに表示される値の一覧を取得します。ただし、 ValidateSet とは異なり、値は検証されません。

この属性は、PowerShell 6.0 で導入されました。

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

ArgumentCompleter 属性

ArgumentCompleter 属性を使用すると、タブ補完値を特定のパラメーターに追加できます。 ArgumentCompleter 属性は、タブ補完が必要なパラメーターごとに定義する必要があります。 dynamicparametersと同様に、使用可能な値は、ユーザーがパラメーター名の後に Tab を押すと実行時に計算されます。

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

パラメーターと変数の検証属性

検証属性は、ユーザーが高度な関数を呼び出すときにユーザーが送信するパラメーター値をテストするように PowerShell に指示します。パラメーター値がテストに失敗した場合、エラーが生成され、関数は呼び出されません。パラメーターの検証は指定された入力にのみ適用され、既定値などのその他の値は検証されません。

また、検証属性を使用して、ユーザーが変数に指定できる値を制限することもできます。

[AllowNull()] [int]$number = 7

検証属性は、パラメーターだけでなく、任意の変数に適用できます。スクリプト内の任意の変数の検証を定義できます。

Note

型指定された変数で属性を使用する場合は、型の前に属性を宣言することをお勧めします。

属性と変数名の前に改行を指定して型を宣言すると、その型は独自のステートメントとして扱われます。

[string]
[ValidateLength(1,5)] $Text = 'Okay'

IsPublic IsSerial Name                                     BaseType
-------- -------- ----                                     --------
True     True     String                                   System.Object

型の後に検証属性を宣言した場合、割り当てられている値は型変換の前に検証されるため、予期しない検証エラーが発生する可能性があります。

[string] [ValidateLength(1,5)]$TicketIDFromInt        = 43
[string] [ValidateLength(1,5)]$TicketIDFromString     = '43'
[ValidateLength(1,5)] [string]$TicketIDAttributeFirst = 43

MetadataError: The attribute cannot be added because variable
TicketIDFromInt with value 43 would no longer be valid.

AllowNull 検証属性

AllowNull属性を使用すると、必須パラメーターの値を$nullできます。次の例では、null 値を持つハッシュテーブル ComputerInfo パラメーターを宣言します。

param(
    [Parameter(Mandatory)]
    [AllowNull()]
    [hashtable]$ComputerInfo
)

Note

AllowNull属性は、文字列型が null 値を受け取らないので、型コンバーターが文字列に設定されている場合は機能しません。このシナリオでは、 AllowEmptyString 属性を使用できます。

AllowEmptyString 検証属性

AllowEmptyString属性を使用すると、必須パラメーターの値を空の文字列 ("") にすることができます。次の例では、空の文字列値を指定できる ComputerName パラメーターを宣言します。

param(
    [Parameter(Mandatory)]
    [AllowEmptyString()]
    [string]$ComputerName
)

AllowEmptyCollection 検証属性

AllowEmptyCollection属性を使用すると、必須パラメーターの値を空のコレクション @()にすることができます。次の例では、空のコレクション値を持つ ComputerName パラメーターを宣言します。

param(
    [Parameter(Mandatory)]
    [AllowEmptyCollection()]
    [string[]]$ComputerName
)

ValidateCount 検証属性

ValidateCount属性は、パラメーターが受け入れるパラメーター値の最小値と最大数を指定します。関数を呼び出すコマンド内のパラメーター値の数がその範囲外の場合、PowerShell はエラーを生成します。

次のパラメーター宣言では、1 ~ 5 個のパラメーター値を受け取る ComputerName パラメーターが作成されます。

param(
    [Parameter(Mandatory)]
    [ValidateCount(1,5)]
    [string[]]$ComputerName
)

ValidateLength 検証属性

ValidateLength属性は、パラメーターまたは変数値の最小文字数と最大文字数を指定します。パラメーターまたは変数に指定された値の長さが範囲外の場合、PowerShell はエラーを生成します。

次の例では、各コンピューター名には 1 ~ 10 文字が必要です。

param(
    [Parameter(Mandatory)]
    [ValidateLength(1,10)]
    [string[]]$ComputerName
)

次の例では、変数 $text の値は、1 文字以上、最大 10 文字にする必要があります。

[ValidateLength(1,10)] [string] $text = 'valid'

ValidatePattern 検証属性

ValidatePattern 属性は、パラメーターまたは変数の値と比較される正規表現を指定します。値が正規表現パターンと一致しない場合、PowerShell によってエラーが生成されます。

次の例では、パラメーター値には 4 桁の数値を含める必要があり、各桁は 0 から 9 の数値にする必要があります。

param(
    [Parameter(Mandatory)]
    [ValidatePattern("[0-9]{4}")]
    [string[]]$ComputerName
)

次の例では、変数 $ticketID の値は正確に 4 桁の数値である必要があり、各桁は 0 から 9 の数値である必要があります。

[ValidatePattern("^[0-9]{4}$")] [string]$ticketID = 1111

ValidateRange 検証属性

ValidateRange属性は、各パラメーターまたは変数値の数値範囲またはValidateRangeKind列挙値を指定します。値がその範囲外の場合、PowerShell によってエラーが生成されます。

ValidateRangeKind 列挙型では、次の値を使用できます。

Positive - 0 より大きい数値。
Negative - 0 未満の数値。
NonPositive - 0 以下の数値。
NonNegative - 0 以上の数値。

次の例では、 Attempts パラメーターの値は 0 から 10 の間である必要があります。

param(
    [Parameter(Mandatory)]
    [ValidateRange(0,10)]
    [int]$Attempts
)

次の例では、変数 $number の値は 0 から 10 の間である必要があります。

[ValidateRange(0,10)] [int]$number = 5

次の例では、変数 $number の値が 0 より大きい必要があります。

[ValidateRange("Positive")] [int]$number = 1

ValidateScript 検証属性

ValidateScript 属性は、パラメーターまたは変数の値を検証するために使用されるスクリプトを指定します。 PowerShell によってスクリプトに値がパイプされ、スクリプトから $false が返された場合、またはスクリプトが例外をスローした場合にエラーが生成されます。

ValidateScript 属性を使用すると、検証対象の値が$_変数にマップされます。 $_変数を使用して、スクリプト内の値を参照できます。

次の例では、 EventDate パラメーターの値が現在の日付以上である必要があります。

param(
    [Parameter(Mandatory)]
    [ValidateScript({$_ -ge (Get-Date)})]
    [datetime]$EventDate
)

次の例では、変数 $date の値は、現在の日時以下である必要があります。

[ValidateScript({$_ -le (Get-Date)})] [datetime]$date = (Get-Date)

Note

ValidateScript を使用する場合、パラメーターに$null値を渡すことはできません。 null 値 ValidateScript を渡すと 引数を検証できません。

既定のエラーメッセージのオーバーライド

PowerShell 6 以降では、指定した値が ErrorMessage 引数で無効な場合に生成される既定のエラーメッセージをオーバーライドできます。 composite 書式指定文字列を指定します。 0 インデックスコンポーネントは、入力値を使用します。 1 インデックスコンポーネントは、入力値の検証に使用ScriptBlock を使用します。

次の例では、 EventDate パラメーターの値が現在の日時以上である必要があります。値が無効な場合、指定した日時が古すぎるとエラーメッセージで報告されます。

param(
    [Parameter(Mandatory)]
    [ValidateScript(
        {$_ -ge (Get-Date)},
        ErrorMessage = "{0} isn't a future date. Specify a later date."
    )]
    [datetime]$EventDate
)

指定した値が過去の日付の場合は、カスタムエラーメッセージが返されます。

Cannot validate argument on parameter 'EventDate'. 1/1/1999 12:00:00 AM
isn't a future date. Specify a later date.

文字列には、オプションの書式文字列コンポーネントを使用して、さらに書式設定を適用できます。

次の例では、 EventDate パラメーターの値が現在の日時以上である必要があります。値が無効な場合、エラーメッセージは、指定した日付が古すぎることを報告します。

param(
    [Parameter(Mandatory)]
    [ValidateScript(
        {$_ -ge (Get-Date).Date},
        ErrorMessage = "{0:d} isn't a future date. Specify a later date."
    )]
    [datetime]$EventDate
)

指定した値が過去の日付の場合は、カスタムエラーメッセージが返されます。

Cannot validate argument on parameter 'EventDate'. 1/1/1999 isn't a future
date. Specify a later date.

ValidateSet 属性

ValidateSet属性は、パラメーターまたは変数の有効な値のセットを指定し、タブ補完を有効にします。パラメーターまたは変数の値がセット内の値と一致しない場合、PowerShell はエラーを生成します。次の例では、 Detail パラメーターの値は、Low、Average、または High のみにできます。

param(
    [Parameter(Mandatory)]
    [ValidateSet("Low", "Average", "High")]
    [string[]]$Detail
)

次の例では、 $flavor 変数の値は Chocolate、Strawberry、または Vanilla である必要があります。

[ValidateSet("Chocolate", "Strawberry", "Vanilla")]
[string]$flavor = "Strawberry"

検証は、スクリプト内でもその変数が割り当てられるたびに発生します。たとえば、次の結果として実行時にエラーが発生します。

param(
    [ValidateSet("hello", "world")]
    [string]$Message
)

$Message = "bye"

この例では、実行時に次のエラーが返されます。

MetadataError: The attribute cannot be added because variable Message with
value bye would no longer be valid.

ValidateSetを使用すると、そのパラメーターの値のタブ拡張も有効になります。詳細については、「 about_Tab_Expansion」を参照してください。

クラスを使用した動的 ValidateSet 値

class を使用すると、実行時に ValidateSet の値動的に生成できます。次の例では、使用可能なサウンドファイルの 3 つのファイルシステムパスをチェックする SoundNames $Sound という名前の class を使用して、変数の有効な値が生成されます。

class SoundNames : System.Management.Automation.IValidateSetValuesGenerator {
    [string[]] GetValidValues() {
        $SoundPaths = '/System/Library/Sounds/',
            '/Library/Sounds','~/Library/Sounds'
        $SoundNames = foreach ($SoundPath in $SoundPaths) {
            if (Test-Path $SoundPath) {
                (Get-ChildItem $SoundPath).BaseName
            }
        }
        return [string[]] $SoundNames
    }
}

[SoundNames] クラスは、次のように動的な ValidateSet 値として実装されます。

param(
    [ValidateSet([SoundNames])]
    [string]$Sound
)

Note

IValidateSetValuesGenerator クラスは PowerShell 6.0 で導入されました

ValidateNotNull 検証属性

ValidateNotNull 属性は、パラメーター値を$nullできないことを指定します。値が $nullされると、PowerShell によって例外が発生します。

ValidateNotNull 属性は、パラメーターが省略可能で、型が未定義の場合、または型コンバーターを持ち、object のような null 値を暗黙的に変換できない場合に使用するように設計されています。 string などの null 値を暗黙的に変換する型を指定した場合、ValidateNotNull 属性を使用している場合でも、null 値は空の文字列に変換されます。このシナリオでは、 ValidateNotNullOrEmpty 属性を使用します。

次の例では、Id パラメーターの値を $nullできません。

param(
    [Parameter()]
    [ValidateNotNull()]
    $Id
)

ValidateNotNullOrEmpty 検証属性

ValidateNotNullOrEmpty 属性は、割り当てられた値を次のいずれかの値にできないことを指定します。

$null
空の文字列 ("")
空の配列 (@())

値が無効な場合、PowerShell によって例外が発生します。

param(
    [Parameter(Mandatory)]
    [ValidateNotNullOrEmpty()]
    [string[]]$UserName
)

ValidateNotNullOrWhiteSpace 検証属性

ValidateNotNullOrWhiteSpace 属性は、割り当てられた値を次のいずれかの値にできないことを指定します。

$null
空の文字列 ("")
空の配列 @()
タブ、スペース、復帰、改行などの空白文字のみを含む文字列
空または空白文字のみを含む文字列を含む配列

値が無効な場合、PowerShell によって例外が発生します。

param(
    [Parameter(Mandatory)]
    [ValidateNotNullOrWhiteSpace()]
    [string[]]$UserName
)

ValidateDrive 検証属性

ValidateDrive 属性は、パラメーター値が、許可されているドライブのみを参照するパスを表す必要があることを指定します。パラメーター値が許可されているドライブ以外のドライブを参照している場合、PowerShell はエラーを生成します。ドライブ自体を除くパスの存在は検証されません。

相対パスを使用する場合は、現在のドライブが許可されているドライブの一覧に含まれている必要があります。

param(
    [ValidateDrive("C", "D", "Variable", "Function")]
    [string]$Path
)

ValidateUserDrive 検証属性

ValidateUserDrive 属性は、パラメーター値がUser ドライブで表す必要があることを指定します。パスが別のドライブを参照している場合、PowerShell によってエラーが生成されます。検証属性は、パスのドライブプレフィックスが存在するかどうかをテストするだけです。

相対パスを使用する場合は、現在のドライブが Userされている必要があります。

function Test-UserDrivePath{
    [OutputType([bool])]
    param(
        [Parameter(Mandatory, Position=0)]
        [ValidateUserDrive()]
        [string]$Path
    )
    $true
}

Test-UserDrivePath -Path C:\

Test-UserDrivePath: Cannot validate argument on parameter 'Path'. The path
argument drive C does not belong to the set of approved drives: User.
Supply a path argument with an approved drive.

Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'

Test-UserDrivePath: Cannot validate argument on parameter 'Path'. Cannot
find drive. A drive with the name 'User' does not exist.

Just Enough Administration (JEA) セッション構成では、 User ドライブを定義できます。この例では、User: ドライブを作成します。

New-PSDrive -Name 'User' -PSProvider FileSystem -Root $Env:HOMEPATH

Name           Used (GB)     Free (GB) Provider      Root
----           ---------     --------- --------      ----
User               75.76         24.24 FileSystem    C:\Users\ExampleUser

Test-UserDrivePath -Path 'User:\A_folder_that_does_not_exist'

True

ValidateTrustedData 検証属性

この属性は PowerShell が内部で使用し、外部での使用を目的としたものではありません。

この属性は、PowerShell 6.1.1 で追加されました。

こちらも参照ください

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-01-18

次の方法で共有

about_Functions_Advanced_Parameters

簡単な説明

長い説明

パラメーターの宣言

パラメーター値の型変換

静的パラメーター

パラメーターの切り替え

スイッチ パラメーターの設計に関する考慮事項

動的パラメーター

パラメーターの属性

パラメーター属性

必須引数

引数 Position

ParameterSetName 引数

ValueFromPipeline 引数

ValueFromPipelineByPropertyName 引数

ValueFromRemainingArguments 引数

HelpMessage 引数

DontShow 引数

Alias 属性

Credential 属性

試験段階の属性

PSDefaultValue 属性

PSDefaultValue 属性の引数

PSTypeName 属性

System.Obsolete 属性

SupportsWildcards 属性

引数の入力候補属性

ArgumentCompletions 属性

ArgumentCompleter 属性

パラメーターと変数の検証属性

AllowNull 検証属性

AllowEmptyString 検証属性

AllowEmptyCollection 検証属性

ValidateCount 検証属性

ValidateLength 検証属性

ValidatePattern 検証属性

ValidateRange 検証属性

ValidateScript 検証属性

既定のエラー メッセージのオーバーライド

ValidateSet 属性

クラスを使用した動的 ValidateSet 値

ValidateNotNull 検証属性

ValidateNotNullOrEmpty 検証属性

ValidateNotNullOrWhiteSpace 検証属性

ValidateDrive 検証属性

ValidateUserDrive 検証属性

ValidateTrustedData 検証属性

こちらも参照ください

フィードバック

その他のリソース

スイッチパラメーターの設計に関する考慮事項

既定のエラーメッセージのオーバーライド