Register-ArgumentCompleter

  • 참조
모듈:
Microsoft.PowerShell.Core

사용자 지정 인수 완료자를 등록합니다.

Syntax

Register-ArgumentCompleter
        -CommandName <String[]>
        -ScriptBlock <ScriptBlock>
        [-Native]
        [<CommonParameters>]
Register-ArgumentCompleter
        [-CommandName <String[]>]
        -ParameterName <String>
        -ScriptBlock <ScriptBlock>
        [<CommonParameters>]

Description

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

예제

예제 1: 사용자 지정 인수 완료자 등록

다음 예제에서는 cmdlet의 Id 매개 변수에 대한 인수 완료자를 Set-TimeZone 등록합니다.

$scriptBlock = {
    param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)

    (Get-TimeZone -ListAvailable).Id | Where-Object {
        $_ -like "$wordToComplete*"
    } | ForEach-Object {
          "'$_'"
    }
}
Register-ArgumentCompleter -CommandName Set-TimeZone -ParameterName Id -ScriptBlock $scriptBlock

첫 번째 명령은 사용자가 Tab 키를 누를 때 전달되는 필수 매개 변수를 사용하는 스크립트 블록을 만듭니다. 자세한 내용은 ScriptBlock 매개 변수 설명을 참조하세요.

스크립트 블록 내에서 id에 사용할 수 있는 값은 cmdlet을 Get-TimeZone 사용하여 검색됩니다. 각 표준 시간대의 ID 속성은 cmdlet에 Where-Object 파이프됩니다. cmdlet은 Where-Object 사용자가 Tab 키를 누르기 전에 입력한 텍스트를 나타내는 제공된 $wordToComplete값으로 시작되지 않는 모든 ID를 필터링합니다. 필터링된 ID는 값에 ForEach-Object 공백이 포함되어 있는 경우 각 값을 따옴표로 묶는 cmdlet에 파이프됩니다.

두 번째 명령은 scriptblock, ParameterName ID 및 CommandName을 전달하여 인수 완료자를 등록합니다Set-TimeZone.

예제 2: 탭 완성 값에 세부 정보 추가

다음 예제에서는 cmdlet의 Name 매개 변수에 대한 탭 완성을 Stop-Service 덮어쓰고 실행 중인 서비스만 반환합니다.

$s = {
    param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters)
    $services = Get-Service | Where-Object {$_.Status -eq "Running" -and $_.Name -like "$wordToComplete*"}
    $services | ForEach-Object {
        New-Object -Type System.Management.Automation.CompletionResult -ArgumentList $_.Name,
            $_.Name,
            "ParameterValue",
            $_.Name
    }
}
Register-ArgumentCompleter -CommandName Stop-Service -ParameterName Name -ScriptBlock $s

첫 번째 명령은 사용자가 Tab 키를 누를 때 전달되는 필수 매개 변수를 사용하는 스크립트 블록을 만듭니다. 자세한 내용은 ScriptBlock 매개 변수 설명을 참조하세요.

스크립트 블록 내에서 첫 번째 명령은 cmdlet을 사용하여 Where-Object 실행 중인 모든 서비스를 검색합니다. 서비스는 cmdlet에 ForEach-Object 파이프됩니다. cmdlet은 ForEach-Object 새 System.Management.Automation.CompletionResult 개체를 만들고 현재 서비스의 이름(파이프라인 변수 $_.Name로 표시됨)으로 채웁니다.

CompletionResult 개체를 사용하면 반환된 각 값에 대한 추가 세부 정보를 제공할 수 있습니다.

  • completionText (String) - 자동 완성 결과로 사용할 텍스트입니다. 명령으로 전송되는 값입니다.
  • listItemText(String) - 사용자가 Ctrl+스페이스를 누를 때와 같이 목록에 표시할 텍스트입니다. 표시에만 사용되며 선택할 때 명령에 전달되지 않습니다.
  • resultType (CompletionResultType) - 완료 결과의 형식입니다.
  • toolTip (String) - 개체에 대해 표시할 세부 정보가 포함된 도구 설명의 텍스트입니다. Ctrl+스페이스바를 누른 후 사용자가 항목을 선택할 때 표시됩니다.

마지막 명령은 중지된 서비스를 cmdlet에 수동으로 Stop-Service 전달할 수 있음을 보여 줍니다. 탭 완성이 영향을 받는 유일한 측면입니다.

예제 3: 사용자 지정 네이티브 인수 완료자 등록

네이티브 매개 변수를 사용하여 네이 티브 명령에 대한 탭 완성을 제공할 수 있습니다. 다음 예제에서는 CLI(명령줄 인터페이스)에 대한 탭 완성을 dotnet 추가합니다.

참고 항목

이 dotnet complete 명령은 버전 2.0 이상에서만 사용할 수 있습니다.

$scriptblock = {
    param($wordToComplete, $commandAst, $cursorPosition)
        dotnet complete --position $cursorPosition $commandAst.ToString() | ForEach-Object {
            [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
        }
}
Register-ArgumentCompleter -Native -CommandName dotnet -ScriptBlock $scriptblock

첫 번째 명령은 사용자가 Tab 키를 누를 때 전달되는 필수 매개 변수를 사용하는 스크립트 블록을 만듭니다. 자세한 내용은 ScriptBlock 매개 변수 설명을 참조하세요.

스크립트 블록 dotnet complete 내에서 명령은 탭 완성을 수행하는 데 사용됩니다. 결과는 System.Management.Automation.CompletionResult 클래스의 새 정적 메서드를 사용하여 각 값에 대한 새 CompletionResult 개체를 만드는 cmdlet에 파이프 ForEach-Object 됩니다.

매개 변수

-CommandName

명령의 이름을 배열로 지정합니다.

Type:String[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Native

인수 완성기가 PowerShell에서 매개 변수 이름을 완료할 수 없는 네이티브 명령에 대한 것임을 나타냅니다.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ParameterName

인수가 완료되는 매개 변수의 이름을 지정합니다. 지정된 매개 변수 이름은 cmdlet의 ForegroundColor 매개 변수와 같은 열거형 값일 Write-Host 수 없습니다.

열거형에 대한 자세한 내용은 about_Enum 참조하세요.

Type:String
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-ScriptBlock

탭 완성을 수행하기 위해 실행할 명령을 지정합니다. 제공하는 스크립트 블록은 입력을 완료하는 값을 반환해야 합니다. 스크립트 블록은 파이프라인(ForEach-Object등 Where-Object) 또는 다른 적합한 메서드를 사용하여 값의 등록을 취소해야 합니다. 값 배열을 반환하면 PowerShell에서 전체 배열을 하나의 탭 완성 값으로 처리합니다.

스크립트 블록은 아래에 지정된 순서대로 다음 매개 변수를 수락해야 합니다. PowerShell이 위치별로 값을 전달하므로 매개 변수의 이름은 중요하지 않습니다.

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

Native 매개 변수를 지정할 때 스크립트 블록은 다음 매개 변수를 지정된 순서로 사용해야 합니다. PowerShell이 위치별로 값을 전달하므로 매개 변수의 이름은 중요하지 않습니다.

  • $wordToComplete(위치 0) - 이 매개 변수는 Tab 키를 누르기 전에 사용자가 제공한 값으로 설정됩니다. 스크립트 블록은 이 값을 사용하여 탭 완성 값을 결정해야 합니다.
  • $commandAst (위치 1) - 이 매개 변수는 현재 입력 줄에 대한 AST(추상 구문 트리)로 설정됩니다. 자세한 내용은 Ast 클래스를 참조 하세요.
  • $cursorPosition(위치 2) - 이 매개 변수는 사용자가 Tab 키를 누를 때 커서의 위치로 설정됩니다.

ArgumentCompleter를 매개 변수 특성으로 제공할 수도 있습니다. 자세한 내용은 about_Functions_Advanced_Parameters 참조하세요.

Type:ScriptBlock
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

입력

None

개체를 이 cmdlet으로 파이프할 수 없습니다.

출력

None

이 cmdlet은 출력을 반환하지 않습니다.