PowerShell-Funktionen

In dieser Folge der Reihe PowerShell lernen werden wir PowerShell-Funktionen untersuchen. In der letzten Folge haben wir uns mit PowerShell-Skripten beschäftigt, mit denen wir begonnen haben, Lösungen zu erstellen und Probleme mit PowerShell zu lösen. PowerShell-Skripte sind großartig, und viele Leute verbringen in dieser Phase des PowerShell-Lernens ziemlich viel Zeit damit. Skripte ermöglichen es Ihnen, die Dinge relativ einfach zu halten, und können Ihnen helfen, Aufgaben schnell zu automatisieren. Wenn Sie besser werden und anfangen, mehr PowerShell zu schreiben, werden Sie sich mit der Erstellung von PowerShell-Funktionen befassen müssen!

Video

Wenn Sie das Videoformat einer schriftlichen Dokumentation vorziehen, bespreche ich dieses Thema im folgenden TechThoughts-Video:

Wann Sie eine PowerShell-Funktion schreiben sollten

Ein PowerShell-Skript ist letztendlich ein Satz Code, der eine Aufgabe ausführt. Genau das tut eine PowerShell-Funktion auch! Warum sollten Sie also eine Funktion statt eines Skripts schreiben? Im Folgenden werden wir einige Gründe dafür nennen. Im Allgemeinen ist ein Skript jedoch etwas für Sie. Wenn Sie Ihren Code weitergeben oder Ihre Teamkollegen damit arbeiten lassen möchten, sollten Sie einige der Möglichkeiten nutzen, die Funktionen bieten. Es gibt keine feste Grenze. Für eine schnelle Aufgabe, die nur einmal auf Ihrer Workstation ausgeführt werden soll, kann ein Skript sinnvoll sein. Wenn Sie eine PowerShell schreiben, die auch von anderen verwendet wird oder die Sie mehr als einmal verwenden, ist eine Funktion wahrscheinlich besser geeignet.

• Einfacher Zweck – eine Funktion wird in der Regel verwendet, um eine eng begrenzte Aufgabe auszuführen und „eine Sache zu tun, und zwar hervorragend“. Das macht Funktionen in hohem Maße wiederverwendbar. Wenn Sie zum Beispiel eine Protokollierungsfunktion schreiben, können Sie diese PowerShell-Protokollierungsfunktion mit anderen Funktionen oder Skripts verwenden.
• Hilfe – Funktionen unterstützen hilfsbasierte Kommentare. Dadurch können Ihre Benutzer z. B. Get-Help eingeben und herausfinden, wie sie Ihre Funktion verwenden können.
• Parameter – Unterstützung für einfache und erweiterte Parameterdeklarationen und -steuerung ermöglicht es Ihrer Funktion, dynamisch zu sein und verschiedene Formen von Benutzereingaben zu verarbeiten.
• Testbar – Funktionen können getestet und als Spotting verwendet werden, was die Qualität des Codes erheblich verbessert.

Anatomie einer PowerShell-Funktion

Hier ist der grundlegende Aufbau und die Reihenfolge einer PowerShell-Funktion. Im Folgenden werden wir in jeden dieser Abschnitte eintauchen und sie im Detail untersuchen.

# function help - (optional but strongly encouraged)# function name# CmdletBinding - (optional)# parameters - (optional)# function logic (optional Begin / Process / End)# return - (optional)function Verb-Noun { param ( ) begin { } process { } end { }}

Funktionshilfe

Wenn Sie die Hilfe am Anfang Ihrer Funktion einfügen, wird sie angezeigt, wenn Get-Help gegen Ihre Funktion ausgeführt wird. Dies ist eine mächtige Fähigkeit, wenn andere Ihren Code erforschen. Wenn Sie sich die Zeit nehmen, eine gute Synopsis und Beschreibung in Kombination mit soliden Beispielen zu verfassen, werden andere verstehen, wozu Ihre Funktion dient und wie sie zu verwenden ist.

Alle Hilfefelder sind optional und Sie können sie nach Belieben hinzufügen oder entfernen. Ich empfehle Ihnen, mindestens die unten aufgeführten Felder einzuschließen.

<#.SYNOPSIS Short description.DESCRIPTION Long description.EXAMPLE C:\PS> Example of how to use this cmdlet.EXAMPLE C:\PS> Another example of how to use this cmdlet.PARAMETER InputObject Specifies the object to be processed. You can also pipe the objects to this command..OUTPUTS Output from this cmdlet (if any).NOTES General notes.COMPONENT The component this cmdlet belongs to#>

CmdletBinding

Wenn Sie eine großartige Funktion schreiben und ihr einen Namen wie Get-AllFileInformation geben, sieht sie aus wie ein Cmdlet und wird sich auch so verhalten. Es ist jedoch ein wichtiger Unterschied, dass eine PowerShell-Funktion kein Cmdlet ist. Cmdlets werden in C# geschrieben und kompiliert, und Ihre PowerShell-Funktion ist in PowerShell geschrieben.

CmdletBinding ist ein Attribut von Funktionen, das Fähigkeiten aktiviert, die sie eher wie kompilierte Cmdlets arbeiten lassen. Durch das Hinzufügen dieses Attributs zu Ihrer Funktion erhält Ihre Funktion eine Reihe zusätzlicher Fähigkeiten, wie z. B.:

• Write-Verbose – ermöglichen Sie es Benutzern, den Schalter -Verbose zu verwenden, um zu sehen, was Ihre Funktion tut, während sie es tut.
• ShouldProcess – wenn Ihre Funktion eine Änderung an einem System vornimmt, die ein hohes Risiko darstellt, möchten Sie möglicherweise, dass der Benutzer die Aktion bestätigt.
• PositionalBinding – ermöglicht die Ausführung Ihrer Funktion ohne explizite Angabe der einzelnen Parameternamen. Die Werte können aus der Reihenfolge abgeleitet werden, in der sie Ihrer Funktion übergeben werden

Parameter

param ( $City, $Units = 'USCS', $Language = 'en', $Short)

Parameter dienen dazu, dem Benutzer eine Möglichkeit zur dynamischen Interaktion mit Ihrer Funktion zu geben. Sie können verschiedene Formen der Eingabe annehmen und eine Vielzahl von Überprüfungen und Validierungen durchführen, um sicherzustellen, dass Sie die richtige Art von Informationen erhalten.

Sie können sehr einfach bleiben und nur die Namen Ihrer Parameter deklarieren. Sie können aber auch sehr genau festlegen, was für Ihre Parameter erforderlich ist:

• Ob der Parameter obligatorisch ist
• Die Position eines Parameters (die Reihenfolge)
• Der Parametertyp (string/int/bool/etc)
• Setzen von Standardwerten
• Eingabevalidierung
• Parametersätze
• Viel mehr

Dieser Beitrag kann nicht alle möglichen Parameterkonfigurationen abdecken. Selbst nach Jahren des Schreibens von PowerShell fällt es mir schwer, mir alle Parametereinstellungen und die Syntax zu merken. Sie sollten wissen, dass Parameterdeklarationen eine Möglichkeit sind, Eingaben in Ihre Funktion aufzunehmen. Sie können sie mit vielen Details und Steuerelementen ausstatten oder sie einfach halten, je nach Bedarf. Merken Sie sich die Links zu den Parametern am Ende dieses Beitrags. Auch heute noch besuche ich sie häufig!

Begin Process End

Diese drei Schlüsselwörter sind Phasen, die Sie innerhalb Ihrer Funktion deklarieren können.

• Begin initialisiert einige Schritte am Anfang
• Process verarbeitet jedes Objekt wie es empfangen wird
• End kann Aufräumarbeiten durchführen.

Dies ist besonders nützlich, wenn Sie möchten, dass Ihre Funktion die Verarbeitung von Eingaben aus der Pipeline unterstützt.

Dies kann in der Theorie schwer zu verstehen sein, daher hier ein Beispiel, das die Verwendung demonstriert.

function Get-PipelineBeginEnd { param ( $SomeInput ) begin { "Begin: The input is $SomeInput" } process { "The value is: $_" } end { "End: The input is $SomeInput" }}#Get-PipelineBeginEnd1, 2, 3 | Get-PipelineBeginEnd -SomeInput 'Test'

Wenn Sie den obigen Code ausführen, beachten Sie, dass Begin einmal läuft, ebenso wie End. Process wird für jedes übergebene Element ausgeführt, und Process hat Zugriff auf das aktuelle Objekt in der Pipeline.

Funktionslogik

Die in einer PowerShell-Funktion enthaltene Logik unterscheidet sich nicht von der eines Skripts. Hier schreiben Sie die Kernlogik, die die Aufgabe ausführt, für die Ihre Funktion bestimmt ist. Dies wurde in den Episoden 1-10 dieses Kurses behandelt. Sie können auch ein vollständiges Live-Beispiel in der Episode PowerShell-Skripte sehen.

Funktionsrückgabe

Nicht alle Funktionen geben etwas zurück, wenn sie ausgeführt werden. Wenn Ihre Funktion etwas zurückgeben soll, können Sie optional return verwenden. Denken Sie daran, dass bei der Verwendung von return alle weiteren Aktionen in der Funktion gestoppt werden und die Funktion beendet wird.

function Get-Total { param ( $Number1, $Number2 ) $total = $Number1 + $Number2 return $total}Get-Total -Number1 2 -Number2 2

Im obigen Beispiel enthält diese einfache Funktion zwei Parameter vom Typ Ganzzahl. Die Logik der Funktion addiert die beiden Zahlen zusammen und gibt die Ganzzahl an den Benutzer zurück.

Ihre erste PowerShell-Funktion

Schauen Sie sich die PowerShell-Funktion unten an. Beachten Sie, dass sich das Layout an das hält, was wir zuvor behandelt haben. Beachten Sie auch, dass der Hilfeabschnitt viele Details über den Zweck und die Verwendung der Funktion enthält.

<#.SYNOPSIS Returns your public IP address..DESCRIPTION Queries the ipify Public IP Address API and returns your public IP..EXAMPLE Get-PublicIP Returns the public IP..OUTPUTS System.String.NOTES https://github.com/rdegges/ipify-api#>function Get-PublicIP { $uri = 'https://api.ipify.org' try { $invokeRestMethodSplat = @{ Uri = $uri ErrorAction = 'Stop' } $publicIP = Invoke-RestMethod @invokeRestMethodSplat } catch { Write-Error $_ } return $publicIP}#Get-PublicIP

Da die eigentliche Logik dieser Funktion recht einfach ist, könnte es verlockend sein, sie als Skript zu belassen. Beachten Sie jedoch, dass diese Funktion eine bestimmte Aufgabe erfüllt, und zwar eine gute. Sie könnten diese Funktion nun in eine andere fortgeschrittene Logik einbinden, anstatt ein Skript referenzieren oder importieren zu müssen. Andere Benutzer in Ihrer Umgebung könnten diese Funktion ebenfalls nutzen, sobald sie sich mit ihr vertraut gemacht haben.

Funktionsumfang

Wie die meisten Sprachen hat PowerShell Scoping-Regeln für Variablen. Wenn sich eine Variable innerhalb einer Funktion befindet, können Sie ihren Wert nicht mehr „sehen“. Hier ist ein Beispiel für dieses Verhalten:

function Get-NumberTimesTwo { param ( $Number ) $total = $Number * 2 return $total}#Get-NumberTimesTwoGet-NumberTimesTwo -Number 2

Die Funktion verhält sich wie erwartet und multipliziert eine Zahl korrekt mit zwei. Versuchen Sie jedoch, in Ihrer Konsole den Wert von $total zu sehen. Sie werden es nicht können. Das liegt daran, dass $total auf die Funktion und nicht auf die aktive Konsolensitzung beschränkt ist.

Dies kann für PowerShell-Neulinge verwirrend sein und das Schreiben von Funktionen erschweren. Es gibt mehrere Strategien, um damit umzugehen.

Sie können den Großteil Ihrer Logik in einem skriptartigen Format schreiben und dabei Variablen testen. Wenn Sie sicher sind, dass die Logik wie beabsichtigt funktioniert, können Sie die Logik in eine Funktion verpacken.

Alternativ können Sie Write-Host, Write-Output oder noch besser Write-Debug verwenden, um zu sehen, was mit Ihren Variablen innerhalb Ihrer Funktion geschieht!

function Get-NumberTimesTwo { param ( $Number ) $total = $Number * 2 Write-Debug $total return $total}#Get-NumberTimesTwoGet-NumberTimesTwo -Number 2 -Debug

Beachten Sie, dass wir mit dem Debug-Schalter Zugriff auf den Wert in $total erhalten, um sicherzustellen, dass unsere Logik das tut, was wir beabsichtigen.

Abschließendes Beispiel

Hier ist ein größeres abschließendes Beispiel von zwei PowerShell-Funktionen, mit denen Sie die beliebte Website reddit mit PowerShell surfen können!

Besuchen Sie den GitHub-Gist-Link unten, um auf den Code zuzugreifen und ihn in Ihre Konsole zu laden.

https://gist.github.com/techthoughts2/cd2b720c9b291510cbd643e6ca73e05f

Während Sie diese Funktionen erkunden, versuchen Sie, die folgenden Fragen zu beantworten:

• Welche der beiden Funktionen ist die primäre Funktion?
• Sind dies Standard- oder erweiterte Funktionen?
• Welche Funktion wird die Pipeline-Eingabe unterstützen?

Additional Reading

• Functions
• Parameters
• Functions Advanced
• Functions Advanced Parameters
• PowerShell Approved Verbs
• CmdletBindingAttribute

Series Navigation << PowerShell ScriptsManage Cloud with PowerShell >>