Compartilhar via

about_Module_Manifests

  • Artigo

Descrição breve

Descreve as configurações e práticas para gravar arquivos de manifesto do módulo.

Descrição longa

Um manifesto de módulo é um arquivo de dados do PowerShell (.psd1) que contém uma tabela de hash. Os pares chaves-valor na tabela de hash descrevem o conteúdo e os atributos do módulo, definem os pré-requisitos e controlam como os componentes são processados.

Os manifestos não são necessários para carregar um módulo, mas são necessários para publicar um módulo na Galeria do PowerShell. Os manifestos também permitem separar a implementação do módulo de como ele é carregado. Com um manifesto, você pode definir requisitos, compatibilidade, ordem de carregamento e muito mais.

Quando você usa New-ModuleManifest sem especificar nenhum parâmetro para as configurações do manifesto, ele grava um arquivo de manifesto mínimo. O trecho abaixo mostra essa saída padrão, recortada de comentários e espaçamento por brevidade:

@{
# 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 = ''
    } # End of PSData hashtable
} # End of PrivateData hashtable
# HelpInfoURI = ''
# DefaultCommandPrefix = ''
}

Você pode usar Test-ModuleManifest para validar um manifesto de módulo antes de publicar seu módulo. Test-ModuleManifest Retorna um erro se o manifesto for inválido ou se o módulo não puder ser importado para a sessão atual porque a sessão não atende aos requisitos definidos no manifesto.

Usando código de script em um manifesto de módulo

Os valores atribuídos às configurações no arquivo de manifesto podem ser expressões avaliadas pelo PowerShell. Isso permite que você construa caminhos e atribua valores condicionalmente com base em variáveis.

Quando você importa um módulo usando Import-Moduleo , o manifesto é avaliado no Restricted modo de idioma. Restricted O modo limita os comandos e variáveis que podem ser usados.

Comandos permitidos

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

Variáveis permitidas

  • $PSScriptRoot
  • $PSEdition
  • $EnabledExperimentalFeatures
  • Quaisquer variáveis de ambiente, como $ENV:TEMP

Para obter mais informações, consulte about_Language_Modes.

Configurações de manifesto

As seções a seguir detalham cada configuração disponível em um manifesto de módulo e como você pode usá-las. Eles começam com uma sinopse do cenário e são seguidos por uma matriz que lista:

  • Tipo de entrada: o tipo de objeto que você pode especificar para essa configuração no manifesto.
  • Obrigatório: Se esse valor for Yes, a configuração será necessária para importar o módulo e publicá-lo na Galeria do PowerShell. Se for No, não é necessário para nenhum dos dois. Se for PowerShell Gallery, ele só será necessário para publicação na Galeria do PowerShell.
  • Valor se não definido: o valor que essa configuração tem quando importada e não definida explicitamente.
  • Aceita curingas: se essa configuração pode ter um valor curinga ou não.

Módulo raiz

Essa configuração especifica o arquivo primário ou raiz do módulo. Quando o módulo é importado, os membros exportados pelo arquivo de módulo raiz são importados para o estado de sessão do chamador.

Valor
Tipo de Entrada System.String
Obrigatório Não
Valor se não definido $null
Aceita curingas Não

O valor deve ser o caminho para uma das seguintes opções:

  • um script (.ps1)
  • um módulo de script (.psm1)
  • um manifesto de módulo (.psd1)
  • uma montagem (.dll)
  • um arquivo XML de definição de cmdlet (.cdxml)
  • um fluxo de trabalho do Windows PowerShell 5.1 (.xaml)

O caminho deve ser relativo ao manifesto do módulo.

Se um manifesto de módulo não tiver nenhum arquivo raiz foi designado na chave RootModule , o manifesto se tornará o arquivo primário do módulo e o módulo se tornará um módulo de manifesto (ModuleType = Manifest). Quando RootModule é definido, o tipo do módulo é determinado a partir da extensão de arquivo usada:

  • a .ps1 ou .psm1 arquivo torna o módulo do tipo Script
  • um .psd1 arquivo torna o módulo do tipo Manifesto
  • um .dll arquivo torna o módulo do tipo Binário
  • um .cdxml arquivo torna o módulo do tipo CIM
  • um .xaml arquivo torna o módulo do tipo Workflow

Por padrão, todos os membros do módulo no RootModule são exportados.

Dica

A velocidade de carregamento do módulo difere entre os tipos de módulo Binary, Script e CIM . Para obter mais informações, consulte Considerações sobre a criação de módulos do PowerShell

Por exemplo, ModuleType deste módulo é Manifest. Os únicos membros do módulo que este módulo pode exportar são aqueles definidos nos módulos especificados com a configuração NestedModules .

@{
    RootModule = ''
}

Observação

Essa configuração também pode ser especificada em manifestos de módulo como ModuleToProcess. Embora esse nome para essa configuração seja válido, é uma prática recomendada usar RootModule em vez disso.

Versão do módulo

Essa configuração especifica a versão do módulo. Quando existem várias versões de um módulo em um sistema, a versão mais recente é carregada por padrão quando você executa Import-Moduleo .

Valor
Tipo de Entrada System.String
Obrigatório Yes
Valor se não definido Nenhum
Aceita curingas Não

O valor dessa configuração deve ser conversível para System.Version quando você executar Import-Moduleo .

Por exemplo, esse manifesto declara a versão do módulo como '1.2.3'.

@{
    ModuleVersion = '1.2.3'
}

Quando você importa o módulo e inspeciona a propriedade Version , observe que ele é um objeto System.Version e não uma cadeia de caracteres:

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

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

Version

CompatiblePSEditions

Essa configuração especifica os PSEditions compatíveis do módulo.

Valor
Tipo de Entrada System.String[]
Valores Aceitos Desktop, Core
Obrigatório Não
Valor se não definido $null
Aceita curingas Não

Se o valor dessa configuração for $null, o módulo poderá ser importado independentemente do PSEdition da sessão. Você pode defini-lo como um ou mais dos valores aceitos.

Para obter informações sobre PSEdition, consulte:

Quando essa configuração é definida, o módulo só pode ser importado para uma sessão em que o $PSEdition valor da variável automática é incluído na configuração.

Observação

Como a $PSEdition variável automática foi introduzida na versão 5.1, versões mais antigas do Windows PowerShell não podem carregar um módulo que usa a configuração CompatiblePSEditions .

Por exemplo, você pode importar este manifesto de módulo em qualquer sessão:

@{
    # CompatiblePSEditions = @()
}

Com a configuração especificada, este módulo só pode ser importado em sessões em que o $PSEdition valor da variável automática é Core.

@{
    CompatiblePSEditions = @('Core')
}

GUID

Essa configuração especifica um identificador exclusivo para o módulo. O GUID é usado para distinguir entre módulos com o mesmo nome.

Valor
Tipo de Entrada System.String
Obrigatório Não
Valor se não definido 00000000-0000-0000-0000-000000000000
Aceita curingas Não

O valor dessa configuração deve ser conversível para System.Guid quando você executar Import-Moduleo .

Cuidado

Embora não seja uma configuração necessária, não especificar um GUID em um manifesto não traz benefícios e pode levar a colisões de nomes para módulos.

Você pode criar um novo guid para usar em seu manifesto:

New-Guid | Select-Object -ExpandProperty Guid

8456b025-2fa5-4034-ae47-e6305f3917ca

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

Se houver outro módulo na máquina com o mesmo nome, você ainda poderá importar o módulo desejado especificando o nome totalmente qualificado do módulo:

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

Autor

Essa configuração identifica o autor do módulo.

Valor
Tipo de Entrada System.String
Obrigatório Galeria do PowerShell
Valor se não definido $null
Aceita curingas Não

Este manifesto declara que o autor do módulo é a Equipe de Experiência do Desenvolvedor da Contoso.

@{
    Author = 'Contoso Developer Experience Team'
}

CompanyName

Essa configuração identifica a empresa ou o fornecedor que criou o módulo.

Valor
Tipo de Entrada System.String
Obrigatório Não
Valor se não definido $null
Aceita curingas Não

Este manifesto declara que o módulo foi criado pela Contoso, Ltd.

@{
    CompanyName = 'Contoso, Ltd.'
}

Essa configuração especifica uma declaração de direitos autorais para o módulo.

Valor
Tipo de Entrada System.String
Obrigatório Não
Valor se não definido $null
Aceita curingas Não

Este manifesto declara uma declaração de direitos autorais reservando todos os direitos à Contoso, Ltd. a partir de 2022.

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

Descrição

Esta configuração descreve o módulo em um nível alto.

Valor
Tipo de Entrada System.String
Obrigatório Galeria do PowerShell
Valor se não definido $null
Aceita curingas Não

Este manifesto inclui uma breve descrição. Você também pode usar uma cadeia de caracteres aqui para escrever uma descrição mais longa ou de várias linhas.

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

PowerShellVersion

Essa configuração especifica a versão mínima do PowerShell exigida por este módulo.

Valor
Tipo de Entrada System.String
Obrigatório Não
Valor se não definido $null
Aceita curingas Não

O valor dessa configuração deve ser conversível para System.Version quando você executar Import-Moduleo .

Se essa configuração não estiver definida, o PowerShell não restringirá a importação do módulo com base na versão atual.

Por exemplo, esse manifesto declara que o módulo é compatível com todas as versões do PowerShell e do Windows PowerShell.

@{
    # PowerShellVersion = ''
}

Com o PowerShellVersion definido como 7.2, você só pode importar o módulo no PowerShell 7.2 ou superior.

@{
    PowerShellVersion = '7.2'
}

PowerShellHostName

Essa configuração especifica o nome do programa host do PowerShell que o módulo requer, como Windows PowerShell ISE Host ou ConsoleHost.

Valor
Tipo de Entrada System.String
Obrigatório Não
Valor se não definido $null
Aceita curingas Não

Você pode encontrar o nome do host para uma sessão com a $Host.Name instrução. Por exemplo, você pode ver que o host de uma sessão remota é ServerRemoteHost em vez de ConsoleHost:

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

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

Este módulo pode ser importado para qualquer host.

@{
    # PowerShellHostName = ''
}

Com PowerShellHostName definido como ServerRemoteHost, você só pode importar o módulo em uma sessão remota do PowerShell.

@{
    PowerShellHostName = 'ServerRemoteHost'
}

PowerShellHostVersion

Essa configuração especifica a versão mínima de um programa host do PowerShell que o módulo requer.

Valor
Tipo de Entrada System.String
Obrigatório Não
Valor se não definido $null
Aceita curingas Não

O valor dessa configuração deve ser conversível para System.Version quando você executar Import-Moduleo .

Cuidado

Embora essa configuração possa ser usada sem a configuração PowerShellHostName , ela aumenta as chances de comportamento inesperado. Use essa configuração somente quando você também estiver usando a configuração PowerShellHostName .

Por exemplo, o módulo desse manifesto pode ser importado de qualquer sessão do PowerShell em execução no ConsoleHost, independentemente da versão do host.

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

Com o PowerShellHostVersion definido como 5.1, você só pode importar o módulo de qualquer sessão do PowerShell em execução no ConsoleHost em que a versão do host seja 5.1 ou superior.

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

DotNetFrameworkVersion

Essa configuração especifica a versão mínima do Microsoft .NET Framework que o módulo requer.

Valor
Tipo de Entrada System.String
Obrigatório Não
Valor se não definido $null
Aceita curingas Não

Observação

Essa configuração é válida apenas para a edição PowerShell Desktop, como o Windows PowerShell 5.1, e só se aplica a versões do .NET Framework inferiores à 4.5. Esse requisito não tem efeito para versões mais recentes do PowerShell ou do .NET Framework.

O valor dessa configuração deve ser conversível para System.Version quando você executar Import-Moduleo .

Por exemplo, esse manifesto declara que seu módulo pode ser importado em qualquer sessão do PowerShell ou do Windows PowerShell, independentemente da versão do Microsoft .NET Framework.

@{
    # DotNetFrameworkVersion = ''
}

Com DotNetFrameworkVersion definido como 4.0, você pode importar este módulo em qualquer sessão do Windows PowerShell em que a versão mais recente disponível do Microsoft .NET Framework seja pelo menos 4.0. Você também pode importá-lo em qualquer sessão do PowerShell.

@{
    DotNetFrameworkVersion = '4.0'
}

CLRVersion

Essa configuração especifica a versão mínima do CLR (Common Language Runtime) do Microsoft .NET Framework que o módulo requer.

Valor
Tipo de Entrada System.String
Obrigatório Não
Valor se não definido $null
Aceita curingas Não

Observação

Essa configuração é válida apenas para a edição PowerShell Desktop, como o Windows PowerShell 5.1, e só se aplica a versões do .NET Framework inferiores à 4.5. Esse requisito não tem efeito para versões mais recentes do PowerShell ou do .NET Framework.

O valor dessa configuração deve ser conversível para System.Version quando você executar Import-Moduleo .

Por exemplo, esse manifesto declara que seu módulo pode ser importado em qualquer sessão do PowerShell ou do Windows PowerShell, independentemente da versão do CLR do Microsoft .NET Framework.

@{
    # CLRVersion = ''
}

Com CLRVersion definido como 4.0, você pode importar este módulo em qualquer sessão do Windows PowerShell em que a versão mais recente disponível do CLR seja pelo menos 4.0. Você também pode importá-lo em qualquer sessão do PowerShell.

@{
    CLRVersion = '4.0'
}

ProcessorArchitecture

Essa configuração especifica a arquitetura do processador que o módulo requer.

Valor
Tipo de Entrada System.String
Valores Aceitos None, MSIL, X86, IA64, , Amd64Arm
Obrigatório Não
Valor se não definido None
Aceita curingas Não

O valor dessa configuração deve ser conversível para System.Reflection.ProcessorArchitecture quando você executar Import-Moduleo .

Por exemplo, esse manifesto declara que seu módulo pode ser importado em qualquer sessão, independentemente da arquitetura do processador do sistema.

@{
    # ProcessorArchitecture = ''
}

Com ProcessorArchitecture definido como Amd64, você só pode importar esse módulo em uma sessão em execução em uma máquina com uma arquitetura correspondente.

@{
    ProcessorArchitecture = 'Amd64'
}

Módulos Necessários

Essa configuração especifica os módulos que devem estar no estado da sessão global. Se os módulos necessários não estiverem no estado de sessão global, o PowerShell os importará. Se os módulos necessários não estiverem disponíveis, o Import-Module comando falhará.

Valor
Tipo de Entrada System.String[], System.Collections.Hashtable[]
Obrigatório Não
Valor se não definido $null
Aceita curingas Não

As entradas para essa configuração podem ser um nome de módulo, uma especificação de módulo completo ou um caminho para um arquivo de módulo.

Quando o valor é um caminho, o caminho pode ser totalmente qualificado ou relativo.

Quando o valor é um nome ou especificação de módulo, o PowerShell procura o módulo especificado no PSModulePath .

Uma especificação de módulo é uma tabela de hash que tem as seguintes chaves.

  • ModuleName - Obrigatório. Especifica o nome do módulo.
  • GUID - Opcional. Especifica o GUID do módulo.
  • Também é necessário especificar pelo menos uma das três chaves abaixo. A RequiredVersion chave não pode ser usada com as ModuleVersion chaves ou MaximumVersion . Você pode definir um intervalo de versão aceitável para o módulo especificando as ModuleVersion chaves e MaximumVersion juntas.
    • ModuleVersion - Especifica uma versão mínima aceitável do módulo.
    • RequiredVersion - Especifica uma versão exata e necessária do módulo.
    • MaximumVersion - Especifica a versão máxima aceitável do módulo.

Observação

RequiredVersion foi adicionado ao Windows PowerShell 5.0. MaximumVersion foi adicionado ao Windows PowerShell 5.1.

Por exemplo, esse manifesto declara que seu módulo não requer nenhum outro módulo para sua funcionalidade.

@{
    # RequiredModules = @()
}

Este manifesto declara que requer o módulo PSReadLine. Quando você executa Import-Module neste manifesto, o PowerShell importa a versão mais recente do PSReadLine que está disponível para a sessão. Se nenhuma versão estiver disponível, a importação retornará um erro.

@{
    RequiredModules = @(
        'PSReadLine'
    )
}

Dica

No PowerShell 2.0, Import-Module não importa módulos necessários automaticamente. Ele apenas verifica se os módulos necessários estão no estado de sessão global.

Este manifesto declara que requer uma versão do módulo PSReadLine fornecido em sua própria pasta de módulo. Quando você executa Import-Module esse manifesto, o PowerShell importa o PSReadLine fornecido do caminho especificado.

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

Este manifesto declara que requer especificamente a versão 2.0.0 do módulo PSReadLine. Quando você executa Import-Module esse manifesto, o PowerShell importa a versão 2.0.0 do PSReadLine se estiver disponível. Se não estiver disponível, Import-Module retornará um erro.

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

Este manifesto declara que requer que o módulo PSReadLine seja importado na versão 2.0.0 ou superior.

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

Este manifesto declara que requer que o módulo PSReadLine seja importado na versão 2.0.0 ou inferior.

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

Esse manifesto declara que requer que o módulo PSDesiredStateConfiguration seja importado em uma versão igual ou superior a 2.0.0, mas não superior a 2.99.99.

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

RequiredAssemblies

Essa configuração especifica os arquivos de assembly (.dll) que o módulo requer. 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 .

Valor
Tipo de Entrada System.String[]
Obrigatório Não
Valor se não definido $null
Aceita curingas Não

As entradas para essa configuração podem ser o nome do arquivo de um assembly ou o caminho para um. Liste todos os assemblies necessários, mesmo que eles também estejam listados como módulos binários na configuração NestedModules .

Esse manifesto requer a example.dll montagem. Antes de carregar qualquer formatação ou arquivo de tipo especificado neste manifesto, o PowerShell é example.dll carregado da Assemblies pasta localizada no mesmo diretório do manifesto do módulo.

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

ScriptsToProcess

Essa configuração especifica os arquivos de script (.ps1) que são executados no estado de sessão do chamador quando o módulo é importado. Você pode usar esses scripts para preparar um ambiente, assim como você pode usar um script de logon.

Valor
Tipo de Entrada System.String[]
Obrigatório Não
Valor se não definido $null
Aceita curingas Não

Para especificar scripts executados no estado de sessão do módulo, use a chave NestedModules .

Quando você importa esse manifesto, o PowerShell executa o Initialize.ps1 na sessão atual.

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

Por exemplo, se Initialize.ps1 grava mensagens informativas e define a $ExampleState variável:

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

Quando você importa o módulo, o script é executado, gravando essas mensagens e definindo $ExampleState em sua sessão.

$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.

TiposParaProcesso

Essa configuração especifica os arquivos de tipo (.ps1xml) que são executados quando o módulo é importado.

Valor
Tipo de Entrada System.String[]
Obrigatório Não
Valor se não definido $null
Aceita curingas Não

Quando você importa o módulo, o PowerShell executa o Update-TypeData cmdlet com os arquivos especificados. Como os arquivos de tipo não têm escopo, eles afetam todos os estados da sessão na sessão.

Para obter mais informações sobre arquivos de tipo, consulte about_Types.ps1xml

Por exemplo, quando você importa esse manifesto, o Example.ps1xml PowerShell carrega os tipos especificados no arquivo da Types pasta localizada no mesmo diretório que o manifesto do módulo.

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

FormatosParaProcesso

Essa configuração especifica os arquivos de formatação (.ps1xml) que são executados quando o módulo é importado.

Valor
Tipo de Entrada System.String[]
Obrigatório Não
Valor se não definido $null
Aceita curingas Não

Quando você importa um módulo, o PowerShell executa o Update-FormatData cmdlet com os arquivos especificados. Como os arquivos de formatação não têm escopo, eles afetam todos os estados da sessão na sessão.

Para obter mais informações sobre arquivos de tipo, consulte about_Format.ps1xml

Por exemplo, quando você importa esse módulo, o Example.ps1xml PowerShell carrega os formatos especificados no arquivo da pasta localizada no mesmo diretório que o manifesto do Formats módulo.

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

Módulos aninhados

Essa configuração especifica módulos de script (.psm1) e módulos binários (.dll) que são importados para o estado de sessão do módulo. Você também pode especificar arquivos de script (.ps1). Os arquivos nessa configuração são executados na ordem em que estão listados.

Valor
Tipo de Entrada System.String[], System.Collections.Hashtable[]
Obrigatório Não
Valor se não definido $null
Aceita curingas Não

As entradas para essa configuração podem ser um nome de módulo, uma especificação de módulo completo ou um caminho para um módulo ou arquivo de script.

Quando o valor é um caminho, o caminho pode ser totalmente qualificado ou relativo.

Quando o valor é um nome ou especificação de módulo, o PowerShell procura o módulo especificado no PSModulePath .

Uma especificação de módulo é uma tabela de hash que tem as seguintes chaves.

  • ModuleName - Obrigatório. Especifica o nome do módulo.
  • GUID - Opcional. Especifica o GUID do módulo.
  • Também é necessário especificar pelo menos uma das três chaves abaixo. A RequiredVersion chave não pode ser usada com as ModuleVersion chaves ou MaximumVersion . Você pode definir um intervalo de versão aceitável para o módulo especificando as ModuleVersion chaves e MaximumVersion juntas.
    • ModuleVersion - Especifica uma versão mínima aceitável do módulo.
    • RequiredVersion - Especifica uma versão exata e necessária do módulo.
    • MaximumVersion - Especifica a versão máxima aceitável do módulo.

Observação

RequiredVersion foi adicionado ao Windows PowerShell 5.0. MaximumVersion foi adicionado ao Windows PowerShell 5.1.

Todos os itens que precisam ser exportados de um módulo aninhado devem ser exportados pelo módulo aninhado usando o Export-ModuleMember cmdlet ou estar listados em uma das propriedades de exportação:

  • FunçõesToExport
  • CmdletsToExport
  • VariáveisToExport
  • AliasesToExport

Os módulos aninhados no estado de sessão do módulo estão disponíveis para o módulo raiz, mas não são retornados por um Get-Module comando no estado de sessão do chamador.

Os scripts (.ps1) listados nessa configuração são executados no estado de sessão do módulo, não no estado de sessão do chamador. Para executar um script no estado de sessão do chamador, liste o nome do arquivo do script na configuração ScriptsToProcess .

Por exemplo, quando você importa esse manifesto, o Helpers.psm1 módulo é carregado no estado de sessão do módulo raiz. Todos os cmdlets declarados no módulo aninhado são exportados, a menos que sejam restritos de outra forma.

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

FunçõesToExport

Essa configuração especifica as funções que o módulo exporta. Você pode usar essa configuração para restringir as funções que são exportadas pelo módulo. Ele pode remover funções da lista de funções exportadas, mas não pode adicionar funções à lista.

Valor
Tipo de Entrada System.String[]
Obrigatório Não
Valor se não definido $null
Aceita curingas Yes

Você pode especificar entradas nessa configuração com curingas. Todas as funções correspondentes na lista de funções exportadas são exportadas.

Dica

Para desempenho e capacidade de descoberta, você deve sempre listar explicitamente as funções que deseja que seu módulo exporte nessa configuração sem usar curingas.

Por exemplo, quando você importa um módulo com a configuração comentada, todas as funções no módulo raiz e quaisquer módulos aninhados são exportados.

@{
    # FunctionsToExport = @()
}

Esse manifesto é funcionalmente idêntico a não especificar a configuração.

@{
    FunctionsToExport = '*'
}

Com FunctionsToExport definido como uma matriz vazia, quando você importa este módulo, nenhuma função do módulo raiz ou qualquer exportação de módulos aninhados está disponível.

@{
    FunctionsToExport = @()
}

Observação

Se você criar o manifesto do módulo com o New-ModuleManifest comando e não especificar o parâmetro FunctionsToExport , o manifesto criado terá essa configuração especificada como uma matriz vazia. A menos que você edite o manifesto, nenhuma função do módulo será exportada.

Com FunctionsToExport definido para incluir apenas a Get-Example função, quando você importa este módulo somente a Get-Example função é disponibilizada, mesmo se outras funções foram exportadas pelo módulo raiz ou quaisquer módulos aninhados.

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

Com FunctionsToExport definido com uma cadeia de caracteres curinga, quando você importa este módulo, qualquer função cujo nome termina com Example é disponibilizada, mesmo que outras funções tenham sido exportadas como membros do módulo pelo módulo raiz ou quaisquer módulos aninhados.

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

CmdletsToExport

Essa configuração especifica os cmdlets que o módulo exporta. Você pode usar essa configuração para restringir os cmdlets que são exportados pelo módulo. Ele pode remover cmdlets da lista de membros do módulo exportados, mas não pode adicionar cmdlets à lista.

Valor
Tipo de Entrada System.String[]
Obrigatório Não
Valor se não definido $null
Aceita curingas Yes

Você pode especificar entradas nessa configuração com curingas. Todos os cmdlets correspondentes na lista de cmdlets exportados são exportados.

Dica

Para desempenho e capacidade de descoberta, você deve sempre listar explicitamente os cmdlets que deseja que seu módulo exporte nessa configuração sem usar curingas.

Por exemplo, quando você importa um módulo com essa configuração comentada, todos os cmdlets no módulo raiz e quaisquer módulos aninhados são exportados.

@{
    # CmdletsToExport = @()
}

Esse manifesto é funcionalmente idêntico a não especificar a configuração.

@{
    CmdletsToExport = '*'
}

Com CmdletsToExport definido como uma matriz vazia, quando você importa esse módulo, nenhum cmdlet, o módulo raiz ou qualquer exportação de módulos aninhados estão disponíveis.

@{
    CmdletsToExport = @()
}

Observação

Se você criar o manifesto do módulo com o New-ModuleManifest comando e não especificar o parâmetro CmdletsToExport , o manifesto criado terá essa configuração especificada como uma matriz vazia. A menos que você edite o manifesto, nenhum cmdlet do módulo será exportado.

Com CmdletsToExport definido para incluir apenas o Get-Example cmdlet, quando você importa esse módulo, somente o Get-Example cmdlet é disponibilizado, mesmo que outros cmdlets tenham sido exportados pelo módulo raiz ou por quaisquer módulos aninhados.

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

Com CmdletsToExport definido com uma cadeia de caracteres curinga, quando você importa esse módulo, qualquer cmdlet cujo nome termina com Example é disponibilizado, mesmo que outros cmdlets tenham sido exportados como membros do módulo pelo módulo raiz ou por quaisquer módulos aninhados.

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

VariáveisToExport

Essa configuração especifica as variáveis que o módulo exporta. Você pode usar essa configuração para restringir as variáveis que são exportadas pelo módulo. Ele pode remover variáveis da lista de membros do módulo exportados, mas não pode adicionar variáveis à lista.

Valor
Tipo de Entrada System.String[]
Obrigatório Não
Valor se não definido $null
Aceita curingas Yes

Você pode especificar entradas nessa configuração com curingas. Todas as variáveis correspondentes na lista de membros do módulo exportado são exportadas.

Dica

Para desempenho e capacidade de descoberta, você deve sempre listar explicitamente as variáveis que deseja que seu módulo exporte nessa configuração sem usar curingas.

Por exemplo, quando você importa um módulo com essa configuração comentada, todas as variáveis no módulo raiz e quaisquer módulos aninhados são exportados.

@{
    # VariablesToExport = @()
}

Esse manifesto é funcionalmente idêntico a não especificar a configuração.

@{
    VariablesToExport = '*'
}

Observação

Se você criar o manifesto do módulo com o New-ModuleManifest comando e não especificar o parâmetro VariablesToExport , o manifesto criado terá essa configuração especificada como '*'. A menos que você edite o manifesto, todas as variáveis do módulo serão exportadas.

Com VariablesToExport definido como uma matriz vazia, quando você importa este módulo, nenhuma variável, o módulo raiz ou qualquer exportação de módulos aninhados estão disponíveis.

@{
    VariablesToExport = @()
}

Com VariablesToExport definido para incluir apenas a SomeExample variável, quando você importa este módulo, somente a $SomeExample variável é disponibilizada, mesmo que outras variáveis tenham sido exportadas pelo módulo raiz ou por quaisquer módulos aninhados.

@{
    VariablesToExport = @(
        'SomeExample'
    )
}

Com VariablesToExport definido com uma cadeia de caracteres curinga, quando você importa este módulo, qualquer variável cujo nome termina com Example é disponibilizada, mesmo se outras variáveis foram exportadas como membros do módulo pelo módulo raiz ou quaisquer módulos aninhados.

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

DscResourcesToExport

Essa configuração especifica os Recursos DSC que o módulo exporta. Você pode usar essa configuração para restringir os Recursos DSC baseados em classe que são exportados pelo módulo. Ele pode remover Recursos DSC da lista de membros do módulo exportados, mas não pode adicionar Recursos DSC à lista.

Valor
Tipo de Entrada System.String[]
Obrigatório Não
Valor se não definido $null
Aceita curingas Yes

Você pode especificar entradas nessa configuração com curingas. Todos os recursos DSC baseados em classe correspondentes no módulo são exportados.

Dica

Para facilitar a descoberta, você deve sempre listar explicitamente todos os Recursos DSC exportados pelo módulo.

Para obter mais informações sobre como criar e usar recursos de DSC, consulte a documentação do DSC.

Esse manifesto exporta todos os recursos DSC baseados em classe e MOF definidos no módulo raiz e em quaisquer módulos aninhados.

@{
    # DscResourcesToExport = @()
}

Esse manifesto exporta todos os Recursos DSC baseados em MOF definidos no módulo raiz e quaisquer módulos aninhados, mas apenas um Recurso DSC baseado em classe, ExampleClassResource.

@{
    DscResourcesToExport = @(
        'ExampleClassResource'
    )
}

Este manifesto exporta todos os Recursos DSC que inclui. Mesmo que o recurso baseado em MOF não estivesse listado, o módulo ainda o exportaria.

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

Lista de Módulos

Essa configuração é uma lista de inventário informativo dos módulos incluídos nesta. Essa lista não afeta o comportamento do módulo.

Valor
Tipo de Entrada System.String[], System.Collections.Hashtable[]
Obrigatório Não
Valor se não definido $null
Aceita curingas Não

As entradas para essa configuração podem ser um nome de módulo, uma especificação de módulo completo ou um caminho para um módulo ou arquivo de script.

Quando o valor é um caminho, o caminho pode ser totalmente qualificado ou relativo.

Quando o valor é um nome ou especificação de módulo, o PowerShell procura o módulo especificado no PSModulePath .

Uma especificação de módulo é uma tabela de hash que tem as seguintes chaves.

  • ModuleName - Obrigatório. Especifica o nome do módulo.
  • GUID - Opcional. Especifica o GUID do módulo.
  • Também é necessário especificar pelo menos uma das três chaves abaixo. A RequiredVersion chave não pode ser usada com as ModuleVersion chaves ou MaximumVersion . Você pode definir um intervalo de versão aceitável para o módulo especificando as ModuleVersion chaves e MaximumVersion juntas.
    • ModuleVersion - Especifica uma versão mínima aceitável do módulo.
    • RequiredVersion - Especifica uma versão exata e necessária do módulo.
    • MaximumVersion - Especifica a versão máxima aceitável do módulo.

Observação

RequiredVersion foi adicionado ao Windows PowerShell 5.0. MaximumVersion foi adicionado ao Windows PowerShell 5.1.

Esse manifesto não fornece uma lista informativa dos módulos que ele inclui. Pode ou não ter módulos. Mesmo que essa configuração não seja especificada, todos os módulos listados nas configurações RootModule, ScriptsToProcess ou NestedModules ainda se comportam normalmente.

@{
    # ModuleList = @()
}

Este manifesto declara que os únicos módulos que inclui são Example.psm1 e os submódulos First.psm1 e Second.psm1 na Submodules pasta.

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

FileList

Essa configuração é uma lista de inventário informativo dos arquivos incluídos neste módulo. Essa lista não afeta o comportamento do módulo.

Valor
Tipo de Entrada System.String[]
Obrigatório Não
Valor se não definido $null
Aceita curingas Yes

As entradas para essa configuração devem ser o caminho relativo para um arquivo da pasta que contém o manifesto do módulo.

Quando um usuário chama Get-Module um manifesto com essa configuração definida, a propriedade FileList contém o caminho completo para esses arquivos, unindo o caminho do módulo com o caminho relativo de cada entrada.

Este manifesto não inclui uma lista de seus arquivos.

@{
    # FileList = @()
}

Esse manifesto declara que os únicos arquivos que ele inclui estão listados nessa configuração.

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

Dados Privados

Essa configuração define uma tabela de hash de dados que está disponível para quaisquer comandos ou funções no escopo do módulo raiz.

Valor
Tipo de Entrada System.Collections.Hashtable
Obrigatório Galeria do PowerShell, Crescendo
Valor se não definido $null
Aceita curingas Não

Quando você exporta um manifesto do Crescendo para criar um novo módulo, Export-CrescendoModule adiciona duas chaves ao PrivateData

  • CrescendoGenerated - carimbo de data/hora quando o módulo foi exportado
  • CrescendoVersion - a versão do Crescendo usada para exportar o módulo

Você pode adicionar suas próprias chaves para armazenar metadados que deseja rastrear. Todas as chaves adicionadas a essa configuração estão disponíveis para funções e cmdlets no módulo raiz usando $MyInvocation.MyCommand.Module.PrivateDatao . A tabela de hash não está disponível no escopo do módulo em si, apenas nos cmdlets definidos no módulo.

Por exemplo, esse manifesto define a chave PublishedDate em PrivateData.

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

Os cmdlets no módulo podem acessar esse valor com a $MyInvocation variável.

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"
    }
}

Depois que o módulo é importado, a função usa o valor de PrivateData para determinar quando o módulo foi publicado.

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

A propriedade filho PSData define uma tabela de hash de valores que oferecem suporte a cenários de extensão específicos.

Valor
Tipo de Entrada System.Collections.Hashtable
Obrigatório Galeria do PowerShell, Recursos experimentais, Módulos do Crescendo
Valor se não definido $null
Aceita curingas Não

A propriedade filho PSData é usada para os seguintes cenários:

  • Galeria do PowerShell - Quando você cria um manifesto de módulo usando New-ModuleManifest o cmdlet, preenche previamente a hashtable PSData com chaves de espaço reservado que são necessárias ao publicar o módulo na Galeria do PowerShell. Para obter mais informações sobre manifestos de módulo e a publicação na Galeria do PowerShell, consulte Valores de manifesto de pacote que afetam a interface do usuário da Galeria do PowerShell.
  • Características experimentais - Os metadados sobre uma característica experimental são mantidos na propriedade ExperimentalFeatures do PSData. A propriedade ExperimentalFeatures é uma matriz de tabelas de hash que contém o nome e a descrição do recurso. Para obter mais informações, consulte Declarando recursos experimentais em módulos.
  • Módulos Crescendo - Quando você exporta um manifesto Crescendo para criar um novo módulo, Export-CrescendoModule adiciona o valor CrescendoBuilt à propriedade PSData.Tags. Você pode usar essa marca para localizar módulos na Galeria do PowerShell que foram criados usando o Crescendo. Para obter mais informações, consulte Export-CrescendoModule.

HelpInfoURI

Essa configuração especifica o endereço da Internet do arquivo XML HelpInfo do módulo.

Valor
Tipo de Entrada System.String
Obrigatório Não
Valor se não definido $null
Aceita curingas Não

O valor dessa configuração deve ser um URI (Uniform Resource Identifier) que começa com http ou https.

O arquivo XML HelpInfo oferece suporte ao recurso Ajuda Atualizável que foi introduzido no PowerShell 3.0. Ele contém informações sobre o local dos arquivos de ajuda que podem ser baixados para o módulo e os números de versão dos arquivos de ajuda mais recentes para cada localidade com suporte.

Para obter informações sobre a Ajuda atualizável, consulte about_Updatable_Help. Para obter informações sobre o arquivo XML HelpInfo, consulte Dando suporte à Ajuda atualizável.

Por exemplo, este módulo suporta ajuda atualizável.

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

DefaultCommandPrefix

Essa configuração especifica um prefixo que é precedido aos substantivos de todos os comandos no módulo quando eles são importados para uma sessão. Os prefixos ajudam a evitar conflitos de nome de comando na sessão de um usuário.

Valor
Tipo de Entrada System.String
Obrigatório Não
Valor se não definido $null
Aceita curingas Não

Os usuários do módulo podem substituir esse prefixo especificando o parâmetro Prefix do Import-Module cmdlet.

Essa configuração foi introduzida no PowerShell 3.0.

Quando esse manifesto é importado, todos os cmdlets importados deste módulo são Example precedidos para o substantivo em seu nome. Por exemplo, Get-Item é importado como Get-ExampleItem.

@{
    DefaultCommandPrefix = 'Example'
}

Confira também