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 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 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 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 programmering C# . Mer information finns i about_Functions_Advanced.

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.

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- och processend -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 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.

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

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

Det rena blocket tar bort alla utdata som skrivs 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-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 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, 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.

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å 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ä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 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:

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 ($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 och end nyckelord.

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 . -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 stoppas av Select-Object -First
4. när pipelinen stoppas av Ctrl+C eller StopProcessing()

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 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å 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 gör när du refererar C till Function: 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 om enheten finns i Function: 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 ä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 för funktioner, samt för cmdletar, leverantörer 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 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-baserad 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 det kommentarsbaserade hjälpnyckelordet .EXTERNALHELP . Utan det här nyckelordet Get-Help kan du 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 .EXTERNALHELP about_Comment_Based_Help. Mer information om XML-baserad hjälp finns i Så här skriver du cmdlethjä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