Dela via

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. Instruktionerna i listan körs som om du hade skrivit dem i kommandotolken.

Funktioner kan vara så enkla som:

function Get-PowerShellProcess { Get-Process PowerShell }

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

Precis som cmdletar kan funktioner ha parametrar. Parametrarna kan namnges, positionella, växla eller dynamiska parametrar. Funktionsparametrar kan läsas från kommandoraden eller från pipelinen.

Funktioner kan returnera värden som kan visas, tilldelas till variabler eller skickas till andra funktioner eller cmdletar. Du kan också ange ett returvärde med hjälp av nyckelordet return. 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.

Funktionens instruktionslista kan innehålla olika typer av instruktionslistor med nyckelorden begin, process, endoch clean. Dessa instruktionslistor hanterar indata från pipelinen på olika sätt.

Nyckelordet filter används för att skapa en typ av funktion som körs på varje objekt i pipelinen. Ett filter liknar en funktion med alla dess instruktioner i ett process block.

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

Viktigt!

I skriptfiler och skriptbaserade moduler måste funktioner definieras innan de kan anropas.

Syntax

Följande är syntaxen för en funktion:

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

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)
  • Ett eller flera PowerShell-kommandon omgivna av klammerparenteser {}

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

Metoder för indatabearbetning

Metoderna som beskrivs i det här avsnittet kallas för indatabearbetningsmetoder. För funktioner representeras dessa tre metoder av begin, processoch 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 end-blocket för funktionen. 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 konturen för en funktion som innehåller ett begin block för engångsförbearbetning, ett process block för bearbetning av flera poster och ett end block för engångspostbearbetning.

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. För mer information, se about_Automatic_Variables.

  • När funktionen anropas i början, eller utanför en pipeline, körs process-blocket en gång.
  • I en pipeline körs process-blocket en gång för varje indataobjekt som når funktionen.
  • Om pipelineindata som når funktionen är tomma process blockera inte köras.
    • Blocken begin, endoch clean körs fortfarande.

Viktigt!

Om en funktionsparameter är inställd på att acceptera pipelineindata och ett process block inte har definierats misslyckas bearbetningen av post för post. I det här fallet körs funktionen bara en gång, oavsett indata.

end

Det här blocket används för att tillhandahålla valfri engångspostbearbetning 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 slutförs normalt utan att felet avslutas
  2. när pipelinekörningen avbryts på grund av ett avslutande fel
  3. när pipelinen stoppas av Select-Object -First
  4. när pipelinen stoppas av Ctrl+ c eller StopProcessing()

Försiktighet

clean Att lägga till blocket är en icke-bakåtkompatibel ändring. Eftersom clean parsas som ett nyckelord hindrar det användare från att direkt anropa ett kommando med namnet clean som den första instruktionen i ett skriptblock. Det är dock inte troligt att det är ett problem. Kommandot kan fortfarande anropas med hjälp av anropsoperatorn (& clean).

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 avgränsa uttrycken.

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

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

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 det här avsnittet.

Funktionsnamn

Du kan tilldela valfritt namn till en funktion, men funktioner som du delar med andra bör följa namngivningsreglerna som har upprättats för alla PowerShell-kommandon.

Funktionsnamn 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 sin åtgärd på.

Functions bör använda standardverb som har godkänts för alla PowerShell-kommandon. Dessa verb hjälper oss att hålla våra kommandonamn konsekventa och enkla för användarna att förstå.

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 det här avsnittet.

Du kan definiera parametrar i klammerparenteserna med 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>
}

Nedan visas ett exempel på den här alternativa syntaxen.

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 Size:

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 exempel:

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 Size i funktionen Get-SmallFiles lägger du till attributet PSDefaultValue enligt följande exempel.

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

Mer information om attributklassen PSDefaultValue finns i PSDefaultValue Attribute Members.

Positionsparametrar

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 matrisvariabel. Värdet som följer funktionsnamnet tilldelas till den första positionen i $args-matrisen $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 parametern On switch efter funktionsnamnet visas funktionen Switch on. 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ända splatting för att representera kommandoparametrar

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 för Get-Command.

function Get-MyCommand { Get-Command @Args }

Du kan använda alla parametrar för Get-Command när du anropar funktionen Get-MyCommand. 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örobjekt 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:

process-instruktionslistan körs en gång för varje objekt i pipelinen. Medan det process 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 måste det process blocket hantera båda fallen. Till exempel:

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

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 nyckelordet begin innan några objekt kommer från pipelinen. Funktionen kör instruktioner med nyckelordet end när alla objekt har tagits emot från pipelinen.

I följande exempel visas den $input automatiska variabeln med nyckelorden begin och end.

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

Om den här funktionen körs med pipelinen visas följande resultat:

1,2,4 | Get-PipelineBeginEnd

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

När begin-instruktionen 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 process-instruktionslista:

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

I det här exemplet skickas varje objekt som skickas till funktionen till process-instruktionslistan. De process-uttrycken 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 stoppas av Select-Object -First
  4. när pipelinen stoppas av Ctrl + C eller StopProcessing()

Försiktighet

clean Att lägga till blocket är en icke-bakåtkompatibel ändring. Eftersom clean parsas som ett nyckelord hindrar det användare från att direkt anropa ett kommando med namnet clean som den första instruktionen i ett skriptblock. Det är dock inte troligt att det är ett problem. Kommandot kan fortfarande anropas med hjälp av anropsoperatorn (& clean).

Filterar

Ett filter är en typ av funktion som körs på varje objekt i pipelinen. Ett filter liknar en funktion med alla dess instruktioner i ett process block.

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

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

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

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

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

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

Funktionsomfång

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

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 funktionen: Enhet

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

När du refererar till den Function: enheten skriver du ett kolon efter Function, precis som när du refererar till C eller D enhet på en dator.

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 om den Function: enheten finns i hjälpavsnittet för providern Function. Skriv Get-Help Function.

Återanvända 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.

Skriva hjälp för functions

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 funktionen Get-MyDisks skriver du:

Get-Help Get-MyDisks

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

  • Comment-Based hjälp för funktioner

    Skapa ett hjälpavsnitt 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 eller slutet av funktionstexten eller på raderna före nyckelordet för funktionen. Mer information om kommentarsbaserad hjälp finns i about_Comment_Based_Help.

  • XML-Based hjälp för funktioner

    Skapa ett XML-baserat hjälpavsnitt, till exempel den typ som vanligtvis skapas för cmdletar. XML-baserad hjälp krävs om du lokaliserar hjälpavsnitt till flera språk.

    Om du vill associera funktionen med det XML-baserade hjälpavsnittet använder du nyckelordet .EXTERNALHELP kommentarsbaserad hjälp. Utan det här nyckelordet kan Get-Help inte hitta funktionshjälpavsnittet och anrop till Get-Help för funktionen returnerar endast automatiskt genererad hjälp.

    Mer information om nyckelordet .EXTERNALHELP finns i about_Comment_Based_Help. Mer information om XML-baserad hjälp finns i How to Write Cmdlet Help.

Se även

  • Last updated on