İşlev bağımsız değişkeninin tamamlanması hakkında

Kısa açıklama

Bağımsız değişken tamamlama, PowerShell'in ipuçları sağlayan, keşfetmeyi sağlayan 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ı uygulamanın farklı yolları 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 tamamlayıcıyı tanımlamanın birkaç yolu vardır.

ValidateSet özelliği

ValidateSet özelliğ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şmezse PowerShell bir hata oluşturur. Aşağıdaki örnekte, Meyve parametresinin değeri yalnızca Elma, Muz veya Armut olabilir.

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

Aşağıdaki örnekte, $flavor değişkeninin değeri Çikolata, Çilek veya Vanilya olmalıdır. ValidateSet özelliği yalnızca parametrelerde değil, herhangi bir değişkende kullanılabilir.

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

Doğrulama, bu değişken komut dosyası içinde bile atandığında 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'e ilişkin değerleri dinamik olarak oluşturmak için bir Sınıf kullanabilirsiniz. Aşağıdaki örnekte, $Sound değişkeni için geçerli değerler, kullanılabilir ses dosyaları için üç dosya sistemi yolunu kontrol eden 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
    }
}

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

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

ArgumentCompletions özelliği

ArgumentCompletions özelliği, belirli bir parametreye sekme tamamlama değerleri eklemenizi sağlar. Sekmenin tamamlanmasını gerektiren her parametre için bir ArgumentCompletions özelliği tanımlanmalıdır. ArgumentCompletions özelliği ValidateSet'e benzer. Her iki özellik de, kullanıcı parametre adından sonra Sekme tuşuna bastığında sunulacak değerlerin bir listesini alır. Ancak ValidateSet'ten farklı olarak değerler doğrulanmaz ve daha çok önerilere benzer. Bu nedenle kullanıcı yalnızca listedeki değerleri değil, herhangi bir değeri de sağlayabilir.

ArgumentCompletions özelliği, seçenekleri tanımlamak için bir scriptblock'a ihtiyaç duyan ArgumentCompleter özelliğiyle karıştırılmamalıdır. belirtilen değerler mevcut

Sözdizimi aşağıdaki gibidir:

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

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

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

Sekmenin tamamlanmasını etkinleştirmek için parametrelerin her birine ArgumentCompletions özelliğine yönelik bir seçenekler listesi sunulur.

Bu özellik PowerShell 6.0'da tanıtıldı.

ArgumentCompleter özelliği

ArgumentCompleter özelliği, belirli bir parametreye sekme tamamlama değerleri eklemenizi sağlar. Sekmenin tamamlanması gereken her parametre için bir ArgumentCompleter özelliği tanımlanmalıdır.

ArgumentCompleter özelliği eklemek için değerleri belirleyen bir komut dosyası bloğu tanımlamanız gerekir. Betik bloğunun aşağıdaki parametreleri aşağıda belirtilen sırayla alması gerekir. Değerler konumsal olarak sağlandığı için parametre adlarının bir önemi yoktur.

Sözdizimi aşağıdaki gibidir:

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

ArgumentCompleter komut dosyası bloğu

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

• $commandName (Konum 0) - Bu parametre, komut dosyası bloğunun sekme tamamlamayı sağladığı komutun adı olarak ayarlanır.
• $parameterName (Konum 1) - Bu parametre, değeri sekmenin tamamlanmasını gerektiren parametreye ayarlanır.
• $wordToComplete (Konum 2) - Bu parametre, kullanıcının Sekme tuşuna basmadan önce sağladığı değere ayarlanır. Komut dosyası 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özdizimi Ağacı (AST) olarak 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 için $PSBoundParameters'ı içeren bir hash tablosuna ayarlanır. Daha fazla bilgi için bkz. about_Automatic_Variables.

ArgumentCompleter komut dosyası bloğu, ForEach-Object, Where-Object veya başka bir uygun yöntem gibi işlem hattını kullanarak değerlerin kaydını kaldırmalıdır. Bir değer dizisinin döndürülmesi, PowerShell'in dizinin tamamını bir sekme tamamlama değeri olarak ele almasına neden olur.

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

Ayrıca benzeri operatörü, kullanıcının aşağıdaki komutu yazıp Sekme tamamlamasını kullanması durumunda 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ı argüman tamamlayıcılar

PowerShell 7,2'den itibaren, parametreli bağımsız değişken tamamlayıcıların daha genel uygulamalarını tanımlamanıza olanak tanıyan yeni bir özellik eklenmiştir.

ArgumentCompleterAttribute'tan türeterek yeniden kullanılabilecek genel tamamlayı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üretilmiş özniteliklerin IArgumentCompleterFactory arayüzünü uygulaması ve özel bir tamamlayıcı oluşturmak için özellik değerlerini kullanması gerekir.

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

Register-ArgumentCompleter cmdlet'i özel bir bağımsız değişken tamamlayıcıyı 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.

Ayrıca bakınız

• about_Functions_Advanced_Parameters
• about_Tab_Expansion
• Register-ArgumentCompleter