about_Requires

Kort beskrivning

Förhindrar att ett skript körs utan nödvändiga element.

Lång beskrivning

Instruktionen #Requires förhindrar att ett skript körs om inte powershell-versionen, modulerna (och versionen) eller snapin-modulerna (och versionen) och versionskraven uppfylls. Om förutsättningarna inte uppfylls kör PowerShell inte skriptet eller tillhandahåller andra körningsfunktioner, till exempel tabbavslut.

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

Mer information om syntaxen finns i ScriptRequirements.

Regler för användning

Ett skript kan innehålla fler än en #Requires instruktion. Instruktionerna #Requires kan visas på valfri rad i ett skript.

Om du placerar en #Requires instruktion i en funktion begränsas INTE dess omfång. Alla #Requires instruktioner tillämpas alltid globalt och måste uppfyllas innan skriptet kan köras.

Varning

Även om en #Requires instruktion kan visas på valfri rad i ett skript påverkar dess position i ett skript inte programmets sekvens. Det globala tillstånd som instruktionen #Requires presenterar måste uppfyllas före skriptkörningen.

Exempel:

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

Du kanske tror att koden ovan inte ska köras eftersom den nödvändiga modulen togs bort före instruktionen #Requires . Tillståndet måste dock #Requires uppfyllas innan skriptet ens kunde köras. Sedan ogiltigförklarade den första raden i skriptet det nödvändiga tillståndet.

Parametrar

-Sammansättningssökväg <> | <. NET-sammansättningsspecifikation>

Viktigt

Syntaxen -Assembly är inaktuell. Den fungerar inte som den ska. Syntaxen lades till i PowerShell 5.1 men den stödjande koden implementerades aldrig. Syntaxen accepteras fortfarande för bakåtkompatibilitet.

Anger sökvägen till sammansättnings-DLL-filen eller ett .NET-sammansättningsnamn. Sammansättningsparametern introducerades i PowerShell 5.0. Mer information om .NET-sammansättningar finns i Sammansättningsnamn.

Ett exempel:

#Requires -Assembly path\to\foo.dll
#Requires -Assembly "System.Management.Automation, Version=3.0.0.0,
  Culture=neutral, PublicKeyToken=31bf3856ad364e35"

-Version <N>[.< n>]

Anger den lägsta version av PowerShell som skriptet kräver. Ange ett huvudversionsnummer och valfritt delversionsnummer.

Ett exempel:

#Requires -Version 6.0

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

Anger en PowerShell-snapin-modul som skriptet kräver. Ange snapin-modulens namn och ett valfritt versionsnummer.

Ett exempel:

#Requires -PSSnapin DiskSnapin -Version 1.2

-Modules <Module-Name> | < Hashtable>

Anger PowerShell-moduler som skriptet kräver. Ange modulnamnet och ett valfritt versionsnummer.

Om de moduler som krävs inte finns i den aktuella sessionen importerar PowerShell dem. Om modulerna inte kan importeras utlöser PowerShell ett avslutande fel.

För varje modul skriver du modulnamnet (<Sträng>) eller en hashtable. Värdet kan vara en kombination av strängar och hashtables. Hashtabellen har följande nycklar.

  • ModuleName - Krävs Anger modulnamnet.
  • GUID - Valfri Anger GUID för modulen.
  • Det är också Obligatoriskt att ange minst en av de tre nycklarna nedan.
    • ModuleVersion – Anger en lägsta godtagbar version av modulen.
    • MaximumVersion – Anger den högsta godkända versionen av modulen.
    • RequiredVersion – Anger en exakt version av modulen som krävs. Detta kan inte användas med de andra versionsnycklarna.

Anteckning

RequiredVersionlades till i Windows PowerShell 5.0. MaximumVersionlades till i Windows PowerShell 5.1.

Ett exempel:

Kräv att AzureRM.Netcore (version 0.12.0 eller senare) är installerat.

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

Kräv att AzureRM.Netcore (endast version 0.12.0) är installerat.

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

Kräver att AzureRM.Netcore (version 0.12.0 eller mindre) är installerad.

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

Kräv att någon version av AzureRM.Netcore och PowerShellGet är installerad.

#Requires -Modules AzureRM.Netcore, PowerShellGet

När du använder RequiredVersion nyckeln kontrollerar du att versionssträngen exakt matchar den versionssträng du behöver.

Get-Module AzureRM.Netcore -ListAvailable
    Directory: /home/azureuser/.local/share/powershell/Modules

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

Följande exempel misslyckas eftersom 0.12 inte exakt matchar 0.12.0.

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

-PSEdition <PSEdition-Name>

Anger en PowerShell-utgåva som skriptet kräver. Giltiga värden är Core för PowerShell och Desktop för Windows PowerShell.

Ett exempel:

#Requires -PSEdition Core

-ShellId

Anger det gränssnitt som skriptet kräver. Ange gränssnittets ID. Om du använder ShellId-parametern måste du även inkludera PSSnapin-parametern . Du hittar aktuellt ShellId genom att fråga den $ShellId automatiska variabeln.

Ett exempel:

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

Anteckning

Den här parametern är avsedd att användas i mini-shells, som har blivit inaktuella.

-RunAsAdministrator

När den här växelparametern läggs till i instruktionen #Requires anger den att PowerShell-sessionen där du kör skriptet måste startas med utökade användarrättigheter. Parametern RunAsAdministrator ignoreras på ett icke-Windows-operativsystem. Parametern RunAsAdministrator introducerades i PowerShell 4.0.

Ett exempel:

#Requires -RunAsAdministrator

Exempel

Följande skript har två #Requires instruktioner. Om kraven som anges i båda instruktionerna inte uppfylls körs inte skriptet. Varje #Requires instruktion måste vara det första objektet på en rad:

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

Se även