Поделиться через

Создание манифеста модуля PowerShell

После написания модуля PowerShell можно добавить необязательный манифест модуля, содержащий сведения о модуле. Например, можно описать автора, указать файлы в модуле (например, вложенные модули), запускать скрипты для настройки среды пользователя, загрузки и форматирования файлов, определения системных требований и ограничения элементов, экспортируемых модулем.

Создание манифеста модуля

Манифест модуля — это файл данных PowerShell,.psd1 описывающий содержимое модуля и определяющий способ обработки модуля. Файл манифеста — это текстовый файл, содержащий хэш-таблицу ключей и значений. Файл манифеста связывается с модулем, именуя манифест так же, как модуль, и сохраняя манифест в корневом каталоге модуля.

Для простых модулей, содержащих только одну .psm1 или двоичную сборку, манифест модуля необязателен. Но рекомендация заключается в том, чтобы использовать манифест модуля по возможности, так как они полезны для организации кода и поддержания сведений о версиях. Кроме того, для экспорта сборки, установленной в глобальном кэше сборок, требуется манифест модуля. Манифест модуля также необходим для модулей, поддерживающих функцию обновляемой справки. Обновляемая справка использует ключ HelpInfoUri в манифесте модуля для поиска файла справки (HelpInfo XML), содержащего расположение обновленных файлов справки для модуля. Дополнительные сведения о обновляемой справке см. в статье "Поддержка обновляемой справки".

Создание и использование манифеста модуля

  1. Рекомендуется создать манифест модуля, чтобы использовать командлет New-ModuleManifest . Параметры можно использовать для указания одного или нескольких ключей и значений манифеста по умолчанию. Единственным требованием является имя файла. New-ModuleManifest создает манифест модуля с указанными значениями и включает оставшиеся ключи и их значения по умолчанию. Если вам нужно создать несколько модулей, используйте New-ModuleManifest для создания шаблона манифеста модуля, который можно изменить для различных модулей. Пример манифеста модуля по умолчанию см. в примере манифеста модуля.

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

    Альтернативой является создание хэш-таблицы манифеста модуля вручную с помощью минимальной информации, необходимой для ModuleVersion. Сохраните файл с тем же именем, что и модуль, и используйте .psd1 расширение файла. Затем можно изменить файл и добавить соответствующие ключи и значения.

  2. Добавьте дополнительные элементы, которые требуется в файле манифеста.

    Чтобы изменить файл манифеста, используйте любой текстовый редактор, который вы предпочитаете. Но файл манифеста — это файл скрипта, содержащий код, поэтому вы можете изменить его в среде сценариев или среды разработки, например Visual Studio Code. Все элементы файла манифеста являются необязательными, за исключением номера ModuleVersion .

    Описание ключей и значений, которые можно включить в манифест модуля, см. в таблице элементов манифеста модуля . Дополнительные сведения см. в описаниях параметров в командлете New-ModuleManifest .

  3. Чтобы устранить любые сценарии, которые могут не охватываться элементами манифеста базового модуля, можно добавить дополнительный код в манифест модуля.

    Для проблем с безопасностью PowerShell выполняет только небольшое подмножество доступных операций в файле манифеста модуля. Как правило, можно использовать if операторы, арифметические операторы и операторы сравнения, а также базовые типы данных PowerShell.

  4. После создания манифеста модуля его можно проверить, чтобы убедиться, что все пути, описанные в манифесте, верны. Чтобы протестировать манифест модуля, используйте Test-ModuleManifest.

    Test-ModuleManifest myModuleName.psd1

  5. Убедитесь, что манифест модуля находится на верхнем уровне каталога, содержащего модуль.

    При копировании модуля в систему и его импорте PowerShell использует манифест модуля для импорта модуля.

  6. При необходимости можно напрямую протестировать манифест модуля с вызовом Import-Module , определив сам манифест.

    Import-Module .\myModuleName.psd1

Элементы манифеста модуля

В следующей таблице описываются элементы, которые можно включить в манифест модуля. Дополнительные сведения см. в about_Module_Manifests.

Элемент По умолчанию Description
RootModule
Тип: String		 <empty string> Файл модуля скрипта или двоичного модуля, связанный с этим манифестом. Предыдущие версии PowerShell назвали этот элемент ModuleToProcess.
Возможные типы для корневого модуля могут быть пустыми, что создает модуль манифеста , имя модуля скрипта (.psm1) или имя двоичного модуля (.exe или .dll). Размещение имени манифеста модуля (.psd1) или файла скрипта (.ps1) в этом элементе приводит к ошибке.
Пример: RootModule = 'ScriptModule.psm1'
ModuleVersion
Тип: Version		 '0.0.1' Номер версии этого модуля. Если значение не указано, New-ModuleManifest используется значение по умолчанию. Строка должна быть в состоянии преобразовать в тип Version , например #.#.#.#. Import-Module загружает первый модуль, который он находит на $PSModulePath , который соответствует имени, и имеет по крайней мере как высокий модульVersion, как параметр MinimumVersion . Чтобы импортировать определенную версию, используйте Import-Module параметр RequiredVersion командлета.
Пример: ModuleVersion = '1.0'
глобальный уникальный идентификатор
Тип: GUID		 '<GUID>' Идентификатор, используемый для уникальной идентификации этого модуля. Если значение не указано, New-ModuleManifest автоматически создает значение. В настоящее время невозможно импортировать модуль по GUID.
Пример: GUID = 'cfc45206-1e49-459d-a8ad-5b571ef94857'
Автор
Тип: String		 '<Current user>' Автор этого модуля. Если значение не указано, New-ModuleManifest использует текущего пользователя.
Пример: Author = 'AuthorNameHere'
Название компании
Тип: String		 'Unknown' Компания или поставщик этого модуля. Если значение не указано, New-ModuleManifest используется значение по умолчанию.
Пример: CompanyName = 'Fabrikam'
Авторское право
Тип: String		 '(c) <Author>. All rights reserved.' Заявление об авторских правах для этого модуля. Если значение не указано, New-ModuleManifest использует значение по умолчанию с текущим пользователем в качестве <Author>значения. Чтобы указать автора, используйте параметр Author .
Пример: Copyright = '2019 AuthorName. All rights reserved.'
Описание
Тип: String		 <empty string> Описание функциональных возможностей, предоставляемых этим модулем.
Пример: Description = 'This is the module's description.'
PowerShellVersion
Тип: Version		 <empty string> Минимальная версия подсистемы PowerShell, требуемая этим модулем. Допустимые значения: 1.0, 2.0, 3.0, 4.0, 5.0, 5.1, 6.0, 6.1, 6.2, 7.0 и 7.1.
Пример: PowerShellVersion = '5.0'
PowerShellHostName
Тип: String		 <empty string> Имя узла PowerShell, необходимого для этого модуля. Это имя предоставляется PowerShell. Чтобы найти имя хост-программы, введите в программе: $Host.Name
Пример: PowerShellHostName = 'ConsoleHost'
PowerShellHostVersion
Тип: Version		 <empty string> Минимальная версия узла PowerShell, необходимого для этого модуля.
Пример: PowerShellHostVersion = '2.0'
DotNetFrameworkVersion
Тип: Version		 <empty string> Минимальная версия Microsoft .NET Framework, необходимая для этого модуля. Это необходимое условие допустимо только для выпуска PowerShell Desktop, например Windows PowerShell 5.1, и применяется только к версиям .NET Framework ниже 4.5.
Пример: DotNetFrameworkVersion = '3.5'
CLRVersion
Тип: Version		 <empty string> Минимальная версия среды CLR, требуемая этим модулем. Это необходимое условие допустимо только для выпуска PowerShell Desktop, например Windows PowerShell 5.1, и применяется только к версиям .NET Framework ниже 4.5.
Пример: CLRVersion = '3.5'
ProcessorArchitecture
Тип: ProcessorArchitecture		 <empty string> Архитектура процессора (None, X86, Amd64), необходимая для этого модуля. Допустимые значения: x86, AMD64, Arm, IA64, MSIL и None (неизвестно или не указано).
Пример: ProcessorArchitecture = 'x86'
RequiredModules
Тип: Object[]		 @() Модули, которые необходимо импортировать в глобальную среду перед импортом этого модуля. Это загружает все модули, перечисленные, если они еще не загружены. Например, некоторые модули уже могут загружаться другим модулем. Можно указать определенную версию для загрузки, RequiredVersion а не ModuleVersion. Если ModuleVersion он используется, он загружает последнюю версию, доступную как минимум с указанной версией. Строки и хэш-таблицы можно объединить в значении параметра.
Пример: RequiredModules = @("MyModule", @{ModuleName="MyDependentModule"; ModuleVersion="2.0"; GUID="cfc45206-1e49-459d-a8ad-5b571ef94857"})
Пример: RequiredModules = @("MyModule", @{ModuleName="MyDependentModule"; RequiredVersion="1.5"; GUID="cfc45206-1e49-459d-a8ad-5b571ef94857"})
RequiredAssemblies
Тип: String[]		 @() Сборки, которые необходимо загрузить перед импортом этого модуля. Указывает имена файлов сборки ,.dllнеобходимые модулю.
PowerShell загружает указанные сборки перед обновлением типов или форматов, импорта вложенных модулей или импорта файла модуля, указанного в значении ключа RootModule. Используйте этот параметр для перечисления всех необходимых модулей сборок.
Пример: RequiredAssemblies = @("assembly1.dll", "assembly2.dll", "assembly3.dll")
ScriptsToProcess
Тип: String[]		 @() Скрипт (.ps1) файлы, которые выполняются в состоянии сеанса вызывающего объекта при импорте модуля. Это может быть глобальное состояние сеанса или, например, для вложенных модулей, состояние сеанса другого модуля. Эти скрипты можно использовать для подготовки среды так же, как и при использовании сценария входа.
Эти скрипты выполняются перед загрузкой любого из модулей, перечисленных в манифесте.
Пример: ScriptsToProcess = @("script1.ps1", "script2.ps1", "script3.ps1")
TypesToProcess
Тип: String[]		 @() Тип файлов (.ps1xml) для загрузки при импорте этого модуля.
Пример: TypesToProcess = @("type1.ps1xml", "type2.ps1xml", "type3.ps1xml")
ФорматыToProcess
Тип: String[]		 @() Форматирование файлов (.ps1xml) для загрузки при импорте этого модуля.
Пример: FormatsToProcess = @("format1.ps1xml", "format2.ps1xml", "format3.ps1xml")
Вложенныеmodules
Тип: Object[]		 @() Модули для импорта в виде вложенных модулей модуля, указанного в RootModule (псевдоним:ModuleToProcess).
Добавление имени модуля в этот элемент аналогично вызову Import-Module из кода скрипта или сборки. Основное различие в использовании файла манифеста заключается в том, что проще увидеть, что вы загружаете. И если модуль не удается загрузить, вы еще не загрузили фактический модуль.
Помимо других модулей, вы также можете загрузить файлы скриптов (.ps1здесь). Эти файлы будут выполняться в контексте корневого модуля. Это эквивалентно перебору скрипта в корневом модуле.
Пример: NestedModules = @("script.ps1", @{ModuleName="MyModule"; ModuleVersion="1.0.0.0"; GUID="50cdb55f-5ab7-489f-9e94-4ec21ff51e59"})
FunctionsToExport
Тип: String[]		 @() Указывает функции для экспорта из этого модуля, чтобы обеспечить лучшую производительность, не используйте подстановочные знаки и не удаляйте запись, используйте пустой массив, если для экспорта нет функций. По умолчанию никакие функции не экспортируются. Этот ключ можно использовать для перечисления функций, экспортируемых модулем.
Модуль экспортирует функции в состояние сеанса вызывающего объекта. Состояние сеанса вызывающего объекта может быть глобальным состоянием сеанса или для вложенных модулей, состояние сеанса другого модуля. При цепочке вложенных модулей все функции, экспортируемые вложенным модулем, будут экспортированы в состояние глобального сеанса, если модуль в цепочке не ограничивает функцию с помощью ключа FunctionsToExport .
Если манифест экспортирует псевдонимы для функций, этот ключ может удалить функции, псевдонимы которых перечислены в ключе AliasesToExport , но этот ключ не может добавить псевдонимы функций в список.
Пример: FunctionsToExport = @("function1", "function2", "function3")
КомандлетыToExport
Тип: String[]		 @() Указывает командлеты для экспорта из этого модуля, чтобы повысить производительность, не использовать подстановочные знаки и не удалять запись, используйте пустой массив, если для экспорта нет командлетов. По умолчанию командлеты не экспортируются. Этот ключ можно использовать для перечисления командлетов, экспортируемых модулем.
Состояние сеанса вызывающего объекта может быть глобальным состоянием сеанса или для вложенных модулей, состояние сеанса другого модуля. При цепочке вложенных модулей все командлеты, экспортируемые вложенным модулем, будут экспортированы в состояние глобального сеанса, если модуль в цепочке не ограничивает командлет с помощью ключа КомандлетаToExport .
Если манифест экспортирует псевдонимы для командлетов, этот ключ может удалить командлеты, псевдонимы которых перечислены в ключе AliasesToExport , но этот ключ не может добавить псевдонимы командлетов в список.
Пример: CmdletsToExport = @("Get-MyCmdlet", "Set-MyCmdlet", "Test-MyCmdlet")
ПеременныеToExport
Тип: String[]		 '*' Указывает переменные, экспортируемые модулем в состояние сеанса вызывающего объекта. Разрешено использование подстановочных символов. По умолчанию экспортируются все переменные ('*'). Этот ключ можно использовать для ограничения переменных, экспортируемых модулем.
Состояние сеанса вызывающего объекта может быть глобальным состоянием сеанса или для вложенных модулей, состояние сеанса другого модуля. При цепочке вложенных модулей все переменные, экспортируемые вложенным модулем, будут экспортированы в состояние глобального сеанса, если модуль в цепочке не ограничивает переменную с помощью ключа VariableToExport .
Если манифест также экспортирует псевдонимы для переменных, этот ключ может удалить переменные, псевдонимы которых перечислены в ключе AliasesToExport , но этот ключ не может добавить в список псевдонимы переменных.
Пример: VariablesToExport = @('$MyVariable1', '$MyVariable2', '$MyVariable3')
AliasesToExport
Тип: String[]		 @() Указывает псевдонимы для экспорта из этого модуля, чтобы обеспечить лучшую производительность, не используйте подстановочные знаки и не удаляйте запись, используйте пустой массив, если для экспорта нет псевдонимов. По умолчанию псевдонимы не экспортируются. Этот ключ можно использовать для перечисления псевдонимов, экспортированных модулем.
Модуль экспортирует псевдонимы в состояние сеанса вызывающего объекта. Состояние сеанса вызывающего объекта может быть глобальным состоянием сеанса или для вложенных модулей, состояние сеанса другого модуля. При цепочке вложенных модулей все псевдонимы, экспортируемые вложенным модулем, будут в конечном итоге экспортированы в состояние глобального сеанса, если модуль в цепочке не ограничивает псевдоним с помощью ключа AliasesToExport .
Пример: AliasesToExport = @("MyAlias1", "MyAlias2", "MyAlias3")
DscResourcesToExport
Тип: String[]		 @() Указывает ресурсы DSC для экспорта из этого модуля. Разрешены подстановочные знаки.
Пример: DscResourcesToExport = @("DscResource1", "DscResource2", "DscResource3")
ModuleList
Тип: Object[]		 @() Указывает все модули, упакованные с помощью этого модуля. Эти модули можно вводить по имени, используя строку, разделенную запятыми, или как хэш-таблицу с ключами ModuleName и GUID . Хэш-таблица также может иметь необязательный ключ ModuleVersion . Ключ ModuleList предназначен для использования в качестве инвентаризации модулей. Эти модули не обрабатываются автоматически.
Пример: ModuleList = @("SampleModule", "MyModule", @{ModuleName="MyModule"; ModuleVersion="1.0.0.0"; GUID="50cdb55f-5ab7-489f-9e94-4ec21ff51e59"})
FileList
Тип: String[]		 @() Список всех файлов, упакованных с помощью этого модуля. Как и в ModuleList, FileList является списком инвентаризации и не обрабатывается в противном случае.
Пример: FileList = @("File1", "File2", "File3")
PrivateData
Тип: Object		 @{...} Указывает все частные данные, которые необходимо передать корневому модулю, указанному ключом RootModule (псевдоним : ModuleToProcess). PrivateData — это хэш-таблица, которая состоит из нескольких элементов: Tags, LicenseUri, ProjectURI, IconUri, ReleaseNotes, Prerelease, RequireLicenseAcceptance и ExternalModuleDependencies.
Теги
Тип: String[]		 @() Теги помогают при обнаружении модулей в онлайн-коллекциях.
Пример: Tags = "PackageManagement", "PowerShell", "Manifest"
LicenseUri
Тип: Uri		 <empty string> URL-адрес лицензии для этого модуля.
Пример: LicenseUri = 'https://www.contoso.com/license'
ProjectUri
Тип: Uri		 <empty string> URL-адрес основного веб-сайта для этого проекта.
Пример: ProjectUri = 'https://www.contoso.com/project'
IconUri
Тип: Uri		 <empty string> URL-адрес значка, представляющего этот модуль.
Пример: IconUri = 'https://www.contoso.com/icons/icon.png'
ReleaseNotes
Тип: String		 <empty string> Указывает заметки о выпуске модуля.
Пример: ReleaseNotes = 'The release notes provide information about the module.
Предварительных
Тип: String		 <empty string> Этот параметр был добавлен в PowerShellGet 1.6.6.6. Строка PreRelease , которая определяет модуль как предварительную версию в онлайн-коллекциях.
Пример: PreRelease = 'alpha'
RequireLicenseAcceptance
Тип: Boolean		 $false Этот параметр был добавлен в PowerShellGet 1.5. Пометка, указывающее, требуется ли явное принятие пользователем для установки, обновления или сохранения.
Пример: RequireLicenseAcceptance = $false
ExternalModuleDependencies
Тип: String[]		 @() Этот параметр был добавлен в PowerShellGet версии 2. Список внешних модулей, от которых зависит этот модуль.
Пример: ExternalModuleDependencies = @("ExtModule1", "ExtModule2", "ExtModule3"). Этот список является информационным только. В отличие от RequiredModules, он не используется для принудительного применения зависимостей.
HelpInfoURI
Тип: String		 <empty string> URI HelpInfo этого модуля.
Пример: HelpInfoURI = 'https://www.contoso.com/help'
DefaultCommandPrefix
Тип: String		 <empty string> Префикс по умолчанию для команд, экспортированных из этого модуля. Переопределите префикс по умолчанию с помощью Import-Module -Prefix.
Пример: DefaultCommandPrefix = 'My'

Пример манифеста модуля

Следующий пример манифеста модуля был создан в New-ModuleManifest PowerShell 7 и содержит ключи и значения по умолчанию.

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

}

См. также

  • Last updated on