Over functies

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

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

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 trefwoord return. Het return trefwoord heeft geen invloed op of onderdrukt geen andere uitvoer die door uw functie wordt geretourneerd. 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 End. Met deze instructie wordt de invoer van de pijplijn anders verwerkt.

Een filter is een speciaal soort functie die gebruikmaakt van het Filter trefwoord.

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.

Syntaxis

Het volgende is de syntaxis voor een functie:

function [<scope:>]<name> [([type]$parameter1[,[type]$parameter2])]
{
  param([type]$parameter1 [,[type]$parameter2])
  dynamicparam {<statement list>}
  begin {<statement list>}
  process {<statement list>}
  end {<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 Dynamicparam voor meer informatie over het trefwoord en dynamische parameters in functies.

Eenvoudige functies

Functies hoeven niet ingewikkeld te zijn om bruikbaar 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 beheerder.

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.

Functienamen moeten bestaan uit een werkwoord-zelfstandig naamwoordpaar waarin het werkwoord de actie identificeert die de functie uitvoert en het zelfstandig naamwoord het item aangeeft waarop de cmdlet zijn actie uitvoert.

Functies moeten gebruikmaken van de standaardwoorden die zijn goedgekeurd voor alle PowerShell-opdrachten. Deze werkwoorden helpen ons om onze opdrachtnamen eenvoudig, consistent en gemakkelijk te begrijpen voor gebruikers te houden.

Zie Goedgekeurde werkwoorden in de Microsoft-documenten 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 in de accolades definiëren met behulp van het trefwoord Param , 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($one, $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
  )
}

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 schakelaar is een parameter waarvoor geen waarde nodig is. 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 achter de functienaam typt, geeft de functie "Inschakelen" weer. Zonder de schakelparameter wordt "Uitschakelen" weergegeven.

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 wanneer Get-Command 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.

Voor meer informatie over splatting, zie about_Splatting.

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 End trefwoorden. In de volgende voorbeeldsyntaxis worden de drie trefwoorden weergegeven:

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

De Begin lijst met instructies wordt slechts één keer uitgevoerd, aan het begin van de functie.

Belangrijk

Als uw functie een Begin, Process of End blok definieert, moet al uw code zich in een van de blokken bevinden.

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.

Nadat de functie alle objecten in de pijplijn heeft ontvangen, wordt de End lijst met instructies één keer uitgevoerd. Als er geen Begin, Process, of End trefwoorden worden gebruikt, worden alle instructies behandeld als een End lijst met instructies.

De volgende functie gebruikt het Process trefwoord. De functie geeft voorbeelden uit de pijplijn weer:

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

Als u deze functie wilt demonstreren, voert u een lijst met getallen in, gescheiden door komma's, zoals wordt weergegeven in het volgende voorbeeld:

1,2,4 | Get-Pipeline

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

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 automatische variabele $input 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, heeft de functie niet 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 lijst met instructies 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

Filteren

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 { $_ }
}

Functiebereik

Een functie bestaat 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 bij de opdrachtprompt.

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 normaal gesproken een bereik. De items die zijn gemaakt in een functie, zoals variabelen, bevinden zich alleen in het functiebereik.

Zie about_Scopes voor meer informatie over het bereik in PowerShell.

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 Function: provider 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. Het is beschikbaar totdat de sessie eindigt.

Als u uw functie in alle PowerShell-sessies wilt gebruiken, voegt u de functie toe aan uw PowerShell-profiel. Zie about_Profilesvoor 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 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 voor een functie schrijven met behulp van een van de volgende twee methoden:

Help op basis van opmerkingen voor Functies

Maak een Help-onderwerp door speciale trefwoorden te gebruiken 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 Help-onderwerp op basis van XML, gebruikt u het .ExternalHelp help-trefwoord op basis van opmerkingen. Zonder dit trefwoord Get-Help kan het Help-onderwerp van de functie niet worden gevonden en roepen naar Get-Help voor de functie retourneren alleen automatisch gegenereerde hulp.

Zie ExternalHelp voor meer informatie over het trefwoord. Zie Help bij cmdlet schrijven in de MSDN-bibliotheek voor meer informatie over Help op basis van XML.