Een PowerShell-modulemanifest schrijven

Nadat u de PowerShell-module hebt geschreven, kunt u een optioneel modulemanifest toevoegen dat informatie over de module bevat. U kunt bijvoorbeeld de auteur beschrijven, bestanden opgeven in de module (zoals geneste modules), scripts uitvoeren om de omgeving van de gebruiker aan te passen, bestanden van het type laden en opmaken, systeemvereisten definiëren en de leden beperken die de module exporteert.

Een modulemanifest maken

Een modulemanifest is een PowerShell-gegevensbestand () dat de inhoud van een module beschrijft en bepaalt .psd1 hoe een module wordt verwerkt. Het manifestbestand is een tekstbestand dat een hashtabel met sleutels en waarden bevat. U koppelt een manifestbestand aan een module door het manifest dezelfde naam te geven als de module en het manifest op te slaan in de hoofdmap van de module.

Voor eenvoudige modules die slechts één of binaire .psm1 assembly bevatten, is een modulemanifest optioneel. De aanbeveling is echter om waar mogelijk een modulemanifest te gebruiken, omdat deze handig zijn om uw code te organiseren en versiegegevens te onderhouden. En een modulemanifest is vereist voor het exporteren van een assembly die is geïnstalleerd in de Global Assembly Cache. Er is ook een modulemanifest vereist voor modules die ondersteuning bieden voor de Help-functie Updatable. Help die kan worden bijgewerkt, gebruikt de sleutel HelpInfoUri in het modulemanifest om het Help-informatiebestand (HelpInfo XML) te zoeken dat de locatie bevat van de bijgewerkte Help-bestanden voor de module. Zie Ondersteunende Help die kan worden bijwerkbaar voor meer informatie over help die kan worden bijwerkbaar.

Een modulemanifest maken en gebruiken

  1. De best practice een modulemanifest te maken, is het gebruik van de cmdlet New-ModuleManifest. U kunt parameters gebruiken om een of meer van de standaardsleutels en -waarden van het manifest op te geven. De enige vereiste is om het bestand een naam te geven. New-ModuleManifest maakt een modulemanifest met de opgegeven waarden en bevat de resterende sleutels en de standaardwaarden. Als u meerdere modules wilt maken, gebruikt u om een modulemanifestsjabloon te New-ModuleManifest maken die kan worden gewijzigd voor uw verschillende modules. Zie voorbeeldmodulemanifest voor een voorbeeld van een standaardmodulemanifest.

    New-ModuleManifest -Path C:\myModuleName.psd1 -ModuleVersion "2.0" -Author "YourNameHere"

    Een alternatief is om handmatig de hashtabel van het modulemanifest te maken met behulp van de minimaal vereiste informatie, moduleversie. U kunt het bestand opslaan met dezelfde naam als uw module en de .psd1 bestandsextensie gebruiken. Vervolgens kunt u het bestand bewerken en de juiste sleutels en waarden toevoegen.

  2. Voeg eventuele extra elementen toe aan het manifestbestand.

    Als u het manifestbestand wilt bewerken, gebruikt u een teksteditor van uw voorkeur. Maar het manifestbestand is een scriptbestand dat code bevat, dus u kunt het bewerken in een script- of ontwikkelomgeving, zoals Visual Studio Code. Alle elementen van een manifestbestand zijn optioneel, met uitzondering van het ModuleVersion-nummer.

    Zie de tabel Modulemanifestelementen voor beschrijvingen van de sleutels en waarden die u kunt opnemen in een modulemanifest. Zie de beschrijvingen van parameters in de cmdlet New-ModuleManifest voor meer informatie.

  3. Als u scenario's wilt aanpakken die mogelijk niet worden gedekt door de manifestelementen van de basismodule, hebt u de mogelijkheid om extra code toe te voegen aan uw modulemanifest.

    Voor beveiligingsproblemen voert PowerShell slechts een kleine subset van de beschikbare bewerkingen uit in een modulemanifestbestand. Over het algemeen kunt u de if instructie, rekenkundige en vergelijkingsoperators en de PowerShell-basisgegevenstypen gebruiken.

  4. Nadat u het modulemanifest hebt gemaakt, kunt u het testen om te controleren of de paden die in het manifest worden beschreven, juist zijn. Gebruik Test-ModuleManifestom uw modulemanifest te testen.

    Test-ModuleManifest myModuleName.psd1

  5. Zorg ervoor dat uw modulemanifest zich bevindt op het hoogste niveau van de map die uw module bevat.

    Wanneer u de module naar een systeem kopieert en importeert, gebruikt PowerShell het modulemanifest om uw module te importeren.

  6. Desgewenst kunt u uw modulemanifest rechtstreeks testen met een aanroep naar Import-Module door het manifest zelf een dot-sourcing te laten uitvoeren.

    Import-Module .\myModuleName.psd1

Modulemanifestelementen

In de volgende tabel worden de elementen beschreven die u in een modulemanifest kunt opnemen.

Element Standaard Beschrijving
RootModule
Type: String
<empty string> Scriptmodule of binair modulebestand dat aan dit manifest is gekoppeld. Vorige versies van PowerShell hebben dit element moduleToProcess genoemd.
Mogelijke typen voor de hoofdmodule kunnen leeg zijn, waardoor een Manifest-module, de naam van een scriptmodule ( ) of de naam van een .psm1 binaire module ( of ) wordt .exe .dll gemaakt. Het plaatsen van de naam van een modulemanifest ( ) of .psd1 een scriptbestand ( .ps1 ) in dit element veroorzaakt een fout.
Voorbeeld: RootModule = 'ScriptModule.psm1'
ModuleVersion
Type: Version
'0.0.1' Versienummer van deze module. Als er geen waarde is opgegeven, wordt New-ModuleManifest de standaardwaarde gebruikt. De tekenreeks moet kunnen converteren naar het type Version bijvoorbeeld #.#.#.# . Import-Modulelaadt de eerste module die wordt gevonden op de $PSModulePath die overeenkomt met de naam, en heeft ten minste een hoge ModuleVersion als de parameter MinimumVersion. Als u een specifieke versie wilt importeren, gebruikt u Import-Module de parameter RequiredVersion van de cmdlet.
Voorbeeld: ModuleVersion = '1.0'
GUID
Type: GUID
'<GUID>' De id die wordt gebruikt om deze module uniek te identificeren. Als er geen waarde is opgegeven, wordt New-ModuleManifest de waarde automatisch gegenereerd. U kunt momenteel geen module importeren op GUID.
Voorbeeld: GUID = 'cfc45206-1e49-459d-a8ad-5b571ef94857'
Auteur
Type: String
'<Current user>' Auteur van deze module. Als er geen waarde is opgegeven, gebruikt New-ModuleManifest de huidige gebruiker.
Voorbeeld: Author = 'AuthorNameHere'
CompanyName
Type: String
'Unknown' Bedrijf of leverancier van deze module. Als er geen waarde is opgegeven, wordt New-ModuleManifest de standaardwaarde gebruikt.
Voorbeeld: CompanyName = 'Fabrikam'
Copyright
Type: String
'(c) <Author>. All rights reserved.' Copyrightverklaring voor deze module. Als er geen waarde is opgegeven, gebruikt New-ModuleManifest de standaardwaarde met de huidige gebruiker als de <Author> . Als u een auteur wilt opgeven, gebruikt u de parameter Auteur.
Voorbeeld: Copyright = '2019 AuthorName. All rights reserved.'
Beschrijving
Type: String
<empty string> Beschrijving van de functionaliteit van deze module.
Voorbeeld: Description = 'This is the module's description.'
PowerShellVersion
Type: Version
<empty string> Minimale versie van de PowerShell-engine die vereist is voor deze module. Geldige waarden zijn 1.0, 2.0, 3.0, 4.0, 5.0, 5.1, 6.0, 6.1, 6.2, 7.0 en 7.1.
Voorbeeld: PowerShellVersion = '5.0'
PowerShellHostName
Type: String
<empty string> Naam van de PowerShell-host die vereist is voor deze module. Deze naam wordt geleverd door PowerShell. Als u de naam van een hostprogramma wilt vinden, typt u in het programma: $host.name .
Voorbeeld: PowerShellHostName = 'ConsoleHost'
PowerShellHostVersion
Type: Version
<empty string> Minimale versie van de PowerShell-host die is vereist voor deze module.
Voorbeeld: PowerShellHostVersion = '2.0'
DotNetFrameworkVersion
Type: Version
<empty string> Minimale versie van Microsoft .NET Framework vereist voor deze module. Deze vereiste is alleen geldig voor de PowerShell Desktop-editie, zoals PowerShell 5.1.
Voorbeeld: DotNetFrameworkVersion = '3.5'
CLRVersion
Type: Version
<empty string> Minimale versie van common language runtime (CLR) die is vereist voor deze module. Deze vereiste is alleen geldig voor de PowerShell Desktop-editie, zoals PowerShell 5.1.
Voorbeeld: CLRVersion = '3.5'
ProcessorArchitecture
Type: ProcessorArchitecture
<empty string> Processorarchitectuur (Geen, X86, Amd64) die vereist is voor deze module. Geldige waarden zijn x86, AMD64, Arm, IA64, MSIL en None (onbekend of niet gespecificeerd).
Voorbeeld: ProcessorArchitecture = 'x86'
RequiredModules
Type: Object[]
@() Modules die moeten worden geïmporteerd in de globale omgeving voordat u deze module importeert. Hiermee worden alle vermelde modules geladen, tenzij ze al zijn geladen. Sommige modules zijn bijvoorbeeld mogelijk al geladen door een andere module. Het is mogelijk om een specifieke versie op te geven die moet worden geladen met RequiredVersion in plaats van ModuleVersion . Wanneer ModuleVersion wordt gebruikt, wordt de nieuwste versie geladen die beschikbaar is met een minimum van de versie die is opgegeven. U kunt tekenreeksen en hashtabellen combineren in de parameterwaarde.
Voorbeeld: RequiredModules = @("MyModule", @{ModuleName="MyDependentModule"; ModuleVersion="2.0"; GUID="cfc45206-1e49-459d-a8ad-5b571ef94857"})
Voorbeeld: RequiredModules = @("MyModule", @{ModuleName="MyDependentModule"; RequiredVersion="1.5"; GUID="cfc45206-1e49-459d-a8ad-5b571ef94857"})
RequiredAssemblies
Type: String[]
@() Assemblies die moeten worden geladen voordat u deze module importeert. Hiermee geeft u de assembly ( .dll ) bestandsnamen die de module vereist.
PowerShell laadt de opgegeven assemblies voordat u typen of indelingen bij werkt, geneste modules importeert of het modulebestand importeert dat is opgegeven in de waarde van de RootModule-sleutel. Gebruik deze parameter om alle assemblies weer te geven die de module nodig heeft.
Voorbeeld: RequiredAssemblies = @("assembly1.dll", "assembly2.dll", "assembly3.dll")
ScriptsToProcess
Type: String[]
@() Script () bestanden die worden uitgevoerd in de sessietoestand van de .ps1 aanroeper wanneer de module wordt geïmporteerd. Dit kan de algemene sessietoestand zijn of, voor geneste modules, de sessietoestand van een andere module. U kunt deze scripts gebruiken om een omgeving voor te bereiden, net zoals u een aanmeldscript zou kunnen gebruiken.
Deze scripts worden uitgevoerd voordat een van de modules die in het manifest worden vermeld, wordt geladen.
Voorbeeld: ScriptsToProcess = @("script1.ps1", "script2.ps1", "script3.ps1")
TypesToProcess
Type: String[]
@() Typ bestanden ( .ps1xml ) die moeten worden geladen bij het importeren van deze module.
Voorbeeld: TypesToProcess = @("type1.ps1xml", "type2.ps1xml", "type3.ps1xml")
FormatsToProcess
Type: String[]
@() Maak bestanden op ( .ps1xml ) die moeten worden geladen bij het importeren van deze module.
Voorbeeld: FormatsToProcess = @("format1.ps1xml", "format2.ps1xml", "format3.ps1xml")
NestedModules
Type: Object[]
@() Modules die moeten worden geïmporteerd als geneste modules van de module die is opgegeven in RootModule (alias:ModuleToProcess).
Het toevoegen van een modulenaam aan dit element is vergelijkbaar met het Import-Module aanroepen vanuit uw script of assemblycode. Het belangrijkste verschil met behulp van een manifestbestand is dat u gemakkelijker kunt zien wat u laadt. En als een module niet kan worden geladen, hebt u de werkelijke module nog niet geladen.
Naast andere modules kunt u hier ook scriptbestanden .ps1 () laden. Deze bestanden worden uitgevoerd in de context van de hoofdmodule. Dit is gelijk aan dot sourcing van het script in uw hoofdmodule.
Voorbeeld: NestedModules = @("script.ps1", @{ModuleName="MyModule"; ModuleVersion="1.0.0.0"; GUID="50cdb55f-5ab7-489f-9e94-4ec21ff51e59"})
FunctionsToExport
Type: String[]
@() Hiermee geeft u de functies te exporteren uit deze module, voor de beste prestaties, geen jokertekens gebruiken en verwijder de vermelding niet, gebruik een lege matrix als er geen functies om te exporteren. Standaard worden er geen functies geëxporteerd. U kunt deze sleutel gebruiken om de functies weer te bieden die door de module worden geëxporteerd.
De module exporteert de functies naar de sessietoestand van de aanroeper. De sessietoestand van de aanroeper kan de globale sessietoestand zijn of, voor geneste modules, de sessietoestand van een andere module. Bij het ketenen van geneste modules worden alle functies die worden geëxporteerd door een geneste module geëxporteerd naar de algemene sessietoestand, tenzij een module in de keten de functie beperkt met behulp van de sleutel FunctionsToExport.
Als het manifest aliassen voor de functies exporteert, kan deze sleutel functies verwijderen waarvan de aliassen worden vermeld in de sleutel AliassenToExport, maar deze sleutel kan geen functiealiassen toevoegen aan de lijst.
Voorbeeld: FunctionsToExport = @("function1", "function2", "function3")
CmdletsToExport
Type: String[]
@() Hiermee geeft u de cmdlets voor het exporteren van deze module, voor de beste prestaties, geen jokertekens gebruiken en niet verwijderen van de vermelding, gebruik een lege matrix als er geen cmdlets om te exporteren. Standaard worden er geen cmdlets geëxporteerd. U kunt deze sleutel gebruiken om een lijst weer te maken van de cmdlets die door de module worden geëxporteerd.
De sessietoestand van de aanroeper kan de globale sessietoestand zijn of, voor geneste modules, de sessietoestand van een andere module. Wanneer u geneste modules aan elkaar vastketent, worden alle cmdlets die door een geneste module worden geëxporteerd, geëxporteerd naar de globale sessietoestand, tenzij een module in de keten de cmdlet beperkt met behulp van de sleutel CmdletsToExport.
Als het manifest aliassen voor de cmdlets exporteert, kan deze sleutel cmdlets verwijderen waarvan de aliassen worden vermeld in de sleutel AliassenToExport, maar deze sleutel kan geen cmdlet-aliassen toevoegen aan de lijst.
Voorbeeld: CmdletsToExport = @("Get-MyCmdlet", "Set-MyCmdlet", "Test-MyCmdlet")
VariablesToExport
Type: String[]
'*' Hiermee geeft u de variabelen op die de module exporteert naar de sessietoestand van de aanroeper. Jokertekens zijn toegestaan. Standaard worden alle variabelen ( '*' ) geëxporteerd. U kunt deze sleutel gebruiken om de variabelen te beperken die door de module worden geëxporteerd.
De sessietoestand van de aanroeper kan de globale sessietoestand zijn of, voor geneste modules, de sessietoestand van een andere module. Wanneer u geneste modules ketent, worden alle variabelen die door een geneste module worden geëxporteerd, geëxporteerd naar de globale sessietoestand, tenzij een module in de keten de variabele beperkt met behulp van de sleutel VariablesToExport.
Als het manifest ook aliassen voor de variabelen exporteert, kan deze sleutel variabelen verwijderen waarvan de aliassen worden vermeld in de sleutel AliassenToExport, maar deze sleutel kan geen variabele aliassen toevoegen aan de lijst.
Voorbeeld: VariablesToExport = @('$MyVariable1', '$MyVariable2', '$MyVariable3')
AliassenToExport
Type: String[]
@() Hiermee geeft u de aliassen voor het exporteren van deze module, voor de beste prestaties, geen jokertekens gebruiken en niet verwijderen van de vermelding, gebruik een lege matrix als er geen aliassen om te exporteren. Standaard worden er geen aliassen geëxporteerd. U kunt deze sleutel gebruiken om een lijst weer te maken van de aliassen die door de module worden geëxporteerd.
De module exporteert de aliassen naar de sessietoestand van de aanroeper. De sessietoestand van de aanroeper kan de globale sessietoestand zijn of, voor geneste modules, de sessietoestand van een andere module. Wanneer u geneste modules aan elkaar vastketent, worden alle aliassen die worden geëxporteerd door een geneste module uiteindelijk geëxporteerd naar de globale sessietoestand, tenzij een module in de keten de alias beperkt met behulp van de sleutel AliassenToExport.
Voorbeeld: AliasesToExport = @("MyAlias1", "MyAlias2", "MyAlias3")
DscResourcesToExport
Type: String[]
@() Hiermee geeft u DSC-resources op die vanuit deze module moeten worden geëxporteerd. Jokertekens zijn toegestaan.
Voorbeeld: DscResourcesToExport = @("DscResource1", "DscResource2", "DscResource3")
ModuleList
Type: Object[]
@() Hiermee geeft u alle modules op die zijn verpakt met deze module. Deze modules kunnen worden ingevoerd op naam, met behulp van een door komma's gescheiden tekenreeks of als een hash-tabel met ModuleName- en GUID-sleutels. De hash-tabel kan ook een optionele ModuleVersion-sleutel hebben. De ModuleList-sleutel is ontworpen om te fungeren als een module-inventaris. Deze modules worden niet automatisch verwerkt.
Voorbeeld: ModuleList = @("SampleModule", "MyModule", @{ModuleName="MyModule"; ModuleVersion="1.0.0.0"; GUID="50cdb55f-5ab7-489f-9e94-4ec21ff51e59"})
Bestandenoverzicht
Type: String[]
@() Lijst met alle bestanden die zijn verpakt met deze module. Net als bij ModuleList is FileList een inventarislijst en wordt deze niet anders verwerkt.
Voorbeeld: FileList = @("File1", "File2", "File3")
PrivateData
Type: Object
@{...} Hiermee geeft u persoonlijke gegevens op die moeten worden doorgegeven aan de hoofdmodule die is opgegeven door de RootModule-sleutel (alias: ModuleToProcess). PrivateData is een hashtabel die uit verschillende elementen bestaat: Tags, LicenseUri, ProjectURI, IconUri, ReleaseNotes, Prerelease, RequireLicenseAcceptance en ExternalModuleDependencies.
Tags
Type: String[]
@() Tags helpen bij moduledetectie in onlinegalerieën.
Voorbeeld: Tags = "PackageManagement", "PowerShell", "Manifest"
LicenseUri
Type: Uri
<empty string> Een URL naar de licentie voor deze module.
Voorbeeld: LicenseUri = 'https://www.contoso.com/license'
ProjectUri
Type: Uri
<empty string> Een URL naar de hoofdwebsite voor dit project.
Voorbeeld: ProjectUri = 'https://www.contoso.com/project'
IconUri
Type: Uri
<empty string> Een URL naar een pictogram dat deze module vertegenwoordigt.
Voorbeeld: IconUri = 'https://www.contoso.com/icons/icon.png'
ReleaseNotes
Type: String
<empty string> Hiermee geeft u de opmerkingen bij de release van de module op.
Voorbeeld: ReleaseNotes = 'The release notes provide information about the module.
Voorlopige
Type: String
<empty string> Deze parameter is toegevoegd in PowerShellGet 1.6.6. Een preRelease-tekenreeks die de module identificeert als een voorlopige versie in onlinegalerieën.
Voorbeeld: PreRelease = 'This module is a prerelease version.
RequireLicenseAcceptance
Type: Boolean
$true Deze parameter is toegevoegd in PowerShellGet 1.5. Vlag om aan te geven of de module expliciete gebruikersacceptatie vereist voor installeren, bijwerken of opslaan.
Voorbeeld: RequireLicenseAcceptance = $false
ExternalModuleDependencies
Type: String[]
@() Deze parameter is toegevoegd in PowerShellGet v2. Een lijst met externe modules van waar deze module afhankelijk van is.
Voorbeeld: ExternalModuleDependencies = @("ExtModule1", "ExtModule2", "ExtModule3")
HelpInfoURI
Type: String
<empty string> HelpInfo-URI van deze module.
Voorbeeld: HelpInfoURI = 'https://www.contoso.com/help'
DefaultCommandPrefix
Type: String
<empty string> Standaardvoorvoegsel voor opdrachten die uit deze module zijn geëxporteerd. Overschrijven het standaardvoorvoegsel met Import-Module -Prefix behulp van .
Voorbeeld: DefaultCommandPrefix = 'My'

Voorbeeldmodulemanifest

Het volgende voorbeeldmodulemanifest is gemaakt New-ModuleManifest met in PowerShell 7 en bevat de standaardsleutels en -waarden.

#
# Module manifest for module 'SampleModuleManifest'
#
# Generated by: User01
#
# Generated on: 10/15/2019
#

@{

# Script module or binary module file associated with this manifest.
# RootModule = ''

# Version number of this module.
ModuleVersion = '0.0.1'

# Supported PSEditions
# CompatiblePSEditions = @()

# ID used to uniquely identify this module
GUID = 'b632e90c-df3d-4340-9f6c-3b832646bf87'

# Author of this module
Author = 'User01'

# Company or vendor of this module
CompanyName = 'Unknown'

# Copyright statement for this module
Copyright = '(c) User01. All rights reserved.'

# Description of the functionality provided by this module
# Description = ''

# Minimum version of the PowerShell engine required by this module
# PowerShellVersion = ''

# Name of the PowerShell host required by this module
# PowerShellHostName = ''

# Minimum version of the PowerShell host required by this module
# PowerShellHostVersion = ''

# Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
# DotNetFrameworkVersion = ''

# Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
# CLRVersion = ''

# Processor architecture (None, X86, Amd64) required by this module
# ProcessorArchitecture = ''

# Modules that must be imported into the global environment prior to importing this module
# RequiredModules = @()

# Assemblies that must be loaded prior to importing this module
# RequiredAssemblies = @()

# Script files (.ps1) that are run in the caller's environment prior to importing this module.
# ScriptsToProcess = @()

# Type files (.ps1xml) to be loaded when importing this module
# TypesToProcess = @()

# Format files (.ps1xml) to be loaded when importing this module
# FormatsToProcess = @()

# Modules to import as nested modules of the module specified in RootModule/ModuleToProcess
# NestedModules = @()

# Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export.
FunctionsToExport = @()

# Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export.
CmdletsToExport = @()

# Variables to export from this module
VariablesToExport = '*'

# Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export.
AliasesToExport = @()

# DSC resources to export from this module
# DscResourcesToExport = @()

# List of all modules packaged with this module
# ModuleList = @()

# List of all files packaged with this module
# FileList = @()

# Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
PrivateData = @{

    PSData = @{

        # Tags applied to this module. These help with module discovery in online galleries.
        # Tags = @()

        # A URL to the license for this module.
        # LicenseUri = ''

        # A URL to the main website for this project.
        # ProjectUri = ''

        # A URL to an icon representing this module.
        # IconUri = ''

        # ReleaseNotes of this module
        # ReleaseNotes = ''

        # Prerelease string of this module
        # Prerelease = ''

        # Flag to indicate whether the module requires explicit user acceptance for install/update/save
        RequireLicenseAcceptance = $true

        # External dependent modules of this module
        # ExternalModuleDependencies = @()

    } # End of PSData hashtable

} # End of PrivateData hashtable

# HelpInfo URI of this module
# HelpInfoURI = ''

# Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix.
# DefaultCommandPrefix = ''

}

Zie ook

about_Comparison_Operators

about_If

Global Assembly Cache

Import-Module

New-ModuleManifest

Test-ModuleManifest

Update-ModuleManifest

Een Windows PowerShell-module schrijven