PowerShell
PowerShell-Funktionen

Einführung

Einfache Funktion ohne Parameter

Dies ist ein Beispiel für eine Funktion, die eine Zeichenfolge zurückgibt. Im Beispiel wird die Funktion in einer Anweisung aufgerufen, die einer Variablen einen Wert zuweist. Der Wert ist in diesem Fall der Rückgabewert der Funktion.

function Get-Greeting{
    "Hello World"
}

# Invoking the function
$greeting = Get-Greeting

# demonstrate output
$greeting
Get-Greeting

function deklariert den folgenden Code als Funktion.

Get-Greeting ist der Name der Funktion. Jedes Mal, wenn diese Funktion im Skript verwendet werden muss, kann die Funktion aufgerufen werden, indem sie nach Namen aufgerufen wird.

{ ... } ist der Skriptblock, der von der Funktion ausgeführt wird.

Wenn der obige Code in der ISE ausgeführt wird, würden die Ergebnisse wie folgt aussehen:

Hello World
Hello World

Grundparameter

Eine Funktion kann mit Parametern über den Parameterblock definiert werden:

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

Oder mit der einfachen Funktionssyntax:

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

Hinweis: Casting-Parameter sind für beide Arten von Parameterdefinitionen nicht erforderlich.

Die Simple Function Syntax (SFS) hat im Vergleich zum Parameterblock sehr eingeschränkte Möglichkeiten.
Sie können zwar Parameter definieren, die in der Funktion [CmdletBinding()] , Sie können jedoch keine Parameterattribute angeben, Parameter Validation verwenden , [CmdletBinding()] mit SFS (und dies ist keine erschöpfende Liste) verwenden.

Funktionen können mit geordneten oder benannten Parametern aufgerufen werden.

Die Reihenfolge der Parameter beim Aufruf entspricht der Reihenfolge der Deklaration im Funktionsheader (standardmäßig) oder kann mithilfe des Position angegeben werden (wie im Beispiel für erweiterte Funktionen oben gezeigt).

$greeting = Write-Greeting "Jim" 82

Alternativ kann diese Funktion mit benannten Parametern aufgerufen werden

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

Pflichtparameter

Parameter einer Funktion können als obligatorisch markiert werden

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

Wenn die Funktion ohne Wert aufgerufen wird, werden Sie in der Befehlszeile nach dem Wert gefragt:

$greeting = Get-Greeting 

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

Erweiterte Funktion

Dies ist eine Kopie des erweiterten Funktions-Snippets der Powershell ISE. Im Grunde ist dies eine Vorlage für viele der Dinge, die Sie mit erweiterten Funktionen in Powershell verwenden können. Wichtige Punkte zu beachten:

• get-help-Integration: Der Anfang der Funktion enthält einen Kommentarblock, der so eingerichtet ist, dass er vom Cmdlet get-help gelesen werden kann. Der Funktionsblock kann sich am Ende befinden, falls gewünscht.
• Die Funktion "Cmdletbinding" verhält sich wie ein Cmdlet
• Parameter
• Parametersätze

<#
.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überprüfung

Es gibt verschiedene Möglichkeiten, um die Parametereintragung in PowerShell zu überprüfen.

Anstatt Code in Funktionen oder Skripts zu schreiben, um Parameterwerte zu überprüfen, werden diese ParameterAttributes ausgegeben, wenn ungültige Werte übergeben werden.

ValidateSet

Manchmal müssen wir die möglichen Werte einschränken, die ein Parameter annehmen kann. Angenommen, wir möchten für den Parameter $Color in einem Skript oder einer Funktion nur Rot, Grün und Blau zulassen.

Wir können das Parameterattribut ValidateSet , um dies einzuschränken. Dies hat den zusätzlichen Vorteil, dass beim Festlegen dieses Arguments (in einigen Umgebungen) das Ausfüllen der Registerkarten zugelassen wird.

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

Sie können auch IgnoreCase angeben, um die Groß- / Kleinschreibung zu deaktivieren.

ValidateRange

Diese Methode der Parametervalidierung erfordert einen minimalen und maximalen Int32-Wert und erfordert, dass der Parameter innerhalb dieses Bereichs liegt.

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

ValidatePattern

Diese Methode der Parameterüberprüfung akzeptiert Parameter, die dem angegebenen Regex-Muster entsprechen.

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

ValidateLength

Diese Methode der Parameterüberprüfung prüft die Länge der übergebenen Zeichenfolge.

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

ValidateCount

Diese Methode der Parameterüberprüfung prüft die Anzahl der übergebenen Argumente, z. B. in einem String-Array.

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

ValidateScript

Schließlich ist die ValidateScript-Methode außerordentlich flexibel, indem ein Skriptblock mit $ _ ausgewertet wird, um das übergebene Argument darzustellen. Es übergibt dann das Argument, wenn das Ergebnis $ true ist (einschließlich aller Ausgaben als gültig).

Dies kann verwendet werden, um zu testen, ob eine Datei vorhanden ist:

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

So prüfen Sie, ob ein Benutzer in AD vorhanden ist:

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

Und so ziemlich alles, was Sie schreiben können (da es nicht auf Oneliners beschränkt ist):

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
)