about_Functions

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 program aplikacji.

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 zwróconych 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. Te instrukcje obsługują dane wejściowe z potoku w inny sposób.

Filtr jest specjalnym rodzajem funkcji, która używa słowa kluczowego Filter .

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

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.

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, w której 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 w utrzymaniu prostych, spójnych i łatwych w zrozumieniu nazw poleceń.

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

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 komunikat "Switch on". Bez parametru switch wyświetla komunikat "Wyłącz".

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 trzeba 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 na temat splattingu, 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 funkcji z potoku przy użyciu Beginsłów kluczowych , Processi End . Poniższa przykładowa składnia przedstawia trzy słowa kluczowe:

function <name> {
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
}

Lista Begin instrukcji jest uruchamiana tylko raz na początku funkcji.

Ważne

Jeśli funkcja definiuje Beginblok lub End , Process cały kod musi znajdować się wewnątrz tych bloków. Żaden kod nie zostanie rozpoznany poza blokami, jeśli którykolwiek z bloków zostanie zdefiniowany.

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

Po odebraniu wszystkich obiektów w potoku End lista instrukcji jest uruchamiana jednorazowo. Jeśli nie Beginsą używane żadne słowa kluczowe , Processlub End , wszystkie instrukcje są traktowane jak End lista instrukcji.

Poniższa funkcja używa słowa kluczowego Process . Funkcja wyświetla przykłady z potoku:

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

Aby zademonstrować tę funkcję, wprowadź listę liczb rozdzielonych przecinkami, jak pokazano w poniższym przykładzie:

1,2,4 | Get-Pipeline

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

W przypadku używania 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 tym, jak funkcja ma wartości.

Jeśli funkcja ma słowo kluczowe, każdy obiekt w elemecie Process zostanie usunięty i $input przypisany do $_elementu .$input Poniższy przykład zawiera listę instrukcji Process :

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

W tym przykładzie każdy obiekt przesyłany potokami do funkcji jest wysyłany do listy instrukcji Process . Instrukcje Process są uruchamiane na każdym obiekcie, jeden obiekt naraz. Zmienna automatyczna jest pusta $input , 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>}

Następujący 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 { $_ }
}

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 skrypcie nie jest dostępna w wierszu polecenia.

Możesz określić zakres funkcji. 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 zwykle tworzą zakres. Elementy utworzone w funkcji, takie jak zmienne, istnieją tylko w zakresie funkcji.

Aby uzyskać więcej informacji na temat zakresu w programie PowerShell, 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żesz 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. 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:

• Comment-Based Pomoc 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ą 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

  Utwórz 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 odnaleźć tematu pomocy funkcji i wywołań funkcji, aby Get-Help funkcja zwróciła tylko pomoc wygenerowaną automatycznie.

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

Zobacz też

• about_Automatic_Variables
• about_Comment_Based_Help
• about_Function_Provider
• about_Functions_Advanced
• about_Functions_Advanced_Methods
• about_Functions_Advanced_Parameters
• about_Functions_CmdletBindingAttribute
• about_Functions_OutputTypeAttribute
• about_Parameters
• about_Profiles
• about_Scopes
• about_Script_Blocks