about_Requires

Kurzbeschreibung

Verhindert, dass ein Skript ohne die erforderlichen Elemente ausgeführt wird.

Lange Beschreibung

Die #Requires Anweisung verhindert, dass ein Skript ausgeführt wird, es sei denn, die PowerShell-Version, Module (und Version) oder Snap-Ins (und Version) und Edition sind erfüllt. Wenn die Voraussetzungen nicht erfüllt sind, führt PowerShell das Skript nicht aus.

Syntax

#Requires -Version <N>[.<n>]
#Requires -PSSnapin <PSSnapin-Name> [-Version <N>[.<n>]]
#Requires -Modules { <Module-Name> | <Hashtable> }
#Requires -PSEdition <PSEdition-Name>
#Requires -ShellId <ShellId> -PSSnapin <PSSnapin-Name> [-Version <N>[.<n>]]
#Requires -RunAsAdministrator

Weitere Informationen zur Syntax finden Sie unter ScriptRequirements.

Regeln für die Verwendung

Ein Skript kann mehrere #Requires Anweisung enthalten. Die #Requires-Anweisungen können in einer beliebigen Zeile in einem Skript angezeigt werden.

Das Platzieren einer #Requires Anweisung in einer Funktion schränkt deren Gültigkeitsbereich NICHT ein. Alle #Requires Anweisungen werden immer global angewendet und müssen erfüllt werden, bevor das Skript ausgeführt werden kann.

Beispiel:

Get-Module AzureRM.Netcore | Remove-Module
#Requires -Modules AzureRM.Netcore

Möglicherweise denken Sie, dass der obige Code nicht ausgeführt werden sollte, da das erforderliche Modul vor der #Requires-Anweisung entfernt wurde. Der #Requires Zustand musste jedoch erfüllt werden, bevor das Skript sogar ausgeführt werden konnte. Dann hat die erste Zeile des Skripts den erforderlichen Zustand ungültig.

Die Parameter

-Assembly <Assemblypfad> | <.NET-Assemblyspezifikation>

Gibt den Pfad zur Assembly-DLL-Datei oder einen .NET-Assemblynamen an. Der parameter Assembly wurde in PowerShell 5.0 eingeführt. Weitere Informationen zu .NET-Assemblys finden Sie unter Assemblynamen.

Beispiel:

#Requires -Assembly path\to\foo.dll

#Requires -Assembly "System.Management.Automation, Version=3.0.0.0,
  Culture=neutral, PublicKeyToken=31bf3856ad364e35"

-Version <N>[.<n>]

Gibt die Mindestversion von PowerShell an, die für das Skript erforderlich ist. Geben Sie eine Hauptversionsnummer und optionale Nebenversionsnummer ein.

Beispiel:

#Requires -Version 6.0

-PSSnapin <PSSnapin-Name> [-Version <N>[.<n>]]

Gibt ein PowerShell-Snap-In an, das für das Skript erforderlich ist. Geben Sie den Snap-In-Namen und eine optionale Versionsnummer ein.

Beispiel:

#Requires -PSSnapin DiskSnapin -Version 1.2

-Module <Modulname> | <Hashtable->

Gibt PowerShell-Module an, die für das Skript erforderlich sind. Geben Sie den Modulnamen und eine optionale Versionsnummer ein.

Wenn sich die erforderlichen Module nicht in der aktuellen Sitzung befinden, importiert PowerShell sie. Wenn die Module nicht importiert werden können, löst PowerShell einen Beendigungsfehler aus.

Geben Sie für jedes Modul den Modulnamen (<String) oder eine Hashtabelle> ein. Der Wert kann eine Kombination aus Zeichenfolgen und Hashtabellen sein. Die Hash-Tabelle verfügt über die folgenden Schlüssel.

• ModuleName - Erforderlicher Gibt den Modulnamen an.
• GUID - Optionaler Gibt die GUID des Moduls an.
• Es ist auch erforderlich , einen der drei folgenden Schlüssel anzugeben. Diese Schlüssel können nicht zusammen verwendet werden.
  • ModuleVersion – Gibt eine akzeptable Mindestversion des Moduls an.
  • RequiredVersion – Gibt eine genaue, erforderliche Version des Moduls an.
  • MaximumVersion – Gibt die maximal zulässige Version des Moduls an.

Beispiel:

Erfordert, dass AzureRM.Netcore (Version 0.12.0 oder höher) installiert ist.

#Requires -Modules @{ ModuleName="AzureRM.Netcore"; ModuleVersion="0.12.0" }

Erfordert, dass AzureRM.Netcore (nur Version 0.12.0) installiert ist.

#Requires -Modules @{ ModuleName="AzureRM.Netcore"; RequiredVersion="0.12.0" }

Erfordert, dass AzureRM.Netcore (Version 0.12.0 oder kleiner) installiert ist.

#Requires -Modules @{ ModuleName="AzureRM.Netcore"; MaximumVersion="0.12.0" }

Fordern Sie an, dass eine beliebige Version von AzureRM.Netcore und PowerShellGet installiert ist.

#Requires -Modules AzureRM.Netcore, PowerShellGet

Stellen Sie bei Verwendung des RequiredVersion Schlüssels sicher, dass die Versionszeichenfolge exakt mit der erforderlichen Versionszeichenfolge übereinstimmt.

Get-Module AzureRM.Netcore -ListAvailable

    Directory: /home/azureuser/.local/share/powershell/Modules

ModuleType Version Name            PSEdition ExportedCommands
---------- ------- ----            --------- ----------------
Script     0.12.0  AzureRM.Netcore Core

Das folgende Beispiel schlägt fehl, da 0,12- nicht genau mit 0.12.0-übereinstimmt.

#Requires -Modules @{ ModuleName="AzureRM.Netcore"; RequiredVersion="0.12" }

-PSEdition <PSEdition-Name>

Gibt eine PowerShell-Edition an, die das Skript erfordert. Gültige Werte sind Core für PowerShell und Desktop- für Windows PowerShell.

Beispiel:

#Requires -PSEdition Core

-ShellId

Gibt die Shell an, die das Skript erfordert. Geben Sie die Shell-ID ein. Wenn Sie den ShellId-Parameter verwenden, müssen Sie auch den PSSnapin-Parameter einschließen. Sie finden die aktuelle ShellId , indem Sie die $ShellId automatische Variable abfragen.

Beispiel:

#Requires -ShellId MyLocalShell -PSSnapin Microsoft.PowerShell.Core

-RunAsAdministrator

Wenn dieser Switch-Parameter ihrer #Requires-Anweisung hinzugefügt wird, gibt er an, dass die PowerShell-Sitzung, in der Sie das Skript ausführen, mit erhöhten Benutzerrechten gestartet werden muss. Der RunAsAdministrator Parameter wird auf einem Nicht-Windows-Betriebssystem ignoriert. Der RunAsAdministrator Parameter wurde in PowerShell 4.0 eingeführt.

Beispiel:

#Requires -RunAsAdministrator

Beispiele

Das folgende Skript enthält zwei #Requires Anweisungen. Wenn die in beiden Anweisungen angegebenen Anforderungen nicht erfüllt sind, wird das Skript nicht ausgeführt. Jede #Requires Anweisung muss das erste Element in einer Zeile sein:

#Requires -Modules AzureRM.Netcore
#Requires -Version 6.0
Param
(
    [parameter(Mandatory=$true)]
    [String[]]
    $Path
)
...

Siehe auch

• über_Automatische_Variablen
• about_Language_Keywords