Udostępnij za pośrednictwem

o_Funkcjach_Zaawansowanych

Krótki opis

Wprowadza funkcje zaawansowane, które są sposobem tworzenia poleceń cmdlet przy użyciu skryptów.

Długi opis

Polecenie cmdlet to pojedyncze polecenie, które uczestniczy w semantyce potokowej PowerShell. Obejmuje to polecenia cmdlet binarne, zaawansowane funkcje programu PowerShell i polecenia cmdlet CDXML.

Funkcje zaawansowane umożliwiają tworzenie poleceń cmdlet napisanych jako funkcja programu PowerShell. Funkcje zaawansowane ułatwiają tworzenie poleceń cmdlet bez konieczności pisania i kompilowania binarnego polecenia cmdlet. Polecenia cmdlet binarne to klasy platformy .NET napisane w języku .NET, takim jak C#.

Funkcje zaawansowane używają atrybutu CmdletBinding, aby zidentyfikować je jako funkcje, które działają jak polecenia cmdlet. Atrybut CmdletBinding jest podobny do atrybutu Cmdlet, który używany jest w skompilowanych klasach cmdlet do identyfikowania klasy jako cmdlet. Aby uzyskać więcej informacji na temat tego atrybutu, zobacz about_Functions_CmdletBindingAttribute.

Parametry funkcji to zmienne zadeklarowane w instrukcji param(). Można użyć opcjonalnego atrybutu [Parameter()] sam lub w połączeniu z atrybutem [Alias()] lub dowolnym atrybutem weryfikacji parametru. Aby uzyskać więcej informacji na temat deklarowania parametrów, zobacz about_Functions_Advanced_Parameters.

W poniższym przykładzie pokazano funkcję, która akceptuje nazwę, a następnie drukuje powitanie przy użyciu podanej nazwy. Zwróć również uwagę, że ta funkcja definiuje nazwę zawierającą parę czasownik-rzeczownik (Send-Greeting), taką jak para czasownik-rzeczownik w skompilowanym cmdlecie. Jednak funkcje nie muszą mieć nazwy w stylu czasownik-rzeczownik.

function Send-Greeting
{
    [CmdletBinding()]
    param(
        [Parameter(Mandatory=$true)]
        [string]$Name
    )

    process
    {
        Write-Host ("Hello " + $Name + "!")
    }
}

Ta funkcja wykonuje pracę w bloku process, który jest odpowiednikiem metody ProcessingRecord używanej w skompilowanych poleceniach cmdlet. Blok process i inne nazwane bloki są opisane w about_Functions_Advanced_Methods.

Funkcje zaawansowane różnią się od skompilowanych poleceń cmdlet w następujący sposób:

  • Powiązanie zaawansowanych parametrów funkcji nie zgłasza wyjątku, kiedy tablica tekstów jest powiązana z parametrem logicznym .
  • Atrybut ValidateSet i atrybut ValidatePattern nie mogą przekazywać nazwanych parametrów.
  • Funkcje zaawansowane nie mogą być używane w transakcjach.

POTOKSTOPTOKEN

Począwszy od programu PowerShell 7.6-preview.4, $PSCmdlet zawiera właściwość PipelineStopToken zezwalającą na dostęp do CancellationToken powiązane ze źródłem zdarzeń zatrzymania programu PowerShell. Token jest wyzwalany, gdy potok programu PowerShell odbiera żądanie zatrzymania. Użyj go z metodą .NET, która akceptuje przeciążenie CancellationToken, aby zamknąć metodę, gdy jest żądana, a nie czekać, aż metoda zwróci.

W poniższym przykładzie funkcja wywołuje HttpClient.GetStringAsync, co może zająć trochę czasu, aby zareagować, gdy sieć działa wolno lub jest zwracanych wiele danych.

function Invoke-CancelableWebRequest {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory=$true)]
        [string]
        $Url
    )

    $client = [System.Net.Http.HttpClient]::new()
    $client.GetStringAsync(
        $Url,
        $PSCmdlet.PipelineStopToken).GetAwaiter().GetResult()
}

Invoke-CancelableWebRequest -Url https://httpbin.org/delay/10
# Press ctrl+c to cancel

Zobacz także

  • Last updated on