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). 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 -Modules { <Module-Name> | <Hashtable> }
#Requires -PSEdition <PSEdition-Name>
#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ą instrukcję #Requires. Instrukcje #Requires mogą być wyświetlane w dowolnym wierszu skryptu.

Umieszczenie instrukcji #Requires wewnątrz funkcji nie ogranicza jej zakresu. Wszystkie instrukcje #Requires są zawsze stosowane globalnie i muszą być spełnione, zanim skrypt będzie mógł zostać wykonany.

Ostrzeżenie

Mimo że instrukcja #Requires może pojawić się w dowolnym wierszu skryptu, jego pozycja w skrycie nie ma wpływu na sekwencję jej aplikacji. Stan globalny, który przedstawia instrukcja #Requires, 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 #Requires musiał zostać spełniony przed wykonaniem skryptu. Następnie pierwszy wiersz skryptu unieważnił wymagany stan.

Parametry

-Assembly <Assembly path> | <specyfikacja zestawu .NET>

Ważny

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 platformy .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 6.0

-Modules <Nazwa modułu> | <> 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 klas i definicji wyliczenia w module. Użyj instrukcji using module 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 - 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 tego używać z innymi kluczami wersji.

Nuta

RequiredVersion dodano w programie Windows PowerShell 5.0. MaximumVersion dodano w programie Windows PowerShell 5.1.

Na przykład:

Wymagaj zainstalowania AzureRM.Netcore (wersja 0.12.0 lub nowsza).

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

Wymagaj zainstalowania AzureRM.Netcore (tylko wersji 0.12.0).

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

Wymaga zainstalowania AzureRM.Netcore (0.12.0 lub mniejszej).

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

Wymagaj zainstalowania dowolnej wersji AzureRM.Netcore i PowerShellGet.

#Requires -Modules AzureRM.Netcore, PowerShellGet

W przypadku używania klucza RequiredVersion 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ż 0.12 nie jest dokładnie zgodna z 0.12.0.

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

-PSEdition PSEdition-Name <>

Określa edycję programu PowerShell wymaganą przez skrypt. Prawidłowe wartości to Core dla programu PowerShell i Desktop dla programu Windows PowerShell.

Na przykład:

#Requires -PSEdition Core

-RunAsAdministrator

Po dodaniu tego parametru przełącznika do instrukcji #Requires 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 instrukcje #Requires. Jeśli wymagania określone w obu instrukcjach nie zostaną spełnione, skrypt nie zostanie uruchomiony. Każda instrukcja #Requires musi być pierwszym elementem w wierszu:

#Requires -Modules AzureRM.Netcore
#Requires -Version 6.0
param
(
    [Parameter(Mandatory=$true)]
    [string[]]
    $Path
)
...

Zobacz także

• about_Automatic_Variables
• about_Language_Keywords