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, placeras, växlas 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 beginmed nyckelorden , process, endoch clean. Dessa instruktionslistor hanterar indata från pipelinen på olika sätt.

Filternyckelordet 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 nyckelord och dynamicparam dynamiska parametrar i funktioner finns i about_Functions_Advanced_Parameters.

Indatabearbetningsmetoder

Metoderna som beskrivs i det här avsnittet kallas indatabearbetningsmetoder. För funktioner representeras dessa tre metoder av beginprocess- och end -blocken 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 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ångsefterbearbetning.

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äkning som bara är tillgänglig för funktioner och skriptblock. Mer information finns i about_Automatic_Variables.

• När funktionen anropas process i början, eller utanför en pipeline, körs 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.

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 efterbearbetning en gång för funktionen.

clean

Blocket clean lades till i PowerShell 7.3.

Blocket clean är ett praktiskt 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()

Varning

clean Att lägga till blocket är en icke-bakåtkompatibel ändring. Eftersom clean tolkas 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 separera -uttrycken.

Följande funktion hittar till exempel alla .jpg filer i den aktuella användarens kataloger som har ändrats 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 PowerShell-profilen 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 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>
}

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

Get-SmallFiles 50

Om du vill definiera ett standardvärde för en parameter skriver du ett likhetstecken och värdet efter parameternamnet, som du ser i 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 hjälpegenskapen 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
  )
}

Mer information om attributklassen PSDefaultValue finns i PSDefaultValue-attributmedlemmar.

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 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å switchparametern.

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

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

När du skriver växelparametern On 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ä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 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 cmdlet-parametrar och värden från återstående argument.

Mer information finns i about_Splatting.

Skicka objekt till functions

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 dessa 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. 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 begin nyckelorden 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 -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 . - process instruktionerna 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 clean blocket. Blocket clean är ett bekvämt 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 avslutande fel
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()

Varning

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

Filter

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 bara 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 det omfång som den skapas i.

Om en funktion är en del av 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. Till exempel läggs funktionen 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å Function: enheten. Den här enheten exponeras av PowerShell-funktionsprovidern .

När du refererar till enheten skriver du ett kolon efter Funktion, precis som du skulle göra när du refererar C till Function: enheten eller D 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 definitionsegenskapen för funktionen. 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 Function: enheten finns i hjälpavsnittet för funktionsprovidern. 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 avslutas.

Om du vill använda din funktion 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 för funktioner, samt för cmdletar, providrar och skript. Om du vill ha hjälp med en funktion skriver Get-Help du följt av funktionsnamnet.

Om du till exempel vill ha 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:

• Comment-Based hjälp om 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 funktionsnyckelordet. Mer information om kommentarsbaserad hjälp finns i about_Comment_Based_Help.

• XML-Based hjälp om 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 det kommentarsbaserade hjälpnyckelordet .EXTERNALHELP . Utan det här nyckelordet Get-Help kan inte hitta hjälpavsnittet för funktionen och anrop till Get-Help för funktionen returnerar endast automatiskt genererad hjälp.

  Mer information om nyckelordet finns i .EXTERNALHELPabout_Comment_Based_Help. Mer information om XML-baserad hjälp finns i Så här skriver du cmdlet-hjälp.

Se även

• 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