about_Functions

Artykuł
05/09/2024

Krótki opis

Opisuje sposób tworzenia i używania funkcji w programie PowerShell.

Długi opis

Funkcja to lista instrukcji programu PowerShell, która ma przypisaną nazwę. Po uruchomieniu funkcji należy wpisać nazwę funkcji. Instrukcje na liście są uruchamiane tak, jakby były wpisywane w wierszu polecenia.

Funkcje mogą być proste:

function Get-PowerShellProcess { Get-Process PowerShell }

Funkcja może być również tak złożona jak polecenie cmdlet lub aplikacja.

Podobnie jak polecenia cmdlet, funkcje mogą mieć parametry. Parametry mogą mieć nazwy, pozycyjne, przełącznik lub parametry dynamiczne. Parametry funkcji można odczytać z wiersza polecenia lub z potoku.

Funkcje mogą zwracać wartości, które mogą być wyświetlane, przypisywane do zmiennych lub przekazywane do innych funkcji lub poleceń cmdlet. Można również określić wartość zwracaną przy użyciu słowa kluczowego return . Słowo return kluczowe nie wpływa ani nie pomija innych danych wyjściowych zwracanych z funkcji. Jednak return słowo kluczowe zamyka funkcję w tym wierszu. Aby uzyskać więcej informacji, zobacz about_Return.

Lista instrukcji funkcji może zawierać różne typy list instrukcji ze słowami kluczowymi begin, process, endi clean. Te instrukcje obsługują dane wejściowe z potoku w inny sposób.

Słowo kluczowe filtru służy do tworzenia typu funkcji uruchamianej na każdym obiekcie w potoku. Filtr przypomina funkcję ze wszystkimi instrukcjami w process bloku.

Funkcje mogą również działać jak polecenia cmdlet. Możesz utworzyć funkcję, która działa tak samo jak polecenie cmdlet bez używania C# programowania. Aby uzyskać więcej informacji, zobacz about_Functions_Advanced.

Ważne

W plikach skryptów i modułach opartych na skryptach funkcje muszą być zdefiniowane, zanim będą mogły być wywoływane.

Składnia

Poniżej przedstawiono składnię funkcji:

function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])]
{
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
  clean {<statement list>}
}

function [<scope:>]<name>
{
  param([type]$parameter1 [,[type]$parameter2])
  dynamicparam {<statement list>}
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
  clean {<statement list>}
}

Funkcja zawiera następujące elementy:

Słowo function kluczowe
Zakres (opcjonalnie)
Wybrana nazwa
Dowolna liczba nazwanych parametrów (opcjonalnie)
Co najmniej jedno polecenie programu PowerShell ujęte w nawiasy klamrowe {}

Aby uzyskać więcej informacji na temat słowa kluczowego dynamicparam i parametrów dynamicznych w funkcjach, zobacz about_Functions_Advanced_Parameters.

Metody przetwarzania danych wejściowych

Metody opisane w tej sekcji są określane jako metody przetwarzania danych wejściowych. W przypadku funkcji te trzy metody są reprezentowane przez beginbloki , processi end funkcji . Program PowerShell 7.3 dodaje metodę procesu blokowego clean .

Nie musisz używać żadnych z tych bloków w funkcjach. Jeśli nie używasz nazwanego bloku, program PowerShell umieszcza kod w end bloku funkcji. Jeśli jednak używasz dowolnego z tych nazwanych bloków lub zdefiniuj dynamicparam blok, musisz umieścić cały kod w nazwanym bloku.

W poniższym przykładzie przedstawiono konspekt funkcji, która zawiera begin blok jednorazowego przetwarzania wstępnego, process blok przetwarzania wielu rekordów oraz end blok jednorazowego przetwarzania końcowego.

Function Test-ScriptCmdlet
{
[CmdletBinding(SupportsShouldProcess=$True)]
    Param ($Parameter1)
    begin{}
    process{}
    end{}
}

`begin`

Ten blok służy do zapewnienia opcjonalnego jednorazowego przetwarzania wstępnego dla funkcji. Środowisko uruchomieniowe programu PowerShell używa kodu w tym bloku raz dla każdego wystąpienia funkcji w potoku.

`process`

Ten blok służy do zapewnienia przetwarzania rekordów po rekordach dla funkcji. Blok można używać process bez definiowania innych bloków. Liczba wykonań process bloków zależy od sposobu używania funkcji i danych wejściowych odbieranych przez funkcję.

Zmienna $_ automatyczna lub $PSItem zawiera bieżący obiekt w potoku do użycia w process bloku. Zmienna automatyczna $input zawiera moduł wyliczający, który jest dostępny tylko dla funkcji i bloków skryptów. Aby uzyskać więcej informacji, zobacz about_Automatic_Variables.

Wywołanie funkcji na początku lub poza potokiem wykonuje process blok raz.
W potoku process blok jest wykonywany raz dla każdego obiektu wejściowego, który dociera do funkcji.
Jeśli dane wejściowe potoku docierające do funkcji są puste, process blok nie jest wykonywany.
- Bloki begin, endi clean nadal są wykonywane.

Ważne

Jeśli parametr funkcji jest ustawiony do akceptowania danych wejściowych potoku, a process blok nie jest zdefiniowany, przetwarzanie rekordu po rekordzie zakończy się niepowodzeniem. W takim przypadku funkcja zostanie wykonana tylko raz, niezależnie od danych wejściowych.

`end`

Ten blok służy do zapewnienia opcjonalnego jednorazowego przetwarzania końcowego dla funkcji.

`clean`

Blok clean został dodany w programie PowerShell 7.3.

Blok clean jest wygodnym sposobem czyszczenia zasobów obejmujących beginbloki , i end . process Jest to semantycznie podobne do finally bloku, który obejmuje wszystkie inne nazwane bloki funkcji skryptu lub polecenia cmdlet skryptu. Czyszczenie zasobów jest wymuszane w następujących scenariuszach:

gdy wykonywanie potoku kończy się normalnie bez błędu zakończenia
gdy wykonywanie potoku zostanie przerwane z powodu błędu zakończenia
gdy potok zostanie zatrzymany przez Select-Object -First
gdy potok jest zatrzymywany za pomocą klawiszy Ctrl+c lub StopProcessing()

Przestroga

clean Dodanie bloku to zmiana powodująca niezgodność. Ponieważ clean element jest analizowany jako słowo kluczowe, uniemożliwia użytkownikom bezpośrednie wywoływanie polecenia o nazwie clean jako pierwszej instrukcji w bloku skryptu. Jednak prawdopodobnie nie będzie to problem. Nadal można wywołać polecenie przy użyciu operatora wywołania (& clean).

Proste funkcje

Funkcje nie muszą być skomplikowane, aby były przydatne. Najprostsze funkcje mają następujący format:

function <function-name> {statements}

Na przykład poniższa funkcja uruchamia program PowerShell z opcją Uruchom jako administrator .

function Start-PSAdmin {Start-Process PowerShell -Verb RunAs}

Aby użyć funkcji, wpisz: Start-PSAdmin

Aby dodać instrukcje do funkcji, wpisz każdą instrukcję w osobnym wierszu lub użyj średnika ; , aby oddzielić instrukcje.

Na przykład poniższa funkcja znajduje wszystkie .jpg pliki w katalogach bieżącego użytkownika, które zostały zmienione po dacie rozpoczęcia.

function Get-NewPix
{
  $start = Get-Date -Month 1 -Day 1 -Year 2010
  $allpix = Get-ChildItem -Path $env:UserProfile\*.jpg -Recurse
  $allpix | Where-Object {$_.LastWriteTime -gt $Start}
}

Możesz utworzyć przybornik przydatnych małych funkcji. Dodaj te funkcje do profilu programu PowerShell zgodnie z opisem w about_Profiles i w dalszej części tego tematu.

Nazwy funkcji

Możesz przypisać dowolną nazwę do funkcji, ale funkcje, które udostępniasz innym osobom, powinny być zgodne z regułami nazewnictwa, które zostały ustanowione dla wszystkich poleceń programu PowerShell.

Nazwy funkcji powinny składać się z pary rzeczowników czasownika, gdzie czasownik identyfikuje akcję wykonywaną przez funkcję, a rzeczownik identyfikuje element, na którym polecenie cmdlet wykonuje swoją akcję.

Funkcje powinny używać standardowych czasowników zatwierdzonych dla wszystkich poleceń programu PowerShell. Te czasowniki pomagają nam zachować spójne i łatwe zrozumienie nazw poleceń przez użytkowników.

Aby uzyskać więcej informacji na temat standardowych czasowników programu PowerShell, zobacz Zatwierdzone czasowniki.

Funkcje z parametrami

Można używać parametrów z funkcjami, w tym nazwanymi parametrami, parametrami pozycyjnymi, parametrami przełącznika i parametrami dynamicznymi. Aby uzyskać więcej informacji na temat parametrów dynamicznych w funkcjach, zobacz about_Functions_Advanced_Parameters.

Nazwane parametry

Można zdefiniować dowolną liczbę nazwanych parametrów. Możesz uwzględnić wartość domyślną nazwanych parametrów zgodnie z opisem w dalszej części tego tematu.

Parametry wewnątrz nawiasów klamrowych można zdefiniować przy użyciu słowa kluczowego param , jak pokazano w następującej przykładowej składni:

function <name> {
  param ([type]$parameter1 [,[type]$parameter2])
  <statement list>
}

Można również zdefiniować parametry poza nawiasami klamrowymi bez słowa kluczowego Param , jak pokazano w następującej przykładowej składni:

function <name> [([type]$parameter1[,[type]$parameter2])] {
  <statement list>
}

Poniżej znajduje się przykład tej alternatywnej składni.

function Add-Numbers([int]$one, [int]$two) {
    $one + $two
}

Chociaż pierwsza metoda jest preferowana, nie ma różnicy między tymi dwiema metodami.

Po uruchomieniu funkcji wartość podana dla parametru jest przypisywana do zmiennej zawierającej nazwę parametru. Wartość tej zmiennej może być używana w funkcji .

Poniższy przykład to funkcja o nazwie Get-SmallFiles. Ta funkcja ma $Size parametr . Funkcja wyświetla wszystkie pliki, które są mniejsze niż wartość parametru $Size , i wyklucza katalogi:

function Get-SmallFiles {
  Param($Size)
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

W funkcji można użyć zmiennej $Size , która jest nazwą zdefiniowaną dla parametru .

Aby użyć tej funkcji, wpisz następujące polecenie:

Get-SmallFiles -Size 50

Możesz również wprowadzić wartość nazwanego parametru bez nazwy parametru. Na przykład następujące polecenie daje taki sam wynik jak polecenie, które nazywa parametr Size :

Get-SmallFiles 50

Aby zdefiniować wartość domyślną parametru, wpisz znak równości i wartość po nazwie parametru, jak pokazano w następującej odmianie przykładu Get-SmallFiles :

function Get-SmallFiles ($Size = 100) {
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

Jeśli wpiszesz Get-SmallFiles wartość bez wartości, funkcja przypisze 100 do $size. Jeśli podasz wartość, funkcja używa tej wartości.

Opcjonalnie możesz podać krótki ciąg pomocy opisujący wartość domyślną parametru, dodając atrybut PSDefaultValue do opisu parametru i określając właściwość Helpelementu PSDefaultValue. Aby podać ciąg pomocy opisujący wartość domyślną (100) parametru Size w Get-SmallFiles funkcji, dodaj atrybut PSDefaultValue , jak pokazano w poniższym przykładzie.

function Get-SmallFiles {
  param (
      [PSDefaultValue(Help = '100')]
      $Size = 100
  )
}

Aby uzyskać więcej informacji na temat klasy atrybutu PSDefaultValue , zobacz PSDefaultValue Attribute Members( Składowe atrybutów PSDefaultValue).

Parametry pozycyjne

Parametr pozycyjny jest parametrem bez nazwy parametru. Program PowerShell używa kolejności wartości parametru, aby skojarzyć każdą wartość parametru z parametrem w funkcji.

W przypadku używania parametrów pozycyjnych wpisz co najmniej jedną wartość po nazwie funkcji. Wartości parametrów pozycyjnych są przypisywane do zmiennej $args tablicy. Wartość zgodna z nazwą funkcji jest przypisywana do pierwszej pozycji w tablicy $args . $args[0]

Następująca Get-Extension funkcja dodaje .txt rozszerzenie nazwy pliku do podanej nazwy pliku:

function Get-Extension {
  $name = $args[0] + ".txt"
  $name
}

Get-Extension myTextFile

myTextFile.txt

Parametry przełącznika

Przełącznik jest parametrem, który nie wymaga wartości. Zamiast tego należy wpisać nazwę funkcji, po której następuje nazwa parametru przełącznika.

Aby zdefiniować parametr przełącznika, określ typ [switch] przed nazwą parametru, jak pokazano w poniższym przykładzie:

function Switch-Item {
  param ([switch]$on)
  if ($on) { "Switch on" }
  else { "Switch off" }
}

Po wpisaniu parametru On przełącznika po nazwie funkcji funkcja wyświetla wartość Switch on. Bez parametru przełącznika wyświetla Switch offwartość .

Switch-Item -on

Switch on

Switch-Item

Switch off

Można również przypisać wartość logiczną do przełącznika podczas uruchamiania funkcji, jak pokazano w poniższym przykładzie:

Switch-Item -on:$true

Switch on

Switch-Item -on:$false

Switch off

Używanie narzędzia Splatting do reprezentowania parametrów polecenia

Do reprezentowania parametrów polecenia można użyć narzędzia splatting. Ta funkcja została wprowadzona w Windows PowerShell 3.0.

Ta technika jest używana w funkcjach wywołujących polecenia w sesji. Nie musisz deklarować ani wyliczać parametrów polecenia ani zmieniać funkcji po zmianie parametrów polecenia.

Następująca przykładowa funkcja wywołuje Get-Command polecenie cmdlet . Polecenie używa @Args polecenia do reprezentowania parametrów .Get-Command

function Get-MyCommand { Get-Command @Args }

Podczas wywoływania Get-MyCommand funkcji można użyć wszystkich parametrówGet-Command. Parametry i wartości parametrów są przekazywane do polecenia przy użyciu polecenia @Args.

Get-MyCommand -Name Get-ChildItem

CommandType     Name                ModuleName
-----------     ----                ----------
Cmdlet          Get-ChildItem       Microsoft.PowerShell.Management

Funkcja @Args używa parametru $Args automatycznego, który reprezentuje niezdecydowane parametry polecenia cmdlet i wartości z pozostałych argumentów.

Aby uzyskać więcej informacji, zobacz about_Splatting.

Potokowanie obiektów do funkcji

Każda funkcja może pobierać dane wejściowe z potoku. Możesz kontrolować sposób przetwarzania danych wejściowych przez funkcję z potoku przy użyciu słów beginkluczowych , process, endi clean . Następująca przykładowa składnia przedstawia następujące słowa kluczowe:

Lista process instrukcji jest uruchamiana jeden raz dla każdego obiektu w potoku. process Gdy blok jest uruchomiony, każdy obiekt potoku jest przypisywany do zmiennej automatycznej$_, jeden obiekt potoku naraz.

Poniższa funkcja używa słowa kluczowego process . Funkcja wyświetla wartości z potoku:

function Get-Pipeline
{
  process {"The value is: $_"}
}

1,2,4 | Get-Pipeline

The value is: 1
The value is: 2
The value is: 4

Jeśli chcesz, aby funkcja, która może przyjmować dane wejściowe lub wejściowe potoku z parametru, process blok musi obsługiwać oba przypadki. Na przykład:

function Get-SumOfNumbers {
    param (
        [int[]]$Numbers
    )

    begin { $retValue = 0 }

    process {
        if ($null -ne $Numbers) {
           foreach ($n in $Numbers) {
               $retValue += $n
           }
        } else {
           $retValue += $_
        }
    }

    end { $retValue }
}

PS> 1,2,3,4 | Get-SumOfNumbers
10
PS> Get-SumOfNumbers 1,2,3,4
10

Gdy używasz funkcji w potoku, obiekty przesyłane potokiem do funkcji są przypisywane do zmiennej automatycznej $input . Funkcja uruchamia instrukcje ze begin słowem kluczowym , zanim wszystkie obiekty pochodzą z potoku. Funkcja uruchamia instrukcje ze end słowem kluczowym po odebraniu wszystkich obiektów z potoku.

W poniższym przykładzie przedstawiono zmienną automatyczną $input z słowami kluczowymi begin i .end

function Get-PipelineBeginEnd {
    begin   { "Begin: The input is $input" }
    end     { "End:   The input is $input" }
}

Jeśli ta funkcja jest uruchamiana przy użyciu potoku, wyświetla następujące wyniki:

1,2,4 | Get-PipelineBeginEnd

Begin: The input is
End:   The input is 1 2 4

Po uruchomieniu instrukcji begin funkcja nie ma danych wejściowych z potoku. Instrukcja end jest uruchamiana po użyciu wartości funkcji .

Jeśli funkcja ma process słowo kluczowe, każdy obiekt w $input pliku jest usuwany z $input elementu i przypisany do elementu $_. Poniższy przykład zawiera process listę instrukcji:

function Get-PipelineInput
{
    process {"Processing:  $_ " }
    end     {"End:   The input is: $input" }
}

W tym przykładzie każdy obiekt, który jest przesyłany potokami do funkcji, jest wysyłany do listy instrukcji process . Instrukcje process są uruchamiane na każdym obiekcie , po jednym obiekcie jednocześnie. Zmienna automatyczna $input jest pusta, gdy funkcja osiągnie end słowo kluczowe .

1,2,4 | Get-PipelineInput

Processing:  1
Processing:  2
Processing:  4
End:   The input is:

Aby uzyskać więcej informacji, zobacz Using Enumerators (Korzystanie z modułów wyliczania)

Program PowerShell 7.3 dodał clean blok. Blok clean jest wygodnym sposobem czyszczenia zasobów utworzonych i używanych w beginblokach , processi end . Jest to semantycznie podobne do finally bloku, który obejmuje wszystkie inne nazwane bloki funkcji skryptu lub polecenia cmdlet skryptu. Czyszczenie zasobów jest wymuszane w następujących scenariuszach:

gdy wykonywanie potoku kończy się normalnie bez błędu zakończenia
gdy wykonywanie potoku zostanie przerwane z powodu błędu zakończenia
gdy potok zostanie zatrzymany przez Select-Object -First
gdy potok jest zatrzymywany za pomocą klawiszy Ctrl+C lub StopProcessing()

Przestroga

Filtry

Filtr jest typem funkcji, która jest uruchamiana na każdym obiekcie w potoku. Filtr przypomina funkcję ze wszystkimi instrukcjami w process bloku.

Składnia filtru jest następująca:

filter [<scope:>]<name> {<statement list>}

Poniższy filtr pobiera wpisy dziennika z potoku, a następnie wyświetla cały wpis lub tylko część komunikatu wpisu:

filter Get-ErrorLog ([switch]$Message)
{
  if ($Message) { Out-Host -InputObject $_.Message }
  else { $_ }
}

Można go użyć w następujący sposób:

Get-WinEvent -LogName System -MaxEvents 100 | Get-ErrorLog -Message

Zakres funkcji

Funkcja istnieje w zakresie, w którym jest tworzona.

Jeśli funkcja jest częścią skryptu, funkcja jest dostępna dla instrukcji w ramach tego skryptu. Domyślnie funkcja w skrypsie nie jest dostępna poza tym skryptem.

Zakres funkcji można określić. Na przykład funkcja jest dodawana do zakresu globalnego w poniższym przykładzie:

function global:Get-DependentSvs {
  Get-Service | Where-Object {$_.DependentServices}
}

Gdy funkcja znajduje się w zakresie globalnym, można użyć funkcji w skryptach, w funkcjach i w wierszu polecenia.

Funkcje tworzą nowy zakres. Elementy utworzone w funkcji, takie jak zmienne, istnieją tylko w zakresie funkcji.

Aby uzyskać więcej informacji, zobacz about_Scopes.

Znajdowanie funkcji i zarządzanie nimi przy użyciu funkcji: dysk

Wszystkie funkcje i filtry w programie PowerShell są automatycznie przechowywane na Function: dysku. Ten dysk jest udostępniany przez dostawcę funkcji programu PowerShell.

Podczas odwoływania się do Function: dysku wpisz dwukropek po funkcji, tak jak w przypadku odwoływania się do C dysku lub D komputera.

Następujące polecenie wyświetla wszystkie funkcje w bieżącej sesji programu PowerShell:

Get-ChildItem function:

Polecenia w funkcji są przechowywane jako blok skryptu we właściwości definicji funkcji. Aby na przykład wyświetlić polecenia w funkcji Help dostarczanej z programem PowerShell, wpisz:

(Get-ChildItem function:help).Definition

Można również użyć następującej składni.

$function:help

Aby uzyskać więcej informacji na temat Function: dysku, zobacz temat pomocy dla dostawcy funkcji . Wpisz Get-Help Function.

Ponowne tworzenie funkcji w nowych sesjach

Podczas wpisywania funkcji w wierszu polecenia programu PowerShell funkcja staje się częścią bieżącej sesji. Funkcja jest dostępna do momentu zakończenia sesji.

Aby użyć funkcji we wszystkich sesjach programu PowerShell, dodaj funkcję do profilu programu PowerShell. Aby uzyskać więcej informacji na temat profilów, zobacz about_Profiles.

Funkcję można również zapisać w pliku skryptu programu PowerShell. Wpisz funkcję w pliku tekstowym, a następnie zapisz plik z .ps1 rozszerzeniem nazwy pliku.

Pisanie pomocy dotyczącej funkcji

Polecenie Get-Help cmdlet otrzymuje pomoc dotyczącą funkcji, a także poleceń cmdlet, dostawców i skryptów. Aby uzyskać pomoc dotyczącą funkcji, wpisz Get-Help nazwę funkcji.

Aby na przykład uzyskać pomoc dotyczącą Get-MyDisks funkcji, wpisz:

Get-Help Get-MyDisks

Pomoc dotyczącą funkcji można napisać przy użyciu jednej z dwóch następujących metod:

Comment-Based Pomoc dla funkcji

Twórca temat pomocy przy użyciu specjalnych słów kluczowych w komentarzach. Aby utworzyć pomoc opartą na komentarzach dla funkcji, komentarze muszą być umieszczone na początku lub na końcu treści funkcji lub w wierszach poprzedzających słowo kluczowe funkcji. Aby uzyskać więcej informacji na temat pomocy opartej na komentarzach, zobacz about_Comment_Based_Help.
XML-Based Pomoc dla funkcji

Twórca temat pomocy opartej na formacie XML, taki jak typ, który jest zwykle tworzony dla poleceń cmdlet. Pomoc oparta na języku XML jest wymagana, jeśli lokalizujesz tematy pomocy w wielu językach.

Aby skojarzyć funkcję z tematem pomocy opartej na języku XML, użyj słowa kluczowego pomocy opartej .EXTERNALHELP na komentarzach. Bez tego słowa kluczowego Get-Help nie można znaleźć tematu pomocy funkcji i wywołań funkcji, aby Get-Help funkcja zwróciła tylko automatycznie wygenerowaną pomoc.

Aby uzyskać więcej informacji na temat słowa kluczowego .EXTERNALHELP , zobacz about_Comment_Based_Help. Aby uzyskać więcej informacji na temat pomocy opartej na formacie XML, zobacz How to Write Cmdlet Help (Jak napisać pomoc dotyczącą poleceń cmdlet).

Udostępnij za pośrednictwem