ja-JP/about_Parameter_Sets.help.txt
|
TOPIC about_Parameter_Sets 簡単な説明 高度な関数でパラメーターセットを定義し、使用する方法を説明します。 詳細な説明 PowerShell では、パラメーターセットを使用することで、1 つの関数で シナリオごとに異なる処理を実行できます。パラメーターセットを使うと、 利用者ごとに異なるパラメーターを公開できます。また、利用者が指定した パラメーターに基づいて、異なる情報を返すこともできます。一度に使用 できるパラメーターセットは 1 つだけです。 パラメーターセットの要件 すべてのパラメーターセットには、次の要件が適用されます。 - あるパラメーターにパラメーターセットを指定しなかった場合、その パラメーターはすべてのパラメーターセットに属します。 - 各パラメーターセットは、パラメーターの組み合わせが一意である必要が あります。可能であれば、一意のパラメーターのうち少なくとも 1 つは 必須パラメーターにします。 - 複数の位置指定パラメーターを含むパラメーターセットでは、各パラメー ターに一意の位置を定義する必要があります。2 つの位置指定パラメー ターが同じ位置を指定することはできません。 注: パラメーターセットの上限は 32 個です。 既定のパラメーターセット 複数のパラメーターセットを定義した場合、CmdletBinding 属性の DefaultParameterSetName キーワードで既定のパラメーターセットを指定 します。コマンドに渡された情報からどのパラメーターセットを使うか 判断できないとき、PowerShell は既定のパラメーターセットを使用します。 CmdletBinding 属性の詳細については、 about_Functions_CmdletBindingAttribute を参照してください。 パラメーターセットの宣言 パラメーターセットを作成するには、そのパラメーターセットに含まれる すべてのパラメーターについて、Parameter 属性の ParameterSetName キーワードを指定する必要があります。複数のパラメーターセットに属する パラメーターには、パラメーターセットごとに Parameter 属性を追加します。 Parameter 属性を使うと、パラメーターセットごとにパラメーターを異なる 方法で定義できます。たとえば、あるセットでは必須、別のセットでは任意 として定義できます。ただし、各パラメーターセットには少なくとも 1 つの 一意のパラメーターを含める必要があります。 パラメーターセット名を割り当てていないパラメーターは、すべての パラメーターセットに属します。 予約されたパラメーターセット名 PowerShell は、特別な処理のためにパラメーターセット名 __AllParameterSets を予約しています。 __AllParameterSets は、明示的な既定名を使用しない場合の既定の パラメーターセットの名前です。 Parameter 属性の ParameterSetName を __AllParameterSets に設定する ことは、ParameterSetName を割り当てないことと同じです。どちらの場合も、 そのパラメーターはすべてのパラメーターセットに属します。 注: CmdletBinding 属性は、DefaultParameterSetName を __AllParameterSets に設定することを妨げません。これを行うと、 PowerShell は Parameter 属性から正しく参照できない明示的な パラメーターセットを作成します。 使用例 次の例の関数は、テキストファイル内の行数、文字数、単語数をカウント します。パラメーターを使って、返してほしい値と計測したいファイルを 指定できます。次の 4 つのパラメーターセットが定義されています。 - Path - PathAll - LiteralPath - LiteralPathAll function Measure-Lines { [CmdletBinding(DefaultParameterSetName = 'Path')] param ( [Parameter(Mandatory, ParameterSetName = 'Path', Position = 0)] [Parameter(Mandatory, ParameterSetName = 'PathAll', Position = 0)] [string[]]$Path, [Parameter(Mandatory, ParameterSetName = 'LiteralPathAll', ValueFromPipeline)] [Parameter(Mandatory, ParameterSetName = 'LiteralPath', ValueFromPipeline)] [string[]]$LiteralPath, [Parameter(ParameterSetName = 'Path')] [Parameter(ParameterSetName = 'LiteralPath')] [switch]$Lines, [Parameter(ParameterSetName = 'Path')] [Parameter(ParameterSetName = 'LiteralPath')] [switch]$Words, [Parameter(ParameterSetName = 'Path')] [Parameter(ParameterSetName = 'LiteralPath')] [switch]$Characters, [Parameter(Mandatory, ParameterSetName = 'PathAll')] [Parameter(Mandatory, ParameterSetName = 'LiteralPathAll')] [switch]$All, [Parameter(ParameterSetName = 'Path')] [Parameter(ParameterSetName = 'PathAll')] [switch]$Recurse ) begin { if ($All) { $Lines = $Words = $Characters = $true } elseif (($Words -eq $false) -and ($Characters -eq $false)) { $Lines = $true } } process { if ($Path) { $Files = Get-ChildItem -Path $Path -Recurse:$Recurse -File } else { $Files = Get-ChildItem -LiteralPath $LiteralPath -File } foreach ($file in $Files) { $result = [ordered]@{ } $result.Add('File', $file.FullName) $content = Get-Content -LiteralPath $file.FullName if ($Lines) { $result.Add('Lines', $content.Length) } if ($Words) { $wc = 0 foreach ($line in $content) { $wc += $line.Split(' ').Length } $result.Add('Words', $wc) } if ($Characters) { $cc = 0 foreach ($line in $content) { $cc += $line.Length } $result.Add('Characters', $cc) } New-Object -TypeName psobject -Property $result } } } 各パラメーターセットには、一意のパラメーター、または一意の組み合わせ のパラメーターが必要です。Path と PathAll のパラメーターセットは 非常によく似ていますが、All パラメーターは PathAll パラメーターセット に固有です。LiteralPath と LiteralPathAll のパラメーターセットでも 同様です。PathAll と LiteralPathAll のパラメーターセットはどちらも All パラメーターを持ちますが、Path パラメーターと LiteralPath パラメーターによって区別されます。 Get-Command -Syntax を使うと、各パラメーターセットの構文が表示され ます。ただし、パラメーターセットの名前は表示されません。次の例は、 各パラメーターセットで使用できるパラメーターを示しています。 (Get-Command Measure-Lines).ParameterSets | Select-Object -Property @{n='ParameterSetName';e={$_.Name}}, @{n='Parameters';e={$_.ToString()}} ParameterSetName Parameters ---------------- ---------- Path [-Path] <string[]> [-Lines] [-Words] [-Characters] [-Recurse] [<CommonParameters>] PathAll [-Path] <string[]> -All [-Recurse] [<CommonParameters>] LiteralPath -LiteralPath <string[]> [-Lines] [-Words] [-Characters] [<CommonParameters>] LiteralPathAll -LiteralPath <string[]> -All [<CommonParameters>] 動作中のパラメーターセット 次の例では PathAll パラメーターセットを使用します。 Measure-Lines test* -All File Lines Words Characters ---- ----- ----- ---------- C:\temp\test\test.help.txt 31 562 2059 C:\temp\test\test.md 30 1527 3224 C:\temp\test\test.ps1 3 3 79 C:\temp\test\test[1].txt 31 562 2059 複数のセットのパラメーターを使ったときのエラー 次の例では、異なるパラメーターセットに固有のパラメーターを使用します。 Get-ChildItem -Path $PSHOME -LiteralPath $PSHOME Get-ChildItem: Parameter set cannot be resolved using the specified named parameters. One or more parameters issued cannot be used together or an insufficient number of parameters were provided. Path パラメーターと LiteralPath パラメーターは、Get-ChildItem コマンドレットの異なるパラメーターセットに固有です。これらの パラメーターを同じコマンドレットで一緒に使うと、エラーが発生します。 1 回のコマンドレット呼び出しで使用できるパラメーターセットは一度に 1 つだけです。 使用されているパラメーターセットを知る方法 自動変数 $PSCmdlet は ParameterSetName プロパティを提供します。この プロパティには、使用中のパラメーターセットの名前が含まれます。関数内 でこのプロパティを使うと、どのパラメーターセットが使われているかを 判定し、パラメーターセット固有の動作を選択できます。 function Get-ParameterSetName { [CmdletBinding(DefaultParameterSetName = 'Set1')] param ( [Parameter(ParameterSetName = 'Set1', Position = 0)] $Var1, [Parameter(ParameterSetName = 'Set2', Position = 0)] $Var2, [Parameter(ParameterSetName = 'Set1', Position = 1)] [Parameter(ParameterSetName = 'Set2', Position = 1)] $Var3, [Parameter(Position = 2)] $Var4 ) "Using Parameter set named '$($PSCmdlet.ParameterSetName)'" switch ($PSCmdlet.ParameterSetName) { 'Set1' { "`$Var1 = $Var1" "`$Var3 = $Var3" "`$Var4 = $Var4" break } 'Set2' { "`$Var2 = $Var2" "`$Var3 = $Var3" "`$Var4 = $Var4" break } } } PS> Get-ParameterSetName 1 2 3 Using Parameter set named 'Set1' $Var1 = 1 $Var3 = 2 $Var4 = 3 PS> Get-ParameterSetName -Var2 1 2 3 Using Parameter set named 'Set2' $Var2 = 1 $Var3 = 2 $Var4 = 3 関連項目 about_Functions_CmdletBindingAttribute about_Functions_Advanced_Parameters about_Functions_Advanced ---- 原文: PowerShell-Docs (CC BY 4.0) の翻訳 / PSHelpJaJP |