about_Functions_Argument_Completion

아티클
10/04/2023

간단한 설명

인수 완성은 힌트를 제공하고 검색을 사용하도록 설정하며 인수 값의 입력 입력 속도를 향상하는 PowerShell의 기능입니다.

자세한 설명

이 문서에서는 PowerShell 함수에 대한 인수 완료자를 구현할 수 있는 다양한 방법을 설명합니다. 인수 완성자는 매개 변수에 사용할 수 있는 값을 제공합니다. 사용 가능한 값은 사용자가 매개 변수 이름 뒤의 Tab 키를 누를 때 런타임에 계산됩니다. 매개 변수에 대한 인수 완료자를 정의하는 방법에는 여러 가지가 있습니다.

참고 항목

Tab 은 Windows의 기본 키 바인딩입니다. 이 키 바인딩은 PSReadLine 모듈 또는 PowerShell을 호스팅하는 애플리케이션에서 변경할 수 있습니다. 키 바인딩은 비 Windows 플랫폼에서 다릅니다. 자세한 내용은 about_PSReadLine을 참조하세요.

ValidateSet 특성

ValidateSet 특성은 매개 변수 또는 변수에 유효한 값 집합을 지정하고 탭 완성을 사용하도록 설정합니다. 매개 변수 또는 변수 값이 집합의 값과 일치하지 않으면 PowerShell에서 오류를 생성합니다. 다음 예제에서 Fruit 매개 변수의 값은 Apple, Banana 또는 Pear일 수 있습니다.

Param(
    [Parameter(Mandatory=$true)]
    [ValidateSet('Apple', 'Banana', 'Pear')]
    [string[]]
    $Fruit
)

다음 예제에서 변수 $flavor 값은 Chocolate, Strawberry 또는 Vanilla여야 합니다. ValidateSet 매개 변수뿐만 아니라 모든 변수에서 특성을 사용할 수 있습니다.

[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.

탭 확장에 대한 자세한 내용은 about_Tab_Expansion 참조하세요.

클래스를 사용하는 동적 ValidateSet 값

클래스를 사용하여 런타임에 ValidateSet에 대한 값을 동적으로 생성할 수 있습니다. 다음 예제에서 변수 $Sound 의 유효한 값은 사용 가능한 사운드 파일에 대한 세 개의 파일 시스템 경로를 검사 SoundNames라는 클래스를 통해 생성됩니다.

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
)

참고 항목

이 클래스는 IValidateSetValuesGenerator PowerShell 6.0에서 도입되었습니다.

ArgumentCompletions 특성

ArgumentCompletions 특성을 사용하면 탭 완성 값을 특정 매개 변수에 추가할 수 있습니다. Tab 완성이 필요한 각 매개 변수에 대해 ArgumentCompletions 특성을 정의해야 합니다. ArgumentCompletions 특성은 ValidateSet과 유사합니다. 두 특성 모두 사용자가 매개 변수 이름 뒤의 Tab 키를 누를 때 표시할 값 목록을 사용합니다. 그러나 ValidateSet과 달리 값의 유효성은 검사되지 않으며 제안과 유사합니다. 따라서 사용자는 목록의 값뿐만 아니라 모든 값을 제공할 수 있습니다.

ArgumentCompletions 특성은 옵션을 정의하기 위해 scriptblock이 필요한 ArgumentCompleter 특성과 혼동해서는 안 됩니다. 지정된 값을 사용할 수 있습니다.

구문은 다음과 같습니다.

function Test-ArgumentCompletions {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory=$true)]
        [ArgumentCompletions('Fruits', 'Vegetables')]
        $Type,

        [Parameter()]
        [ArgumentCompletions('Apple', 'Banana', 'Orange')]
        $Fruit,

        [Parameter()]
        [ArgumentCompletions('Onion', 'Carrot', 'Lettuce')]
        $Vegetable
    )
}

각 매개 변수에는 탭 완성을 사용하도록 설정하기 위해 ArgumentCompletions 특성에 대한 옵션 목록이 제공됩니다.

이 특성은 PowerShell 6.0에서 도입되었습니다.

ArgumentCompleter 특성

ArgumentCompleter 특성을 사용하면 탭 완성 값을 특정 매개 변수에 추가할 수 있습니다. Tab 완성이 필요한 각 매개 변수에 대해 ArgumentCompleter 특성을 정의해야 합니다.

ArgumentCompleter 특성을 추가하려면 값을 결정하는 스크립트 블록을 정의해야 합니다. 스크립트 블록은 아래 지정된 순서대로 다음 매개 변수를 사용해야 합니다. 값이 위치적으로 제공되기 때문에 매개 변수의 이름은 중요하지 않습니다.

구문은 다음과 같습니다.

function MyArgumentCompleter {
    Param(
        [Parameter(Mandatory)]
        [ArgumentCompleter( {
            param ( $commandName,
                    $parameterName,
                    $wordToComplete,
                    $commandAst,
                    $fakeBoundParameters )
            # Perform calculation of tab completed values here.
        } )]
        $ParamName
    )
}

ArgumentCompleter 스크립트 블록

스크립트 블록 매개 변수는 다음 값으로 설정됩니다.

$commandName (위치 0) - 이 매개 변수는 스크립트 블록이 탭 완성을 제공하는 명령의 이름으로 설정됩니다.
$parameterName (위치 1) - 이 매개 변수는 값에 탭 완성이 필요한 매개 변수로 설정됩니다.
$wordToComplete(위치 2) - 이 매개 변수는 Tab 키를 누르기 전에 사용자가 제공한 값으로 설정됩니다. 스크립트 블록은 이 값을 사용하여 탭 완성 값을 결정해야 합니다.
$commandAst (위치 3) - 이 매개 변수는 현재 입력 줄에 대한 AST(추상 구문 트리)로 설정됩니다. 자세한 내용은 AST 형식 설명서를 참조하세요.
$fakeBoundParameters(위치 4) - 사용자가 Tab 키를 누르기 전에 이 매개 변수가 for cmdlet을 포함하는 $PSBoundParameters 해시 테이블로 설정됩니다. 자세한 내용은 about_Automatic_Variables 참조하세요.

ArgumentCompleter 스크립트 블록은 파이프라인(예: ForEach-Object) Where-Object또는 다른 적합한 메서드를 사용하여 값의 등록을 취소해야 합니다. 값 배열을 반환하면 PowerShell에서 전체 배열을 하나의 탭 완성 값으로 처리합니다.

다음 예제에서는 값 매개 변수에 탭 완성을 추가합니다. Value 매개 변수만 지정하면 Value에 대해 가능한 모든 값 또는 인수가 표시됩니다. Type 매개 변수를 지정하면 Value 매개 변수는 해당 형식에 대해 가능한 값만 표시합니다.

또한 연산자는 -like 사용자가 다음 명령을 입력하고 Tab 완성을 사용하는 경우 Apple만 반환되도록 합니다.

Test-ArgumentCompleter -Type Fruits -Value A

function MyArgumentCompleter{
    param ( $commandName,
            $parameterName,
            $wordToComplete,
            $commandAst,
            $fakeBoundParameters )

    $possibleValues = @{
        Fruits = @('Apple', 'Orange', 'Banana')
        Vegetables = @('Onion', 'Carrot', 'Lettuce')
    }

    if ($fakeBoundParameters.ContainsKey('Type')) {
        $possibleValues[$fakeBoundParameters.Type] | Where-Object {
            $_ -like "$wordToComplete*"
        }
    } else {
        $possibleValues.Values | ForEach-Object {$_}
    }
}

function Test-ArgumentCompleter {
[CmdletBinding()]
 param (
        [Parameter(Mandatory=$true)]
        [ValidateSet('Fruits', 'Vegetables')]
        $Type,

        [Parameter(Mandatory=$true)]
        [ArgumentCompleter({ MyArgumentCompleter @args })]
        $Value
      )
}

클래스 기반 인수 완료자

PowerShell 7.2부터 매개 변수가 있는 인수 완료자의 보다 일반적인 구현을 정의할 수 있는 새로운 기능이 추가되었습니다.

파생하면 ArgumentCompleterAttribute다시 사용할 수 있는 제네릭 완료자를 만들 수 있습니다. 예를 들면 다음과 같습니다.

[DirectoryCompleter(ContainingFile="pswh.exe", Depth=2)]

[DateCompleter(WeekDay='Monday', From="LastYear")]

[GitCommits(Branch='release')]

파생 특성은 인터페이스를 IArgumentCompleterFactory 구현하고 속성 값을 사용하여 특수 완성자를 만들어야 합니다.

using namespace System.Collections
using namespace System.Collections.Generic
using namespace System.Management.Automation
using namespace System.Management.Automation.Language

class NumberCompleter : IArgumentCompleter {

    [int] $From
    [int] $To
    [int] $Step

    NumberCompleter([int] $from, [int] $to, [int] $step) {
        if ($from -gt $to) {
            throw [ArgumentOutOfRangeException]::new("from")
        }
        $this.From = $from
        $this.To = $to
        $this.Step = $step -lt 1 ? 1 : $step
    }

    [IEnumerable[CompletionResult]] CompleteArgument(
        [string] $CommandName,
        [string] $parameterName,
        [string] $wordToComplete,
        [CommandAst] $commandAst,
        [IDictionary] $fakeBoundParameters) {

        $resultList = [List[CompletionResult]]::new()
        $local:to = $this.To
        $local:step = $this.Step
        for ($i = $this.From; $i -lt $to; $i += $step) {
            $resultList.Add([CompletionResult]::new($i.ToString()))
        }

        return $resultList
    }
}

class NumberCompletionsAttribute : ArgumentCompleterAttribute, IArgumentCompleterFactory {
    [int] $From
    [int] $To
    [int] $Step

    NumberCompletionsAttribute([int] $from, [int] $to, [int] $step) {
        $this.From = $from
        $this.To = $to
        $this.Step = $step
    }

    [IArgumentCompleter] Create() { return [NumberCompleter]::new($this.From, $this.To, $this.Step) }
}

PowerShell의 사용량은 다음과 같습니다.

function Add{
    param(
       [NumberCompletions(0, 100, 5)]
       [int] $X,

       [NumberCompletions(0, 100, 5)]
       [int] $Y
    )
    $X + $Y
}

Register-ArgumentCompleter

cmdlet은 Register-ArgumentCompleter 사용자 지정 인수 완료자를 등록합니다. 인수 완성기를 사용하면 지정한 명령에 대해 런타임에 동적 탭 완성을 제공할 수 있습니다.

자세한 내용은 Register-ArgumentCompleter를 참조하세요.

Share via

about_Functions_Argument_Completion

간단한 설명

자세한 설명

ValidateSet 특성

클래스를 사용하는 동적 ValidateSet 값

ArgumentCompletions 특성

ArgumentCompleter 특성

ArgumentCompleter 스크립트 블록

클래스 기반 인수 완료자

Register-ArgumentCompleter

참고 항목

피드백

추가 리소스