PowerShell
PowerShell-functies

Invoering

Eenvoudige functie zonder parameters

Dit is een voorbeeld van een functie die een tekenreeks retourneert. In het voorbeeld wordt de functie aangeroepen in een instructie die een waarde toekent aan een variabele. De waarde in dit geval is de retourwaarde van de functie.

function Get-Greeting{
    "Hello World"
}

# Invoking the function
$greeting = Get-Greeting

# demonstrate output
$greeting
Get-Greeting

function verklaart de volgende code als een functie.

Get-Greeting is de naam van de functie. Telkens wanneer die functie in het script moet worden gebruikt, kan de functie worden opgeroepen door hem bij naam aan te roepen.

{ ... } is het scriptblok dat door de functie wordt uitgevoerd.

Als de bovenstaande code wordt uitgevoerd in de ISE, zouden de resultaten ongeveer zo zijn:

Hello World
Hello World

Basisparameters

Een functie kan worden gedefinieerd met parameters met behulp van het param-blok:

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

Of met behulp van de eenvoudige functiesyntaxis:

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

Opmerking: Castingparameters zijn niet vereist in beide parameterdefinities.

Simple Function Syntax (SFS) heeft zeer beperkte mogelijkheden in vergelijking met het param-blok.
Hoewel u parameters kunt definiëren om te worden blootgesteld binnen de functie, kun je niet opgeven Parameter attributen , gebruik maken van het valideren van parameters , onder andere [CmdletBinding()] , met SFS (en dit is een niet-limitatieve lijst).

Functies kunnen worden opgeroepen met geordende of benoemde parameters.

De volgorde van de parameters op de aanroep komt overeen met de volgorde van de aangifte in de functiekop (standaard), of kan worden opgegeven met behulp van het Position Positieparameter (zoals getoond in het geavanceerde functievoorbeeld hierboven).

$greeting = Write-Greeting "Jim" 82

Als alternatief kan deze functie worden opgeroepen met benoemde parameters

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

Verplichte parameters

Parameters voor een functie kunnen als verplicht worden gemarkeerd

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

Als de functie zonder waarde wordt aangeroepen, vraagt de opdrachtregel om de waarde:

$greeting = Get-Greeting 

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

Geavanceerde functie

Dit is een kopie van het geavanceerde functiefragment van de Powershell ISE. Kortom, dit is een sjabloon voor veel dingen die u kunt gebruiken met geavanceerde functies in Powershell. Belangrijke aandachtspunten:

• get-help-integratie - het begin van de functie bevat een commentaarblok dat is ingesteld om te worden gelezen door de get-help-cmdlet. Het functieblok kan zich aan het einde bevinden, indien gewenst.
• cmdletbinding - functie gedraagt zich als een cmdlet
• parameters
• parametersets

<#
.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
    {
    }
}

Parameter Validatie

Er zijn verschillende manieren om parameterinvoer te valideren, in PowerShell.

In plaats van code te schrijven in functies of scripts om parameterwaarden te valideren, worden deze ParameterAttributes gegenereerd als ongeldige waarden worden doorgegeven.

ValidateSet

Soms moeten we de mogelijke waarden beperken die een parameter kan accepteren. Stel dat we alleen rood, groen en blauw willen toestaan voor de parameter $Color in een script of functie.

We kunnen het parameterkenmerk ValidateSet gebruiken om dit te beperken. Het heeft als bijkomend voordeel dat bij het instellen van dit argument (in sommige omgevingen) het invullen van tabbladen wordt toegestaan.

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

U kunt ook IgnoreCase opgeven om IgnoreCase te schakelen.

ValidateRange

Voor deze methode voor parametervalidatie is een minimale en maximale Int32-waarde vereist en moet de parameter zich binnen dat bereik bevinden.

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

ValidatePattern

Deze methode voor parametervalidatie accepteert parameters die overeenkomen met het opgegeven regex-patroon.

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

ValidateLength

Deze methode voor parametervalidatie test de lengte van de doorgegeven string.

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

ValidateCount

Deze methode voor parametervalidatie test het aantal doorgegeven argumenten in bijvoorbeeld een reeks tekenreeksen.

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

ValidateScript

Ten slotte is de ValidateScript-methode buitengewoon flexibel, neemt een scriptblok en evalueert het met $ _ om het doorgegeven argument weer te geven. Vervolgens wordt het argument doorgegeven als het resultaat $ true is (inclusief eventuele uitvoer als geldig).

Dit kan worden gebruikt om te testen of een bestand bestaat:

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

Controleren of een gebruiker in AD bestaat:

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

En vrijwel alles wat je kunt schrijven (omdat het niet beperkt is tot 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
)