PowerShell
PowerShell-funktioner

Introduktion

Enkel funktion utan parametrar

Detta är ett exempel på en funktion som returnerar en sträng. I exemplet kallas funktionen i ett uttalande som tilldelar ett värde till en variabel. Värdet i detta fall är funktionens returvärde.

function Get-Greeting{
    "Hello World"
}

# Invoking the function
$greeting = Get-Greeting

# demonstrate output
$greeting
Get-Greeting

function förklarar följande kod som en funktion.

Get-Greeting är namnet på funktionen. Varje gång den funktionen måste användas i skriptet kan funktionen kallas med hjälp av att anropa den med namn.

{ ... } är skriptblocket som körs av funktionen.

Om ovanstående kod körs i ISE, skulle resultaten vara något som:

Hello World
Hello World

Grundläggande parametrar

En funktion kan definieras med parametrar med hjälp av paramblocket:

function Write-Greeting {
    param(
        [Parameter(Mandatory,Position=0)]
        [String]$name,
        [Parameter(Mandatory,Position=1)]
        [Int]$age
    )
    "Hello $name, you are $age years old."
}

Eller med den enkla funktionssyntaxen:

function Write-Greeting ($name, $age) {
    "Hello $name, you are $age years old."
}

Obs: Gjutningsparametrar krävs inte i någon typ av parameterdefinition.

Enkel funktionssyntax (SFS) har mycket begränsade funktioner jämfört med parametern.
Även om du kan definiera parametrar som ska exponeras inom funktionen, kan du inte specificera parameterattribut , använda parametervalidering , inkludera [CmdletBinding()] med SFS (och detta är en icke uttömmande lista).

Funktioner kan påkallas med beställda eller namngivna parametrar.

Ordern på parametrarna på anropningen matchas med deklarationen i funktionshuvudet (som standard) eller kan specificeras med Position Parameter Attribut (som visas i det avancerade funktionsexemplet ovan).

$greeting = Write-Greeting "Jim" 82

Alternativt kan denna funktion aktiveras med namngivna parametrar

$greeting = Write-Greeting -name "Bob" -age 82

Obligatoriska parametrar

Parametrar till en funktion kan markeras som obligatoriska

function Get-Greeting{
    param
    (
        [Parameter(Mandatory=$true)]$name
    )
    "Hello World $name"
}

Om funktionen åberopas utan ett värde kommer kommandoraden att uppmana värdet:

$greeting = Get-Greeting 

cmdlet Get-Greeting at command pipeline position 1
Supply values for the following parameters:
name: 

Avancerad funktion

Detta är en kopia av det avancerade funktionsavsnittet från Powershell ISE. I grund och botten är detta en mall för många av de saker du kan använda med avancerade funktioner i Powershell. Viktiga punkter att notera:

• get-help integration - början av funktionen innehåller ett kommentarblock som är inställt för att läsas av get-help cmdlet. Funktionsblocket kan vara beläget i slutet, om så önskas.
• cmdletbinding - funktionen fungerar som en cmdlet
• parametrar
• parameteruppsättningar

<#
.Synopsis
   Short description
.DESCRIPTION
   Long description
.EXAMPLE
   Example of how to use this cmdlet
.EXAMPLE
   Another example of how to use this cmdlet
.INPUTS
   Inputs to this cmdlet (if any)
.OUTPUTS
   Output from this cmdlet (if any)
.NOTES
   General notes
.COMPONENT
   The component this cmdlet belongs to
.ROLE
   The role this cmdlet belongs to
.FUNCTIONALITY
   The functionality that best describes this cmdlet
#>
function Verb-Noun
{
    [CmdletBinding(DefaultParameterSetName='Parameter Set 1', 
                  SupportsShouldProcess=$true, 
                  PositionalBinding=$false,
                  HelpUri = 'http://www.microsoft.com/',
                  ConfirmImpact='Medium')]
    [Alias()]
    [OutputType([String])]
    Param
    (
        # Param1 help description
        [Parameter(Mandatory=$true, 
                   ValueFromPipeline=$true,
                   ValueFromPipelineByPropertyName=$true, 
                   ValueFromRemainingArguments=$false, 
                   Position=0,
                   ParameterSetName='Parameter Set 1')]
        [ValidateNotNull()]
        [ValidateNotNullOrEmpty()]
        [ValidateCount(0,5)]
        [ValidateSet("sun", "moon", "earth")]
        [Alias("p1")] 
        $Param1,

        # Param2 help description
        [Parameter(ParameterSetName='Parameter Set 1')]
        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [ValidateScript({$true})]
        [ValidateRange(0,5)]
        [int]
        $Param2,

        # Param3 help description
        [Parameter(ParameterSetName='Another Parameter Set')]
        [ValidatePattern("[a-z]*")]
        [ValidateLength(0,15)]
        [String]
        $Param3
    )

    Begin
    {
    }
    Process
    {
        if ($pscmdlet.ShouldProcess("Target", "Operation"))
        {
        }
    }
    End
    {
    }
}

Parametervalidering

Det finns olika sätt att validera parameterinmatning i PowerShell.

I stället för att skriva kod inom funktioner eller skript för att validera parametervärden kommer dessa ParameterAttribut att kasta om ogiltiga värden passeras.

ValidateSet

Ibland måste vi begränsa de möjliga värdena som en parameter kan acceptera. Säg att vi bara vill tillåta röd, grön och blå för parametern $Color i ett skript eller en funktion.

Vi kan använda ValidateSet parametern attribut för att begränsa detta. Det har den ytterligare fördelen att tillåta att fliken är klar när du ställer in detta argument (i vissa miljöer).

param(
    [ValidateSet('red','green','blue',IgnoreCase)]
    [string]$Color
)

Du kan också ange IgnoreCase att inaktivera IgnoreCase .

ValidateRange

Denna metod för validering av parametrar tar ett min och max Int32-värde och kräver att parametern ligger inom det intervallet.

param(
    [ValidateRange(0,120)]
    [Int]$Age
)

ValidatePattern

Denna metod för validering av parametrar accepterar parametrar som matchar det angivna regexmönstret.

param(
    [ValidatePattern("\w{4-6}\d{2}")]
    [string]$UserName
)

ValidateLength

Denna metod för validering av parametrar testar längden på den passerade strängen.

param(
    [ValidateLength(0,15)]
    [String]$PhoneNumber
)

ValidateCount

Denna metod för validering av parametrar testar mängden argument som skickats i till exempel en rad strängar.

param(
    [ValidateCount(1,5)]
    [String[]]$ComputerName
)

ValidateScript

Slutligen är ValidateScript-metoden utomordentligt flexibel, tar en skriptblock och utvärderar den med $ _ för att representera det godkända argumentet. Det skickar sedan argumentet om resultatet är $ true (inklusive eventuell utgång som giltig).

Detta kan användas för att testa att en fil finns:

param(
    [ValidateScript({Test-Path $_})]
    [IO.FileInfo]$Path 
)

För att kontrollera att en användare finns i AD:

param(
    [ValidateScript({Get-ADUser $_})]
    [String]$UserName
)

Och i stort sett allt annat du kan skriva (eftersom det inte är begränsat till oneliners):

param(
    [ValidateScript({
        $AnHourAgo = (Get-Date).AddHours(-1)
        if ($_ -lt $AnHourAgo.AddMinutes(5) -and $_ -gt $AnHourAgo.AddMinutes(-5)) {
            $true
        } else {
            throw "That's not within five minutes. Try again."
        }
    })]
    [String]$TimeAboutAnHourAgo
)