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 ani nie udostępnia innych funkcji środowiska uruchomieniowego, takich jak uzupełnianie kart.

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.

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.

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.

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ótu. 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ć co najmniej jeden 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 jej używać z innymi kluczami wersji.

Uwaga

RequiredVersiondodano Windows PowerShell 5.0. MaximumVersiondodano w Windows PowerShell 5.1.

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.

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 .

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.

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
)
...

Zobacz też