about_Functions

Artykuł
03/13/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 wpisz nazwę funkcji. Instrukcje na liście są uruchamiane tak, jakby były wpisywane w wierszu polecenia.

Funkcje mogą być tak proste, jak:

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ć nazwę, położenie, przełącznik lub parametry dynamiczne. Parametry funkcji można odczytywać z wiersza polecenia lub z potoku.

Funkcje mogą zwracać wartości, które mogą być wyświetlane, przypisane do zmiennych lub przekazywane do innych funkcji lub poleceń cmdlet. Możesz 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, processi end. Ta instrukcja zawiera listę obsługi danych wejściowych z potoku w inny sposób.

Słowo kluczowe filtru służy do tworzenia typu funkcji uruchamianej w 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 należy zdefiniować funkcje, 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>}
}

function [<scope:>]<name>
{
  param([type]$parameter1 [,[type]$parameter2])
  dynamicparam {<statement list>}
  begin {<statement list>}
  process {<statement list>}
  end {<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 funkcji , processi end .

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 i 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 udostępniania przetwarzania rekordów według rekordów dla funkcji. Blok można używać process bez definiowania innych bloków. process Liczba wykonań 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 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 na akceptowanie danych wejściowych potoku, a process blok nie jest zdefiniowany, przetwarzanie rekordu po rekordzie zakończy się niepowodzeniem. W takim przypadku funkcja będzie wykonywana tylko raz, niezależnie od danych wejściowych.

`end`

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

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 Administracja istrator.

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 następująca 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

Parametry można używać 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 przedstawiono 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żna 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
  }
}

W przypadku wpisywania Get-SmallFiles bez wartości funkcja przypisuje 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ść Help 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 o klasie atrybutów 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 tablicowej. 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 wpisz nazwę funkcji, po której następuje nazwa parametru switch.

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 Switch onwartość . Bez parametru switch 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ć splattingu. Ta funkcja jest wprowadzana w programie 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.

Poniższa 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 , processi end . 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 pobierać 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 dokonaniu wartości przez funkcję .

Jeśli funkcja ma process słowo kluczowe, każdy obiekt w $input pliku zostanie usunięty i $input 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 naraz. 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)

Filtry

Filtr jest typem funkcji uruchamianej 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 została utworzona.

Jeśli funkcja jest częścią skryptu, funkcja jest dostępna dla instrukcji w tym skrypcie. 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żesz użyć funkcji w skryptach, 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 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:

Pomoc oparta na komentarzach dla funkcji

Utwórz temat pomocy przy użyciu specjalnych słów kluczowych w komentarzach. Aby utworzyć pomoc opartą na komentarzach dla funkcji, komentarze muszą zostać 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.
Pomoc oparta na xml dla funkcji

Utwórz temat pomocy opartej na formacie XML, taki jak typ, który jest zwykle tworzony dla poleceń cmdlet. Pomoc oparta na formacie 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łania Get-Help funkcji zwracają 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).