Como gravar um manifesto de módulo do PowerShell

2025-03-25

Depois de escrever o módulo do PowerShell, você pode adicionar um manifesto de módulo opcional que inclui informações sobre o módulo. Por exemplo, você pode descrever o autor, especificar arquivos no módulo (como módulos aninhados), executar scripts para personalizar o ambiente, o tipo de carga e os arquivos de formatação do usuário, definir os requisitos do sistema e limitar os membros exportados pelo módulo.

Criando um manifesto de módulo

Um manifesto do módulo é um arquivo de dados do PowerShell (.psd1) que descreve o conteúdo de um módulo e determina como um módulo é processado. O arquivo de manifesto é um arquivo de texto que contém uma tabela de hash de chaves e valores. Você vincula um arquivo de manifesto a um módulo nomeando o manifesto da mesma forma que o módulo e armazenando o manifesto no diretório raiz do módulo.

Para módulos simples que contêm apenas um único .psm1 ou assembly binário, um manifesto de módulo é opcional. Porém, a recomendação é usar um manifesto de módulo sempre que possível, pois eles são úteis para ajudá-lo a organizar seu código e manter as informações de controle de versão. Além disso, um manifesto de módulo é necessário para exportar um assembly instalado no de Cache de Assembly Global do. Um manifesto de módulo também é necessário para módulos que dão suporte ao recurso de Ajuda Atualizável. A Ajuda Atualizável usa a chave HelpInfoUri no manifesto do módulo para localizar o arquivo HelpInfo XML (Informações de Ajuda) que contém o local dos arquivos de ajuda atualizados para o módulo. Para obter mais informações sobre a Ajuda Atualizável, consulte suporte à ajuda atualizável.

Para criar e usar um manifesto de módulo

A melhor prática para criar um manifesto de módulo é usar o cmdlet New-ModuleManifest. Você pode usar parâmetros para especificar uma ou mais das chaves e valores padrão do manifesto. O único requisito é nomear o arquivo. New-ModuleManifest cria um manifesto de módulo com seus valores especificados e inclui as chaves restantes e seus valores padrão. Se você precisar criar vários módulos, use New-ModuleManifest para criar um modelo de manifesto de módulo que possa ser modificado para seus diferentes módulos. Para obter um exemplo de um manifesto de módulo padrão, consulte o manifesto do módulo Exemplo.

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

Uma alternativa é criar manualmente a tabela de hash do manifesto do módulo usando as informações mínimas necessárias, ModuleVersion. Salve o arquivo com o mesmo nome do módulo e use a extensão de arquivo .psd1. Em seguida, você pode editar o arquivo e adicionar as chaves e os valores apropriados.
Adicione quaisquer elementos adicionais desejados no arquivo de manifesto.

Para editar o arquivo de manifesto, use qualquer editor de texto que você preferir. Porém, o arquivo de manifesto é um arquivo de script que contém código, portanto, talvez você queira editá-lo em um ambiente de script ou desenvolvimento, como o Visual Studio Code. Todos os elementos de um arquivo de manifesto são opcionais, exceto o número ModuleVersion.

Para obter descrições das chaves e valores que você pode incluir em um manifesto de módulo, consulte os elementos de manifesto do módulo tabela. Para obter mais informações, consulte as descrições de parâmetro no cmdlet New-ModuleManifest.
Para resolver quaisquer cenários que possam não ser cobertos pelos elementos de manifesto do módulo base, você tem a opção de adicionar código adicional ao manifesto do módulo.

Para questões de segurança, o PowerShell executa apenas um pequeno subconjunto das operações disponíveis em um arquivo de manifesto do módulo. Em geral, você pode usar a instrução if, os operadores aritméticos e de comparação e os tipos de dados básicos do PowerShell.
Depois de criar o manifesto do módulo, você pode testá-lo para confirmar se todos os caminhos descritos no manifesto estão corretos. Para testar o manifesto do módulo, use Test-ModuleManifest.

Test-ModuleManifest myModuleName.psd1
Verifique se o manifesto do módulo está localizado no nível superior do diretório que contém o módulo.

Quando você copia o módulo em um sistema e o importa, o PowerShell usa o manifesto do módulo para importar o módulo.
Opcionalmente, você pode testar diretamente o manifesto do módulo com uma chamada para Import-Module, fornecendo o manifesto em si.

Import-Module .\myModuleName.psd1

Elementos de manifesto do módulo

A tabela a seguir descreve os elementos que você pode incluir em um manifesto de módulo.

Elemento	Padrão	Descrição
rootModule Tipo: `String`	`<empty string>`	Módulo de script ou arquivo de módulo binário associado a este manifesto. As versões anteriores do PowerShell chamaram esse elemento de ModuleToProcess. Os tipos possíveis para o módulo raiz podem estar vazios, o que cria um módulo Manifest, o nome de um módulo de script (`.psm1`) ou o nome de um módulo binário (`.exe` ou `.dll`). Colocar o nome de um manifesto de módulo (`.psd1`) ou um arquivo de script (`.ps1`) nesse elemento causa um erro. Exemplo: `RootModule = 'ScriptModule.psm1'`
ModuleVersion Tipo: `Version`	`'0.0.1'`	Número de versão deste módulo. Se um valor não for especificado, `New-ModuleManifest` usará o padrão. A cadeia de caracteres deve ser capaz de converter para o tipo `Version` por exemplo `#.#.#.#`. `Import-Module` carrega o primeiro módulo encontrado no $PSModulePath que corresponde ao nome e tem pelo menos um ModuleVersion, como o parâmetro MinimumVersion. Para importar uma versão específica, use o parâmetro RequiredVersion do cmdlet `Import-Module`. Exemplo: `ModuleVersion = '1.0'`
GUID Tipo: `GUID`	`'<GUID>'`	ID usada para identificar exclusivamente este módulo. Se um valor não for especificado, `New-ModuleManifest` gerará automaticamente o valor. No momento, não é possível importar um módulo GUID. Exemplo: `GUID = 'cfc45206-1e49-459d-a8ad-5b571ef94857'`
de autor do Tipo: `String`	`'<Current user>'`	Autor deste módulo. Se um valor não for especificado, `New-ModuleManifest` usará o usuário atual. Exemplo: `Author = 'AuthorNameHere'`
CompanyName Tipo: `String`	`'Unknown'`	Empresa ou fornecedor deste módulo. Se um valor não for especificado, `New-ModuleManifest` usará o padrão. Exemplo: `CompanyName = 'Fabrikam'`
de direitos autorais do Tipo: `String`	`'(c) <Author>. All rights reserved.'`	Declaração de direitos autorais para este módulo. Se um valor não for especificado, `New-ModuleManifest` usará o padrão com o usuário atual como o `<Author>`. Para especificar um autor, use o parâmetro autor do. Exemplo: `Copyright = '2019 AuthorName. All rights reserved.'`
Descrição Tipo: `String`	`<empty string>`	Descrição da funcionalidade fornecida por este módulo. Exemplo: `Description = 'This is the module's description.'`
do PowerShellVersion Tipo: `Version`	`<empty string>`	Versão mínima do mecanismo do PowerShell exigida por este módulo. Os valores válidos são 1.0, 2.0, 3.0, 4.0, 5.0, 5.1, 6.0, 6.1, 6.2, 7.0 e 7.1. Exemplo: `PowerShellVersion = '5.0'`
PowerShellHostName Tipo: `String`	`<empty string>`	Nome do host do PowerShell exigido por este módulo. Esse nome é fornecido pelo PowerShell. Para localizar o nome de um programa host, no programa, digite: `$Host.Name`. Exemplo: `PowerShellHostName = 'ConsoleHost'`
do PowerShellHostVersion Tipo: `Version`	`<empty string>`	Versão mínima do host do PowerShell exigida por este módulo. Exemplo: `PowerShellHostVersion = '2.0'`
DotNetFrameworkVersion Tipo: `Version`	`<empty string>`	Versão mínima do Microsoft .NET Framework exigida por este módulo. Esse pré-requisito é válido apenas para a edição do PowerShell Desktop, como o Windows PowerShell 5.1, e se aplica apenas a versões do .NET Framework inferiores à 4.5. Exemplo: `DotNetFrameworkVersion = '3.5'`
CLRVersion Tipo: `Version`	`<empty string>`	Versão mínima do CLR (Common Language Runtime) exigida por este módulo. Esse pré-requisito é válido apenas para a edição do PowerShell Desktop, como o Windows PowerShell 5.1, e se aplica apenas a versões do .NET Framework inferiores à 4.5. Exemplo: `CLRVersion = '3.5'`
ProcessorArchitecture Tipo: `ProcessorArchitecture`	`<empty string>`	Arquitetura do processador (None, X86, Amd64) exigida por este módulo. Os valores válidos são x86, AMD64, Arm, IA64, MSIL e None (desconhecido ou não especificado). Exemplo: `ProcessorArchitecture = 'x86'`
RequiredModules Tipo: `Object[]`	`@()`	Módulos que devem ser importados para o ambiente global antes de importar este módulo. Isso carrega todos os módulos listados, a menos que eles já tenham sido carregados. Por exemplo, alguns módulos já podem ser carregados por um módulo diferente. É possível especificar uma versão específica para carregar usando `RequiredVersion` em vez de `ModuleVersion`. Quando `ModuleVersion` for usado, ele carregará a versão mais recente disponível com um mínimo da versão especificada. Você pode combinar cadeias de caracteres e tabelas de hash no valor do parâmetro. Exemplo: `RequiredModules = @("MyModule", @{ModuleName="MyDependentModule"; ModuleVersion="2.0"; GUID="cfc45206-1e49-459d-a8ad-5b571ef94857"})` Exemplo: `RequiredModules = @("MyModule", @{ModuleName="MyDependentModule"; RequiredVersion="1.5"; GUID="cfc45206-1e49-459d-a8ad-5b571ef94857"})`
requiredAssemblies Tipo: `String[]`	`@()`	Assemblies que devem ser carregados antes de importar este módulo. Especifica os nomes de arquivo do assembly (`.dll`) exigidos pelo módulo. O PowerShell carrega os assemblies especificados antes de atualizar tipos ou formatos, importar módulos aninhados ou importar o arquivo de módulo especificado no valor da chave RootModule. Use esse parâmetro para listar todos os assemblies necessários para o módulo. Exemplo: `RequiredAssemblies = @("assembly1.dll", "assembly2.dll", "assembly3.dll")`
ScriptsToProcess Tipo: `String[]`	`@()`	Arquivos de script (`.ps1`) que são executados no estado de sessão do chamador quando o módulo é importado. Esse pode ser o estado da sessão global ou, para módulos aninhados, o estado da sessão de outro módulo. Você pode usar esses scripts para preparar um ambiente assim como você pode usar um script de logon. Esses scripts são executados antes que qualquer um dos módulos listados no manifesto seja carregado. Exemplo: `ScriptsToProcess = @("script1.ps1", "script2.ps1", "script3.ps1")`
TypesToProcess Tipo: `String[]`	`@()`	Digite arquivos (`.ps1xml`) a serem carregados ao importar este módulo. Exemplo: `TypesToProcess = @("type1.ps1xml", "type2.ps1xml", "type3.ps1xml")`
FormatsToProcess Tipo: `String[]`	`@()`	Formate arquivos (`.ps1xml`) a serem carregados ao importar este módulo. Exemplo: `FormatsToProcess = @("format1.ps1xml", "format2.ps1xml", "format3.ps1xml")`
nestedModules Tipo: `Object[]`	`@()`	Módulos a serem importados como módulos aninhados do módulo especificado em RootModule (alias:ModuleToProcess). Adicionar um nome de módulo a esse elemento é semelhante a chamar `Import-Module` de dentro de seu script ou código de assembly. A principal diferença usando um arquivo de manifesto é que é mais fácil ver o que você está carregando. E, se um módulo falhar ao carregar, você ainda não terá carregado o módulo real. Além de outros módulos, você também pode carregar arquivos de script (`.ps1`) aqui. Esses arquivos serão executados no contexto do módulo raiz. Isso é equivalente a não fornecer o script em seu módulo raiz. Exemplo: `NestedModules = @("script.ps1", @{ModuleName="MyModule"; ModuleVersion="1.0.0.0"; GUID="50cdb55f-5ab7-489f-9e94-4ec21ff51e59"})`
FunçõesParaExportar Tipo: `String[]`	`@()`	Especifica as funções a serem exportadas deste módulo, para melhor desempenho, não use curingas e não exclua a entrada, use uma matriz vazia se não houver funções para exportar. Por padrão, nenhuma função é exportada. Você pode usar essa chave para listar as funções exportadas pelo módulo. O módulo exporta as funções para o estado de sessão do chamador. O estado da sessão do chamador pode ser o estado da sessão global ou, para módulos aninhados, o estado da sessão de outro módulo. Ao encadear módulos aninhados, todas as funções exportadas por um módulo aninhado serão exportadas para o estado de sessão global, a menos que um módulo na cadeia restrinja a função usando a chave FunctionsToExport. Se o manifesto exportar aliases para as funções, essa chave poderá remover funções cujos aliases estão listados na chave AliasesToExport, mas essa chave não pode adicionar aliases de função à lista. Exemplo: `FunctionsToExport = @("function1", "function2", "function3")`
CmdletsToExport Tipo: `String[]`	`@()`	Especifica os cmdlets a serem exportados deste módulo, para melhor desempenho, não use curingas e não exclua a entrada, use uma matriz vazia se não houver cmdlets para exportar. Por padrão, nenhum cmdlet é exportado. Você pode usar essa chave para listar os cmdlets exportados pelo módulo. O estado da sessão do chamador pode ser o estado da sessão global ou, para módulos aninhados, o estado da sessão de outro módulo. Quando você estiver encadeando módulos aninhados, todos os cmdlets exportados por um módulo aninhado serão exportados para o estado de sessão global, a menos que um módulo na cadeia restrinja o cmdlet usando a chave cmdletsToExport do. Se o manifesto exportar aliases para os cmdlets, essa chave poderá remover cmdlets cujos aliases estão listados no chave de AliasesToExport, mas essa chave não pode adicionar aliases de cmdlet à lista. Exemplo: `CmdletsToExport = @("Get-MyCmdlet", "Set-MyCmdlet", "Test-MyCmdlet")`
VariáveisParaExportar Tipo: `String[]`	`'*'`	Especifica as variáveis que o módulo exporta para o estado de sessão do chamador. Caracteres curinga são permitidos. Por padrão, todas as variáveis (`''`) são exportadas. Você pode usar essa chave para restringir as variáveis exportadas pelo módulo. O estado da sessão do chamador pode ser o estado da sessão global ou, para módulos aninhados, o estado da sessão de outro módulo. Quando você estiver encadeando módulos aninhados, todas as variáveis exportadas por um módulo aninhado serão exportadas para o estado da sessão global, a menos que um módulo na cadeia restrinja a variável usando a chave VariablesToExport*. Se o manifesto também exportar aliases para as variáveis, essa chave poderá remover variáveis cujos aliases estão listados na chave AliasesToExport, mas essa chave não pode adicionar aliases variáveis à lista. Exemplo: `VariablesToExport = @('$MyVariable1', '$MyVariable2', '$MyVariable3')`
AliasesToExport Tipo: `String[]`	`@()`	Especifica os aliases a serem exportados deste módulo, para melhor desempenho, não use curingas e não exclua a entrada, use uma matriz vazia se não houver aliases para exportar. Por padrão, nenhum aliases é exportado. Você pode usar essa chave para listar os aliases exportados pelo módulo. O módulo exporta os aliases para o estado de sessão do chamador. O estado da sessão do chamador pode ser o estado da sessão global ou, para módulos aninhados, o estado da sessão de outro módulo. Quando você estiver encadeando módulos aninhados, todos os aliases exportados por um módulo aninhado serão exportados para o estado de sessão global, a menos que um módulo na cadeia restrinja o alias usando a chave AliasesToExport. Exemplo: `AliasesToExport = @("MyAlias1", "MyAlias2", "MyAlias3")`
DscResourcesToExport Tipo: `String[]`	`@()`	Especifica os recursos de DSC a serem exportados deste módulo. Caracteres curinga são permitidos. Exemplo: `DscResourcesToExport = @("DscResource1", "DscResource2", "DscResource3")`
ModuleList Tipo: `Object[]`	`@()`	Especifica todos os módulos que são empacotados com este módulo. Esses módulos podem ser inseridos por nome, usando uma cadeia de caracteres separada por vírgulas ou como uma tabela de hash com moduleName e chaves de GUID. A tabela de hash também pode ter uma chave de ModuleVersion opcional. A chave ModuleList foi projetada para atuar como um inventário de módulo. Esses módulos não são processados automaticamente. Exemplo: `ModuleList = @("SampleModule", "MyModule", @{ModuleName="MyModule"; ModuleVersion="1.0.0.0"; GUID="50cdb55f-5ab7-489f-9e94-4ec21ff51e59"})`
filelist Tipo: `String[]`	`@()`	Lista de todos os arquivos empacotados com este módulo. Assim como acontece com ModuleList, filelist é uma lista de inventário e não é processado de outra forma. Exemplo: `FileList = @("File1", "File2", "File3")`
PrivateData Tipo: `Object`	`@{...}`	Especifica todos os dados privados que precisam ser passados para o módulo raiz especificado pela chave RootModule (alias: ModuleToProcess). PrivateData é uma tabela de hash que compreende vários elementos: Tags, LicenseUri, ProjectURI, IconUri, ReleaseNotes, de Pré-lançamento, RequireLicenseAcceptancee ExternalModuleDependencies.
Marcações Tipo: `String[]`	`@()`	As marcas ajudam na descoberta de módulos em galerias online. Exemplo: `Tags = "PackageManagement", "PowerShell", "Manifest"`
LicenseUri Tipo: `Uri`	`<empty string>`	Uma URL para a licença deste módulo. Exemplo: `LicenseUri = 'https://www.contoso.com/license'`
do ProjectUri Tipo: `Uri`	`<empty string>`	Uma URL para o site principal deste projeto. Exemplo: `ProjectUri = 'https://www.contoso.com/project'`
IconUri Tipo: `Uri`	`<empty string>`	Uma URL para um ícone que representa este módulo. Exemplo: `IconUri = 'https://www.contoso.com/icons/icon.png'`
ReleaseNotes Tipo: `String`	`<empty string>`	Especifica as notas de versão do módulo. Exemplo: `ReleaseNotes = 'The release notes provide information about the module.`
pré-lançamento Tipo: `String`	`<empty string>`	Esse parâmetro foi adicionado ao PowerShellGet 1.6.6. Um preRelease cadeia de caracteres que identifica o módulo como uma versão de pré-lançamento em galerias online. Exemplo: `PreRelease = 'alpha'`
RequireLicenseAcceptance Tipo: `Boolean`	`$false`	Esse parâmetro foi adicionado ao PowerShellGet 1.5. Sinalizar para indicar se o módulo requer aceitação explícita do usuário para instalar, atualizar ou salvar. Exemplo: `RequireLicenseAcceptance = $false`
ExternalModuleDependencies Tipo: `String[]`	`@()`	Esse parâmetro foi adicionado no PowerShellGet v2. Uma lista de módulos externos dos quais este módulo depende. Exemplo: `ExternalModuleDependencies = @("ExtModule1", "ExtModule2", "ExtModule3")`
HelpInfoURI Tipo: `String`	`<empty string>`	URI helpInfo deste módulo. Exemplo: `HelpInfoURI = 'https://www.contoso.com/help'`
DefaultCommandPrefix Tipo: `String`	`<empty string>`	Prefixo padrão para comandos exportados deste módulo. Substitua o prefixo padrão usando `Import-Module -Prefix`. Exemplo: `DefaultCommandPrefix = 'My'`

Manifesto do módulo de exemplo

O manifesto do módulo de exemplo a seguir foi criado com New-ModuleManifest no PowerShell 7 e contém as chaves e os valores padrão.

#
# 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 = $false

        # 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 = ''

}

Compartilhar via

Como gravar um manifesto de módulo do PowerShell

Criando um manifesto de módulo

Para criar e usar um manifesto de módulo

Elementos de manifesto do módulo

Manifesto do módulo de exemplo

Consulte também

Recursos adicionais