à propos des Exigences

Brève description

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 à moins que la version, les modules (et la version) ou les composants logiciels enfichables (et la version) et les conditions préalables d’édition de PowerShell ne soient remplis. Si les conditions préalables ne sont pas remplies, PowerShell n’exécute pas le script.

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 instructions #Requires. Les instructions #Requires peuvent apparaître sur n’importe quelle ligne d’un script.

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

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 de #Requires doit être respecté avant que le script puisse même s’exécuter. Ensuite, la première ligne du script a invalidé l’état requis.

Paramètres

-Assembly <chemin d’assembly> | <spécification d’assembly .NET>

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

-PSSnapin <Nom> _PSSnapin [-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 <> de nom de module | <> de table de hachage

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.

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 possède 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 l’une des trois touches ci-dessous. Ces touches ne peuvent pas être utilisées ensemble.
  • ModuleVersion : spécifie une version minimale acceptable du module.
  • RequiredVersion : spécifie une version exacte et requise du module.
  • MaximumVersion : spécifie la version maximale acceptable du module.

Par exemple:

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

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

Exiger que AzureRM.Netcore (uniquement 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 inférieure) soit installé.

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

Exiger que n’importe quelle version de AzureRM.Netcore et PowerShellGet est installée.

#Requires -Modules AzureRM.Netcore, PowerShellGet

Lorsque vous utilisez la clé RequiredVersion, 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

-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

-ExécuterEn Tant qu’Administrateur

Lorsque ce paramètre de commutateur est ajouté à votre instruction #Requires, 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 RunAsAdministrator est ignoré sur un système d’exploitation non Windows. Le paramètre RunAsAdministrator a été introduit dans PowerShell 4.0.

Par exemple:

#Requires -RunAsAdministrator

Exemples

Le script suivant comporte deux instructions #Requires. Si les exigences spécifiées dans les deux instructions ne sont pas remplies, le script ne s’exécute pas. Chaque instruction #Requires 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

• about_Automatic_Variables
• about_Language_Keywords