about_Requires
Krótki opis
Zapobiega uruchamianiu skryptu bez wymaganych elementów.
Długi opis
Instrukcja #Requires uniemożliwia uruchomienie skryptu, chyba że są spełnione wymagania wstępne dotyczące wersji programu PowerShell, modułów (i wersji) lub przystawki (i wersji). Jeśli wymagania wstępne nie są spełnione, program PowerShell nie uruchamia skryptu ani nie udostępnia innych funkcji środowiska uruchomieniowego, takich jak uzupełnianie karty.
Składnia
#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
Aby uzyskać więcej informacji na temat składni, zobacz ScriptRequirements.
Reguły do użycia
Skrypt może zawierać więcej niż jedną #Requires instrukcję. Instrukcje #Requires mogą być wyświetlane w dowolnym wierszu w skrypcie.
Umieszczenie instrukcji #Requires wewnątrz funkcji nie ogranicza jej zakresu. Wszystkie #Requires instrukcje są zawsze stosowane globalnie i muszą być spełnione przed wykonaniem skryptu.
Ostrzeżenie
Mimo że #Requires instrukcja może pojawić się w dowolnym wierszu skryptu, jego pozycja w skry skrycie nie ma wpływu na sekwencję jej aplikacji. Stan globalny, który #Requires przedstawia instrukcja, musi zostać spełniony przed wykonaniem skryptu.
Przykład:
Get-Module AzureRM.Netcore | Remove-Module
#Requires -Modules AzureRM.Netcore
Można pomyśleć, że powyższy kod nie powinien być uruchamiany, ponieważ wymagany moduł został usunięty przed instrukcją #Requires . Jednak stan musiał zostać spełniony przed #Requires wykonaniem skryptu. Następnie pierwszy wiersz skryptu unieważnił wymagany stan.
Parametry
-Ścieżka zestawu zestawu <> | <. Specyfikacja zestawu NET>
Ważne
Składnia -Assembly jest przestarzała. Nie pełni żadnej funkcji. Składnia została dodana w programie PowerShell 5.1, ale kod pomocniczy nigdy nie został zaimplementowany. Składnia jest nadal akceptowana pod kątem zgodności z poprzednimi wersjami.
Określa ścieżkę do pliku DLL zestawu lub nazwy zestawu .NET. Parametr Zestawu został wprowadzony w programie PowerShell 5.0. Aby uzyskać więcej informacji na temat zestawów .NET, zobacz Nazwy zestawów.
Na przykład:
#Requires -Assembly path\to\foo.dll
#Requires -Assembly "System.Management.Automation, Version=3.0.0.0,
Culture=neutral, PublicKeyToken=31bf3856ad364e35"
-Wersja <N>[.<n>]
Określa minimalną wersję programu PowerShell wymaganą przez skrypt. Wprowadź numer wersji głównej i opcjonalny numer wersji pomocniczej.
Na przykład:
#Requires -Version 5.1
-PSSnapin PSSnapin-Name <> [-Version <N>[.<n>]]
Określa przystawkę programu PowerShell, która wymaga skryptu. Wprowadź nazwę przystawki i opcjonalny numer wersji.
Na przykład:
#Requires -PSSnapin DiskSnapin -Version 1.2
-Modules <Module-Name> | <Tabela skrótów>
Określa moduły programu PowerShell wymagane przez skrypt. Wprowadź nazwę modułu i opcjonalny numer wersji.
Jeśli wymagane moduły nie są w bieżącej sesji, program PowerShell je importuje. Jeśli nie można zaimportować modułów, program PowerShell zgłasza błąd zakończenia.
Instrukcja #Requires nie ładuje definicji klasy i wyliczenia w module. using module Użyj instrukcji na początku skryptu, aby zaimportować moduł, w tym definicje klasy i wyliczenia. Aby uzyskać więcej informacji, zobacz about_Using.
Dla każdego modułu wpisz nazwę modułu (<ciąg>) lub tabelę skrótu. Wartość może być kombinacją ciągów i tabel skrótów. Tabela skrótów ma następujące klucze.
ModuleName- Required Określa nazwę modułu.GUID- Opcjonalnie Określa identyfikator GUID modułu.- Wymagane jest również określenie co najmniej jednego z trzech poniższych kluczy.
ModuleVersion- Określa minimalną akceptowalną wersję modułu.MaximumVersion- Określa maksymalną akceptowalną wersję modułu.RequiredVersion- Określa dokładną, wymaganą wersję modułu. Nie można tego używać z innymi kluczami wersji.
Uwaga
RequiredVersion Dodano element w programie Windows PowerShell 5.0.
MaximumVersion Dodano element w programie Windows PowerShell 5.1.
Na przykład:
Wymagaj zainstalowania Hyper-V (wersji 1.1 lub nowszej).
#Requires -Modules @{ ModuleName="Hyper-V"; ModuleVersion="1.1" }
Wymaga zainstalowania Hyper-V (tylko wersja 1.1) .
#Requires -Modules @{ ModuleName="Hyper-V"; RequiredVersion="1.1" }
Wymaga zainstalowania Hyper-V (wersji 1.1 lub mniejszej).
#Requires -Modules @{ ModuleName="Hyper-V"; MaximumVersion="1.1" }
Wymaga zainstalowania dowolnej wersji programu PSScheduledJob i PSWorkflow.
#Requires -Modules PSWorkflow, PSScheduledJob
W przypadku używania RequiredVersion klucza upewnij się, że ciąg wersji jest dokładnie zgodny z ciągiem wersji, którego chcesz wymagać.
Get-Module Hyper-V
ModuleType Version Name ExportedCommands
---------- ------- ---- ------------------
Binary 2.0.0.0 hyper-v {Add-VMAssignableDevice, ...}
Poniższy przykład kończy się niepowodzeniem, ponieważ wersja 2.0.0 nie jest dokładnie zgodna z 2.0.0.0.
#Requires -Modules @{ ModuleName="Hyper-V"; RequiredVersion="2.0.0" }
-PSEdition PSEdition-Name <>
Określa edycję programu PowerShell wymaganą przez skrypt. Prawidłowe wartości to Core dla programu PowerShell i programu Desktop dla programu Windows PowerShell.
Na przykład:
#Requires -PSEdition Core
-ShellId
Określa powłokę wymaganą przez skrypt. Wprowadź identyfikator powłoki. Jeśli używasz parametru ShellId , musisz również dołączyć parametr PSSnapin .
Bieżący identyfikator ShellId można znaleźć, wysyłając zapytanie do zmiennej automatycznej $ShellId .
Na przykład:
#Requires -ShellId MyLocalShell -PSSnapin Microsoft.PowerShell.Core
Uwaga
Ten parametr jest przeznaczony do użycia w mini-powłokach, które zostały przestarzałe.
-RunAsAdministrator
Po dodaniu tego parametru przełącznika do #Requires instrukcji określa, że sesja programu PowerShell, w której jest uruchomiony skrypt, musi zostać uruchomiona z podwyższonym poziomem uprawnień użytkownika. Parametr RunAsAdministrator jest ignorowany w systemie operacyjnym innej niż Windows. Parametr RunAsAdministrator został wprowadzony w programie PowerShell 4.0.
Na przykład:
#Requires -RunAsAdministrator
Przykłady
Poniższy skrypt zawiera dwie #Requires instrukcje. Jeśli wymagania określone w obu instrukcjach nie zostaną spełnione, skrypt nie zostanie uruchomiony. Każda #Requires instrukcja musi być pierwszym elementem w wierszu:
#Requires -Modules PSWorkflow
#Requires -Version 3
Param
(
[parameter(Mandatory=$true)]
[String[]]
$Path
)
...
