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 , Processoch End. Dessa instruktionslistor hanterar indata från pipelinen på olika sätt.

Ett filter är en särskild typ av funktion som använder nyckelordet Filter .

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.

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

function [<scope:>]<name>
{
  param([type]$parameter1 [,[type]$parameter2])
  dynamicparam {<statement list>}
  begin {<statement list>}
  process {<statement list>}
  end {<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.

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

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.

Funktionsnamnen ska 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 enkla, konsekventa och enkla för användarna att förstå.

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

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 inom 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 On växelparametern efter funktionsnamnet visar funktionen "Slå på". Utan switchparametern visas "Stäng av".

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 om splatting 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 , Processoch End . Följande exempelsyntax visar de tre nyckelorden:

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

Instruktionslistan Begin körs endast en gång, i början av funktionen.

Viktigt

Om funktionen definierar ett Begin- Process eller End -block måste all kod finnas i dessa block. Ingen kod identifieras utanför blocken om något av blocken har definierats.

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.

När funktionen tar emot alla objekt i pipelinen körs instruktionslistan End en gång. Om inga Beginnyckelord Process, , eller End används behandlas alla -instruktioner som en End instruktionslista.

Följande funktion använder nyckelordet Process . Funktionen visar exempel från pipelinen:

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

Om du vill demonstrera den här funktionen anger du en lista med tal avgränsade med kommatecken, som du ser i följande exempel:

1,2,4 | Get-Pipeline

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

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 hjälp av 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

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

Funktionsomfång

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

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 i kommandotolken.

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 normalt ett omfång. Objekten som skapas i en funktion, till exempel variabler, finns bara i funktionsomfånget.

Mer information om omfång i PowerShell 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. Den ä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