about_Functions

Artikel
06/26/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 naam van de functie. De instructies in de lijst worden uitgevoerd alsof u ze bij de opdrachtprompt hebt getypt.

Functies kunnen net zo eenvoudig zijn als:

function Get-PowerShellProcess { Get-Process pwsh }

Zodra een functie is gedefinieerd, kunt u deze gebruiken zoals de ingebouwde cmdlets. Als u bijvoorbeeld de zojuist gedefinieerde Get-PowerShellProcess functie wilt aanroepen:

Get-PowerShellProcess

 NPM(K)    PM(M)      WS(M)     CPU(s)      Id  SI ProcessName
 ------    -----      -----     ------      --  -- -----------
    110    78.72     172.39      10.62   10936   1 pwsh

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

Net als cmdlets kunnen functies parameters hebben. De parameters kunnen benoemd, positioneel, 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 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. Het return trefwoord sluit echter de functie op die regel af. Zie about_Return voor meer informatie.

De instructielijst van de functie kan verschillende typen instructielijsten bevatten met de trefwoorden begin, processen cleanend. Met deze instructie wordt de invoer van de pijplijn anders verwerkt.

Het trefwoord filter wordt gebruikt om een type functie te maken dat op elk object in de pijplijn wordt uitgevoerd. 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 programmeren te gebruiken C# . Zie about_Functions_Advanced voor meer informatie.

Belangrijk

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

Syntaxis

Hier volgen 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 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 begin, processen end blokken 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 die een begin blok bevat voor eenmalige verwerking, een process blok voor meerdere recordverwerking en een end blok voor eenmalige naverwerking.

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

`begin`

Dit blok wordt gebruikt om optionele eenmalige voorverwerking voor de functie op te geven. De PowerShell-runtime gebruikt de code in dit blok één keer voor elk exemplaar van de functie in de pijplijn.

`process`

Dit blok wordt gebruikt voor record-by-recordverwerking 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 begin, enden clean blokken worden nog steeds uitgevoerd.

Belangrijk

Als een functieparameter is ingesteld op het accepteren van pijplijninvoer en er process geen blok is gedefinieerd, mislukt record-by-recordverwerking. In dit geval wordt uw functie slechts eenmaal uitgevoerd, ongeacht de invoer.

`end`

Dit blok wordt gebruikt om optionele eenmalige naverwerking voor de functie te bieden.

`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 begin, processen end blokken 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 is voltooid zonder afsluitfout
wanneer de uitvoering van de pijplijn wordt onderbroken vanwege een afsluitfout
wanneer de pijplijn is gestopt door Select-Object -First
wanneer de pijplijn wordt gestopt door Ctrl+c of StopProcessing()

Het schone blok negeert alle uitvoer die naar de geslaagde stroom is geschreven.

Let op

Het toevoegen van het clean blok is een belangrijke wijziging. Omdat clean deze wordt geparseerd als een trefwoord, voorkomt u dat gebruikers rechtstreeks een opdracht aanroepen met de naam clean als de eerste instructie in een scriptblok. Het is echter waarschijnlijk geen probleem. 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 start u bijvoorbeeld PowerShell met de optie Als administrator uitvoeren.

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

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

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

Met de volgende functie worden bijvoorbeeld alle .jpg bestanden in de mappen van de huidige gebruiker gevonden 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 nuttige 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 de naamgevingsregels volgen die zijn ingesteld voor alle PowerShell-opdrachten.

Namen van functies moeten bestaan uit een werkwoord-zelfstandig naamwoordpaar waarbij de bewerking wordt geïdentificeerd die de functie uitvoert en het zelfstandig naamwoord het item identificeert waarop de cmdlet de actie uitvoert.

Functies moeten gebruikmaken van de standaardwoorden 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, positionele parameters, switchparameters 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 voor benoemde parameters opnemen, zoals verderop in dit onderwerp wordt beschreven.

U kunt parameters binnen 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 die wordt aangeroepen Get-SmallFiles. Deze functie heeft een $Size parameter. Met de functie worden alle bestanden weergegeven die kleiner zijn dan de waarde van de $Size parameter en worden mappen uitgesloten:

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 Grootte 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 variant 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 Grootte 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
  )
  Get-ChildItem $HOME | Where-Object {
    $_.Length -lt $Size -and !$_.PSIsContainer
  }
}

Zie de kenmerkenklasse PSDefaultValue voor meer informatie over de kenmerkklasse PSDefaultValue.

Positionele parameters

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

Wanneer u positionele parameters gebruikt, typt u een of meer waarden na 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] op vóór de parameternaam, zoals wordt weergegeven in het volgende voorbeeld:

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

Wanneer u de On schakelparameter typt na de functienaam, wordt de functie weergegeven Switch on. Zonder de schakelparameter wordt deze 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 wordt 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 cmdlet aangeroepen Get-Command . De opdracht gebruikt @Args om de parameters van Get-Command.

function Get-MyCommand { Get-Command @Args }

U kunt alle parameters gebruiken van Get-Command 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-declaratieve cmdlet-parameters en -waarden uit resterende argumenten vertegenwoordigt.

Zie about_Splatting voor meer informatie.

Objecten doorlijnen 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, processen endclean 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. Met de functie worden waarden uit de pijplijn weergegeven:

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 verwerken. Voorbeeld:

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 aan de functie worden doorgesluisd, toegewezen aan de $input automatische variabele. De functie voert instructies uit met het begin trefwoord voordat objecten afkomstig zijn uit de pijplijn. 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 en end trefwoorden.

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 $input verwijderd uit $input en toegewezen aan $_. In het volgende voorbeeld ziet u een process lijst met instructies:

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

In dit voorbeeld wordt elk object dat naar de functie wordt doorgesluisd naar de process instructielijst verzonden. 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 gebruikt in de begin, processen end blokken. 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 is voltooid zonder afsluitfout
wanneer de uitvoering van de pijplijn wordt onderbroken vanwege een afsluitfout
wanneer de pijplijn is gestopt door Select-Object -First
wanneer de pijplijn wordt gestopt door Ctrl+C of StopProcessing()

Let op

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 uit 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 wordt 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 binnen het globale bereik valt, kunt u de functie in scripts, in functies en op de opdrachtregel gebruiken.

Functies maken een nieuw bereik. De items die zijn gemaakt in een functie, 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 bij het verwijzen naar het C station of D station 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 functieprovider voor meer informatie over het Function: 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 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 u Get-Help gevolgd door de functienaam.

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

Get-Help Get-MyDisks

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

Help op basis van opmerkingen voor Functies

Een Help-onderwerp maken 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 trefwoord van de functie. Zie about_Comment_Based_Help voor meer informatie over hulp op basis van opmerkingen.
Help op basis van XML voor Functies

Maak 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 helponderwerp op basis van XML, gebruikt u het .EXTERNALHELP help-trefwoord op basis van opmerkingen. Zonder dit trefwoord Get-Help kunt u het Help-onderwerp van de functie niet vinden en wordt aangeroepen Get-Help om de functie alleen automatisch gegenereerde help te retourneren.

Zie about_Comment_Based_Help voor meer informatie over het .EXTERNALHELP trefwoord. Zie Help voor cmdlets schrijven voor meer informatie over help op basis van XML.

Delen via