about_Parameter_Sets

간단한 설명

고급 함수에서 매개 변수 집합을 정의하고 사용하는 방법을 설명합니다.

긴 설명

PowerShell은 매개 변수 집합을 사용하여 다양한 시나리오에 대해 다른 작업을 수행할 수 있는 단일 함수를 작성할 수 있도록 합니다. 매개 변수 집합을 사용하면 사용자에게 다른 매개 변수를 노출할 수 있습니다. 또한 사용자가 지정한 매개 변수에 따라 다른 정보를 반환합니다. 한 번에 하나의 매개 변수 집합만 사용할 수 있습니다.

매개 변수 집합 요구 사항

다음 요구 사항은 모든 매개 변수 집합에 적용됩니다.

• 매개 변수에 대해 매개 변수 집합이 지정되지 않은 경우 매개 변수는 모든 매개 변수 집합에 속합니다.

• 각 매개 변수 집합에는 고유한 매개 변수 조합이 있어야 합니다. 가능하면 고유 매개 변수 중 하나 이상이 필수 매개 변수여야 합니다.

• 여러 위치 매개 변수를 포함하는 매개 변수 집합은 각 매개 변수에 대해 고유한 위치를 정의해야 합니다. 두 위치 매개 변수에 동일한 위치를 지정할 수 없습니다.

기본 매개 변수 집합

여러 매개 변수 집합이 정의 DefaultParameterSetName 되면 CmdletBinding 특성의 키워드가 기본 매개 변수 집합을 지정합니다. PowerShell은 명령에 제공된 정보에 따라 사용할 매개 변수 집합을 확인할 수 없는 경우 기본 매개 변수 집합을 사용합니다. CmdletBinding 특성에 대한 자세한 내용은 about_Functions_CmdletBindingAttribute 참조하세요.

매개 변수 집합 선언

매개 변수 집합을 만들려면 매개 변수 집합의 모든 매개 변수에 대해 ParameterParameterSetName키워드를 지정 해야 합니다. 여러 매개 변수 집합에 속하는 매개 변수의 경우 각 매개 변수 집합에 대한 매개 변수 특성을 추가합니다.

매개 변수 특성을 사용하면 각 매개 변수 집합에 대해 매개 변수를 다르게 정의할 수 있습니다. 예를 들어 한 집합에서 매개 변수를 필수로 정의하고 다른 집합에서는 선택적으로 정의할 수 있습니다. 그러나 각 매개 변수 집합에는 하나 이상의 고유 매개 변수가 포함되어야 합니다.

할당된 매개 변수 집합 이름이 없는 매개 변수는 모든 매개 변수 집합에 속합니다.

예약된 매개 변수 집합 이름

PowerShell은 특수 처리를 위해 매개 변수 집합 이름을 __AllParameterSets 예약합니다.

__AllParameterSets 는 명시적 기본 이름을 사용하지 않을 때 설정된 기본 매개 변수의 이름입니다.

ParameterSetName 매개 변수 특성 __AllParameterSets 의 설정은 .을 할당하지 않는 것과 ParameterSetName같습니다. 두 경우 모두 매개 변수는 모든 매개 변수 집합에 속합니다.

예시

다음 예제 함수는 텍스트 파일의 숫자 줄, 문자 및 단어를 계산합니다. 매개 변수를 사용하여 반환할 값과 측정하려는 파일을 지정할 수 있습니다. 다음과 같은 네 가지 매개 변수 집합이 정의되어 있습니다.

• 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 매개 변수 집합에 모두 All 매개 변수LiteralPathAll있더라도 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 매개 변수는 cmdlet의 다른 매개 변수 집합에 Get-ChildItem 고유합니다. 매개 변수가 동일한 cmdlet에서 함께 실행되면 오류가 throw됩니다. 한 번에 하나의 매개 변수 집합만 cmdlet 호출당 사용할 수 있습니다.

사용되는 매개 변수 집합을 아는 방법

자동 변수 $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