about_Functions

Kort beskrivning

Beskriver hur du skapar och använder funktioner i PowerShell.

Lång beskrivning

En funktion är en lista över PowerShell-instruktioner som har ett namn som du tilldelar. När du kör en funktion skriver du funktionsnamnet.

PowerShell definierar två typer av funktioner:

• En funktion är ett kodblock som kan anropas med namn. Det kan ta indata och returnera utdata. Funktioner definieras med nyckelordet function .
• Ett filter är en typ av funktion som är utformad för att bearbeta data från pipelinen. Filter definieras med nyckelordet filter .

Du kan gruppera uttrycken i en funktion i ett av fyra olika fördefinierade skriptblock. Dessa skriptblock namnges med nyckelorden begin, process, endoch clean. Om du inte använder de här nyckelorden placerar PowerShell -instruktionerna i lämpligt kodblock.

Funktioner kan också fungera som cmdletar. Du kan skapa en funktion som fungerar precis som en cmdlet utan programmering C# . Mer information finns i about_Functions_Advanced.

Funktionssyntax

Funktioner definieras med hjälp av följande syntax:

function [<scope:>]<name> {
  param([type]$Parameter1 [,[type]$Parameter2])
  dynamicparam {<statement list>}
  begin {<statement list>}
  process {<statement list>}
  end {<statement list>}
  clean {<statement list>}
}

En funktion innehåller följande objekt:

• Ett function nyckelord
• Ett omfång (valfritt)
• Ett namn som du väljer
• Valfritt antal namngivna parametrar (valfritt), inklusive dynamiska parametrar
• En eller flera PowerShell-instruktioner omgivna i klammerparenteser {}

Om du inte använder något av nyckelorden (, , , begin) i en process definition placerar PowerShell -uttrycken end i cleanblocket. functionend

Mer information om nyckelord och dynamicparam dynamiska parametrar i funktioner finns i about_Functions_Advanced_Parameters.

En funktion kan vara så enkel som:

function Get-PowerShellProcess { Get-Process pwsh }

När en funktion har definierats kan du använda den som de inbyggda cmdletarna. Om du till exempel vill anropa den nyligen definierade Get-PowerShellProcess funktionen:

Get-PowerShellProcess

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

En funktion kan också vara lika komplex som en cmdlet.

Funktioner kan returnera värden som kan visas, tilldelas till variabler eller skickas till andra funktioner eller cmdletar. Du kan använda nyckelordet return för att returnera utdata. Nyckelordet return påverkar eller utelämnar inte andra utdata som returneras från funktionen. Nyckelordet return avslutar dock funktionen på den raden. Mer information finns i about_Return.

Filtersyntax

Syftet med filter funktionen är att ge ett kortfattat sätt att definiera en funktion som körs på varje objekt i pipelinen.

Syntaxen för ett filter är följande:

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

Om du vill förenkla syntaxen för filter funktioner utelämnar du nyckelordet för skriptblocket (begin, process, end, clean). PowerShell placerar -uttrycken process i blocket. Du kan använda något av de andra blocken i en filterfunktion, men avsikten var att ge ett kortfattat sätt att definiera en funktion som har det enda syftet att bearbeta varje objekt i pipelinen.

Följande filter tar loggposter från pipelinen och visar sedan antingen hela posten eller endast meddelandedelen av posten:

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

Den kan användas på följande sätt:

Get-WinEvent -LogName System -MaxEvents 100 | Get-EventMessage -MessageOnly

Metoder för indatabearbetning

Metoderna som beskrivs i det här avsnittet kallas för indatabearbetningsmetoder. För funktioner, dessa tre metoder med namnet med hjälp beginprocessav , och end block i funktionen. PowerShell 7.3 lägger till en clean blockprocessmetod.

Du behöver inte använda något av dessa block i dina funktioner. Om du inte använder ett namngivet block placerar PowerShell koden i funktionsblocket end . Men om du använder något av dessa namngivna block eller definierar ett dynamicparam block måste du placera all kod i ett namngivet block.

I följande exempel visas dispositionen för en funktion som innehåller ett begin block för engångsförbearbetande, blockdata process från pipelinen och ett end block för efterbearbetning en gång.

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

begin

Det här blocket används för att tillhandahålla valfri engångsförbearbetning för funktionen. PowerShell-körningen använder koden i det här blocket en gång för varje instans av funktionen i pipelinen.

process

Det här blocket används för att tillhandahålla post-för-post-bearbetning för funktionen. Du kan använda ett process block utan att definiera de andra blocken. Antalet process blockkörningar beror på hur du använder funktionen och vilka indata funktionen tar emot.

Den automatiska variabeln $_ eller $PSItem innehåller det aktuella objektet i pipelinen för användning i process blocket. Den $input automatiska variabeln innehåller en uppräknare som bara är tillgänglig för funktioner och skriptblock. Mer information finns i about_Automatic_Variables.

• Om funktionen anropas utan pipelineindata kör process PowerShell bara blocket en gång.
• I en pipeline process körs blocket en gång för varje indataobjekt som når funktionen.
• Om pipelineindata som når funktionen är tomma process körs inte blocket.
  • Blocken begin, endoch clean körs fortfarande.

end

Använd det här blocket för att tillhandahålla valfri efterbearbetning en gång för funktionen.

clean

Blocket clean lades till i PowerShell 7.3.

Blocket clean är ett bekvämt sätt för användare att rensa resurser som sträcker sig över blocken begin, processoch end . Det liknar semantiskt ett finally block som omfattar alla andra namngivna block i en skriptfunktion eller en skript-cmdlet. Resursrensning tillämpas för följande scenarier:

1. när pipelinekörningen har slutförts utan ett avslutande fel
2. när pipelinekörningen avbryts på grund av ett avslutande fel
3. när pipelinen trunkeras, till exempel: Select-Object -First
4. när pipelinen stoppas av Ctrl+c eller StopProcessing()

Det rena blocket tar bort alla utdata som skrivits till dataströmmen Lyckades .

Enkla funktioner

Funktioner behöver inte vara komplicerade för att vara användbara. De enklaste funktionerna har följande format:

function <function-name> { statements }

Följande funktion startar till exempel PowerShell med alternativet Kör som administratör .

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

Om du vill använda funktionen skriver du: Start-PSAdmin

Om du vill lägga till instruktioner i funktionen skriver du varje -instruktion på en separat rad eller använder ett semikolon (;) för att separera uttrycken.

Följande funktion hittar till exempel alla .jpg filer i den aktuella användarens kataloger som har ändrats efter startdatumet.

function Get-NewPicture {
  $start = Get-Date -Month 1 -Day 1 -Year 2010
  $allPics = Get-ChildItem -Path $Env:USERPROFILE\*.jpg -Recurse
  $allPics | Where-Object {$_.LastWriteTime -gt $Start}
}

Du kan skapa en verktygslåda med användbara små funktioner. Lägg till dessa funktioner i din PowerShell-profil enligt beskrivningen i about_Profiles och senare i den här artikeln.

Funktionsnamn

Du kan tilldela valfritt namn till en funktion. För funktioner som du delar med andra bör du dock följa standardreglerna för PowerShell-namngivning.

• Namn bör bestå av ett verb-substantivpar där verbet identifierar den åtgärd som funktionen utför och substantivet identifierar det objekt som cmdleten utför åtgärden på.
• Namn bör använda de godkända verben för alla PowerShell-kommandon. Genom att använda godkända verb skapas konsekvens för användarna.

Mer information om PowerShell-standardverb finns i Godkända verb.

Funktioner med parametrar

Du kan använda parametrar med funktioner, inklusive namngivna parametrar, positionsparametrar, växelparametrar och dynamiska parametrar. Mer information om dynamiska parametrar i funktioner finns i about_Functions_Advanced_Parameters.

Namngivna parametrar

Du kan definiera valfritt antal namngivna parametrar. Du kan inkludera ett standardvärde för namngivna parametrar enligt beskrivningen senare i den här artikeln.

Du kan definiera parametrar i klammerparenteserna med hjälp av nyckelordet param , enligt följande exempelsyntax:

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

Du kan också definiera parametrar utanför klammerparenteserna utan nyckelordet param , enligt följande exempelsyntax:

function <name> [([type]$Parameter1[,[type]$Parameter2])] {
  <statement list>
}

Följande funktion använder till exempel den alternativa syntaxen för att definiera två parametrar:

function Add-Numbers([int]$One, [int]$Two) {
    $One + $Two
}

Den första metoden är att föredra, men det finns ingen skillnad mellan dessa två metoder.

När du kör funktionen tilldelas värdet som du anger för en parameter till en variabel som innehåller parameternamnet. Värdet för variabeln kan användas i funktionen.

Följande exempel är en funktion som heter Get-SmallFiles. Den här funktionen har en $Size parameter. Funktionen visar alla filer som är mindre än värdet för parametern $Size och utesluter kataloger:

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

I funktionen kan du använda variabeln $Size , som är det namn som definierats för parametern.

Om du vill använda den här funktionen skriver du följande kommando:

Get-SmallFiles -Size 50

Du kan också ange ett värde för en namngiven parameter utan parameternamnet. Följande kommando ger till exempel samma resultat som ett kommando som namnger parametern Storlek :

Get-SmallFiles 50

Om du vill definiera ett standardvärde för en parameter skriver du ett likhetstecken och värdet efter parameternamnet, enligt följande variant av Get-SmallFiles exemplet:

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

Om du skriver Get-SmallFiles utan ett värde tilldelar funktionen 100 till $size. Om du anger ett värde använder funktionen det värdet.

Du kan också ange en kort hjälpsträng som beskriver standardvärdet för parametern genom att lägga till attributet PSDefaultValue i beskrivningen av parametern och ange egenskapen Hjälp för PSDefaultValue. Om du vill ange en hjälpsträng som beskriver standardvärdet (100) för parametern Storlek i Get-SmallFiles funktionen lägger du till attributet PSDefaultValue enligt följande exempel.

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

Mer information om attributklassen PSDefaultValue finns i PSDefaultValue-attributmedlemmar.

Positionella parametrar

En positionsparameter är en parameter utan parameternamn. PowerShell använder parametervärdeordningen för att associera varje parametervärde med en parameter i funktionen.

När du använder positionsparametrar skriver du ett eller flera värden efter funktionsnamnet. Positionsparametervärden tilldelas till $args matrisvariabeln. Värdet som följer funktionsnamnet tilldelas till den första positionen i matrisen $args , $args[0].

Följande Get-Extension funktion lägger till filnamnstillägget .txt till ett filnamn som du anger:

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

Get-Extension myTextFile

myTextFile.txt

Växla parametrar

En växel är en parameter som inte kräver något värde. I stället skriver du funktionsnamnet följt av namnet på växelparametern.

Om du vill definiera en växelparameter anger du typen [switch] före parameternamnet, enligt följande exempel:

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

När du skriver On växelparametern efter funktionsnamnet visar Switch onfunktionen . Utan växelparametern visas Switch off.

Switch-Item -On

Switch on

Switch-Item

Switch off

Du kan också tilldela ett booleskt värde till en växel när du kör funktionen, som du ser i följande exempel:

Switch-Item -On:$true

Switch on

Switch-Item -On:$false

Switch off

Använd splatting för att skicka parametervärden

Du kan använda splatting för att representera parametrarna för ett kommando. Den här funktionen introduceras i Windows PowerShell 3.0.

Använd den här tekniken i funktioner som anropar kommandon i sessionen. Du behöver inte deklarera eller räkna upp kommandoparametrarna eller ändra funktionen när kommandoparametrarna ändras.

Följande exempelfunktion anropar cmdleten Get-Command . Kommandot använder @args för att representera parametrarna Get-Commandför .

function Get-MyCommand { Get-Command @args }

Du kan använda alla parametrar Get-Command för när du anropar Get-MyCommand funktionen. Parametrarna och parametervärdena skickas till kommandot med hjälp av @args.

Get-MyCommand -Name Get-ChildItem

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

Funktionen @args använder den $args automatiska parametern, som representerar odeklarerade cmdletparametrar och värden från återstående argument.

Mer information finns i about_Splatting.

Rörledningsobjekt till funktioner

Alla funktioner kan ta indata från pipelinen. Du kan styra hur en funktion bearbetar indata från pipelinen med hjälp av beginnyckelorden , process, endoch clean . Följande exempelsyntax visar följande nyckelord:

Instruktionslistan process körs en gång för varje objekt i pipelinen. process När blocket körs tilldelas varje pipelineobjekt till den $_ automatiska variabeln, ett pipelineobjekt i taget.

Följande funktion använder nyckelordet process . Funktionen visar värden från pipelinen:

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

1, 2, 4 | Get-Pipeline

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

Om du vill ha en funktion som kan ta pipelineindata eller indata från en parameter process måste blocket hantera båda fallen. Till exempel:

function Get-SumOfNumbers {
    param (
        [int[]]$Numbers
    )

    begin { $retValue = 0 }

    process {
        if ($MyInvocation.ExpectingInput) {
           "Pipeline input: $_"
           $retValue += $_
        } else {
           foreach ($n in $Numbers) {
               "Command line input: $n"
               $retValue += $n
           }
        }
    }

    end { "Sum = $retValue" }
}


PS> 1,2,3,4 | Get-SumOfNumbers
Pipeline input: 1
Pipeline input: 2
Pipeline input: 3
Pipeline input: 4
Sum = 10
PS> Get-SumOfNumbers 1,2,3,4
Command line input: 1
Command line input: 2
Command line input: 3
Command line input: 4
Sum = 10

När du använder en funktion i en pipeline tilldelas de objekt som skickas till funktionen till den $input automatiska variabeln. Funktionen kör instruktioner med skriptblocket begin innan några objekt kommer från pipelinen. Funktionen kör instruktioner med skriptblocket end när det inte finns fler objekt i pipelinen.

I följande exempel visas den $input automatiska variabel som används i blocken begin och end skriptet.

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

När du kör funktionen med pipelineindata visas följande resultat:

1, 2, 4 | Get-PipelineBeginEnd

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

När -instruktionen begin körs har funktionen inte indata från pipelinen. -instruktionen end körs efter att funktionen har värdena.

Om funktionen har ett process nyckelord tas varje objekt i $input bort från $input och tilldelas till $_. I följande exempel finns en instruktionslista process :

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

I det här exemplet skickas varje objekt som skickas till funktionen till instruktionslistan process . -uttrycken process körs på varje objekt, ett objekt i taget. Den $input automatiska variabeln är tom när funktionen når nyckelordet end .

1, 2, 4 | Get-PipelineInput

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

Mer information finns i Använda uppräknare

PowerShell 7.3 har lagt till blocket clean . Blocket clean är ett praktiskt sätt för användare att rensa resurser som skapats och använts i blocken begin, processoch end . Det liknar semantiskt ett finally block som omfattar alla andra namngivna block i en skriptfunktion eller en skript-cmdlet. Resursrensning tillämpas för följande scenarier:

1. när pipelinekörningen slutförs normalt utan att felet avslutas
2. när pipelinekörningen avbryts på grund av ett avslutande fel
3. när pipelinen trunkeras, till exempel: Select-Object -First
4. när pipelinen stoppas av Ctrl+C eller StopProcessing()

Funktionsomfång

Det finns en funktion i omfånget där du skapar den.

Om en funktion ingår i ett skript är funktionen tillgänglig för instruktioner i skriptet. Som standard är en funktion i ett skript inte tillgänglig utanför skriptet.

Du kan ange omfånget för en funktion. Funktionen läggs till i det globala omfånget i följande exempel:

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

När en funktion finns i det globala omfånget kan du använda funktionen i skript, i funktioner och på kommandoraden.

Funktioner skapar ett nytt omfång. Objekten som skapas i en funktion, till exempel variabler, finns bara i funktionsomfånget.

Mer information finns i about_Scopes.

Hitta och hantera funktioner med hjälp av Function: enheten

Alla funktioner och filter i PowerShell lagras automatiskt på Function: enheten. Den här enheten exponeras av PowerShell-funktionsprovidern.

När du refererar till enheten skriver du ett kolon efter Function:, precis som du gör när du refererar till C datorns eller D enhetens enhet.

Följande kommando visar alla funktioner i den aktuella sessionen i PowerShell:

Get-ChildItem Function:

Kommandona i funktionen lagras som ett skriptblock i funktionens definitionsegenskap. Om du till exempel vill visa kommandona i hjälpfunktionen som medföljer PowerShell skriver du:

(Get-ChildItem Function:help).Definition

Du kan också använda följande syntax.

$Function:help

Mer information finns i about_Function_Provider.

Återanvänd funktioner i nya sessioner

När du skriver en funktion i PowerShell-kommandotolken blir funktionen en del av den aktuella sessionen. Funktionen är tillgänglig tills sessionen är slut.

Om du vill använda funktionen i alla PowerShell-sessioner lägger du till funktionen i din PowerShell-profil. Mer information om profiler finns i about_Profiles.

Du kan också spara funktionen i en PowerShell-skriptfil. Skriv din funktion i en textfil och spara sedan filen med filnamnstillägget .ps1 .

Skapa hjälp för funktioner

Cmdleten Get-Help får hjälp med funktioner, cmdletar, providers och skript. Om du vill få hjälp med en funktion skriver du Get-Help följt av funktionsnamnet.

Om du till exempel vill få hjälp med Get-MyDisks funktionen skriver du:

Get-Help Get-MyDisks

Du kan skriva hjälp för en funktion med någon av följande två metoder:

• Kommentarsbaserad hjälp för funktioner

  Skapa hjälp med hjälp av särskilda nyckelord i kommentarerna. Om du vill skapa kommentarsbaserad hjälp för en funktion måste kommentarerna placeras i början, slutet eller i funktionens brödtext. Mer information om kommentarsbaserad hjälp finns i about_Comment_Based_Help.

• XML-baserad hjälp för funktioner

  XML-baserad hjälp krävs om du behöver lokalisera hjälpinnehåll till flera språk. Om du vill associera funktionen med den XML-baserade hjälpfilen använder du det kommentarsbaserade hjälpnyckelordet .EXTERNALHELP . Utan det här nyckelordet Get-Help kan du inte hitta funktionshjälpfilen och returnerar bara den automatiskt genererade hjälpen.

  Mer information om nyckelordet finns i .EXTERNALHELP about_Comment_Based_Help. Mer information om XML-baserad hjälp finns i Så här skriver du cmdlethjälp.

Se även

• om_Automatiska_Variabler
• om_kommentarbaserad_hjälp
• about_Function_Provider
• about_Functions_Advanced
• om_Funktioner_Avancerade_Metoder
• om_Funktioner_Avancerade_Parameterar
• about_Functions_CmdletBindingAttribute
• om_Funktioner_OutputTypeAttribut
• about_Parameters
• om_profiler
• om_Räckvidder
• om_Skript_Block