about_Requires
Krótki opis
Uniemożliwia uruchamianie 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.
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.
#Requires Umieszczenie instrukcji 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 skrycie nie ma wpływu na sekwencję 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żesz 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, #Requires zanim skrypt może nawet zostać wykonany. 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 obsługuje żadnej funkcji. Składnia została dodana w programie PowerShell 5.1, ale kod pomocniczy nigdy nie został zaimplementowany. Składnia jest nadal akceptowana w celu zapewnienia zgodności z poprzednimi wersjami.
Określa ścieżkę do pliku DLL zestawu lub nazwy zestawu .NET. Parametr Assembly 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"
-Version <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 6.0
-PSSnapin <PSSnapin-Name> [-Version <N>[.<n>]]
Określa przystawkę programu PowerShell wymaganą przez skrypt. Wprowadź nazwę przystawki i opcjonalny numer wersji.
Na przykład:
#Requires -PSSnapin DiskSnapin -Version 1.2
-Modules, nazwa> modułu <| <Hashtable>
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.
Dla każdego modułu wpisz nazwę modułu (<Ciąg>) lub tabelę skrótów. Wartość może być kombinacją ciągów i tabel skrótów. Tabela skrótów ma następujące klucze.
ModuleName- Wymagane Określa nazwę modułu.GUID- Opcjonalne Określa identyfikator GUID modułu.- Jest to również wymagane , aby określić jeden z trzech poniższych kluczy. Tych kluczy nie można używać razem.
ModuleVersion— Określa minimalną akceptowalną wersję modułu.RequiredVersion— Określa dokładną, wymaganą wersję modułu.MaximumVersion- Określa maksymalną akceptowalną wersję modułu.
Uwaga
RequiredVersiondodano Windows PowerShell 5.0.
MaximumVersiondodano w Windows PowerShell 5.1.
Na przykład:
Wymagaj zainstalowania AzureRM.Netcore (wersji 0.12.0 lub nowszej).
#Requires -Modules @{ ModuleName="AzureRM.Netcore"; ModuleVersion="0.12.0" }
Wymagaj zainstalowania AzureRM.Netcore (tylko wersja 0.12.0) .
#Requires -Modules @{ ModuleName="AzureRM.Netcore"; RequiredVersion="0.12.0" }
Wymaga zainstalowania AzureRM.Netcore (wersji 0.12.0 lub mniejszej).
#Requires -Modules @{ ModuleName="AzureRM.Netcore"; MaximumVersion="0.12.0" }
Wymagaj, aby jakakolwiek wersja i AzureRM.NetcorePowerShellGet została zainstalowana.
#Requires -Modules AzureRM.Netcore, PowerShellGet
W przypadku korzystania z RequiredVersion klucza upewnij się, że ciąg wersji jest dokładnie zgodny z wymaganym ciągiem wersji.
Get-Module AzureRM.Netcore -ListAvailable
Directory: /home/azureuser/.local/share/powershell/Modules
ModuleType Version Name PSEdition ExportedCommands
---------- ------- ---- --------- ----------------
Script 0.12.0 AzureRM.Netcore Core
Poniższy przykład kończy się niepowodzeniem, ponieważ wartość 0.12 nie jest dokładnie zgodna z 0.12.0.
#Requires -Modules @{ ModuleName="AzureRM.Netcore"; RequiredVersion="0.12" }
-PSEdition <PSEdition-Name>
Określa wersję programu PowerShell wymaganą przez skrypt. Prawidłowe wartości to Core dla programu PowerShell i programu Desktop dla 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ż uwzględnić 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 shellach, które zostały przestarzałe.
-RunAsAdministrator
Po dodaniu tego parametru przełącznika do instrukcji #Requires określa, że sesja programu PowerShell, w której uruchamiasz skrypt, musi zostać uruchomiona z podwyższonym poziomem uprawnień użytkownika. Parametr RunAsAdministrator jest ignorowany w systemie operacyjnym innych 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 AzureRM.Netcore
#Requires -Version 6.0
Param
(
[parameter(Mandatory=$true)]
[String[]]
$Path
)
...