about_Functions_Argument_Completion

Makale
04/13/2023

Kısa açıklama

Bağımsız değişken tamamlama, PowerShell'in ipuçları sağlayan, bulmayı etkinleştiren ve bağımsız değişken değerlerinin giriş girişini hızlandıran bir özelliğidir.

Uzun açıklama

Bu makalede, PowerShell işlevleri için bağımsız değişken tamamlayıcıları uygulayabileceğiniz farklı yöntemler açıklanmaktadır. Bağımsız değişken tamamlayıcıları bir parametre için olası değerleri sağlar. Kullanılabilir değerler, kullanıcı parametre adından sonra Sekme tuşuna bastığında çalışma zamanında hesaplanır. Bir parametre için bağımsız değişken tamlayıcı tanımlamanın çeşitli yolları vardır.

Not

Sekme , Windows'ta varsayılan anahtar bağlamadır. Bu anahtar bağlama, PSReadLine modülü veya PowerShell'i barındıran uygulama tarafından değiştirilebilir. Anahtar bağlama, Windows dışı platformlarda farklıdır. Daha fazla bilgi için bkz . about_PSReadLine.

ValidateSet özniteliği

ValidateSet özniteliği, bir parametre veya değişken için bir dizi geçerli değer belirtir ve sekmenin tamamlanmasını sağlar. Bir parametre veya değişken değeri kümedeki bir değerle eşleşmiyorsa PowerShell hata oluşturur. Aşağıdaki örnekte Fruit parametresinin değeri yalnızca Apple, Banana veya Pear olabilir.

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

Aşağıdaki örnekte değişkenin $flavor değeri Chocolate, Strawberry veya Vanilla olmalıdır. ValidateSet özniteliği yalnızca parametrelerde değil, herhangi bir değişkende kullanılabilir.

[ValidateSet('Chocolate', 'Strawberry', 'Vanilla')]
[string]$flavor = 'Strawberry'

Bu değişken betik içinde bile atandığında doğrulama gerçekleşir.

Param(
    [ValidateSet('hello', 'world')]
    [string]$Message
)

$Message = 'bye'

Bu örnek çalışma zamanında aşağıdaki hatayı döndürür:

MetadataError: The attribute cannot be added because variable Message with
value bye would no longer be valid.

Sekme genişletme hakkında daha fazla bilgi için bkz . about_Tab_Expansion.

Sınıfları kullanan Dinamik ValidateSet değerleri

Çalışma zamanında ValidateSet değerlerini dinamik olarak oluşturmak için bir Sınıf kullanabilirsiniz. Aşağıdaki örnekte, değişken $Sound için geçerli değerler, kullanılabilir ses dosyaları için üç dosya sistemi yolunu denetleen SoundNames adlı bir Sınıf aracılığıyla oluşturulur:

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
    }
}

Sınıf [SoundNames] daha sonra aşağıdaki gibi dinamik bir ValidateSet değeri olarak uygulanır:

Param(
    [ValidateSet([SoundNames])]
    [string]$Sound
)

Not

IValidateSetValuesGenerator sınıfı PowerShell 6.0'da tanıtıldı.

ArgumentCompletions özniteliği

ArgumentCompletions özniteliği, belirli bir parametreye sekme tamamlama değerleri eklemenize olanak tanır. Sekme tamamlaması gereken her parametre için bir ArgumentCompletions özniteliği tanımlanmalıdır. ArgumentCompletions özniteliği ValidateSet'e benzer. Her iki öznitelik de kullanıcı parametre adından sonra Sekme tuşuna bastığında sunulacak değerlerin listesini alır. Ancak ValidateSet'in aksine, değerler doğrulanmaz ve önerilere benzer. Bu nedenle, kullanıcı yalnızca listedeki değerleri değil herhangi bir değeri sağlayabilir.

ArgumentCompletions özniteliği, seçenekleri tanımlamak için bir betik bloğuna ihtiyaç duyan ArgumentCompleter özniteliğiyle karıştırılmamalıdır. belirtilen değerler kullanılabilir

Söz dizimi şu şekildedir:

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

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

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

Parametrelerin her birine, sekme tamamlamayı etkinleştirmek için ArgumentCompletions özniteliğine bir seçenek listesi sağlanır.

Bu öznitelik PowerShell 6.0'da kullanıma sunulmuştur.

ArgumentCompleter özniteliği

ArgumentCompleter özniteliği, belirli bir parametreye sekme tamamlama değerleri eklemenize olanak tanır. Sekme tamamlaması gereken her parametre için bir ArgumentCompleter özniteliği tanımlanmalıdır.

ArgumentCompleter özniteliği eklemek için değerleri belirleyen bir betik bloğu tanımlamanız gerekir. Betik bloğu aşağıdaki parametreleri aşağıda belirtilen sırayla almalıdır. Değerler konum olarak sağlandığından parametrenin adları önemli değildir.

Söz dizimi şu şekildedir:

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

ArgumentCompleter betik bloğu

Betik bloğu parametreleri aşağıdaki değerlere ayarlanır:

$commandName (Konum 0) - Bu parametre, betik bloğunun sekme tamamlama sağladığı komutun adına ayarlanır.
$parameterName (Konum 1) - Bu parametre, değeri sekme tamamlama gerektiren parametreye ayarlanır.
$wordToComplete(Konum 2) - Bu parametre, kullanıcının Sekme tuşuna basmadan önce sağladığı değere ayarlanır. Betik bloğunuz sekme tamamlama değerlerini belirlemek için bu değeri kullanmalıdır.
$commandAst (Konum 3) - Bu parametre, geçerli giriş satırı için Soyut Söz Dizimi Ağacı 'na (AST) ayarlanır. Daha fazla bilgi için AST türü belgelerine bakın.
$fakeBoundParameters(Konum 4) - Bu parametre, kullanıcı Sekme tuşuna basmadan önce cmdlet'ini içeren $PSBoundParameters bir karma tabloya ayarlanır. Daha fazla bilgi için bkz. about_Automatic_Variables.

ArgumentCompleter betik bloğu, , Where-Objectveya başka bir uygun yöntem gibi ForEach-Objectişlem hattını kullanarak değerlerin kaydını kaldırmalıdır. Bir değer dizisi döndürmek, PowerShell'in tüm diziyi tek sekme tamamlama değeri olarak ele almasına neden olur.

Aşağıdaki örnek, Value parametresine sekme tamamlama ekler. Yalnızca Value parametresi belirtilirse, Value için tüm olası değerler veya bağımsız değişkenler görüntülenir. Tür parametresi belirtildiğinde, Value parametresi yalnızca bu tür için olası değerleri görüntüler.

Buna ek olarak, -like işleç kullanıcı aşağıdaki komutu yazıp Sekme tamamlama kullanırsa yalnızca Apple'ın döndürülmesini sağlar.

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
      )
}

Sınıf tabanlı bağımsız değişken tamlayıcıları

PowerShell 7.2'den başlayarak, parametreli bağımsız değişken tamamlayıcılarının daha genel uygulamalarını tanımlamanıza olanak tanıyan yeni bir özellik eklendi.

'den ArgumentCompleterAttributetüretilerek, yeniden kullanılabilecek genel tamlayıcılar oluşturmak mümkündür, örneğin:

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

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

[GitCommits(Branch='release')]

Türetilen öznitelikler arabirimini IArgumentCompleterFactory uygulamalı ve özel bir tamlayıcı oluşturmak için özellik değerlerini kullanmalıdır.

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'den kullanım şu şekilde olacaktır:

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

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

Register-ArgumentCompleter

cmdlet'i Register-ArgumentCompleter özel bir bağımsız değişken tamlayıcı kaydeder. Bağımsız değişken tamamlayıcı, belirttiğiniz herhangi bir komut için çalışma zamanında dinamik sekme tamamlama sağlamanıza olanak tanır.

Daha fazla bilgi için bkz . Register-ArgumentCompleter.