撰寫 PowerShell 模組之後，您可以新增包含模組相關信息的選擇性模組指令清單。 例如，您可以描述作者、指定模組中的檔案（例如巢狀模組）、執行腳本來自定義用戶的環境、載入類型和格式化檔案、定義系統需求，以及限制模組導出的成員。
建立模組指令清單
模組指令清單 是 PowerShell 數據檔（.psd1），描述模組的內容，並決定模組的處理方式。 指令清單檔是包含索引鍵和值的哈希表的文本檔。 您可將指令清單檔案連結至模組，方法是將指令清單命名為與模組相同的 ，並將指令清單儲存在模組的根目錄中。
對於只包含單一 .psm1 或二進位元件的簡單模組，模組指令清單是選擇性的。 但是，建議盡可能使用模組指令清單，因為它們有助於組織程式代碼並維護版本控制資訊。 而且，需要模組指令清單才能匯出安裝在 全域程式集緩存中的元件。 支援可更新說明功能的模組也需要模組指令清單。 可更新的說明會使用模組指令清單中的 HelpInfoUri 索引鍵來尋找包含模組更新說明檔位置的說明資訊 （HelpInfo XML） 檔案。 如需可更新說明的詳細資訊，請參閱 支援可更新的說明。
若要建立和使用模組指令清單
建立模組指令清單的最佳做法是使用 New-ModuleManifest Cmdlet。 您可以使用參數來指定一或多個指令清單的預設索引鍵和值。 唯一的需求是命名檔案。
New-ModuleManifest會使用指定的值建立模組指令清單，並包含其餘索引鍵及其預設值。 如果您需要建立多個模組，請使用New-ModuleManifest建立模組指令清單範本，以針對不同的模組修改。 如需預設模組指令清單的範例，請參閱 範例模組指令清單。New-ModuleManifest -Path C:\myModuleName.psd1 -ModuleVersion "2.0" -Author "YourNameHere"替代方法是使用所需的最少資訊手動建立模組指令清單的哈希表，ModuleVersion。 您可以使用與模組相同的名稱來儲存盤案，並使用
.psd1擴展名。 然後，您可以編輯檔案，並新增適當的索引鍵和值。在指令清單檔中新增您想要的任何其他元素。
若要編輯指令清單檔，請使用您偏好的任何文本編輯器。 但是，指令清單檔案是包含程式碼的腳本檔案，因此您可能想要在腳本或開發環境中編輯它，例如Visual Studio Code。 指令清單檔的所有元素都是選擇性的，除了 ModuleVersion number 之外。
如需您可以在模組指令清單中包含之索引鍵和值的描述，請參閱 模組指令清單元素 數據表。 如需詳細資訊，請參閱 New-ModuleManifest Cmdlet 中的參數描述。
若要解決基底模組指令清單元素可能未涵蓋的任何案例，您可以選擇將其他程式代碼新增至模組指令清單。
基於安全性考慮，PowerShell 只會在模組指令清單檔案中執行一小部分的可用作業。 一般而言，您可以使用
if語句、算術和比較運算符，以及基本的 PowerShell 數據類型。建立模組指令清單之後，您可以測試它，以確認指令清單中所述的任何路徑都正確。 若要測試模組指令清單，請使用 Test-ModuleManifest。
Test-ModuleManifest myModuleName.psd1請確定您的模組指令清單位於包含模組的目錄最上層。
當您將模組複製到系統並匯入它時，PowerShell 會使用模組指令清單來匯入模組。
或者，您可以藉由點來源指令清單本身來直接測試模組指令清單，並呼叫 Import-Module。
Import-Module .\myModuleName.psd1
模組指令清單元素
下表描述您可以在模組指令清單中包含的專案。 如需詳細資訊，請參閱 about_Module_Manifests。
| 元素 | 預設 | 說明 |
|---|---|---|
|
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 上找到的第一個模組，而且至少具有與 ModuleVersion一樣高的模組，做為 MinimumVersion 參數。 若要匯入特定版本，請使用 Import-Module Cmdlet 的 RequiredVersion 參數。範例： ModuleVersion = '1.0' |
|
GUID 類型: GUID |
'<GUID>' |
用來唯一識別此模組的標識碼。 如果未指定值，New-ModuleManifest 自動產生值。 您目前無法透過 GUID匯入模組。 範例： GUID = 'cfc45206-1e49-459d-a8ad-5b571ef94857' |
|
作者 類型: String |
'<Current user>' |
本課程模組的作者。 如果未指定值，New-ModuleManifest 會使用目前的使用者。 範例： Author = 'AuthorNameHere' |
|
CompanyName 類型: 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，且僅適用於低於 4.5 的 .NET Framework 版本。 範例： DotNetFrameworkVersion = '3.5' |
|
CLRVersion 類型: Version |
<empty string> |
本課程模組所需的 Common Language Runtime （CLR） 最低版本。 此必要條件僅適用於 PowerShell Desktop 版本，例如 Windows PowerShell 5.1，且僅適用於低於 4.5 的 .NET Framework 版本。 範例： CLRVersion = '3.5' |
|
ProcessorArchitecture 類型: ProcessorArchitecture |
<empty string> |
本課程模組所需的處理器架構（無、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") |
|
FormatsToProcess 類型: String[] |
@() |
匯入此課程模組時要載入的格式檔案（.ps1xml）。 範例： FormatsToProcess = @("format1.ps1xml", "format2.ps1xml", "format3.ps1xml") |
|
NestedModules 類型: 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") |
|
CmdletsToExport 類型: String[] |
@() |
指定要從此模組導出的 Cmdlet，以獲得最佳效能，請勿使用通配符，也不會刪除專案，如果沒有要導出的 Cmdlet，請使用空陣列。 根據預設，不會匯出任何 Cmdlet。 您可以使用此金鑰來列出模組所匯出的 Cmdlet。 呼叫端的會話狀態可以是全域會話狀態，或對於巢狀模組而言，另一個模組的會話狀態。 當您鏈結巢狀模組時，巢狀模組所匯出的所有 Cmdlet 都會匯出至全域會話狀態，除非鏈結中的模組使用 CmdletToExport 索引鍵來限制 Cmdlet。 如果指令清單匯出 Cmdlet 的別名，此索引鍵可以移除別名列在 AliasesToExport 機碼中的 Cmdlet，但此機碼無法將 Cmdlet 別名新增至清單中。 範例： CmdletsToExport = @("Get-MyCmdlet", "Set-MyCmdlet", "Test-MyCmdlet") |
|
VariablesToExport 類型: String[] |
'*' |
指定模組匯出至呼叫端工作階段狀態的變數。 允許使用通配符字元。 根據預設，會匯出所有變數 （'*'）。 您可以使用此金鑰來限制模組所匯出的變數。呼叫端的會話狀態可以是全域會話狀態，或對於巢狀模組而言，另一個模組的會話狀態。 當您鏈結巢狀模組時，巢狀模組導出的所有變數都會匯出至全域會話狀態，除非鏈結中的模組使用 VariablesToExport 索引鍵來限制變數。 如果指令清單也會匯出變數的別名，此索引鍵可以移除別名列在 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、發行前版本、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 中新增。
發行前版本 字串，將模組識別為在線資源庫中的發行前版本。 範例： PreRelease = 'alpha' |
|
RequireLicenseAcceptance 類型: Boolean |
$false |
此參數已在PowerShellGet1.5中新增。 旗標，用於指示模組是否需要使用者在安裝、更新或儲存操作時的明確接受。 範例： RequireLicenseAcceptance = $false |
|
ExternalModuleDependencies 類型: String[] |
@() |
此參數已在PowerShellGet v2中新增。 此模組相依的外部模組清單。 範例： ExternalModuleDependencies = @("ExtModule1", "ExtModule2", "ExtModule3"). 此清單僅供參考。 與 RequiredModules 不同，它不會用來強制執行相依性。 |
|
HelpInfoURI 類型: String |
<empty string> |
此課程模組的 HelpInfo URI。 範例： HelpInfoURI = 'https://www.contoso.com/help' |
|
DefaultCommandPrefix 類型: String |
<empty string> |
從本課程模組導出之命令的預設前置詞。 使用 Import-Module -Prefix覆寫預設前置詞。 範例： DefaultCommandPrefix = 'My' |
範例模組指令清單
下列範例模組指令清單是在PowerShell 7中使用 New-ModuleManifest 建立，並包含預設索引鍵和值。
#
# 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 = ''
}
