about_Parameter_Sets
簡単な説明
高度な関数でパラメーター セットを定義して使用する方法について説明します。
長い説明
PowerShell では、パラメーター セットを使用して、シナリオごとに異なるアクションを実行できる 1 つの関数を記述できます。 パラメーター セットを使用すると、さまざまなパラメーターをユーザーに公開できます。 また、ユーザーが指定したパラメーターに基づいて異なる情報を返します。 一度に使用できるパラメーター セットは 1 つだけです。
パラメーター セットの要件
次の要件は、すべてのパラメーター セットに適用されます。
パラメーターにパラメーター セットが指定されていない場合、パラメーターはすべてのパラメーター セットに属します。
各パラメーター セットには、パラメーターの一意の組み合わせが必要です。 可能であれば、少なくとも 1 つの一意のパラメーターを必須パラメーターにする必要があります。
複数の位置指定パラメーターを含むパラメーター セットでは、パラメーターごとに一意の位置を定義する必要があります。 2 つの位置指定パラメーターで同じ位置を指定することはできません。
セット内の 1 つのパラメーターのみが、 の値
true
を使用してValueFromPipeline
キーワード (keyword)を宣言できます。 複数のパラメーターを使用すると、 の値true
をValueFromPipelineByPropertyName
使用してキーワード (keyword)を定義できます。
注意
パラメーター セットは 32 個に制限されています。
既定のパラメーター セット
複数のパラメーター セットが定義されている場合、DefaultParameterSetName
CmdletBinding 属性のキーワード (keyword)は既定のパラメーター セットを指定します。
PowerShell は、コマンドに指定された情報に基づいて使用するパラメーター セットを決定できない場合に、既定のパラメーター セットを使用します。 CmdletBinding 属性の詳細については、「about_functions_cmdletbindingattribute」を参照してください。
パラメーター セットの宣言
パラメーター セットを作成するには、パラメーター セット内のすべてのパラメーターに対して Parameter 属性のキーワード (keyword)を指定ParameterSetName
する必要があります。 複数のパラメーター セットに属するパラメーターの場合は、パラメーター セットごとに Parameter 属性を追加します。
Parameter 属性を使用すると、パラメーター セットごとに異なる方法でパラメーターを定義できます。 たとえば、あるセットでは必須としてパラメーターを定義し、別のセットでは省略可能として定義できます。 ただし、各パラメーター セットには、少なくとも 1 つの一意のパラメーターが含まれている必要があります。
パラメーター セット名が割り当てられていないパラメーターは、すべてのパラメーター セットに属します。
例
次の関数例では、テキスト ファイル内の行、文字、単語の数をカウントします。 パラメーターを使用して、返す値と測定するファイルを指定できます。 次の 4 つのパラメーター セットが定義されています。
- パス
- PathAll
- LiteralPath
- LiteralPathAll
function Measure-Lines {
[CmdletBinding(DefaultParameterSetName = 'Path')]
param (
[Parameter(Mandatory = $true,
ParameterSetName = 'Path',
HelpMessage = 'Enter one or more filenames',
Position = 0)]
[Parameter(Mandatory = $true,
ParameterSetName = 'PathAll',
Position = 0)]
[string[]]$Path,
[Parameter(Mandatory = $true, ParameterSetName = 'LiteralPathAll')]
[Parameter(Mandatory = $true,
ParameterSetName = 'LiteralPath',
HelpMessage = 'Enter a single filename',
ValueFromPipeline = $true)]
[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 = $true, ParameterSetName = 'PathAll')]
[Parameter(Mandatory = $true, 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
}
if ($Path) {
$Files = Get-ChildItem -Path $Path -Recurse:$Recurse
}
else {
$Files = Get-ChildItem -LiteralPath $LiteralPath
}
}
process {
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
固有です。 パラメーター セットと LiteralPathAll
パラメーター セットについてもLiteralPath
同様です。 パラメーター セットと LiteralPathAll
パラメーター セットのPathAll
両方に 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 つだけです。