about_Requires
Kort beskrivning
Förhindrar att ett skript körs utan nödvändiga element.
Lång beskrivning
#Requires-instruktionen förhindrar att ett skript körs om inte kraven för PowerShell-version, moduler (och version) och version uppfylls. Om kraven inte uppfylls kör PowerShell inte skriptet eller tillhandahåller andra körningsfunktioner, till exempel tabbar.
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 mer än en #Requires instruktion. - #Requires instruktionerna 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 sekvensen för programmet. Det globala tillstånd som -instruktionen #Requires presenterar måste uppfyllas innan 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 stödkoden 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.
Till 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.
Till exempel:
#Requires -Version 5.1
-PSSnapin <PSSnapin-Name> [-Version <N>[.<n>]]
Anger en PowerShell-snapin-modul som skriptet kräver. Ange snapin-modulnamnet och ett valfritt versionsnummer.
Till 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.
Instruktionen #Requires läser inte in klass- och uppräkningsdefinitioner i modulen. Använd -instruktionen using module i början av skriptet för att importera modulen, inklusive klass- och uppräkningsdefinitionerna. Mer information finns i about_Using.
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- Obligatoriskt Anger modulnamnet. -
GUID- Valfritt 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 maximala godkända versionen av modulen. -
RequiredVersion– Anger en exakt, nödvändig version av modulen. Detta kan inte användas med de andra versionsnycklarna.
-
Kommentar
RequiredVersion lades till i Windows PowerShell 5.0.
MaximumVersion lades till i Windows PowerShell 5.1.
Till exempel:
Kräv att Hyper-V (version 1.1 eller senare) är installerat.
#Requires -Modules @{ ModuleName="Hyper-V"; ModuleVersion="1.1" }
Kräver att Hyper-V (endast version 1.1) är installerat.
#Requires -Modules @{ ModuleName="Hyper-V"; RequiredVersion="1.1" }
Kräver att Hyper-V (version 1.1 eller mindre) är installerad.
#Requires -Modules @{ ModuleName="Hyper-V"; MaximumVersion="1.1" }
Kräver att alla versioner av PSScheduledJob och PSWorkflow, är installerade.
#Requires -Modules PSWorkflow, PSScheduledJob
När du använder RequiredVersion nyckeln kontrollerar du att versionssträngen exakt matchar den versionssträng som du vill kräva.
Get-Module Hyper-V
ModuleType Version Name ExportedCommands
---------- ------- ---- ------------------
Binary 2.0.0.0 hyper-v {Add-VMAssignableDevice, ...}
Följande exempel misslyckas eftersom 2.0.0 inte exakt matchar 2.0.0.0.
#Requires -Modules @{ ModuleName="Hyper-V"; RequiredVersion="2.0.0" }
-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.
Till 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 parametern PSSnapin .
Du hittar aktuellt ShellId genom att fråga den $ShellId automatiska variabeln.
Till exempel:
#Requires -ShellId MyLocalShell -PSSnapin Microsoft.PowerShell.Core
Kommentar
Den här parametern är avsedd att användas i mini-shells, som har föråldrats.
-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 i ett operativsystem som inte är Windows. Parametern RunAsAdministrator introducerades i PowerShell 4.0.
Till exempel:
#Requires -RunAsAdministrator
Exempel
Följande skript har två #Requires instruktioner. Om kraven som anges i båda uttrycken inte uppfylls körs inte skriptet. Varje #Requires instruktion måste vara det första objektet på en rad:
#Requires -Modules PSWorkflow
#Requires -Version 3
Param
(
[parameter(Mandatory=$true)]
[String[]]
$Path
)
...
