about_Functions

Artikel
05/09/2024

Korte beschrijving

Hierin wordt beschreven hoe u functies maakt en gebruikt in PowerShell.

Lange beschrijving

Een functie is een lijst met PowerShell-instructies met een naam die u toewijst. Wanneer u een functie uitvoert, typt u de functienaam. De instructies in de lijst worden uitgevoerd alsof u ze bij de opdrachtprompt hebt getypt.

Functies kunnen zo eenvoudig zijn als:

function Get-PowerShellProcess { Get-Process PowerShell }

Een functie kan ook zo complex zijn als een cmdlet of een toepassing.

Net als cmdlets kunnen functies parameters hebben. De parameters kunnen benoemde, positionele, switch- of dynamische parameters zijn. Functieparameters kunnen worden gelezen vanaf de opdrachtregel of vanuit de pijplijn.

Functies kunnen waarden retourneren die kunnen worden weergegeven, toegewezen aan variabelen of kunnen worden doorgegeven aan andere functies of cmdlets. U kunt ook een retourwaarde opgeven met behulp van het return trefwoord. Het return trefwoord heeft geen invloed op of onderdrukt andere uitvoer die wordt geretourneerd door uw functie. Met het return trefwoord wordt de functie echter op die regel afgesloten. Zie about_Return voor meer informatie.

De instructielijst van de functie kan verschillende typen instructielijsten bevatten met de trefwoorden begin, process, enden clean. Deze instructielijsten verwerken invoer van de pijplijn op een andere manier.

Het trefwoord filter wordt gebruikt om een type functie te maken dat wordt uitgevoerd op elk object in de pijplijn. Een filter lijkt op een functie met alle bijbehorende instructies in een process blok.

Functies kunnen ook fungeren als cmdlets. U kunt een functie maken die net als een cmdlet werkt zonder C# programmeren. Zie about_Functions_Advanced voor meer informatie.

Belangrijk

In scriptbestanden en op scripts gebaseerde modules moeten functies worden gedefinieerd voordat ze kunnen worden aangeroepen.

Syntax

Hier volgt de syntaxis voor een functie:

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

Een functie bevat de volgende items:

Een function trefwoord
Een bereik (optioneel)
Een naam die u selecteert
Een willekeurig aantal benoemde parameters (optioneel)
Een of meer PowerShell-opdrachten tussen accolades {}

Zie about_Functions_Advanced_Parameters voor meer informatie over het dynamicparam trefwoord en de dynamische parameters in functies.

Invoerverwerkingsmethoden

De methoden die in deze sectie worden beschreven, worden de invoerverwerkingsmethoden genoemd. Voor functies worden deze drie methoden vertegenwoordigd door de beginblokken , processen end van de functie. PowerShell 7.3 voegt een clean blokprocesmethode toe.

U hoeft geen van deze blokken in uw functies te gebruiken. Als u geen benoemd blok gebruikt, plaatst PowerShell de code in het end blok van de functie. Als u echter een van deze benoemde blokken gebruikt of een dynamicparam blok definieert, moet u alle code in een benoemd blok plaatsen.

In het volgende voorbeeld ziet u het overzicht van een functie met een begin blok voor eenmalige voorverwerking, een process blok voor verwerking van meerdere records en een end blok voor eenmalige naverwerking.

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

`begin`

Dit blok wordt gebruikt voor optionele eenmalige voorverwerking voor de functie. De PowerShell-runtime gebruikt de code in dit blok eenmaal voor elk exemplaar van de functie in de pijplijn.

`process`

Dit blok wordt gebruikt voor het verwerken van records per record voor de functie. U kunt een process blok gebruiken zonder de andere blokken te definiëren. Het aantal blokuitvoeringen is afhankelijk van process hoe u de functie gebruikt en welke invoer de functie ontvangt.

De automatische variabele $_ of $PSItem bevat het huidige object in de pijplijn voor gebruik in het process blok. De $input automatische variabele bevat een enumerator die alleen beschikbaar is voor functies en scriptblokken. Zie about_Automatic_Variables voor meer informatie.

Als u de functie aan het begin of buiten een pijplijn aanroept, wordt het process blok eenmaal uitgevoerd.
Binnen een pijplijn wordt het process blok eenmaal uitgevoerd voor elk invoerobject dat de functie bereikt.
Als de pijplijninvoer die de functie bereikt, leeg is, wordt het process blok niet uitgevoerd.
- De beginblokken , enden clean worden nog steeds uitgevoerd.

Belangrijk

Als een functieparameter is ingesteld om pijplijninvoer te accepteren en er process geen blok is gedefinieerd, mislukt de verwerking van records voor record. In dit geval wordt uw functie slechts eenmaal uitgevoerd, ongeacht de invoer.

`end`

Dit blok wordt gebruikt voor optionele eenmalige naverwerking voor de functie.

`clean`

Het clean blok is toegevoegd in PowerShell 7.3.

Het clean blok is een handige manier voor gebruikers om resources op te schonen die zich over de beginblokken , processen end beslaan. Het is semantisch vergelijkbaar met een finally blok dat alle andere benoemde blokken van een scriptfunctie of een script-cmdlet omvat. Het opschonen van resources wordt afgedwongen voor de volgende scenario's:

wanneer de uitvoering van de pijplijn normaal wordt voltooid zonder afsluitfout
wanneer de uitvoering van de pijplijn wordt onderbroken vanwege een afsluitfout
wanneer de pijplijn wordt gestopt door Select-Object -First
wanneer de pijplijn wordt gestopt met Ctrl+C of StopProcessing()

Waarschuwing

Het toevoegen van het clean blok is een wijziging die fouten veroorzaakt. Omdat clean wordt geparseerd als een trefwoord, voorkomt u dat gebruikers rechtstreeks een opdracht met de naam clean aanroepen als de eerste instructie in een scriptblok. Het is echter niet waarschijnlijk dat het een probleem is. De opdracht kan nog steeds worden aangeroepen met behulp van de aanroepoperator (& clean).

Eenvoudige functies

Functies hoeven niet ingewikkeld te zijn om nuttig te zijn. De eenvoudigste functies hebben de volgende indeling:

function <function-name> {statements}

Met de volgende functie wordt PowerShell bijvoorbeeld gestart met de optie Uitvoeren als administrator .

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

Als u de functie wilt gebruiken, typt u: Start-PSAdmin

Als u instructies wilt toevoegen aan de functie, typt u elke instructie op een afzonderlijke regel of gebruikt u een puntkomma ; om de instructies te scheiden.

Met de volgende functie vindt u bijvoorbeeld alle .jpg bestanden in de mappen van de huidige gebruiker die zijn gewijzigd na de begindatum.

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

U kunt een werkset met handige kleine functies maken. Voeg deze functies toe aan uw PowerShell-profiel, zoals beschreven in about_Profiles en verderop in dit onderwerp.

Functienamen

U kunt elke naam toewijzen aan een functie, maar functies die u met anderen deelt, moeten voldoen aan de naamgevingsregels die zijn ingesteld voor alle PowerShell-opdrachten.

Functienamen moeten bestaan uit een paar werkwoord-zelfstandig naamwoorden, waarbij het werkwoord de actie identificeert die de functie uitvoert en het zelfstandig naamwoord het item identificeert waarop de cmdlet de actie uitvoert.

Functies moeten de standaardwerkwoorden gebruiken die zijn goedgekeurd voor alle PowerShell-opdrachten. Deze werkwoorden helpen ons om onze opdrachtnamen consistent en gemakkelijk te begrijpen voor gebruikers.

Zie Goedgekeurde werkwoorden voor meer informatie over de standaard PowerShell-werkwoorden.

Functies met parameters

U kunt parameters gebruiken met functies, waaronder benoemde parameters, positieparameters, schakelparameters en dynamische parameters. Zie about_Functions_Advanced_Parameters voor meer informatie over dynamische parameters in functies.

Benoemde parameters

U kunt een willekeurig aantal benoemde parameters definiëren. U kunt een standaardwaarde opnemen voor benoemde parameters, zoals verderop in dit onderwerp wordt beschreven.

U kunt parameters in de accolades definiëren met behulp van het param trefwoord, zoals wordt weergegeven in de volgende voorbeeldsyntaxis:

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

U kunt ook parameters buiten de accolades definiëren zonder het Param trefwoord, zoals wordt weergegeven in de volgende voorbeeldsyntaxis:

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

Hieronder ziet u een voorbeeld van deze alternatieve syntaxis.

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

Hoewel de eerste methode de voorkeur heeft, is er geen verschil tussen deze twee methoden.

Wanneer u de functie uitvoert, wordt de waarde die u opgeeft voor een parameter toegewezen aan een variabele die de parameternaam bevat. De waarde van die variabele kan worden gebruikt in de functie.

Het volgende voorbeeld is een functie met de naam Get-SmallFiles. Deze functie heeft een $Size parameter. De functie geeft alle bestanden weer die kleiner zijn dan de waarde van de $Size parameter en sluit mappen uit:

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

In de functie kunt u de $Size variabele gebruiken. Dit is de naam die is gedefinieerd voor de parameter.

Als u deze functie wilt gebruiken, typt u de volgende opdracht:

Get-SmallFiles -Size 50

U kunt ook een waarde invoeren voor een benoemde parameter zonder de parameternaam. De volgende opdracht geeft bijvoorbeeld hetzelfde resultaat als een opdracht die de parameter Size noemt:

Get-SmallFiles 50

Als u een standaardwaarde voor een parameter wilt definiëren, typt u een gelijkteken en de waarde achter de parameternaam, zoals wordt weergegeven in de volgende variatie van het Get-SmallFiles voorbeeld:

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

Als u zonder waarde typt Get-SmallFiles , wijst de functie 100 toe aan $size. Als u een waarde opgeeft, gebruikt de functie die waarde.

U kunt desgewenst een korte Help-tekenreeks opgeven die de standaardwaarde van uw parameter beschrijft door het kenmerk PSDefaultValue toe te voegen aan de beschrijving van uw parameter en de eigenschap Help van PSDefaultValue op te geven. Als u een Help-tekenreeks wilt opgeven die de standaardwaarde (100) van de parameter Size in de Get-SmallFiles functie beschrijft, voegt u het kenmerk PSDefaultValue toe, zoals wordt weergegeven in het volgende voorbeeld.

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

Zie Leden van het kenmerk PSDefaultValue voor meer informatie over de kenmerkklasse PSDefaultValue.

Positionele parameters

Een positionele parameter is een parameter zonder parameternaam. PowerShell gebruikt de parameterwaardevolgorde om elke parameterwaarde te koppelen aan een parameter in de functie.

Wanneer u positionele parameters gebruikt, typt u een of meer waarden achter de functienaam. Positionele parameterwaarden worden toegewezen aan de $args matrixvariabele. De waarde die volgt op de functienaam, wordt toegewezen aan de eerste positie in de $args matrix, $args[0].

Met de volgende Get-Extension functie wordt de .txt bestandsnaamextensie toegevoegd aan een bestandsnaam die u opgeeft:

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

Get-Extension myTextFile

myTextFile.txt

Parameters wisselen

Een schakeloptie is een parameter waarvoor geen waarde is vereist. In plaats daarvan typt u de functienaam gevolgd door de naam van de switchparameter.

Als u een switchparameter wilt definiëren, geeft u het type [switch] voor de parameternaam op, zoals wordt weergegeven in het volgende voorbeeld:

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

Wanneer u de On switchparameter achter de functienaam typt, wordt de functie weergegeven Switch on. Zonder de switchparameter wordt weergegeven Switch off.

Switch-Item -on

Switch on

Switch-Item

Switch off

U kunt ook een Booleaanse waarde toewijzen aan een switch wanneer u de functie uitvoert, zoals wordt weergegeven in het volgende voorbeeld:

Switch-Item -on:$true

Switch on

Switch-Item -on:$false

Switch off

Splatting gebruiken om opdrachtparameters weer te geven

U kunt splatting gebruiken om de parameters van een opdracht weer te geven. Deze functie is geïntroduceerd in Windows PowerShell 3.0.

Gebruik deze techniek in functies die opdrachten in de sessie aanroepen. U hoeft de opdrachtparameters niet te declareren of op te sommen, of de functie te wijzigen wanneer de opdrachtparameters worden gewijzigd.

Met de volgende voorbeeldfunctie wordt de Get-Command cmdlet aangeroepen. De opdracht gebruikt @Args om de parameters van te vertegenwoordigen.Get-Command

function Get-MyCommand { Get-Command @Args }

U kunt alle parameters van Get-Command gebruiken wanneer u de Get-MyCommand functie aanroept. De parameters en parameterwaarden worden doorgegeven aan de opdracht met behulp van @Args.

Get-MyCommand -Name Get-ChildItem

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

De @Args functie maakt gebruik van de $Args automatische parameter, die niet-opgegeven cmdlet-parameters en waarden van resterende argumenten vertegenwoordigt.

Zie about_Splatting voor meer informatie.

Objecten doorspitten naar functies

Elke functie kan invoer van de pijplijn overnemen. U kunt bepalen hoe een functie invoer van de pijplijn verwerkt met behulp van begin, process, enden clean trefwoorden. In de volgende voorbeeldsyntaxis ziet u de volgende trefwoorden:

De process instructielijst wordt één keer uitgevoerd voor elk object in de pijplijn. Terwijl het process blok wordt uitgevoerd, wordt elk pijplijnobject toegewezen aan de $_ automatische variabele, één pijplijnobject tegelijk.

De volgende functie gebruikt het process trefwoord. De functie geeft waarden uit de pijplijn weer:

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

1,2,4 | Get-Pipeline

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

Als u een functie wilt die pijplijninvoer of -invoer van een parameter kan overnemen, moet het process blok beide gevallen afhandelen. Bijvoorbeeld:

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

Wanneer u een functie in een pijplijn gebruikt, worden de objecten die naar de functie worden doorgesluisd, toegewezen aan de $input automatische variabele. De functie voert instructies uit met het begin trefwoord voordat er objecten uit de pijplijn afkomstig zijn. De functie voert instructies uit met het end trefwoord nadat alle objecten van de pijplijn zijn ontvangen.

In het volgende voorbeeld ziet u de $input automatische variabele met begin trefwoorden en end .

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

Als deze functie wordt uitgevoerd met behulp van de pijplijn, worden de volgende resultaten weergegeven:

1,2,4 | Get-PipelineBeginEnd

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

Wanneer de begin instructie wordt uitgevoerd, beschikt de functie niet over de invoer van de pijplijn. De end instructie wordt uitgevoerd nadat de functie de waarden heeft.

Als de functie een process trefwoord heeft, wordt elk object in $input verwijderd uit $input en toegewezen aan $_. Het volgende voorbeeld bevat een process instructielijst:

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

In dit voorbeeld wordt elk object dat naar de functie wordt doorgesluisd, verzonden naar de process instructielijst. De process instructies worden uitgevoerd op elk object, één object tegelijk. De $input automatische variabele is leeg wanneer de functie het end trefwoord bereikt.

1,2,4 | Get-PipelineInput

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

Zie Enumerators gebruiken voor meer informatie

PowerShell 7.3 heeft het clean blok toegevoegd. Het clean blok is een handige manier voor gebruikers om resources op te schonen die zijn gemaakt en worden gebruikt in de beginblokken , processen end . Het is semantisch vergelijkbaar met een finally blok dat alle andere benoemde blokken van een scriptfunctie of een script-cmdlet omvat. Het opschonen van resources wordt afgedwongen voor de volgende scenario's:

wanneer de uitvoering van de pijplijn normaal wordt voltooid zonder afsluitfout
wanneer de uitvoering van de pijplijn wordt onderbroken vanwege een afsluitfout
wanneer de pijplijn wordt gestopt door Select-Object -First
wanneer de pijplijn wordt gestopt met Ctrl+C of StopProcessing()

Waarschuwing

Het toevoegen van het clean blok is een wijziging die fouten veroorzaakt. Omdat clean wordt geparseerd als een trefwoord, voorkomt dit dat gebruikers rechtstreeks een opdracht met de naam clean aanroepen als de eerste instructie in een scriptblok. Het is echter niet waarschijnlijk dat het een probleem is. De opdracht kan nog steeds worden aangeroepen met behulp van de aanroepoperator (& clean).

Filters

Een filter is een type functie dat wordt uitgevoerd op elk object in de pijplijn. Een filter lijkt op een functie met alle bijbehorende instructies in een process blok.

De syntaxis van een filter is als volgt:

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

Het volgende filter neemt logboekvermeldingen van de pijplijn en geeft vervolgens de hele vermelding of alleen het berichtgedeelte van de vermelding weer:

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

Deze kan als volgt worden gebruikt:

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

Functiebereik

Er bestaat een functie in het bereik waarin deze is gemaakt.

Als een functie deel uitmaakt van een script, is de functie beschikbaar voor instructies in dat script. Standaard is een functie in een script niet beschikbaar buiten dat script.

U kunt het bereik van een functie opgeven. De functie wordt bijvoorbeeld toegevoegd aan het globale bereik in het volgende voorbeeld:

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

Wanneer een functie zich binnen het globale bereik bevindt, kunt u de functie gebruiken in scripts, in functies en op de opdrachtregel.

Functies maken een nieuw bereik. De items die in een functie zijn gemaakt, zoals variabelen, bevinden zich alleen in het functiebereik.

Zie about_Scopes voor meer informatie.

Functies zoeken en beheren met behulp van de functie: Station

Alle functies en filters in PowerShell worden automatisch opgeslagen in het Function: station. Dit station wordt weergegeven door de PowerShell-functieprovider .

Wanneer u naar het Function: station verwijst, typt u een dubbele punt na Functie, net zoals u zou doen wanneer u verwijst naar het C station of D van een computer.

Met de volgende opdracht worden alle functies in de huidige sessie van PowerShell weergegeven:

Get-ChildItem function:

De opdrachten in de functie worden opgeslagen als een scriptblok in de definitie-eigenschap van de functie. Als u bijvoorbeeld de opdrachten wilt weergeven in de Help-functie die bij PowerShell wordt geleverd, typt u:

(Get-ChildItem function:help).Definition

U kunt ook de volgende syntaxis gebruiken.

$function:help

Zie het Help-onderwerp voor de Function:functieprovider voor meer informatie over het station. Typ Get-Help Function.

Functies opnieuw gebruiken in nieuwe sessies

Wanneer u een functie typt bij de PowerShell-opdrachtprompt, wordt de functie onderdeel van de huidige sessie. De functie is beschikbaar totdat de sessie is beëindigd.

Als u uw functie in alle PowerShell-sessies wilt gebruiken, voegt u de functie toe aan uw PowerShell-profiel. Zie about_Profiles voor meer informatie over profielen.

U kunt uw functie ook opslaan in een PowerShell-scriptbestand. Typ uw functie in een tekstbestand en sla het bestand vervolgens op met de .ps1 bestandsnaamextensie.

Help voor Functies schrijven

De Get-Help cmdlet krijgt hulp voor functies, evenals voor cmdlets, providers en scripts. Als u hulp wilt krijgen voor een functie, typt Get-Help u gevolgd door de functienaam.

Als u bijvoorbeeld hulp wilt krijgen voor de Get-MyDisks functie, typt u:

Get-Help Get-MyDisks

U kunt help voor een functie schrijven met behulp van een van de volgende twee methoden:

Comment-Based Help voor Functions

Creatie een Help-onderwerp met speciale trefwoorden in de opmerkingen. Als u hulp op basis van opmerkingen voor een functie wilt maken, moeten de opmerkingen worden geplaatst aan het begin of einde van de hoofdtekst van de functie of op de regels voorafgaand aan het functiewoord. Zie about_Comment_Based_Help voor meer informatie over hulp op basis van opmerkingen.
XML-Based Help voor Functions

Creatie een Help-onderwerp op basis van XML, zoals het type dat doorgaans wordt gemaakt voor cmdlets. Hulp op basis van XML is vereist als u Help-onderwerpen in meerdere talen wilt lokaliseren.

Als u de functie wilt koppelen aan het OP XML gebaseerde Help-onderwerp, gebruikt u het .EXTERNALHELP op opmerkingen gebaseerde Help-trefwoord. Zonder dit trefwoord kan Get-Help het Help-onderwerp voor de functie niet worden gevonden en kan aanroepen naar Get-Help voor de functie alleen automatisch gegenereerde help retourneren.

Zie about_Comment_Based_Help voor meer informatie over het .EXTERNALHELP trefwoord. Zie How to Write Cmdlet Help (Help voor cmdlets schrijven) voor meer informatie over help op basis van XML.

Delen via