Partilhar via

about_Module_Manifests

  • Artigo

Breve descrição

Descreve as configurações e práticas para escrever 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 que você separe 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 parâmetros para as configurações do manifesto, ele grava um arquivo de manifesto mínimo. O trecho abaixo mostra essa saída padrão, cortada de comentários e espaçamento para maior 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 o 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 construir caminhos e atribuir condicionalmente valores com base em variáveis.

Quando você importa um módulo usando Import-Moduleo , o manifesto é avaliado no Restricted modo de linguagem. Restricted mode 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, só é 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.

RootModule

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.

Value
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 um dos seguintes:

  • um script (.ps1)
  • um módulo de script (.psm1)
  • um manifesto do módulo (.psd1)
  • uma assembleia (.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 para o 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 tipo de módulo binário
  • um .cdxml arquivo faz com que o módulo tipo CIM
  • um .xaml arquivo torna o tipo de módulo Fluxo de trabalho

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

Gorjeta

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

Nota

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.

ModuleVersion

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 .

Value
Tipo de entrada System.String
Obrigatório Sim
Valor se não definido Nenhuma
Aceita curingas Não

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

Por exemplo, este 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

PSEdições compatíveis

Esta configuração especifica as PSEdições compatíveis do módulo.

Value
Tipo de entrada System.String[]
Valores aceites 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 da 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.

Nota

Como a variável automática foi introduzida na versão 5.1, as $PSEdition 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 esse 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

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

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

Atenção

Embora não seja uma configuração necessária, não especificar um GUID em um manifesto não tem 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.

Value
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 Contoso Developer Experience Team.

@{
    Author = 'Contoso Developer Experience Team'
}

CompanyName

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

Value
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.'
}

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

Value
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.'
}

Description

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

Value
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 com várias linhas.

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

PowerShellVersion

Esta configuração especifica a versão mínima do PowerShell que este módulo requer.

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

Value
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 exige.

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

Atenção

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.

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

Nota

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 a 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 Common Language Runtime (CLR) do Microsoft .NET Framework que o módulo requer.

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

Nota

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

Value
Tipo de entrada System.String
Valores aceites None, MSIL, X86, IA64, Amd64, Arm
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, este 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 este 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 da sessão global, o PowerShell os importa. Se os módulos necessários não estiverem disponíveis, o Import-Module comando falhará.

Value
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 - Necessá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ões aceitável para o módulo especificando as ModuleVersion teclas e MaximumVersion juntas.
    • ModuleVersion - Especifica uma versão mínima aceitável do módulo.
    • RequiredVersion - Especifica uma versão exata e obrigatória do módulo.
    • MaximumVersion - Especifica a versão máxima aceitável do módulo.

Nota

RequiredVersion foi adicionado no Windows PowerShell 5.0. MaximumVersion foi adicionado no 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 esse manifesto, o PowerShell importa a versão mais recente do PSReadLine disponível para a sessão. Se nenhuma versão estiver disponível, a importação retornará um erro.

@{
    RequiredModules = @(
        'PSReadLine'
    )
}

Gorjeta

No PowerShell 2.0, Import-Module não importa os 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 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 devolve 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'
        }
    )
}

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

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

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

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

ScriptsToProcess

Essa configuração especifica 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 login.

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

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

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

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

Por exemplo, se Initialize.ps1 escreve 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.

TiposparaProcessar

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

Value
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 pasta localizada no mesmo diretório que o manifesto do Types módulo.

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

FormatosParaProcessar

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

Value
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 Formats pasta localizada no mesmo diretório do manifesto do módulo.

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

NestedModules

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 são listados.

Value
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 de módulo ou especificação, 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 - Necessá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ões aceitável para o módulo especificando as ModuleVersion teclas e MaximumVersion juntas.
    • ModuleVersion - Especifica uma versão mínima aceitável do módulo.
    • RequiredVersion - Especifica uma versão exata e obrigatória do módulo.
    • MaximumVersion - Especifica a versão máxima aceitável do módulo.

Nota

RequiredVersion foi adicionado no Windows PowerShell 5.0. MaximumVersion foi adicionado no 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 listados em uma das propriedades de exportação:

  • FunçõesparaExportar
  • CmdletsToExport
  • VariáveisParaExportar
  • AliasesToExport

Os módulos aninhados no estado da 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 da sessão do chamador.

Os scripts (.ps1) listados nessa configuração são executados no estado da sessão do módulo, não no estado da 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 da sessão do módulo raiz. Todos os cmdlets declarados no módulo aninhado são exportados, a menos que sejam restringidos de outra forma.

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

FunçõesparaExportar

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.

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

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

Gorjeta

Para desempenho e capacidade de descoberta, você deve sempre listar explicitamente as funções que deseja que o 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 todos os módulos aninhados são exportados.

@{
    # FunctionsToExport = @()
}

Este 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 = @()
}

Nota

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 que outras funções tenham sido exportadas pelo módulo raiz ou por 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 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 exportados pelo módulo. Ele pode remover cmdlets da lista de membros do módulo exportados, mas não pode adicionar cmdlets à lista.

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

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

Gorjeta

Para desempenho e capacidade de descoberta, você deve sempre listar explicitamente os cmdlets que deseja que o 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 todos os módulos aninhados são exportados.

@{
    # CmdletsToExport = @()
}

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

@{
    CmdletsToExport = '*'
}

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

@{
    CmdletsToExport = @()
}

Nota

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 este módulo, qualquer cmdlet cujo nome termina com Example é disponibilizado, mesmo que outros cmdlets tenham sido exportados como membros do módulo raiz ou quaisquer módulos aninhados.

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

VariáveisParaExportar

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.

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

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

Gorjeta

Para desempenho e capacidade de descoberta, você deve sempre listar explicitamente as variáveis que deseja que o 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 todos os módulos aninhados são exportados.

@{
    # VariablesToExport = @()
}

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

@{
    VariablesToExport = '*'
}

Nota

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 são exportadas.

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

@{
    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 que outras variáveis tenham sido exportadas como membros do módulo raiz pelo módulo raiz ou por 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.

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

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

Gorjeta

Para detetabilidade, você deve sempre listar explicitamente todos os recursos DSC exportados pelo módulo.

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

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

@{
    # DscResourcesToExport = @()
}

Esse manifesto exporta todos os recursos DSC baseados em MOF definidos no módulo raiz e todos os 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

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

Value
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 de módulo ou especificação, 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 - Necessá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ões aceitável para o módulo especificando as ModuleVersion teclas e MaximumVersion juntas.
    • ModuleVersion - Especifica uma versão mínima aceitável do módulo.
    • RequiredVersion - Especifica uma versão exata e obrigatória do módulo.
    • MaximumVersion - Especifica a versão máxima aceitável do módulo.

Nota

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

Este manifesto não fornece uma lista informativa dos módulos que inclui. Pode ou não ter módulos. Embora 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 Submodules declara que os únicos módulos que inclui são Example.psm1 e os submódulos First.psm1 e Second.psm1 na pasta.

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

FileList

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

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

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 dos seus ficheiros.

@{
    # 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.

Value
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 Crescendo para criar um novo módulo, Export-CrescendoModule adiciona duas chaves a 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.PrivateData. 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.

Value
Tipo de entrada System.Collections.Hashtable
Obrigatório Galeria do PowerShell, recursos experimentais, módulos 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.
  • Recursos experimentais - Os metadados sobre um recurso experimental são mantidos na propriedade ExperimentalFeatures do PSData. A propriedade ExperimentalFeatures é uma matriz de hashtables 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.

AjudaInfoURI

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

Value
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 para download para o módulo e os números de versão dos arquivos de ajuda mais recentes para cada localidade suportada.

Para obter informações sobre a Ajuda atualizável, consulte about_Updatable_Help. Para obter informações sobre o arquivo XML HelpInfo, consulte Supporting Updatable Help.

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 é anexado 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.

Value
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 desse módulo têm Example prendido o substantivo em seu nome. Por exemplo, Get-Item é importado como Get-ExampleItem.

@{
    DefaultCommandPrefix = 'Example'
}

Consulte também