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 的相關信息，請參閱：

• about_PowerShell_Editions
• 具有相容 PowerShell 版本的模組。

定義此設定時，模組只能匯入設定中包含自動變數值的會話 $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、、MSILX86、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'
}

另請參閱

• about_PowerShell_Editions
• New-ModuleManifest
• Test-ModuleManifest
• 具有相容 PowerShell 版本的模組
• 影響 PowerShell 資源庫 UI 的套件指令清單值
• PowerShell 模組撰寫考慮