Partager 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 les composants logiciels enfichables PowerShell, les modules (et la version) ou les composants logiciels enfichables (et version) 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 -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

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 5.1

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

Spécifie un composant logiciel enfichable PowerShell requis par le script. Entrez le nom du composant logiciel enfichable et un numéro de version facultatif.

Par exemple :

#Requires -PSSnapin DiskSnapin -Version 1.2

-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 Hyper-V (version 1.1 ou version ultérieure) soit installé.

#Requires -Modules @{ ModuleName="Hyper-V"; ModuleVersion="1.1" }

Nécessite que Hyper-V (uniquement la version 1.1) soit installée.

#Requires -Modules @{ ModuleName="Hyper-V"; RequiredVersion="1.1" }

Nécessite que Hyper-V (version 1.1 ou version inférieure) soit installé.

#Requires -Modules @{ ModuleName="Hyper-V"; MaximumVersion="1.1" }

Nécessite que n’importe quelle version et PSScheduledJobPSWorkflow, soit installée.

#Requires -Modules PSWorkflow, PSScheduledJob

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

Get-Module Hyper-V

ModuleType Version    Name     ExportedCommands
---------- -------    ----     ------------------
Binary     2.0.0.0    hyper-v  {Add-VMAssignableDevice, ...}

L’exemple suivant échoue, car la version 2.0.0 ne correspond pas exactement à 2.0.0.0.

#Requires -Modules @{ ModuleName="Hyper-V"; RequiredVersion="2.0.0" }

-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

-ShellId

Spécifie l’interpréteur de commandes requis par le script. Entrez l’ID de l’interpréteur de commandes. Si vous utilisez le paramètre ShellId , vous devez également inclure le paramètre PSSnapin . Vous trouverez le ShellId actuel en interrogeant la $ShellId variable automatique.

Par exemple :

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

Remarque

Ce paramètre est destiné à être utilisé dans les mini-interpréteurs de commandes, qui ont été déconseillés.

-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 PSWorkflow
#Requires -Version 3
Param
(
    [parameter(Mandatory=$true)]
    [String[]]
    $Path
)
...

Voir aussi