Share via

about_Requires

  • Article

Description courte

Empêche l’exécution d’un script sans les éléments requis.

Description longue

L’instruction #Requires empêche l’exécution d’un script, sauf si la version, les modules (et la version) PowerShell et les conditions préalables à l’édition sont remplies. Si les conditions préalables ne sont pas remplies, PowerShell n’exécute pas le script ou fournit d’autres fonctionnalités d’exécution, telles que la saisie semi-automatique de tabulation.

Syntaxe

#Requires -Version <N>[.<n>]
#Requires -Modules { <Module-Name> | <Hashtable> }
#Requires -PSEdition <PSEdition-Name>
#Requires -RunAsAdministrator

Pour plus d’informations sur la syntaxe, consultez ScriptRequirements.

Règles d’utilisation

Un script peut inclure plusieurs #Requires instructions. Les #Requires instructions peuvent apparaître sur n’importe quelle ligne d’un script.

Placer une #Requires instruction à l’intérieur d’une fonction ne limite pas son étendue. Toutes les #Requires instructions sont toujours appliquées globalement et doivent être remplies avant que le script puisse s’exécuter.

Avertissement

Même si une #Requires instruction peut apparaître sur n’importe quelle ligne d’un script, sa position dans un script n’affecte pas la séquence de son application. L’état global présenté par l’instruction #Requires doit être respecté avant l’exécution du script.

Exemple :

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

Vous pouvez penser que le code ci-dessus ne doit pas s’exécuter, car le module requis a été supprimé avant l’instruction #Requires . Toutefois, l’état #Requires doit être respecté avant que le script ne puisse même s’exécuter. Ensuite, la première ligne du script a invalidé l’état requis.

Paramètres

-Chemin de l’assembly d’assembly <> | <. Spécification de l’assembly NET>

Important

La -Assembly syntaxe est déconseillée. Elle ne sert pas de fonction. La syntaxe a été ajoutée dans PowerShell 5.1, mais le code de prise en charge n’a jamais été implémenté. La syntaxe est toujours acceptée pour la compatibilité descendante.

Spécifie le chemin d’accès au fichier DLL d’assembly ou à un nom d’assembly .NET. Le paramètre Assembly a été introduit dans PowerShell 5.0. Pour plus d’informations sur les assemblys .NET, consultez noms d’assemblys.

Par exemple :

#Requires -Assembly path\to\foo.dll

#Requires -Assembly "System.Management.Automation, Version=3.0.0.0,
  Culture=neutral, PublicKeyToken=31bf3856ad364e35"

-Version <N>[.<n>]

Spécifie la version minimale de PowerShell requise par le script. Entrez un numéro de version principal et un numéro de version secondaire facultatif.

Par exemple :

#Requires -Version 6.0

-Modules <Module-Name> | <Hashtable>

Spécifie les modules PowerShell requis par le script. Entrez le nom du module et un numéro de version facultatif.

Si les modules requis ne sont pas dans la session active, PowerShell les importe. Si les modules ne peuvent pas être importés, PowerShell génère une erreur de fin.

L’instruction ne charge pas les #Requires définitions de classe et d’énumération dans le module. Utilisez l’instruction using module au début de votre script pour importer le module, y compris les définitions de classe et d’énumération. Pour plus d’informations, consultez about_Using.

Pour chaque module, tapez le nom du module (<String>) ou une table de hachage. La valeur peut être une combinaison de chaînes et de tables de hachage. La table de hachage contient les clés suivantes.

  • ModuleName - Obligatoire Spécifie le nom du module.
  • GUID - Facultatif Spécifie le GUID du module.
  • Il est également nécessaire de spécifier au moins l’une des trois clés ci-dessous.
    • ModuleVersion - Spécifie une version minimale acceptable du module.
    • MaximumVersion - Spécifie la version maximale acceptable du module.
    • RequiredVersion - Spécifie une version exacte et requise du module. Cela ne peut pas être utilisé avec les autres clés de version.

Remarque

RequiredVersion a été ajouté dans Windows PowerShell 5.0. MaximumVersion a été ajouté dans Windows PowerShell 5.1.

Par exemple :

Exiger que AzureRM.Netcore (version 0.12.0 ou version ultérieure) soit installé.

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

Exiger que AzureRM.Netcore (seule version 0.12.0) soit installé.

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

Nécessite que AzureRM.Netcore (version 0.12.0 ou version inférieure) soit installé.

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

Exiger que n’importe quelle version et AzureRM.NetcorePowerShellGet soit installée.

#Requires -Modules AzureRM.Netcore, PowerShellGet

Lorsque vous utilisez la RequiredVersion clé, vérifiez que votre chaîne de version correspond exactement à la chaîne de version dont vous avez besoin.

Get-Module AzureRM.Netcore -ListAvailable

    Directory: /home/azureuser/.local/share/powershell/Modules

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

L’exemple suivant échoue, car 0.12 ne correspond pas exactement à 0.12.0.

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

-PSEdition <PSEdition-Name>

Spécifie une édition PowerShell requise par le script. Les valeurs valides sont Core pour PowerShell et Desktop pour Windows PowerShell.

Par exemple :

#Requires -PSEdition Core

-RunAs Administration istrator

Lorsque ce paramètre de commutateur est ajouté à votre #Requires instruction, il spécifie que la session PowerShell dans laquelle vous exécutez le script doit être démarrée avec des droits d’utilisateur élevés. Le paramètre RunAs Administration istrator est ignoré sur un système d’exploitation non Windows. Le paramètre RunAs Administration istrator a été introduit dans PowerShell 4.0.

Par exemple :

#Requires -RunAsAdministrator

Exemples

Le script suivant comporte deux #Requires instructions. Si les exigences spécifiées dans les deux instructions ne sont pas remplies, le script ne s’exécute pas. Chaque #Requires instruction doit être le premier élément d’une ligne :

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

Voir aussi