about_Module_Manifests
簡短描述
描述撰寫模組指令清單檔案的設定和作法。
詳細描述
模組指令清單是包含哈希表的 PowerShell 資料檔 (.psd1
)。
哈希表中的索引鍵/值組描述模組的內容和屬性、定義必要條件,以及控制元件的處理方式。
指令清單不需要載入模組,但需要將模組發佈至 PowerShell 資源庫。 指令清單也可讓您將模組的實作與載入方式分開。 透過指令清單,您可以定義需求、相容性、載入順序等等。
當您不使用 New-ModuleManifest
指定指令清單設定的任何參數時,它會寫入最小的指令清單檔案。 下列代碼段會顯示此預設輸出,並擷取評論和間距以求簡潔:
@{
# 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 = ''
}
在發佈模組之前,您可以使用 Test-ModuleManifest
來驗證模組指令清單。 Test-ModuleManifest
如果指令清單無效或模組無法匯入目前的會話,因為會話不符合指令清單中設定的需求,則傳回錯誤。
在模組指令清單中使用文本程序代碼
指派指令清單檔中設定的值可以是PowerShell所評估的表達式。 這可讓您根據變數建構路徑,並有條件地指派值。
當您使用 Import-Module
匯入模組時,指令清單會以 Restricted
語言模式進行評估。 Restricted
模式會限制可以使用的命令和變數。
允許的命令
Import-LocalizedData
ConvertFrom-StringData
Write-Host
Out-Host
Join-Path
允許的變數
$PSScriptRoot
$PSEdition
$EnabledExperimentalFeatures
- 任何環境變數,例如
$ENV:TEMP
如需詳細資訊,請參閱 about_Language_Modes。
指令清單設定
下列各節詳細說明模組指令清單中的每個可用設定,以及如何使用這些設定。 它們會從設定的摘要開始,後面接著列出下列矩陣:
- 輸入類型:您可以在指令清單中指定此設定的物件類型。
- 必要:如果此值為
Yes
,則需要設定才能匯入模組,並將它發佈至 PowerShell 資源庫。No
如果是 ,則兩者都不需要。PowerShell Gallery
如果是 ,則只需要發佈至 PowerShell 資源庫。 - 如果未設定,則為值:匯入且未明確設定此設定的值。
- 接受通配符:此設定是否可以採用通配符值。
RootModule
此設定會指定模組的主要或根檔案。 匯入模組時,根模組檔案所導出的成員會匯入呼叫端的會話狀態。
值 | |
---|---|
輸入類型 | System.String |
必要 | No |
如果未設定,則為值 | $null |
接受通配符 | No |
值必須是下列其中一項的路徑:
- 文稿 (
.ps1
) - 文稿模組 (
.psm1
) - 模組指令清單 (
.psd1
) - 元件 (
.dll
) - Cmdlet 定義 XML 檔案 (
.cdxml
) - Windows PowerShell 5.1 工作流程 (
.xaml
)
路徑應該相對於模組指令清單。
如果在 RootModule 機碼中指定模組指令清單沒有根檔案,指令清單就會成為模組的主要檔案,而模組會變成指令清單模組(ModuleType = Manifest)。 定義 RootModule 時,模組的類型取決於所使用的擴展名:
- 或
.ps1
.psm1
檔案使模組類型 腳本 - 檔案
.psd1
會讓模組類型 指令清單 - 檔案
.dll
會讓模組類型 為 Binary - 檔案
.cdxml
會讓模組類型 CIM - 檔案
.xaml
會讓模組類型 工作流程
根據預設,會導出 RootModule 中的所有模組成員。
提示
模組載入速度在二進位、腳本和 CIM 模組類型之間有所不同。 如需詳細資訊,請參閱 PowerShell模組撰寫考慮
例如,此模組的 ModuleType 是 指令清單。 此模組唯一可以導出的模組成員是在使用 NestedModules 設定所指定的模組中定義的模組成員。
@{
RootModule = ''
}
注意
此設定也可以在模組指令清單中指定為 ModuleToProcess。 雖然此設定的名稱有效,但最佳做法是改為使用 RootModule 。
ModuleVersion
此設定會指定模組的版本。 當系統上有多個模組版本存在時,當您執行 Import-Module
時,預設會載入最新版本。
值 | |
---|---|
輸入類型 | System.String |
必要 | Yes |
如果未設定,則為值 | 無 |
接受通配符 | No |
當您執行 Import-Module
時,這個設定的值必須可轉換成 System.Version
。
例如,此指令清單會將模組的版本宣告為 '1.2.3'
。
@{
ModuleVersion = '1.2.3'
}
當您匯入模組並檢查 Version 屬性時,請注意它是 System.Version 物件,而不是字串:
$ExampleModule = Import-Module example.psd1
$ExampleModule.Version
$ExampleModule.Version.GetType().Name
Major Minor Build Revision
----- ----- ----- --------
1 2 3 -1
Version
CompatiblePSEditions
此設定會指定模組的相容 PSEditions。
值 | |
---|---|
輸入類型 | System.String[] |
接受的值 | Desktop , Core |
必要 | No |
如果未設定,則為值 | $null |
接受通配符 | No |
如果此設定的值是 $null
,則不論會話的 PSEdition 為何,都可以匯入模組。 您可以將它設定為一或多個可接受的值。
如需 PSEdition 的相關信息,請參閱:
定義此設定時,模組只能匯入設定中包含自動變數值的會話 $PSEdition
。
注意
$PSEdition
因為自動變數是在 5.1 版中引進的,舊版的 Windows PowerShell 無法載入使用 CompatiblePSEditions 設定的模組。
例如,您可以在任何工作階段中匯入此模組指令清單:
@{
# CompatiblePSEditions = @()
}
透過指定的設定,此模組只能在自動變數值為Core
的會話$PSEdition
中匯入。
@{
CompatiblePSEditions = @('Core')
}
GUID
此設定會指定模組的唯一標識符。 GUID 可用來區分具有相同名稱的模組。
值 | |
---|---|
輸入類型 | System.String |
必要 | No |
如果未設定,則為值 | 00000000-0000-0000-0000-000000000000 |
接受通配符 | No |
當您執行 Import-Module
時,這個設定的值必須可轉換成 System.Guid
。
警告
雖然這不是必要的設定,但在指令清單中未指定 GUID 沒有任何優點,而且可能會導致模組的名稱衝突。
您可以在指令清單中建立要使用的新 GUID:
New-Guid | Select-Object -ExpandProperty Guid
8456b025-2fa5-4034-ae47-e6305f3917ca
@{
GUID = '8456b025-2fa5-4034-ae47-e6305f3917ca'
}
如果電腦上有另一個具有相同名稱的模組,您仍然可以藉由指定模組的完整名稱來匯入您想要的模組:
Import-Module -FullyQualifiedName @{
ModuleName = 'Example'
GUID = '8456b025-2fa5-4034-ae47-e6305f3917ca'
ModuleVersion = '1.0.0'
}
作者
此設定可識別模組作者。
值 | |
---|---|
輸入類型 | System.String |
必要 | PowerShell 資源庫 |
如果未設定,則為值 | $null |
接受通配符 | No |
此指令清單會宣告模組的作者是 Contoso 開發人員體驗小組。
@{
Author = 'Contoso Developer Experience Team'
}
CompanyName
此設定會識別建立模組的公司或廠商。
值 | |
---|---|
輸入類型 | System.String |
必要 | No |
如果未設定,則為值 | $null |
接受通配符 | No |
此指令清單會宣告模組是由 Contoso, Ltd 建立。
@{
CompanyName = 'Contoso, Ltd.'
}
著作權
此設定會指定模組的著作權聲明。
值 | |
---|---|
輸入類型 | System.String |
必要 | No |
如果未設定,則為值 | $null |
接受通配符 | No |
自 2022 年起,本指令清單宣告保留 Contoso, Ltd. 的所有權利。
@{
Copyright = '(c) 2022 Contoso, Ltd. All rights reserved.'
}
描述
此設定描述高階的模組。
值 | |
---|---|
輸入類型 | System.String |
必要 | PowerShell 資源庫 |
如果未設定,則為值 | $null |
接受通配符 | No |
此指令清單包含簡短描述。 您也可以使用 here-string 來撰寫較長或多行的描述。
@{
Description = 'Example commands to show a valid module manifest'
}
PowerShellVersion
此設定會指定本課程模組所需的最低 PowerShell 版本。
值 | |
---|---|
輸入類型 | System.String |
必要 | No |
如果未設定,則為值 | $null |
接受通配符 | No |
當您執行 Import-Module
時,這個設定的值必須可轉換成 System.Version
。
如果未設定此設定,PowerShell 不會根據目前的版本限制模組的匯入。
例如,此指令清單會宣告模組與每個版本的 PowerShell 和 Windows PowerShell 相容。
@{
# PowerShellVersion = ''
}
將 PowerShellVersion 設定為 7.2
,您只能在 PowerShell 7.2 或更高版本中匯入模組。
@{
PowerShellVersion = '7.2'
}
PowerShellHostName
此設定會指定模組所需的PowerShell主機程式名稱,例如 Windows PowerShell ISE 主機 或 ConsoleHost。
值 | |
---|---|
輸入類型 | System.String |
必要 | No |
如果未設定,則為值 | $null |
接受通配符 | No |
您可以使用語句找到會話 $Host.Name
的主機名稱。 例如,您可以看到遠程會話的主機是 ServerRemoteHost , 而不是 ConsoleHost:
$Host.Name
Enter-PSSession -ComputerName localhost
$Host.Name
ConsoleHost
[localhost]: PS C:\Users\username\Documents> $Host.Name
ServerRemoteHost
此模組可以匯入任何主機。
@{
# PowerShellHostName = ''
}
當 PowerShellHostName 設定為 ServerRemoteHost
時,您只能在遠端 PowerShell 工作階段中匯入模組。
@{
PowerShellHostName = 'ServerRemoteHost'
}
PowerShellHostVersion
此設定會指定模組所需的 PowerShell 主機程式最低版本。
值 | |
---|---|
輸入類型 | System.String |
必要 | No |
如果未設定,則為值 | $null |
接受通配符 | No |
當您執行 Import-Module
時,這個設定的值必須可轉換成 System.Version
。
警告
雖然此設定可以在不使用 PowerShellHostName 設定的情況下使用,但會增加非預期行為的機率。 當您也使用PowerShellHostName設定時,才使用此設定。
例如,不論主機的版本為何,此指令清單的模組都可以從 ConsoleHost 中執行的任何 PowerShell 會話匯入。
@{
PowerShellHostName = 'ConsoleHost'
# PowerShellHostVersion = ''
}
當 PowerShellHostVersion 設定為 5.1
時,您只能從主機版本為 5.1 或更高版本的 ConsoleHost 中執行的任何 PowerShell 會話匯入模組。
@{
PowerShellHostName = 'ConsoleHost'
PowerShellHostVersion = '5.1'
}
DotNetFrameworkVersion
此設定會指定模組所需的 Microsoft .NET Framework 最低版本。
值 | |
---|---|
輸入類型 | System.String |
必要 | No |
如果未設定,則為值 | $null |
接受通配符 | No |
注意
此設定僅適用於 PowerShell Desktop 版本,例如 Windows PowerShell 5.1,且僅適用於低於 4.5 的 .NET Framework 版本。 這項需求對較新版本的PowerShell或 .NET Framework 沒有任何作用。
當您執行 Import-Module
時,這個設定的值必須可轉換成 System.Version
。
例如,此指令清單會宣告其模組可以在任何 PowerShell 或 Windows PowerShell 會話中匯入,而不論 Microsoft .NET Framework 的版本為何。
@{
# DotNetFrameworkVersion = ''
}
當 DotNetFrameworkVersion 設定為 4.0
時,您可以在 Windows PowerShell 的任何會話中匯入此模組,其中 Microsoft .NET Framework 的最新版本至少為 4.0。 您也可以在任何 PowerShell 工作階段中匯入它。
@{
DotNetFrameworkVersion = '4.0'
}
CLRVersion
此設定會指定模組所需的 Microsoft .NET Framework Common Language Runtime (CLR) 最低版本。
值 | |
---|---|
輸入類型 | System.String |
必要 | No |
如果未設定,則為值 | $null |
接受通配符 | No |
注意
此設定僅適用於 PowerShell Desktop 版本,例如 Windows PowerShell 5.1,且僅適用於低於 4.5 的 .NET Framework 版本。 這項需求對較新版本的PowerShell或 .NET Framework 沒有任何作用。
當您執行 Import-Module
時,這個設定的值必須可轉換成 System.Version
。
例如,此指令清單會宣告其模組可以在任何 PowerShell 或 Windows PowerShell 會話中匯入,而不論 Microsoft .NET Framework 的 CLR 版本為何。
@{
# CLRVersion = ''
}
將 CLRVersion 設定為 4.0
時,您可以在 Windows PowerShell 的任何會話中匯入此模組,其中最新可用的 CLR 版本至少為 4.0。 您也可以在任何 PowerShell 工作階段中匯入它。
@{
CLRVersion = '4.0'
}
ProcessorArchitecture
此設定會指定模組所需的處理器架構。
值 | |
---|---|
輸入類型 | System.String |
接受的值 | None 、、MSIL X86 、IA64 、、Amd64 、Arm |
必要 | No |
如果未設定,則為值 | None |
接受通配符 | No |
當您執行 Import-Module
時,這個設定的值必須可轉換成 System.Reflection.ProcessorArchitecture
。
例如,此指令清單會宣告其模組可以在任何會話中匯入,而不論系統的處理器架構為何。
@{
# ProcessorArchitecture = ''
}
將 ProcessorArchitecture 設定為 Amd64
時,您只能在具有相符架構的電腦上執行的會話中匯入此模組。
@{
ProcessorArchitecture = 'Amd64'
}
RequiredModules
此設定會指定必須處於全域會話狀態的模組。 如果所需的模組不是處於全域會話狀態,PowerShell 會匯入它們。
如果無法使用所需的模組,命令會 Import-Module
失敗。
值 | |
---|---|
輸入類型 | System.String[] , System.Collections.Hashtable[] |
必要 | No |
如果未設定,則為值 | $null |
接受通配符 | No |
此設定的專案可以是模組名稱、完整模組規格或模組檔案的路徑。
當值為路徑時,路徑可以是完整或相對路徑。
當值是名稱或模組規格時,PowerShell 會 搜尋 PSModulePath 中的指定模組。
模組規格是具有下列索引鍵的哈希表。
ModuleName
- 必要。 指定模組名稱。GUID
- 選擇性。 指定模組的 GUID。- 也必須指定下列三個索引鍵中的至少一個。 索引
RequiredVersion
鍵不能與 或MaximumVersion
索引鍵搭配ModuleVersion
使用。 您可以藉由同時指定ModuleVersion
和MaximumVersion
索引鍵,來定義模組可接受的版本範圍。ModuleVersion
- 指定模組的最低可接受的版本。RequiredVersion
- 指定模組的確切必要版本。MaximumVersion
- 指定模組的最大可接受的版本。
注意
RequiredVersion
已在 Windows PowerShell 5.0 中新增。
MaximumVersion
已在 Windows PowerShell 5.1 中新增。
例如,此指令清單會宣告其模組不需要任何其他模組的功能。
@{
# RequiredModules = @()
}
此指令清單會宣告它需要 PSReadLine 模組。 當您在此指令清單上執行 Import-Module
時,PowerShell 會匯入可供會話使用的最新版本 PSReadLine。 如果沒有可用的版本,匯入會傳回錯誤。
@{
RequiredModules = @(
'PSReadLine'
)
}
提示
在 PowerShell 2.0 中, Import-Module
不會自動匯入必要的模組。 它只會驗證所需的模組是否處於全域會話狀態。
此指令清單宣告其需要其本身模組資料夾中廠商的 PSReadLine 模組版本。 當您在此指令清單上執行 Import-Module
時,PowerShell 會從指定的路徑匯入廠商的 PSReadLine。
@{
RequiredModules = @(
'Vendored\PSReadLine\PSReadLine.psd1'
)
}
此指令清單會宣告它特別需要 PSReadLine 模組 2.0.0 版。 當您在此指令清單上執行 Import-Module
時,PowerShell 會匯入 PSReadLine 2.0.0 版,如果有的話。 如果無法使用, Import-Module
則傳回錯誤。
@{
RequiredModules = @(
@{
ModuleName = 'PSReadLine'
RequiredVersion = '2.0.0'
}
)
}
此指令清單會宣告它需要 PSReadLine 模組在 2.0.0 版或更新版本匯入。
@{
RequiredModules = @(
@{
ModuleName = 'PSReadLine'
ModuleVersion = '2.0.0'
}
)
}
此指令清單會宣告它要求 PSReadLine 模組在 2.0.0 版或更低版本匯入。
@{
RequiredModules = @(
@{
ModuleName = 'PSReadLine'
MaximumVersion = '2.0.0'
}
)
}
此指令清單宣告其需要 PSDesiredStateConfiguration 模組在等於或高於 2.0.0 的版本匯入,但不高於 2.99.99。
@{
RequiredModules = @(
@{
ModuleName = 'PSDesiredStateConfiguration'
ModuleVersion = '2.0.0'
MaximumVersion = '2.99.99'
}
)
}
RequiredAssemblies
此設定會指定模組所需的元件 (.dll
) 檔案。
PowerShell 會先載入指定的元件,再更新類型或格式、匯入巢狀模組,或匯入 RootModule 機碼值中指定的模組檔案。
值 | |
---|---|
輸入類型 | System.String[] |
必要 | No |
如果未設定,則為值 | $null |
接受通配符 | No |
這個設定的專案可以是元件的檔名或路徑。 列出所有必要的元件,即使它們也列為 NestedModules 設定中的二進位模組也一樣。
此指令清單需要 example.dll
元件。 載入此指令清單中指定的任何格式或類型檔案之前,PowerShell 會從Assemblies
與模組指令清單位於相同目錄中的資料夾載入example.dll
。
@{
RequiredAssemblies = @(
'Assemblies\Example.dll'
)
}
ScriptsToProcess
此設定會指定匯入模組時,以呼叫端會話狀態執行的腳本 (.ps1
) 檔案。 您可以使用這些腳本來準備環境,就像您可能使用登入腳本一樣。
值 | |
---|---|
輸入類型 | System.String[] |
必要 | No |
如果未設定,則為值 | $null |
接受通配符 | No |
若要指定在模組會話狀態中執行的腳本,請使用 NestedModules 機碼。
當您匯入此指令清單時,PowerShell 會在目前的工作階段中執行 Initialize.ps1
。
@{
ScriptsToProcess = @(
'Scripts\Initialize.ps1'
)
}
例如,如果 Initialize.ps1
寫入參考訊息並設定 $ExampleState
變數:
if ([string]::IsNullOrEmpty($ExampleState)) {
Write-Information "Example not initialized."
Write-Information "Initializing now..."
$ExampleState = 'Initialized'
} else {
Write-Information "Example already initialized."
}
當您匯入模組時,腳本會執行,並在會話中撰寫這些訊息和設定 $ExampleState
。
$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.
TypesToProcess
此設定會指定匯入模組時所執行的類型檔案 (.ps1xml
)。
值 | |
---|---|
輸入類型 | System.String[] |
必要 | No |
如果未設定,則為值 | $null |
接受通配符 | No |
當您匯入模組時,PowerShell 會使用指定的檔案執行 Update-TypeData
Cmdlet。 因為類型檔案沒有範圍,所以會影響會話中的所有會話狀態。
如需類型檔案的詳細資訊,請參閱 about_Types.ps1xml
例如,當您匯入此指令清單時,PowerShell 會從Types
與模組指令清單位於相同目錄中的資料夾載入檔案中指定的Example.ps1xml
類型。
@{
TypesToProcess = @(
'Types\Example.ps1xml'
)
}
FormatsToProcess
此設定會指定匯入模組時所執行的格式化檔案 (.ps1xml
)。
值 | |
---|---|
輸入類型 | System.String[] |
必要 | No |
如果未設定,則為值 | $null |
接受通配符 | No |
當您匯入模組時,PowerShell 會使用指定的檔案執行 Update-FormatData
Cmdlet。 由於格式化檔案的範圍並未設定,因此會影響會話中的所有會話狀態。
如需類型檔案的詳細資訊,請參閱 about_Format.ps1xml
例如,當您匯入此模組時,PowerShell 會從Formats
與模組指令清單位於相同目錄中的資料夾載入檔案中指定的Example.ps1xml
格式。
@{
FormatsToProcess = @(
'Formats\Example.ps1xml'
)
}
NestedModules
此設定會指定匯入模組會話狀態的腳本模組 (.psm1
) 和二進位模組 (.dll
)。 您也可以指定文稿檔案 (.ps1
)。 此設定中的檔案會依照列出的順序執行。
值 | |
---|---|
輸入類型 | System.String[] , System.Collections.Hashtable[] |
必要 | No |
如果未設定,則為值 | $null |
接受通配符 | No |
此設定的專案可以是模組名稱、完整模組規格,或模組或腳本檔案的路徑。
當值為路徑時,路徑可以是完整或相對路徑。
當值為模組名稱或規格時,PowerShell 會在 PSModulePath 中搜尋指定的模組。
模組規格是具有下列索引鍵的哈希表。
ModuleName
- 必要。 指定模組名稱。GUID
- 選擇性。 指定模組的 GUID。- 也必須指定下列三個索引鍵中的至少一個。 索引
RequiredVersion
鍵不能與 或MaximumVersion
索引鍵搭配ModuleVersion
使用。 您可以藉由同時指定ModuleVersion
和MaximumVersion
索引鍵,來定義模組可接受的版本範圍。ModuleVersion
- 指定模組的最低可接受的版本。RequiredVersion
- 指定模組的確切必要版本。MaximumVersion
- 指定模組的最大可接受的版本。
注意
RequiredVersion
已在 Windows PowerShell 5.0 中新增。
MaximumVersion
已在 Windows PowerShell 5.1 中新增。
任何需要從巢狀模組導出的專案,都必須由巢狀模組使用 Export-ModuleMember
Cmdlet 匯出,或列在其中一個匯出屬性中:
- FunctionsToExport
- CmdletsToExport
- VariablesToExport
- AliasesToExport
模組會話狀態中的巢狀模組可供根模組使用,但不會由 Get-Module
呼叫端會話狀態中的命令傳回。
此設定中列出的文稿 (.ps1
) 是在模組的工作階段狀態中執行,而不是在呼叫端的作業階段狀態中執行。 若要在呼叫端的會話狀態中執行腳本,請在 ScriptsToProcess 設定中列出腳本檔名。
例如,當您匯入此指令清單時,模組 Helpers.psm1
會載入根模組的會話狀態。 除非另有限制,否則會匯出巢狀模組中宣告的任何 Cmdlet。
@{
NestedModules = @(
'Helpers\Helpers.psm1'
)
}
FunctionsToExport
此設定會指定模組導出的函式。 您可以使用此設定來限制模組所匯出的函式。 它可以從導出的函式清單中移除函式,但無法將函式新增至清單。
值 | |
---|---|
輸入類型 | System.String[] |
必要 | No |
如果未設定,則為值 | $null |
接受通配符 | Yes |
您可以使用通配符指定此設定中的專案。 匯出函式清單中的所有相符函式都會匯出。
提示
為了達到效能和可探索性,您應該一律明確列出您希望模組在此設定中導出的函式,而不需使用任何通配符。
例如,當您匯入已批注化設定的模組時,會匯出根模組和任何巢狀模組中的所有函式。
@{
# FunctionsToExport = @()
}
此指令清單的功能與完全不指定設定相同。
@{
FunctionsToExport = '*'
}
當 FunctionsToExport 設定為空數位時,當您匯入此模組時,根模組或任何巢狀模組匯出都無法使用。
@{
FunctionsToExport = @()
}
注意
如果您使用 命令建立模組指令清單 New-ModuleManifest
,但未指定 FunctionsToExport 參數,則建立的指令清單會指定此設定為空數位。 除非您編輯指令清單,否則不會匯出模組中的函式。
當 FunctionsToExport 設定為只包含 Get-Example
函式時,當您只匯入此模組時,即使 Get-Example
根模組或任何巢狀模組導出其他函式也一樣。
@{
FunctionsToExport = @(
'Get-Example'
)
}
使用 通配符字串設定 FunctionsToExport 時,當您匯入此模組時,即使根模組或任何巢狀模組已將其他函式導出為模塊成員,其名稱結尾 Example
為可用的函式也一樣。
@{
FunctionsToExport = @(
'*Example'
)
}
CmdletsToExport
此設定會指定模組導出的 Cmdlet。 您可以使用此設定來限制模組所匯出的 Cmdlet。 它可以從導出的模組成員清單中移除 Cmdlet,但無法將 Cmdlet 新增至清單。
值 | |
---|---|
輸入類型 | System.String[] |
必要 | No |
如果未設定,則為值 | $null |
接受通配符 | Yes |
您可以使用通配符指定此設定中的專案。 匯出 Cmdlet 清單中的所有相符 Cmdlet 都會匯出。
提示
為了達到效能和可探索性,您應該一律明確列出您希望模組在此設定中導出的 Cmdlet,而不需使用任何通配符。
例如,當您匯入已加上此設定的模組加上批注時,根模組中的所有 Cmdlet 和任何巢狀模組都會匯出。
@{
# CmdletsToExport = @()
}
此指令清單的功能與完全不指定設定相同。
@{
CmdletsToExport = '*'
}
當 CmdletsToExport 設定為空陣列時,當您匯入此模組時,沒有任何 Cmdlet 會匯出根模組或任何巢狀模組。
@{
CmdletsToExport = @()
}
注意
如果您使用 命令建立模組指令清單 New-ModuleManifest
,但未指定 CmdletsToExport 參數,則所建立的指令清單具有指定為空數位的這個設定。 除非您編輯指令清單,否則不會匯出模組中的 Cmdlet。
當 CmdletsToExport 設定為只包含 Get-Example
Cmdlet 時,當您只 Get-Example
匯入此模組時,Cmdlet 才可供使用,即使根模組或任何巢狀模組導出其他 Cmdlet 也一樣。
@{
CmdletsToExport = @(
'Get-Example'
)
}
使用 通配符字串設定 CmdletToExport 時,當您匯入此模組時,即使根模組或任何巢狀模組以模組成員的形式匯出其他 Cmdlet,其名稱結尾 Example
為可用的 Cmdlet 也一樣。
@{
CmdletsToExport = @(
'*Example'
)
}
VariablesToExport
此設定會指定模組導出的變數。 您可以使用此設定來限制模組匯出的變數。 它可以從導出的模組成員清單中移除變數,但無法將變數新增至清單。
值 | |
---|---|
輸入類型 | System.String[] |
必要 | No |
如果未設定,則為值 | $null |
接受通配符 | Yes |
您可以使用通配符指定此設定中的專案。 匯出模組成員清單中的所有相符變數都會匯出。
提示
為了達到效能和可探索性,您應該一律明確列出您希望模組在此設定中導出的變數,而不需使用任何通配符。
例如,當您匯入已加上此設定的模組加上批注時,會匯出根模組和任何巢狀模組中的所有變數。
@{
# VariablesToExport = @()
}
此指令清單的功能與完全不指定設定相同。
@{
VariablesToExport = '*'
}
注意
如果您使用 命令建立模組指令清單 New-ModuleManifest
,但未指定 VariablesToExport 參數,則所建立的指令清單會指定為 '*'
。 除非您編輯指令清單,否則會匯出模組中的所有變數。
當 VariablesToExport 設定為空陣列時,當您匯入此模組時,根模組或任何巢狀模組匯出都無法使用變數。
@{
VariablesToExport = @()
}
當 VariablesToExport 設定為只包含 SomeExample
變數時,當您只匯入此模組時 $SomeExample
,即使根模組或任何巢狀模組導出其他變數也一樣。
@{
VariablesToExport = @(
'SomeExample'
)
}
使用 通配符字串設定 VariablesToExport 時,當您匯入此模組時,即使根模組或任何巢狀模組會將其他變數匯出為模組成員,但名稱結尾 Example
為 可用的變數也一樣。
@{
VariablesToExport = @(
'*Example'
)
}
DscResourcesToExport
此設定會指定模組導出的 DSC 資源。 您可以使用此設定來限制模組匯出的類別型 DSC 資源。 它可以從導出的模組成員清單中移除 DSC 資源,但無法將 DSC 資源新增至清單。
值 | |
---|---|
輸入類型 | System.String[] |
必要 | No |
如果未設定,則為值 | $null |
接受通配符 | Yes |
您可以使用通配符指定此設定中的專案。 模組中的所有相符類別型 DSC 資源都會匯出。
提示
為了探索能力,您應該一律明確地列出模組匯出的所有 DSC 資源。
如需撰寫和使用 DSC 資源的詳細資訊,請參閱 DSC 的檔。
此指令清單會匯出根模組和任何巢狀模組中定義的所有類別型和MOF型 DSC 資源。
@{
# DscResourcesToExport = @()
}
這個指令清單會匯出根模組和任何巢狀模組中定義的所有MOF型 DSC 資源,但只有一個以類別為基礎的 DSC 資源。 ExampleClassResource
@{
DscResourcesToExport = @(
'ExampleClassResource'
)
}
此指令清單會匯出它所包含的所有 DSC 資源。 即使未列出MOF型資源,模組仍會匯出它。
@{
DscResourcesToExport = @(
'ExampleClassResource'
'ExampleMofResourceFirst'
)
}
ModuleList
這個設定是此設定中包含的模組資訊清單清單清單。 此清單不會影響模組的行為。
值 | |
---|---|
輸入類型 | System.String[] , System.Collections.Hashtable[] |
必要 | No |
如果未設定,則為值 | $null |
接受通配符 | No |
此設定的專案可以是模組名稱、完整模組規格,或模組或腳本檔案的路徑。
當值為路徑時,路徑可以是完整或相對路徑。
當值為模組名稱或規格時,PowerShell 會在 PSModulePath 中搜尋指定的模組。
模組規格是具有下列索引鍵的哈希表。
ModuleName
- 必要。 指定模組名稱。GUID
- 選擇性。 指定模組的 GUID。- 也必須指定下列三個索引鍵中的至少一個。 索引
RequiredVersion
鍵不能與 或MaximumVersion
索引鍵搭配ModuleVersion
使用。 您可以藉由同時指定ModuleVersion
和MaximumVersion
索引鍵,來定義模組可接受的版本範圍。ModuleVersion
- 指定模組的最低可接受的版本。RequiredVersion
- 指定模組的確切必要版本。MaximumVersion
- 指定模組的最大可接受的版本。
注意
RequiredVersion
已在 Windows PowerShell 5.0 中新增。
MaximumVersion
已在 Windows PowerShell 5.1 中新增。
此指令清單不提供其包含之模組的信息清單。 它可能或可能沒有模組。 即使未指定此設定,RootModule、ScriptsToProcess 或 NestedModules 設定中所列的任何模組仍會正常運作。
@{
# ModuleList = @()
}
這個指令清單會宣告它所包含的唯一模組是 Example.psm1
和 子模組 First.psm1
,以及 Second.psm1
資料夾中的 Submodules
。
@{
ModuleList = @(
'Example.psm1'
'Submodules\First.psm1'
'Submodules\Second.psm1'
)
}
檔案清單
此設定是本課程模組中包含的檔案資訊清單清單清單。 此清單不會影響模組的行為。
值 | |
---|---|
輸入類型 | System.String[] |
必要 | No |
如果未設定,則為值 | $null |
接受通配符 | Yes |
此設定的項目應該是包含模組指令清單之資料夾之檔案的相對路徑。
當使用者針對已定義此設定的指令清單呼叫 Get-Module
時, FileList 屬性會包含這些檔案的完整路徑,並將模組的路徑與每個專案的相對路徑聯結。
此指令清單不包含其檔案清單。
@{
# FileList = @()
}
此指令清單會宣告它所包含的唯一檔案會列在此設定中。
@{
FileList = @(
'Example.psd1'
'Example.psm1'
'Assemblies\Example.dll'
'Scripts\Initialize.ps1'
'Submodules\First.psm1'
'Submodules\Second.psm1'
)
}
PrivateData
此設定會定義根模組範圍中任何命令或函式可用的數據哈希表。
值 | |
---|---|
輸入類型 | System.Collections.Hashtable |
必要 | PowerShell 資源庫,克雷森多 |
如果未設定,則為值 | $null |
接受通配符 | No |
當您匯出 Crescendo 指令清單以建立新模組時, Export-CrescendoModule
請將兩個密鑰新增至 PrivateData
- CrescendoGenerated - 導出模組時的時間戳
- CrescendoVersion - 用來導出模組的 Crescendo 版本
您可以新增自己的金鑰來儲存您要追蹤的元資料。新增至此設定的任何索引鍵都可供根模組中的函式和 Cmdlet 使用 $MyInvocation.MyCommand.Module.PrivateData
。 哈希表在模組範圍本身中無法使用,只能在您在模組中定義的 Cmdlet 中使用。
例如,此指令清單會在 PrivateData 中定義 PublishedDate 金鑰。
@{
PrivateData = @{
PublishedDate = '2022-06-01'
}
}
模組中的 Cmdlet 可以使用 變數來存取此值 $MyInvocation
。
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"
}
}
匯入模組之後,函式會使用 PrivateData 的值來判斷模組何時發佈。
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
PSData 子屬性會定義支援特定擴充案例之值的哈希表。
值 | |
---|---|
輸入類型 | System.Collections.Hashtable |
必要 | PowerShell 資源庫、實驗性功能、Crescendo 模組 |
如果未設定,則為值 | $null |
接受通配符 | No |
PSData 子屬性用於下列案例:
- PowerShell 資源庫 - 當您使用
New-ModuleManifest
Cmdlet 建立模組指令清單時,會預先填入 PSData 哈希表,其中包含將模組發佈至 PowerShell 資源庫 時所需的位置持有者索引鍵。 如需模組指令清單和發佈至 PowerShell 資源庫 的詳細資訊,請參閱影響 PowerShell 資源庫 UI 的封裝指令清單值。 - 實驗性功能 - 實驗功能的元數據會保留在 PSData 的 ExperimentalFeatures 屬性中。 ExperimentalFeatures 屬性是包含功能名稱和描述的哈希表數位。 如需詳細資訊,請參閱 在模組中宣告實驗性功能。
- Crescendo 模組 - 當您匯出 Crescendo 指令清單以建立新模組時,
Export-CrescendoModule
請將值CrescendoBuilt
新增至 PSData.Tags 屬性。 您可以使用此標籤,在使用 Crescendo 建立的 PowerShell 資源庫 中尋找模組。 如需詳細資訊,請參閱 Export-CrescendoModule。
HelpInfoURI
此設定會指定模組之 HelpInfo XML 檔案的因特網位址。
值 | |
---|---|
輸入類型 | System.String |
必要 | No |
如果未設定,則為值 | $null |
接受通配符 | No |
此設定的值必須是以 HTTP 或 HTTPs 開頭的統一資源識別碼 (URI)。
HelpInfo XML 檔案支援 PowerShell 3.0 中引進的可更新說明功能。 其中包含模組可下載說明檔的位置,以及每個支援地區設定的最新說明檔版本號碼的相關信息。
如需可更新說明的相關信息,請參閱 about_Updatable_Help。 如需 HelpInfo XML 檔案的相關信息,請參閱 支援可更新的說明。
例如,此課程模組支援可更新的說明。
@{
HelpInfoUri = 'http://https://go.microsoft.com/fwlink/?LinkID=603'
}
DefaultCommandPrefix
此設定會指定在模組中彙入會話時,模組中所有命令名詞前面加上的前置詞。 前置詞有助於防止用戶會話中的命令名稱衝突。
值 | |
---|---|
輸入類型 | System.String |
必要 | No |
如果未設定,則為值 | $null |
接受通配符 | No |
模組用戶可以藉由指定 Cmdlet 的 Import-Module
Prefix 參數來覆寫此前置詞。
此設定是在PowerShell 3.0中引進的。
匯入此指令清單時,從此模組 Example
彙入的任何 Cmdlet 會在其名稱前面加上名詞。 例如, Get-Item
會匯入為 Get-ExampleItem
。
@{
DefaultCommandPrefix = 'Example'
}