Partager via

about_Module_Manifests

Brève description

Décrit les paramètres et les pratiques d’écriture de fichiers manifeste de module.

Description longue

Un manifeste de module est un fichier de données PowerShell (.psd1) contenant une table de hachage. Les paires clés-valeur dans la table de hachage décrivent le contenu et les attributs du module, définissent les prérequis et contrôlent la façon dont les composants sont traités.

Les manifestes ne sont pas requis pour charger un module, mais ils sont nécessaires pour publier un module sur le PowerShell Gallery. Les manifestes vous permettent également de séparer l’implémentation de votre module de la façon dont il se charge. Avec un manifeste, vous pouvez définir des exigences, une compatibilité, un ordre de chargement, etc.

Lorsque vous utilisez New-ModuleManifest sans spécifier de paramètres pour les paramètres du manifeste, il écrit un fichier manifeste minimal. L’extrait de code ci-dessous vous montre cette sortie par défaut, énipée de commentaires et d’espacement pour la concision :

@{
# RootModule = ''
ModuleVersion = '1.0'
# CompatiblePSEditions = @()
GUID = 'e7184b71-2527-469f-a50e-166b612dfb3b'
Author = 'username'
CompanyName = 'Unknown'
Copyright = '(c) 2022 username. All rights reserved.'
# Description = ''
# PowerShellVersion = ''
# PowerShellHostName = ''
# PowerShellHostVersion = ''
# DotNetFrameworkVersion = ''
# CLRVersion = ''
# ProcessorArchitecture = ''
# RequiredModules = @()
# RequiredAssemblies = @()
# ScriptsToProcess = @()
# TypesToProcess = @()
# FormatsToProcess = @()
# NestedModules = @()
FunctionsToExport = @()
CmdletsToExport = @()
VariablesToExport = '*'
AliasesToExport = @()
# DscResourcesToExport = @()
# ModuleList = @()
# FileList = @()
PrivateData = @{
    PSData = @{
        # Tags = @()
        # LicenseUri = ''
        # ProjectUri = ''
        # IconUri = ''
        # ReleaseNotes = ''
        # ExternalModuleDependencies = @()
    } # End of PSData hashtable
} # End of PrivateData hashtable
# HelpInfoURI = ''
# DefaultCommandPrefix = ''
}

Vous pouvez utiliser Test-ModuleManifest pour valider un manifeste de module avant de publier votre module. Test-ModuleManifest retourne une erreur si le manifeste n’est pas valide ou si le module ne peut pas être importé dans la session active, car la session ne répond pas aux exigences définies dans le manifeste.

Utilisation du code de script dans un manifeste de module

Les valeurs affectées aux paramètres dans le fichier manifeste peuvent être des expressions évaluées par PowerShell. Cela vous permet de construire des chemins d’accès et d’attribuer des valeurs conditionnellement en fonction de variables.

Lorsque vous importez un module à l’aide de Import-Module, le manifeste est évalué en mode langage Restricted. Restricted mode limite les commandes et variables qui peuvent être utilisées.

Commandes autorisées

  • Import-LocalizedData
  • ConvertFrom-StringData
  • Write-Host
  • Out-Host
  • Join-Path

Variables autorisées

  • $PSScriptRoot
  • $PSEdition
  • $EnabledExperimentalFeatures
  • Toutes les variables d’environnement, comme $Env:TEMP

Pour plus d’informations, consultez about_Language_Modes.

Paramètres du manifeste

Les sections suivantes détaillent tous les paramètres disponibles dans un manifeste de module et la façon dont vous pouvez les utiliser. Ils commencent par un synopsis du paramètre et sont suivis d’une matrice qui répertorie :

  • type d’entrée: type d’objet que vous pouvez spécifier pour ce paramètre dans le manifeste.
  • Obligatoire : si cette valeur est « Oui », le paramètre est requis pour importer le module et le publier sur le PowerShell Gallery. S’il s’agit de « Non », il est requis pour ni l’un ni l’autre. Si c’est le cas, il n’est PowerShell Gallerynécessaire que pour la publication sur le PowerShell Gallery.
  • Valeur si aucun paramètre n’est défini: la valeur de ce paramètre est importée et non définie explicitement.
  • accepte les caractères génériques: indique si ce paramètre peut prendre une valeur générique ou non.

RootModule

Ce paramètre spécifie le fichier principal ou racine du module. Lorsque le module est importé, les membres exportés par le fichier de module racine sont importés dans l’état de session de l’appelant.

Valeur
type d’entrée System.String
obligatoire Non
valeur si la valeur n’est pas définie $null
accepte des caractères génériques Non

La valeur doit être le chemin d’accès à l’un des éléments suivants :

  • un script (.ps1)
  • un module de script (.psm1)
  • un manifeste de module (.psd1)
  • un assembly (.dll)
  • un fichier XML de définition d’applet de commande (.cdxml)
  • a Windows PowerShell 5.1 Workflow (.xaml)

Le chemin d’accès doit être relatif au manifeste du module.

Si aucun fichier racine n’a été désigné dans le RootModule clé, le manifeste devient le fichier principal du module et le module devient un module manifeste (ModuleType = Manifeste). Lorsque RootModule est défini, le type du module est déterminé à partir de l’extension de fichier utilisée :

  • un fichier .ps1 ou .psm1 rend le type de module Script
  • un fichier .psd1 rend le type de module Manifest
  • un fichier .dll rend le type de module binaire
  • un fichier .cdxml rend le type de module CIM
  • un fichier .xaml rend le type de module workflow

Par défaut, tous les membres du module de l'RootModule sont exportés.

Pourboire

La vitesse de chargement du module diffère entre binaire, de script et les types de modules CIM . Pour plus d’informations, consultez considérations relatives à la création de modules PowerShell

Par exemple, le ModuleType de ce module est manifeste. Les seuls membres de module que ce module peut exporter sont ceux définis dans les modules spécifiés avec le paramètre NestedModules.

@{
    RootModule = ''
}

Note

Ce paramètre peut également être spécifié dans les manifestes de module en tant que ModuleToProcess. Bien que ce nom soit valide, il est recommandé d’utiliser RootModule à la place.

ModuleVersion

Ce paramètre spécifie la version du module. Quand plusieurs versions d’un module existent sur un système, la dernière version est chargée par défaut lorsque vous exécutez Import-Module.

Valeur
type d’entrée System.String
obligatoire Oui
valeur si la valeur n’est pas définie Aucun
accepte des caractères génériques Non

La valeur de ce paramètre doit être convertible en System.Version lorsque vous exécutez Import-Module.

Par exemple, ce manifeste déclare la version du module en tant que '1.2.3'.

@{
    ModuleVersion = '1.2.3'
}

Lorsque vous importez le module et inspectez la propriété Version, notez qu’il s’agit d’un objet System.Version et non d’une chaîne :

$ExampleModule = Import-Module example.psd1
$ExampleModule.Version
$ExampleModule.Version.GetType().Name

Major  Minor  Build  Revision
-----  -----  -----  --------
1      2      3      -1

Version

CompatiblePSEditions

Ce paramètre spécifie les PSEditions compatibles du module.

Valeur
type d’entrée System.String[]
valeurs acceptées Desktop, Core
obligatoire Non
valeur si la valeur n’est pas définie $null
accepte des caractères génériques Non

Si la valeur de ce paramètre est $null, le module peut être importé indépendamment de la psEdition de la session. Vous pouvez le définir sur une ou plusieurs des valeurs acceptées.

Pour plus d’informations sur PSEdition, consultez :

Lorsque ce paramètre est défini, le module peut uniquement être importé dans une session où la valeur de la variable automatique $PSEdition est incluse dans le paramètre.

Note

Étant donné que la variable automatique $PSEdition a été introduite dans la version 5.1, les versions antérieures de Windows PowerShell ne peuvent pas charger un module qui utilise le paramètre CompatiblePSEditions.

Par exemple, vous pouvez importer ce manifeste de module dans n’importe quelle session :

@{
    # CompatiblePSEditions = @()
}

Avec le paramètre spécifié, ce module ne peut être importé que dans les sessions où la valeur de la variable automatique $PSEdition est Core.

@{
    CompatiblePSEditions = @('Core')
}

GUID

Ce paramètre spécifie un identificateur unique pour le module. L'GUID est utilisé pour faire la distinction entre les modules portant le même nom.

Valeur
type d’entrée System.String
obligatoire Non
valeur si la valeur n’est pas définie 00000000-0000-0000-0000-000000000000
accepte des caractères génériques Non

La valeur de ce paramètre doit être convertible en System.Guid lorsque vous exécutez Import-Module.

Prudence

Bien qu’il ne s’agit pas d’un paramètre obligatoire, il n’est pas nécessaire de spécifier un GUID dans un manifeste n’a aucun avantage et peut entraîner des collisions de noms pour les modules.

Vous pouvez créer un guid à utiliser dans votre manifeste :

New-Guid | Select-Object -ExpandProperty Guid

8456b025-2fa5-4034-ae47-e6305f3917ca

@{
    GUID = '8456b025-2fa5-4034-ae47-e6305f3917ca'
}

S’il existe un autre module sur l’ordinateur portant le même nom, vous pouvez toujours importer celui souhaité en spécifiant le nom complet du module :

Import-Module -FullyQualifiedName @{
    ModuleName    = 'Example'
    GUID          = '8456b025-2fa5-4034-ae47-e6305f3917ca'
    ModuleVersion = '1.0.0'
}

Author

Ce paramètre identifie l’auteur du module.

Valeur
type d’entrée System.String
obligatoire PowerShell Gallery
valeur si la valeur n’est pas définie $null
accepte des caractères génériques Non

Ce manifeste déclare que l’auteur du module est l’équipe d’expérience des développeurs Contoso.

@{
    Author = 'Contoso Developer Experience Team'
}

CompanyName

Ce paramètre identifie l’entreprise ou le fournisseur qui a créé le module.

Valeur
type d’entrée System.String
obligatoire Non
valeur si la valeur n’est pas définie $null
accepte des caractères génériques Non

Ce manifeste déclare que le module a été créé par Contoso, Ltd.

@{
    CompanyName = 'Contoso, Ltd.'
}

Ce paramètre spécifie une instruction de copyright pour le module.

Valeur
type d’entrée System.String
obligatoire Non
valeur si la valeur n’est pas définie $null
accepte des caractères génériques Non

Ce manifeste déclare une déclaration de copyright réservant tous les droits à Contoso, Ltd. à compter de 2022.

@{
    Copyright = '(c) 2022 Contoso, Ltd. All rights reserved.'
}

Description

Ce paramètre décrit le module à un niveau élevé.

Valeur
type d’entrée System.String
obligatoire PowerShell Gallery
valeur si la valeur n’est pas définie $null
accepte des caractères génériques Non

Ce manifeste inclut une brève description. Vous pouvez également utiliser une chaîne ici pour écrire une description plus longue ou multiligne.

@{
    Description = 'Example commands to show a valid module manifest'
}

PowerShellVersion

Ce paramètre spécifie la version minimale de PowerShell requise par ce module.

Valeur
type d’entrée System.String
obligatoire Non
valeur si la valeur n’est pas définie $null
accepte des caractères génériques Non

La valeur de ce paramètre doit être convertible en System.Version lorsque vous exécutez Import-Module.

Si ce paramètre n’est pas défini, PowerShell ne limite pas l’importation du module en fonction de la version actuelle.

Par exemple, ce manifeste déclare que le module est compatible avec chaque version de PowerShell et Windows PowerShell.

@{
    # PowerShellVersion = ''
}

Avec powerShellVersion défini sur 7.2, vous pouvez uniquement importer le module dans PowerShell 7.2 ou version ultérieure.

@{
    PowerShellVersion = '7.2'
}

PowerShellHostName

Ce paramètre spécifie le nom du programme hôte PowerShell requis par le module, tel que hôte Windows PowerShell ISE ou ConsoleHost.

Valeur
type d’entrée System.String
obligatoire Non
valeur si la valeur n’est pas définie $null
accepte des caractères génériques Non

Vous trouverez le nom de l’hôte pour une session avec l’instruction $Host.Name. Par exemple, vous pouvez voir que l’hôte d’une session distante est ServerRemoteHost au lieu de ConsoleHost:

$Host.Name
Enter-PSSession -ComputerName localhost
$Host.Name

ConsoleHost
[localhost]: PS C:\Users\username\Documents> $Host.Name
ServerRemoteHost

Ce module peut être importé dans n’importe quel hôte.

@{
    # PowerShellHostName = ''
}

Avec PowerShellHostName défini sur ServerRemoteHost, vous ne pouvez importer le module que dans une session PowerShell distante.

@{
    PowerShellHostName = 'ServerRemoteHost'
}

PowerShellHostVersion

Ce paramètre spécifie la version minimale d’un programme hôte PowerShell requis par le module.

Valeur
type d’entrée System.String
obligatoire Non
valeur si la valeur n’est pas définie $null
accepte des caractères génériques Non

La valeur de ce paramètre doit être convertible en System.Version lorsque vous exécutez Import-Module.

Prudence

Bien que ce paramètre puisse être utilisé sans le paramètre PowerShellHostName, il augmente les chances de comportement inattendu. Utilisez ce paramètre uniquement lorsque vous utilisez également le paramètre PowerShellHostName.

Par exemple, le module de ce manifeste peut être importé à partir de n’importe quelle session PowerShell exécutée dans ConsoleHost, quelle que soit la version de l’hôte.

@{
    PowerShellHostName = 'ConsoleHost'
    # PowerShellHostVersion = ''
}

Avec le PowerShellHostVersion défini sur 5.1, vous ne pouvez importer le module qu’à partir de n’importe quelle session PowerShell s’exécutant dans ConsoleHost où la version de l’hôte est 5.1 ou ultérieure.

@{
    PowerShellHostName    = 'ConsoleHost'
    PowerShellHostVersion = '5.1'
}

DotNetFrameworkVersion

Ce paramètre spécifie la version minimale de Microsoft .NET Framework requise par le module.

Valeur
type d’entrée System.String
obligatoire Non
valeur si la valeur n’est pas définie $null
accepte des caractères génériques Non

Note

Ce paramètre est valide pour l’édition PowerShell Desktop uniquement, comme Windows PowerShell 5.1, et s’applique uniquement aux versions de .NET Framework inférieures à 4.5. Cette exigence n’a aucun effet sur les versions plus récentes de PowerShell ou de .NET Framework.

La valeur de ce paramètre doit être convertible en System.Version lorsque vous exécutez Import-Module.

Par exemple, ce manifeste déclare que son module peut être importé dans n’importe quelle session PowerShell ou Windows PowerShell, quelle que soit la version de Microsoft .NET Framework.

@{
    # DotNetFrameworkVersion = ''
}

Avec DotNetFrameworkVersion défini sur 4.0, vous pouvez importer ce module dans n’importe quelle session de Windows PowerShell où la dernière version disponible de Microsoft .NET Framework est au moins 4.0. Vous pouvez également l’importer dans n’importe quelle session PowerShell.

@{
    DotNetFrameworkVersion = '4.0'
}

CLRVersion

Ce paramètre spécifie la version minimale du Common Language Runtime (CLR) du Microsoft .NET Framework requis par le module.

Valeur
type d’entrée System.String
obligatoire Non
valeur si la valeur n’est pas définie $null
accepte des caractères génériques Non

Note

Ce paramètre est valide pour l’édition PowerShell Desktop uniquement, comme Windows PowerShell 5.1, et s’applique uniquement aux versions de .NET Framework inférieures à 4.5. Cette exigence n’a aucun effet sur les versions plus récentes de PowerShell ou de .NET Framework.

La valeur de ce paramètre doit être convertible en System.Version lorsque vous exécutez Import-Module.

Par exemple, ce manifeste déclare que son module peut être importé dans n’importe quelle session PowerShell ou Windows PowerShell, quelle que soit la version de la version CLR de Microsoft .NET Framework.

@{
    # CLRVersion = ''
}

Avec CLRVersion défini sur 4.0, vous pouvez importer ce module dans n’importe quelle session de Windows PowerShell où la dernière version disponible du CLR est au moins 4.0. Vous pouvez également l’importer dans n’importe quelle session PowerShell.

@{
    CLRVersion = '4.0'
}

ProcessorArchitecture

Ce paramètre spécifie l’architecture du processeur requise par le module.

Valeur
type d’entrée System.String
valeurs acceptées None, , MSIL, X86IA64, , Amd64Arm
obligatoire Non
valeur si la valeur n’est pas définie None
accepte des caractères génériques Non

La valeur de ce paramètre doit être convertible en System.Reflection.ProcessorArchitecture lorsque vous exécutez Import-Module.

Par exemple, ce manifeste déclare que son module peut être importé dans n’importe quelle session, quelle que soit l’architecture du processeur du système.

@{
    # ProcessorArchitecture = ''
}

Avec ProcessorArchitecture défini sur Amd64, vous pouvez uniquement importer ce module dans une session s’exécutant sur un ordinateur avec une architecture correspondante.

@{
    ProcessorArchitecture = 'Amd64'
}

RequiredModules

Ce paramètre spécifie les modules qui doivent être dans l’état de session globale. Si les modules requis ne sont pas dans l’état de session global, PowerShell les importe. Si les modules requis ne sont pas disponibles, la commande Import-Module échoue.

Valeur
type d’entrée System.String[], System.Collections.Hashtable[]
obligatoire Non
valeur si la valeur n’est pas définie $null
accepte des caractères génériques Non

Les entrées de ce paramètre peuvent être un nom de module, une spécification complète du module ou un chemin d’accès à un fichier de module.

Lorsque la valeur est un chemin d’accès, le chemin d’accès peut être qualifié ou relatif complet.

Lorsque la valeur est un nom ou une spécification de module, PowerShell recherche le PSModulePath pour le module spécifié.

Une spécification de module est une table de hachage qui a les clés suivantes.

  • ModuleName - obligatoire . Spécifie le nom du module.
  • GUID - facultatif . Spécifie le GUID du module.
  • Il est également obligatoire pour spécifier au moins l’une des trois clés ci-dessous. La clé RequiredVersion ne peut pas être utilisée avec les clés ModuleVersion ou MaximumVersion. Vous pouvez définir une plage de versions acceptable pour le module en spécifiant les clés ModuleVersion et MaximumVersion 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.

Note

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

Par exemple, ce manifeste déclare que son module ne nécessite aucun autre module pour ses fonctionnalités.

@{
    # RequiredModules = @()
}

Ce manifeste déclare qu’il requiert le module PSReadLine. Lorsque vous exécutez Import-Module sur ce manifeste, PowerShell importe la dernière version de PSReadLine disponible pour la session. Si aucune version n’est disponible, l’importation retourne une erreur.

@{
    RequiredModules = @(
        'PSReadLine'
    )
}

Pourboire

Dans PowerShell 2.0, Import-Module n’importe pas automatiquement les modules requis. Il vérifie uniquement que les modules requis sont dans l’état de session global.

Ce manifeste déclare qu’il nécessite une version du module PSReadLine fournisseur dans son propre dossier de module. Lorsque vous exécutez Import-Module sur ce manifeste, PowerShell importe le PSReadLine fournisseur à partir du chemin spécifié.

@{
    RequiredModules = @(
        'Vendored\PSReadLine\PSReadLine.psd1'
    )
}

Ce manifeste déclare qu’il nécessite spécifiquement la version 2.0.0 du module PSReadLine. Lorsque vous exécutez Import-Module sur ce manifeste, PowerShell importe la version 2.0.0 de PSReadLine si elle est disponible. S’il n’est pas disponible, Import-Module retourne une erreur.

@{
    RequiredModules = @(
        @{
            ModuleName      = 'PSReadLine'
            RequiredVersion = '2.0.0'
        }
    )
}

Ce manifeste déclare qu’il exige que le module PSReadLine soit importé à la version 2.0.0 ou ultérieure.

@{
    RequiredModules = @(
        @{
            ModuleName    = 'PSReadLine'
            ModuleVersion = '2.0.0'
        }
    )
}

Ce manifeste déclare qu’il exige que le module PSReadLine soit importé à la version 2.0.0 ou inférieure.

@{
    RequiredModules = @(
        @{
            ModuleName     = 'PSReadLine'
            MaximumVersion = '2.0.0'
        }
    )
}

Ce manifeste déclare qu’il exige que le module PSDesiredStateConfiguration soit importé à une version égale ou supérieure à 2.0.0, mais pas supérieure à 2.99.99.

@{
    RequiredModules = @(
        @{
            ModuleName     = 'PSDesiredStateConfiguration'
            ModuleVersion  = '2.0.0'
            MaximumVersion = '2.99.99'
        }
    )
}

RequiredAssemblies

Ce paramètre spécifie les fichiers d’assembly (.dll) requis par le module. PowerShell charge les assemblys spécifiés avant de mettre à jour des types ou des formats, d’importer des modules imbriqués ou d’importer le fichier de module spécifié dans la valeur de la clé RootModule.

Valeur
type d’entrée System.String[]
obligatoire Non
valeur si la valeur n’est pas définie $null
accepte des caractères génériques Non

Les entrées de ce paramètre peuvent être le nom de fichier d’un assembly ou le chemin d’accès à un. Répertoriez tous les assemblys requis, même s’ils sont également répertoriés en tant que modules binaires dans le paramètre NestedModules.

Ce manifeste nécessite l’assembly example.dll. Avant de charger des fichiers de mise en forme ou de type spécifiés dans ce manifeste, PowerShell charge example.dll à partir du dossier Assemblies situé dans le même répertoire que le manifeste du module.

@{
    RequiredAssemblies = @(
        'Assemblies\Example.dll'
    )
}

ScriptsToProcess

Ce paramètre spécifie les fichiers de script (.ps1) qui s’exécutent dans l’état de session de l’appelant lorsque le module est importé. Vous pouvez utiliser ces scripts pour préparer un environnement, tout comme vous pouvez utiliser un script de connexion.

Valeur
type d’entrée System.String[]
obligatoire Non
valeur si la valeur n’est pas définie $null
accepte des caractères génériques Non

Pour spécifier des scripts qui s’exécutent dans l’état de session du module, utilisez la clé NestedModules.

Lorsque vous importez ce manifeste, PowerShell exécute le Initialize.ps1 dans votre session active.

@{
    ScriptsToProcess = @(
        'Scripts\Initialize.ps1'
    )
}

Par exemple, si Initialize.ps1 écrit des messages d’information et définit la variable $ExampleState :

if ([string]::IsNullOrEmpty($ExampleState)) {
    Write-Information "Example not initialized."
    Write-Information "Initializing now..."
    $ExampleState = 'Initialized'
} else {
    Write-Information "Example already initialized."
}

Lorsque vous importez le module, le script s’exécute, en écrivant ces messages et en définissant $ExampleState dans votre session.

$InformationPreference = 'Continue'
"Example State is: $ExampleState"
Import-Module .\example7x.psd1
"Example State is: $ExampleState"
Import-Module .\example7x.psd1 -Force

Example State is:

Example not initialized.
Initializing now...

Example State is: Initialized

Example already initialized.

TypesToProcess

Ce paramètre spécifie les fichiers de type (.ps1xml) qui s’exécutent lorsque le module est importé.

Valeur
type d’entrée System.String[]
obligatoire Non
valeur si la valeur n’est pas définie $null
accepte des caractères génériques Non

Lorsque vous importez le module, PowerShell exécute l’applet de commande Update-TypeData avec les fichiers spécifiés. Étant donné que les fichiers de type ne sont pas délimités, ils affectent tous les états de session de la session.

Pour plus d’informations sur les fichiers de type, consultez about_Types.ps1xml

Par exemple, lorsque vous importez ce manifeste, PowerShell charge les types spécifiés dans le fichier Example.ps1xml à partir du dossier Types situé dans le même répertoire que le manifeste du module.

@{
    TypesToProcess = @(
        'Types\Example.ps1xml'
    )
}

FormatsToProcess

Ce paramètre spécifie les fichiers de mise en forme (.ps1xml) qui s’exécutent lorsque le module est importé.

Valeur
type d’entrée System.String[]
obligatoire Non
valeur si la valeur n’est pas définie $null
accepte des caractères génériques Non

Lorsque vous importez un module, PowerShell exécute l’applet de commande Update-FormatData avec les fichiers spécifiés. Étant donné que les fichiers de mise en forme ne sont pas limités, ils affectent tous les états de session de la session.

Pour plus d’informations sur les fichiers de type, consultez about_Format.ps1xml

Par exemple, lorsque vous importez ce module, PowerShell charge les formats spécifiés dans le fichier Example.ps1xml à partir du dossier Formats situé dans le même répertoire que le manifeste du module.

@{
    FormatsToProcess = @(
        'Formats\Example.ps1xml'
    )
}

NestedModules

Ce paramètre spécifie les modules de script (.psm1) et les modules binaires (.dll) importés dans l’état de session du module. Vous pouvez également spécifier des fichiers de script (.ps1). Les fichiers de ce paramètre s’exécutent dans l’ordre dans lequel ils sont répertoriés.

Valeur
type d’entrée System.String[], System.Collections.Hashtable[]
obligatoire Non
valeur si la valeur n’est pas définie $null
accepte des caractères génériques Non

Les entrées de ce paramètre peuvent être un nom de module, une spécification complète du module ou un chemin d’accès à un fichier de module ou de script.

Lorsque la valeur est un chemin d’accès, le chemin d’accès peut être qualifié ou relatif complet.

Lorsque la valeur est un nom de module ou une spécification, PowerShell recherche le PSModulePath pour le module spécifié.

Une spécification de module est une table de hachage qui a les clés suivantes.

  • ModuleName - obligatoire . Spécifie le nom du module.
  • GUID - facultatif . Spécifie le GUID du module.
  • Il est également obligatoire pour spécifier au moins l’une des trois clés ci-dessous. La clé RequiredVersion ne peut pas être utilisée avec les clés ModuleVersion ou MaximumVersion. Vous pouvez définir une plage de versions acceptable pour le module en spécifiant les clés ModuleVersion et MaximumVersion 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.

Note

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

Tous les éléments qui doivent être exportés à partir d’un module imbriqué doivent être exportés par le module imbriqué à l’aide de l’applet de commande Export-ModuleMember ou être répertoriés dans l’une des propriétés d’exportation :

  • FunctionsToExport
  • CmdletsToExport
  • VariablesToExport
  • AliasesToExport

Les modules imbriqués dans l’état de session du module sont disponibles pour le module racine, mais ils ne sont pas retournés par une commande Get-Module dans l’état de session de l’appelant.

Les scripts (.ps1) répertoriés dans ce paramètre sont exécutés dans l’état de session du module, et non dans l’état de session de l’appelant. Pour exécuter un script dans l’état de session de l’appelant, répertoriez le nom de fichier de script dans le paramètre ScriptsToProcess.

Par exemple, lorsque vous importez ce manifeste, le module Helpers.psm1 est chargé dans l’état de session du module racine. Les applets de commande déclarées dans le module imbriqué sont exportées, sauf restriction contraire.

@{
    NestedModules = @(
        'Helpers\Helpers.psm1'
    )
}

FunctionsToExport

Ce paramètre spécifie les fonctions que le module exporte. Vous pouvez utiliser ce paramètre pour restreindre les fonctions exportées par le module. Elle peut supprimer des fonctions de la liste des fonctions exportées, mais elle ne peut pas ajouter de fonctions à la liste.

Valeur
type d’entrée System.String[]
obligatoire Non
valeur si la valeur n’est pas définie $null
accepte des caractères génériques Oui

Vous pouvez spécifier des entrées dans ce paramètre avec des caractères génériques. Toutes les fonctions correspondantes dans la liste des fonctions exportées sont exportées.

Pourboire

Pour des performances et une détectabilité, vous devez toujours répertorier explicitement les fonctions que vous souhaitez exporter dans ce paramètre sans utiliser de caractères génériques.

Par exemple, lorsque vous importez un module avec le paramètre commenté, toutes les fonctions du module racine et tous les modules imbriqués sont exportées.

@{
    # FunctionsToExport = @()
}

Ce manifeste est fonctionnellement identique à ne pas spécifier le paramètre du tout.

@{
    FunctionsToExport = '*'
}

Avec FunctionsToExport défini en tant que tableau vide, lorsque vous importez ce module, aucune fonction n’est disponible pour le module racine ou les modules imbriqués exportés.

@{
    FunctionsToExport = @()
}

Note

Si vous créez votre manifeste de module avec la commande New-ModuleManifest et que vous ne spécifiez pas le paramètre FunctionsToExport, le manifeste créé a ce paramètre spécifié comme tableau vide. Sauf si vous modifiez le manifeste, aucune fonction du module n’est exportée.

Avec FunctionsToExport défini pour inclure uniquement la fonction Get-Example, lorsque vous importez ce module uniquement la fonction Get-Example est rendue disponible, même si d’autres fonctions ont été exportées par le module racine ou les modules imbriqués.

@{
    FunctionsToExport = @(
        'Get-Example'
    )
}

Avec FunctionsToExport défini avec une chaîne générique, lorsque vous importez ce module toute fonction dont le nom se termine par Example est rendu disponible, même si d’autres fonctions ont été exportées en tant que membres de module par le module racine ou tous les modules imbriqués.

@{
    FunctionsToExport = @(
        '*Example'
    )
}

CmdletsToExport

Ce paramètre spécifie les applets de commande que le module exporte. Vous pouvez utiliser ce paramètre pour restreindre les applets de commande exportées par le module. Il peut supprimer des applets de commande de la liste des membres de module exportés, mais elle ne peut pas ajouter d’applets de commande à la liste.

Valeur
type d’entrée System.String[]
obligatoire Non
valeur si la valeur n’est pas définie $null
accepte des caractères génériques Oui

Vous pouvez spécifier des entrées dans ce paramètre avec des caractères génériques. Toutes les applets de commande correspondantes dans la liste des applets de commande exportées sont exportées.

Pourboire

Pour des performances et une détectabilité, vous devez toujours répertorier explicitement les applets de commande que vous souhaitez exporter dans ce paramètre sans utiliser de caractères génériques.

Par exemple, lorsque vous importez un module avec ce paramètre commenté, toutes les applets de commande du module racine et tous les modules imbriqués sont exportées.

@{
    # CmdletsToExport = @()
}

Ce manifeste est fonctionnellement identique à ne pas spécifier le paramètre du tout.

@{
    CmdletsToExport = '*'
}

Avec CmdletsToExport défini comme tableau vide, lorsque vous importez ce module, aucune applet de commande n’est disponible pour le module racine ou toute exportation de modules imbriqués.

@{
    CmdletsToExport = @()
}

Note

Si vous créez votre manifeste de module avec la commande New-ModuleManifest et que vous ne spécifiez pas le paramètre CmdletsToExport, le manifeste créé a ce paramètre spécifié comme tableau vide. Sauf si vous modifiez le manifeste, aucune applet de commande du module n’est exportée.

Avec CmdletsToExport défini pour inclure uniquement l’applet de commande Get-Example, lorsque vous importez ce module uniquement l’applet de commande Get-Example est rendue disponible, même si d’autres applets de commande ont été exportées par le module racine ou les modules imbriqués.

@{
    CmdletsToExport = @(
        'Get-Example'
    )
}

Avec CmdletsToExport défini avec une chaîne générique, lorsque vous importez ce module, toute applet de commande dont le nom se termine par Example est rendue disponible, même si d’autres applets de commande ont été exportées en tant que membres du module racine ou de modules imbriqués.

@{
    CmdletsToExport = @(
        '*Example'
    )
}

VariablesToExport

Ce paramètre spécifie les variables que le module exporte. Vous pouvez utiliser ce paramètre pour restreindre les variables exportées par le module. Elle peut supprimer des variables de la liste des membres de module exportés, mais elle ne peut pas ajouter de variables à la liste.

Valeur
type d’entrée System.String[]
obligatoire Non
valeur si la valeur n’est pas définie $null
accepte des caractères génériques Oui

Vous pouvez spécifier des entrées dans ce paramètre avec des caractères génériques. Toutes les variables correspondantes dans la liste des membres de module exportés sont exportées.

Pourboire

Pour des performances et une détectabilité, vous devez toujours répertorier explicitement les variables que votre module doit exporter dans ce paramètre sans utiliser de caractères génériques.

Par exemple, lorsque vous importez un module avec ce paramètre commenté, toutes les variables du module racine et tous les modules imbriqués sont exportés.

@{
    # VariablesToExport = @()
}

Ce manifeste est fonctionnellement identique à ne pas spécifier le paramètre du tout.

@{
    VariablesToExport = '*'
}

Note

Si vous créez votre manifeste de module avec la commande New-ModuleManifest et que vous ne spécifiez pas le paramètre VariablesToExport, le manifeste créé a ce paramètre spécifié comme '*'. Sauf si vous modifiez le manifeste, toutes les variables du module sont exportées.

Avec VariablesToExport défini en tant que tableau vide, lorsque vous importez ce module, aucune variable n’est disponible pour le module racine ou pour les modules imbriqués.

@{
    VariablesToExport = @()
}

Avec VariablesToExport défini pour inclure uniquement la variable SomeExample, lorsque vous importez ce module uniquement la variable $SomeExample est rendue disponible, même si d’autres variables ont été exportées par le module racine ou les modules imbriqués.

@{
    VariablesToExport = @(
        'SomeExample'
    )
}

Avec VariablesToExport défini avec une chaîne générique, lorsque vous importez ce module toute variable dont le nom se termine par Example est rendu disponible, même si d’autres variables ont été exportées en tant que membres du module racine ou de modules imbriqués.

@{
    VariablesToExport = @(
        '*Example'
    )
}

DscResourcesToExport

Ce paramètre spécifie les ressources DSC que le module exporte. Vous pouvez utiliser ce paramètre pour restreindre les ressources DSC basées sur la classe exportées par le module. Il peut supprimer des ressources DSC de la liste des membres de module exportés, mais il ne peut pas ajouter de ressources DSC à la liste.

Valeur
type d’entrée System.String[]
obligatoire Non
valeur si la valeur n’est pas définie $null
accepte des caractères génériques Oui

Vous pouvez spécifier des entrées dans ce paramètre avec des caractères génériques. Toutes les ressources DSC basées sur des classes correspondantes dans le module sont exportées.

Pourboire

Pour la détectabilité, vous devez toujours répertorier explicitement toutes les ressources DSC que votre module exporte.

Pour plus d’informations sur la création et l’utilisation de ressources DSC, consultez la documentation pour DSC.

Ce manifeste exporte toutes les ressources DSC basées sur des classes et MOF définies dans le module racine et tous les modules imbriqués.

@{
    # DscResourcesToExport = @()
}

Ce manifeste exporte toutes les ressources DSC basées sur MOF définies dans le module racine et tous les modules imbriqués, mais une seule ressource DSC basée sur une classe, ExampleClassResource.

@{
    DscResourcesToExport = @(
        'ExampleClassResource'
    )
}

Ce manifeste exporte toutes les ressources DSC qu’elle inclut. Même si la ressource MOF-Based n’était pas répertoriée, le module l’exporterait toujours.

@{
    DscResourcesToExport = @(
        'ExampleClassResource'
        'ExampleMofResourceFirst'
    )
}

ModuleList

Ce paramètre est une liste d’inventaire informationnel des modules inclus dans celui-ci. Cette liste n’affecte pas le comportement du module.

Valeur
type d’entrée System.String[], System.Collections.Hashtable[]
obligatoire Non
valeur si la valeur n’est pas définie $null
accepte des caractères génériques Non

Les entrées de ce paramètre peuvent être un nom de module, une spécification complète du module ou un chemin d’accès à un fichier de module ou de script.

Lorsque la valeur est un chemin d’accès, le chemin d’accès peut être qualifié ou relatif complet.

Lorsque la valeur est un nom de module ou une spécification, PowerShell recherche le PSModulePath pour le module spécifié.

Une spécification de module est une table de hachage qui a les clés suivantes.

  • ModuleName - obligatoire . Spécifie le nom du module.
  • GUID - facultatif . Spécifie le GUID du module.
  • Il est également obligatoire pour spécifier au moins l’une des trois clés ci-dessous. La clé RequiredVersion ne peut pas être utilisée avec les clés ModuleVersion ou MaximumVersion. Vous pouvez définir une plage de versions acceptable pour le module en spécifiant les clés ModuleVersion et MaximumVersion 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.

Note

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

Ce manifeste ne fournit pas de liste d’informations des modules qu’il inclut. Il peut ou non avoir des modules. Même si ce paramètre n’est pas spécifié, tous les modules répertoriés dans le RootModule, ScriptsToProcessou paramètres imbriquésModules se comportent normalement.

@{
    # ModuleList = @()
}

Ce manifeste déclare que les seuls modules qu’il inclut sont Example.psm1 et les sous-modules First.psm1 et Second.psm1 dans le dossier Submodules.

@{
    ModuleList = @(
        'Example.psm1'
        'Submodules\First.psm1'
        'Submodules\Second.psm1'
    )
}

FileList

Ce paramètre est une liste d’inventaire informationnel des fichiers inclus dans ce module. Cette liste n’affecte pas le comportement du module.

Valeur
type d’entrée System.String[]
obligatoire Non
valeur si la valeur n’est pas définie $null
accepte des caractères génériques Oui

Les entrées de ce paramètre doivent être le chemin relatif d’un fichier à partir du dossier contenant le manifeste du module.

Lorsqu’un utilisateur appelle Get-Module par rapport à un manifeste défini avec ce paramètre défini, la propriété FileList contient le chemin complet de ces fichiers, en joignant le chemin d’accès du module avec le chemin relatif de chaque entrée.

Ce manifeste n’inclut pas de liste de ses fichiers.

@{
    # FileList = @()
}

Ce manifeste déclare que les seuls fichiers qu’il inclut sont répertoriés dans ce paramètre.

@{
    FileList = @(
        'Example.psd1'
        'Example.psm1'
        'Assemblies\Example.dll'
        'Scripts\Initialize.ps1'
        'Submodules\First.psm1'
        'Submodules\Second.psm1'
    )
}

PrivateData

Ce paramètre définit une table de hachage de données disponible pour toutes les commandes ou fonctions dans l’étendue du module racine.

Valeur
type d’entrée System.Collections.Hashtable
obligatoire PowerShell GalleryCrescendo
valeur si la valeur n’est pas définie $null
accepte des caractères génériques Non

Lorsque vous exportez un manifeste Crescendo pour créer un module, Export-CrescendoModule ajoute deux clés à PrivateData

  • CrescendoGenerated - timestamp lorsque le module a été exporté
  • CrescendoVersion : la version de Crescendo utilisée pour exporter le module

Vous pouvez ajouter vos propres clés pour contenir les métadonnées que vous souhaitez suivre. Toutes les clés ajoutées à ce paramètre sont disponibles pour les fonctions et les applets de commande dans le module racine à l’aide de $MyInvocation.MyCommand.Module.PrivateData. La table de hachage n’est pas disponible dans l’étendue du module elle-même, uniquement dans les applets de commande que vous définissez dans le module.

Par exemple, ce manifeste définit la clé PublishedDate dans privateData.

@{
    PrivateData = @{
        PublishedDate = '2022-06-01'
    }
}

Les applets de commande du module peuvent accéder à cette valeur avec la variable $MyInvocation.

function Get-Stale {
    [CmdletBinding()]
    param()

    $PublishedDate = $MyInvocation.MyCommand.Module.PrivateData.PublishedDate
    $CurrentDate = Get-Date

    try {
        $PublishedDate = Get-Date -Date $PublishedDate -ErrorAction Stop
    } catch {
        # The date was set in the manifest, set to an invalid value, or
        # the script module was directly imported without the manifest.
        throw "Unable to determine published date. Check the module manifest."
    }

    if ($CurrentDate -gt $PublishedDate.AddDays(30)) {
        Write-Warning "This module version was published more than 30 days ago."
    } else {
        $TimeUntilStale = $PublishedDate.AddDays(30) - $CurrentDate
        "This module will be stale in $($TimeUntilStale.Days) days"
    }
}

Une fois le module importé, la fonction utilise la valeur de PrivateData pour déterminer quand le module a été publié.

Get-Stale -TestDate '2022-06-15'
Get-Stale -TestDate '2022-08-01'

This module will be stale in 16 days

WARNING: This module version was published more than 30 days ago.

PrivateData.PSData

La propriété PSData enfant définit une table de hachage de valeurs qui prend en charge des scénarios d’extension spécifiques.

Valeur
type d’entrée System.Collections.Hashtable
obligatoire PowerShell Gallery, Fonctionnalités expérimentales, modules Crescendo
valeur si la valeur n’est pas définie $null
accepte des caractères génériques Non

La propriété enfant PSData est utilisée pour les scénarios suivants :

  • PowerShell Gallery - Lorsque vous créez un manifeste de module à l’aide New-ModuleManifest de l’applet de commande préremplit la table de hachage PSData avec des clés d’espace réservé nécessaires lors de la publication du module sur le PowerShell Gallery. Pour plus d’informations sur les manifestes de module et la publication dans PowerShell Gallery, consultez les valeurs du manifeste de package qui ont un impact sur l’interface PowerShell Gallery utilisateur.
  • Fonctionnalités expérimentales : les métadonnées relatives à une fonctionnalité expérimentale sont conservées dans la propriété ExperimentalFeatures de PSData. La propriété ExperimentalFeatures est un tableau de tables de hachage contenant le nom et la description de la fonctionnalité. Pour plus d’informations, consultez Déclaration des fonctionnalités expérimentales dans les modules.
  • Modules Crescendo : lorsque vous exportez un manifeste Crescendo pour créer un module, Export-CrescendoModule ajoute la valeur CrescendoBuilt à la propriété PSData.Tags. Vous pouvez utiliser cette balise pour rechercher des modules dans ceux qui ont été créés à l’aide PowerShell Gallery de Crescendo. Pour plus d’informations, consultez Export-CrescendoModule.
  • La propriété PSData.ExternalModuleDependencies est un tableau de noms de modules qui sont des dépendances pour ce module. Cette propriété est informationnelle uniquement et n’affecte pas l’installation ou le chargement du module.

HelpInfoURI

Ce paramètre spécifie l’adresse Internet du fichier XML HelpInfo pour le module.

Valeur
type d’entrée System.String
obligatoire Non
valeur si la valeur n’est pas définie $null
accepte des caractères génériques Non

La valeur de ce paramètre doit être un URI (Uniform Resource Identifier) qui commence par http ou https.

Le fichier XML HelpInfo prend en charge la fonctionnalité d’aide pouvant être mise à jour qui a été introduite dans PowerShell 3.0. Il contient des informations sur l’emplacement des fichiers d’aide téléchargeables pour le module et les numéros de version des fichiers d’aide les plus récents pour chaque paramètre régional pris en charge.

Pour plus d’informations sur l’aide pouvant être mise à jour, consultez about_Updatable_Help. Pour plus d’informations sur le fichier XML HelpInfo, consultez Prise en charge de l’aide pouvant être mise à jour.

Par exemple, ce module prend en charge l’aide pouvant être mise à jour.

@{
    HelpInfoUri = 'http://https://go.microsoft.com/fwlink/?LinkID=603'
}

DefaultCommandPrefix

Ce paramètre spécifie un préfixe qui est ajouté aux noms de toutes les commandes du module lorsqu’elles sont importées dans une session. Les préfixes permettent d’empêcher les conflits de noms de commandes dans la session d’un utilisateur.

Valeur
type d’entrée System.String
obligatoire Non
valeur si la valeur n’est pas définie $null
accepte des caractères génériques Non

Les utilisateurs de module peuvent remplacer ce préfixe en spécifiant le paramètre préfixe de l’applet de commande Import-Module.

Ce paramètre a été introduit dans PowerShell 3.0.

Lorsque ce manifeste est importé, toutes les applets de commande importées à partir de ce module ont Example ajoutées au nom du nom. Par exemple, Get-Item est importé en tant que Get-ExampleItem.

@{
    DefaultCommandPrefix = 'Example'
}

Voir aussi

  • Last updated on