Parameter für Funktionen

Das funktioniert prinzipiell wie bei der Übergabe von Parametern an Skripte.

Hier ein Beispiel mit Definition von einem Standardwert für den Parameter:

Function Get-SmallFiles.ps1
1function Get-SmallFiles {
2    param ( $Size = 100000 )                       # Best Practise
3    Get-ChildItem -path "E:\_temp" | where {$_.Length -lt $Size -and !$_.PSIsContainer} 
4}

Aufruf dann mittels:

Get-SmallFiles –Size 50000

Eine Übergabe sollte stets mit param Deklarationen erfolgen und möglichst nicht über die Übergabe in einer Klammer zur Funktion:

function Get-SmallFiles ($size = 100000) {           # nicht Best Practise
    Get-ChildItem E:\_temp | where {$_.Length -lt $Size -and !$_.PSIsContainer}
}

Mittels param kann man dann auch Mandatory – also benötigte – Parameter deklarieren und gleich noch den Datentyp festlegen (int) und Default-Werte sauber deklrieren.

Tipp

Tipp für Funktionsnamen: Bitte die Verb-Noun Syntax nutzen und auch gleich noch Such- und Hilfemerkmale für die eigenen Funktionen einbauen: Get-JBSmallFiles ; hier z.B. für die Autorenschaft oder andere Ideen.

Beispielhafte Funktion inklusive eingebauter Hilfe und einem Parameter vom Typ Switch (Schalter-Parameter):

Function Get-SmallFiles-02.ps1
1function Get-SmallFiles {
2param ( 
3    [Parameter(Mandatory=$true)]
4    [int]                                     # Typ Integer
5    $Size = 100000 
6    )
7Get-ChildItem -Path "E:\_temp" | where {$_.Length -lt $Size -and !$_.PSIsContainer} 
8}

Man testet am Besten gleich die Hilfen zur neuen Funktion (Cmdlet) Get-CriticalEvent

Function Get-CriticalEvent.ps1
 1# aus Weltner S. 480ff.
 2# komplette Funktionsdefinition mit Anfangsblock / Kommentierungen
 3# =============================
 4
 5function Get-CriticalEvent
 6{
 7<#
 8    .SYNOPSIS
 9        listet Fehler und Warnungen aus dem System-Ereignisprotokoll auf
10    .DESCRIPTION
11        liefert Fehler und Warnungen der letzten 48 Stunden aus dem 
12        System-Ereignisprotokoll,
13        die auf Wunsch in einem GridView angezeigt werden. Der Beobachtungszeitraum
14        kann mit dem Parameter -Hours geändert werden.
15    .PARAMETER  Hours
16        Anzahl der Stunden des Beobachtungszeitraums. Vorgabe ist 48.
17    .PARAMETER  ShowWindow
18        Wenn dieser Switch-Parameter angegeben wird, erscheint das Ergebnis in einem
19        eigenen Fenster und wird nicht in die Konsole ausgegeben
20    .EXAMPLE
21        Get-CriticalEvent
22        liefert Fehler und Warnungen der letzten 48 Stunden aus dem 
23        System-Ereignisprotokoll
24    .EXAMPLE
25        Get-CriticalEvent -Hours 100
26        liefert Fehler und Warnungen der letzten 100 Stunden aus dem 
27        System-Ereignisprotokoll
28    .EXAMPLE
29        Get-CriticalEvent -Hours 24 -ShowWindow
30        liefert Fehler und Warnungen der letzten 24 Stunden aus dem 
31        System-Ereignisprotokoll und stellt sie in einem eigenen Fenster dar
32    .NOTES
33        Dies ist ein Beispiel aus Tobias Weltners' PowerShell Buch
34    .LINK
35        http://www.powertheshell.com
36#>
37param(
38    [int32]    $Hours = 48, 
39    [Switch]   $ShowWindow
40    )
41  if ($ShowWindow)
42  {
43    Set-Alias Out-Default Out-GridView
44  }
45
46  $Heute = Get-Date
47  $Differenz = New-TimeSpan -Hours $Hours
48  $Stichtag = $Heute - $Differenz
49
50  Get-EventLog -LogName System -EntryType Error, Warning -After $Stichtag |
51    Select-Object -Property TimeGenerated, Message | Out-Default
52}

Bei manchen Funktionen erhält man ungewünschte Rückgabewerte aus den Funktionen. Diese lassen sich leicht unterdrücken.

# statt:
function Speak-Text($text) {
    $speaker = New-Object -COMObject SAPI.SPVoice
    $speaker.Speak($text)
    }
# besser:
function Speak-Text($text) {
    $speaker = New-Object -COMObject SAPI.SPVoice
    $null = $speaker.Speak($text)
    }