about_Functions

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

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, Processen End. Deze instructielijsten verwerken invoer van de pijplijn op een andere manier.

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

function [<scope:>]<name>
{
  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 about_Functions_Advanced_Parameters voor meer informatie over het Dynamicparam trefwoord en de dynamische parameters in functies.

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 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 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 waarin 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 eenvoudig, consistent en gemakkelijk te begrijpen voor gebruikers.

Zie Goedgekeurde werkwoorden in de Microsoft Docs 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. Met de functie worden alle bestanden weergegeven die kleiner zijn dan de waarde van de $Size parameter en worden directory's 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 met de naam van de parameter Grootte :

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 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 PSDefaultValue Attribute Members (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 naam van de functie. Positionele parameterwaarden worden toegewezen aan de $args matrixvariabele. De waarde na 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

Schakelen tussen parameters

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 switchparameter achter de naam van de functie typt, wordt 'Inschakelen' weergegeven. 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 is geïntroduceerd in Windows PowerShell 3.0.

Gebruik deze techniek in functies die opdrachten aanroepen in de sessie. 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 Get-Commandweer te geven.

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 over splatting.

Objecten doorsntaken naar functies

Elke functie kan invoer van de pijplijn overnemen. U kunt bepalen hoe een functie invoer uit de pijplijn verwerkt met behulp van Begintrefwoorden , Processen End . In de volgende voorbeeldsyntaxis ziet u de drie trefwoorden:

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

De Begin instructielijst 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 die blokken bevinden. Er wordt geen code buiten de blokken herkend als een van de blokken is gedefinieerd.

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 instructielijst één keer uitgevoerd. Als er geen Begintrefwoorden , Processof End worden gebruikt, worden alle instructies behandeld als een End instructielijst.

De volgende functie gebruikt het Process trefwoord. Met de functie worden voorbeelden van de pijplijn weergegeven:

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 naar de functie worden doorgesluisd, toegewezen aan de $input automatische variabele. Met de functie worden instructies met het Begin trefwoord uitgevoerd voordat er objecten uit de pijplijn komen. Met de functie worden instructies met het End trefwoord uitgevoerd 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

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

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 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 gebruiken in scripts, in functies en op de opdrachtregel.

Functies maken normaal gesproken een bereik. De items die in een functie zijn gemaakt, zoals variabelen, bestaan 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 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. Deze is beschikbaar totdat de sessie wordt 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 behulp van 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 op XML gebaseerd Help-onderwerp, 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 van de functie en 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 het schrijven van cmdlets) voor meer informatie over help op basis van XML.

Zie ook

• 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