建立新的模組資訊清單。

語法

New-ModuleManifest [-Path] <string> -Author <string> -CompanyName <string> -Copyright <string> -Description <string> -FileList <string[]> -FormatsToProcess <string[]> -ModuleToProcess <string> -NestedModules <string[]> -RequiredAssemblies <string[]> -TypesToProcess <string[]> [-AliasesToExport <string[]>] [-ClrVersion <Version>] [-CmdletsToExport <string[]>] [-DotNetFrameworkVersion <Version>] [-FunctionsToExport <string[]>] [-Guid <Guid>] [-ModuleList <Object[]>] [-ModuleVersion <Version>] [-PassThru] [-PowerShellHostName <string>] [-PowerShellHostVersion <Version>] [-PowerShellVersion <Version>] [-PrivateData <Object>] [-ProcessorArchitecture {<None> | <MSIL> | <X86> | <IA64> | <Amd64>}] [-RequiredModules <Object[]>] [-ScriptsToProcess <string[]>] [-VariablesToExport <string[]>] [-Confirm] [-WhatIf] [<CommonParameters>]

描述

New-ModuleManifest Cmdlet 會建立新的模組資訊清單 (.psd1) 檔案、填入其值,並且以指定的路徑來儲存資訊清單檔案。

模組作者可以使用這個 Cmdlet 來建立其模組的資訊清單。模組資訊清單是包含雜湊表的 .psd1 檔案。雜湊表中的索引鍵和值會描述模組的內容和屬性、定義必要條件,以及決定元件的處理方式。模組不需要有資訊清單。

New-ModuleManifest 會建立內含所有常用資訊清單索引鍵的資訊清單,因此您可以使用此預設輸出做為資訊清單範本。若要新增或變更值,或是新增此 Cmdlet 不會新增的模組索引鍵,請在文字編輯器中開啟產生的檔案。

此 Cmdlet 的每個參數 (Path 和 PassThru 除外) 都會建立模組資訊清單索引鍵及其值。在模組資訊清單中,只有 ModuleVersion 索引鍵是必要項。不過,此 Cmdlet 還有其他幾個必要的參數。因此,您可以輸入 "New-ModuleManifest" 命令且不指定參數,讓 Cmdlet 提示您輸入其他常用索引鍵的值。若要將值保留空白,請按 ENTER。

如需模組資訊清單之格式、作用和需求的完整描述,請參閱 MSDN (Microsoft Developer Network) Library 中的<如何撰寫模組資訊清單>(英文),網址為:https://go.microsoft.com/fwlink/?LinkId=143613。

參數

-AliasesToExport <string[]>

指定模組匯出的別名。允許使用萬用字元。

您可以使用此參數來限制模組所匯出的別名。它可以從已匯出的別名清單中移除別名,但是不能在清單中新增別名。

如果您省略此參數,New-ModuleManifest 就會建立值為 * (全部) 的 AliasesToExport 索引鍵,表示資訊清單將匯出該模組所匯出的所有別名。

必要?

false

位置?

named

預設值

* (all)

接受管線輸入?

false

接受萬用字元?

true

-Author <string>

指定模組作者。

此參數是 Cmdlet 的必要項,但是 Author 索引鍵不是資訊清單的必要項。如果省略此參數,且未於出現提示時輸入值,New-ModuleManifest 就會建立值為目前使用者名稱的 Author 索引鍵。

必要?

true

位置?

named

預設值

Name of the current user

接受管線輸入?

false

接受萬用字元?

false

-ClrVersion <Version>

指定模組需要的 Microsoft .NET Framework Common Language Runtime (CLR) 版本。

如果省略此參數,New-ModuleManifest 會建立值為空字串的 CLRVersion 索引鍵。

必要?

false

位置?

named

預設值

接受管線輸入?

false

接受萬用字元?

false

-CmdletsToExport <string[]>

指定模組匯出的 Cmdlet。允許使用萬用字元。

您可以使用此參數來限制模組所匯出的 Cmdlet。它可以從已匯出的 Cmdlet 清單中移除 Cmdlet,但是不能在清單中新增 Cmdlet。

如果您省略此參數,New-ModuleManifest 就會建立值為 * (全部) 的 CmdletsToExport 索引鍵,表示資訊清單將匯出該模組所匯出的所有 Cmdlet。

必要?

false

位置?

named

預設值

* (all)

接受管線輸入?

false

接受萬用字元?

true

-CompanyName <string>

識別建立模組的公司或廠商。

此參數是 Cmdlet 的必要項,但是 CompanyName 索引鍵不是資訊清單的必要項。如果省略此參數,且未於出現提示時輸入值,New-ModuleManifest 就會建立值為 "Unknown" 的 CompanyName 索引鍵。

必要?

true

位置?

named

預設值

"Unknown"

接受管線輸入?

false

接受萬用字元?

false

-Copyright <string>

指定模組的著作權聲明。

此參數是 Cmdlet 的必要項,但是 Copyright 索引鍵不是資訊清單的必要項。如果省略此參數,且未於出現提示時輸入值,New-ModuleManifest 就會建立值為 "(c) <年份> <使用者名稱>. All rights reserved."的 Copyright 索引鍵,其中 <年份> 是目前的年份,而 <使用者名稱> 是 Author 索引鍵的值 (如果有指定的話) 或目前使用者的名稱。

必要?

true

位置?

named

預設值

(c) <year> <username>. All rights reserved.

接受管線輸入?

false

接受萬用字元?

false

-Description <string>

描述模組的內容。

此參數是 Cmdlet 的必要項,但是 Description 索引鍵不是資訊清單的必要項。如果省略此參數,且未於出現提示時輸入值,New-ModuleManifest 就會建立值為空字串的 Description 索引鍵。

必要?

true

位置?

named

預設值

接受管線輸入?

false

接受萬用字元?

false

-DotNetFrameworkVersion <Version>

指定模組需要的 Microsoft .NET Framework 版本。

如果省略此參數,New-ModuleManifest 會建立值為空字串的 DotNetFrameWorkVersion 索引鍵。

必要?

false

位置?

named

預設值

接受管線輸入?

false

接受萬用字元?

false

-FileList <string[]>

指定模組中包含的所有項目。

這個索引鍵是設計成當做模組清查使用。這些檔案不會自動隨模組一起匯出。

此參數是 Cmdlet 的必要項,但是 FileList 索引鍵不是資訊清單的必要項。如果省略此參數,且未於出現提示時輸入值,New-ModuleManifest 就會建立值為空陣列的 FileList 索引鍵。

必要?

true

位置?

named

預設值

接受管線輸入?

false

接受萬用字元?

false

-FormatsToProcess <string[]>

指定匯入模組時要執行的格式化檔案 (.ps1xml)。

當您匯入模組時,Windows PowerShell 就會使用指定的檔案來執行 Update-FormatData Cmdlet。因為格式化檔案沒有限定範圍,所以它們會影響工作階段中的所有工作階段狀態。

此參數是 Cmdlet 的必要項,但是 FormatsToProcess 索引鍵不是資訊清單的必要項。如果省略此參數,且未於出現提示時輸入值,New-ModuleManifest 就會建立值為空陣列的 FormatsToProcess 索引鍵。

必要?

true

位置?

named

預設值

接受管線輸入?

false

接受萬用字元?

false

-FunctionsToExport <string[]>

指定模組匯出的函數。允許使用萬用字元。

您可以使用此參數來限制模組所匯出的函數。它可以從已匯出的別名清單中移除函數,但是不能在清單中新增函數。

如果您省略此參數,New-ModuleManifest 就會建立值為 * (全部) 的 FunctionsToExport 索引鍵,表示資訊清單將匯出該模組所匯出的所有函數。

必要?

false

位置?

named

預設值

* (all)

接受管線輸入?

false

接受萬用字元?

true

-Guid <Guid>

指定模組的唯一識別碼。此 GUID 可用來分辨名稱相同的模組。

如果省略此參數,New-ModuleManifest 會在資訊清單中建立 GUID 索引鍵,並產生 GUID 做為其值。

若要在 Windows PowerShell 中建立新的 GUID,請輸入 "[guid]::NewGuid()"。

必要?

false

位置?

named

預設值

A GUID generated for the module

接受管線輸入?

false

接受萬用字元?

false

-ModuleList <Object[]>

列出與這個模組一起封裝的所有模組。

請以字串形式輸入每個模組名稱,或輸入具有 ModuleName 和 GUID 索引鍵的雜湊表。此雜湊表也可以具有選擇性 ModuleVersion 索引鍵。

這個索引鍵是設計成當做模組清查使用。系統不會自動處理這些模組。

如果省略此參數,New-ModuleManifest 就會在資訊清單中建立值為空陣列的 ModuleList 索引鍵。

必要?

false

位置?

named

預設值

接受管線輸入?

false

接受萬用字元?

false

-ModuleToProcess <string>

指定模組的主要檔案或「根」檔案。匯入模組時,從根模組檔案匯出的成員都會匯入呼叫者的工作階段狀態中。請輸入一個指令碼模組 (.psm1) 或二進位模組 (.dll) 的檔案名稱。

如果模組具有資訊清單檔案,而且尚未在 ModuleToProcess 索引鍵中指定任何根檔案,資訊清單就會變成模組的主要檔案,而模組也會變成「資訊清單模組」(ModuleType = Manifest)。

若要從具有資訊清單之模組中的 .psm1 或 .dll 檔案匯出成員,您必須在資訊清單的 ModuleToProcess 或 NestedModules 索引鍵值中指定這些檔案的名稱。否則,系統就不會匯出這些檔案的成員。

此參數是 Cmdlet 的必要項,但是 ModuleToProcess 索引鍵不是資訊清單的必要項。如果省略此參數,且未於出現提示時輸入值,New-ModuleManifest 就會建立值為空字串的 ModuleToProcess 索引鍵。

必要?

true

位置?

named

預設值

接受管線輸入?

false

接受萬用字元?

false

-ModuleVersion <Version>

指定模組的版本。

此參數不是 Cmdlet 的必要項,但是 ModuleVersion 索引鍵是資訊清單的必要項。如果省略此參數,New-ModuleManifest 會建立值為 "1.0" 的 ModuleVersion 索引鍵。

必要?

false

位置?

named

預設值

1.0

接受管線輸入?

false

接受萬用字元?

false

-NestedModules <string[]>

指定要匯入模組之工作階段狀態中的指令碼模組 (.psm1) 和二進位模組 (.dll)。NestedModules 索引鍵中的檔案會依照它們列在值中的順序執行。

一般而言,巢狀模組會包含根模組進行內部處理所需的命令。根據預設,巢狀模組中的命令會從模組的工作階段狀態匯出至呼叫者的工作階段狀態中,但是根模組可以限制它所匯出的命令 (例如,使用 Export-Module 命令)。

雖然根模組可以使用模組工作階段狀態中的巢狀模組,不過呼叫者工作階段中的 Get-Module 命令不會傳回這些模組。

列於 NestedModules 索引鍵中的指令碼 (.ps1) 是在模組的工作階段狀態中執行,而不是在呼叫者的工作階段中執行。若要在呼叫者的工作階段狀態中執行指令碼,請在資訊清單的 ScriptsToProcess 索引鍵值中列出指令碼檔案名稱。

此參數是 Cmdlet 的必要項,但是 NestedModules 索引鍵不是資訊清單的必要項。如果省略此參數,且未於出現提示時輸入值,New-ModuleManifest 就會建立值為空陣列的 NestedModules 索引鍵。

必要?

true

位置?

named

預設值

接受管線輸入?

false

接受萬用字元?

false

-PassThru

除了建立 .psd1 檔案之外,還會將產生的模組資訊清單寫入主控台。根據預設,此 Cmdlet 不會產生任何輸出。

必要?

false

位置?

named

預設值

False

接受管線輸入?

false

接受萬用字元?

false

-Path <string>

指定新模組資訊清單的路徑和檔名。請輸入路徑及副檔名為 .psd1 的檔名,例如 "$pshome\Modules\MyModule\MyModule.psd1"。此參數為必要項。

如果指定現有檔案的路徑,除非該檔案擁有唯讀屬性,否則 New-ModuleManifest 便會取代檔案而不顯示警告。

資訊清單必須位於模組的目錄中,而且資訊清單檔案名稱必須與模組目錄名稱相同,但是副檔名為 .psd1。

注意:出現提示要求輸入 Path 參數的值時,您不能使用變數 (例如 $pshome 或 $home) 來回應。若要使用變數,請在命令中包含 Path 參數。

必要?

true

位置?

1

預設值

接受管線輸入?

false

接受萬用字元?

false

-PowerShellHostName <string>

指定模組所需之 Windows PowerShell 主機程式的名稱。請輸入主機程式的名稱,例如 "Windows PowerShell ISE Host" 或 "ConsoleHost"。不允許使用萬用字元。

若要尋找主機程式的名稱,請在程式中,輸入 "$host.name"。

如果省略此參數,New-ModuleManifest 會建立值為空字串的 PowerShellHostName 索引鍵。

必要?

false

位置?

named

預設值

接受管線輸入?

false

接受萬用字元?

false

-PowerShellHostVersion <Version>

指定將搭配此模組使用的最小 Windows PowerShell 主機程式版本。請輸入版本號碼,例如 1.1。

如果省略此參數,New-ModuleManifest 會建立值為空字串的 PowerShellHostName 索引鍵。

必要?

false

位置?

named

預設值

接受管線輸入?

false

接受萬用字元?

false

-PowerShellVersion <Version>

指定將搭配此模組使用的最小 Windows PowerShell 版本。請輸入 1.0 或 2.0。您不一定非要使用 2.0 版。

如果省略此參數,New-ModuleManifest 會建立值為空字串的 PowerShellVersion 索引鍵。

必要?

false

位置?

named

預設值

接受管線輸入?

false

接受萬用字元?

false

-PrivateData <Object>

指定在匯入模組時傳遞至模組的資料。

如果省略此參數,New-ModuleManifest 會建立值為空字串的 PrivateData 索引鍵。

必要?

false

位置?

named

預設值

接受管線輸入?

false

接受萬用字元?

false

-ProcessorArchitecture <ProcessorArchitecture>

指定模組所需的處理器架構。有效的值包括 x86、AMD64、IA64 和 None (未知或未指定)。

如果省略此參數,New-ModuleManifest 會建立值為空字串的 ProcessorArchitecture 索引鍵。

必要?

false

位置?

named

預設值

接受管線輸入?

false

接受萬用字元?

false

-RequiredAssemblies <string[]>

指定模組需要的組件 (.dll) 檔案。Windows PowerShell 會先載入指定的組件,然後再更新類型或格式、匯入巢狀模組,或匯入 ModuleToProcess 索引鍵值中指定的模組檔案。

請使用這個參數來列出模組所需的所有組件,包括必須載入以更新 FormatsToProcess 或 TypesToProcess 索引鍵中所列之任何格式化檔案或類型檔案的組件,即使這些組件也在 NestedModules 索引鍵中列為二進位模組也一樣。

此參數是 Cmdlet 的必要項,但是 RequiredAssemblies 索引鍵不是資訊清單的必要項。如果省略此參數,且未於出現提示時輸入值,New-ModuleManifest 就會建立值為空陣列的 RequiredAssemblies 索引鍵。

必要?

true

位置?

named

預設值

接受管線輸入?

false

接受萬用字元?

false

-RequiredModules <Object[]>

指定必須位於全域工作階段狀態中的模組。如果所需的模組沒有位於全域工作階段狀態中,嘗試匯入此模組的作業將會失敗。

請以字串形式輸入每個模組名稱,或輸入具有 ModuleName 和 GUID 索引鍵的雜湊表。此雜湊表也可以具有選擇性 ModuleVersion 索引鍵。如需詳細資訊,請參閱範例。

Windows PowerShell 不會自動匯入所需的模組。它只會確認所需的模組是否存在。不過,模組可以包含將所需模組匯入全域工作階段狀態中的指令碼 (.ps1)。

如果省略此參數,New-ModuleManifest 會建立值為空陣列的 RequiredModules 索引鍵。

必要?

false

位置?

named

預設值

接受管線輸入?

false

接受萬用字元?

false

-ScriptsToProcess <string[]>

指定匯入模組時要在呼叫者之工作階段狀態中執行的指令碼 (.ps1) 檔案。您可以使用這些指令碼來準備環境,就如同使用登入指令碼一樣。

若要指定在模組之工作階段狀態中執行的指令碼,請使用 NestedModules 索引鍵。

如果省略此參數,New-ModuleManifest 會建立值為空陣列的 ScriptsToProcess 索引鍵。

必要?

false

位置?

named

預設值

接受管線輸入?

false

接受萬用字元?

false

-TypesToProcess <string[]>

指定匯入模組時要執行的類型檔案 (.ps1xml)。

當您匯入模組時,Windows PowerShell 就會使用指定的檔案來執行 Update-TypeData Cmdlet。因為類型檔案沒有限定範圍,所以它們會影響工作階段中的所有工作階段狀態。

此參數是 Cmdlet 的必要項,但是 TypesToProcess 索引鍵不是資訊清單的必要項。如果省略此參數,且未於出現提示時輸入值,New-ModuleManifest 就會建立值為空陣列的 TypesToProcess 索引鍵。

必要?

true

位置?

named

預設值

接受管線輸入?

false

接受萬用字元?

false

-VariablesToExport <string[]>

指定模組匯出的變數。允許使用萬用字元。

您可以使用此參數來限制模組所匯出的變數。它可以從已匯出的變數清單中移除變數,但是不能在清單中新增變數。

如果您省略此參數,New-ModuleManifest 就會建立值為 * (全部) 的 VariablesToExport 索引鍵,表示資訊清單將匯出該模組所匯出的所有變數。

必要?

false

位置?

named

預設值

* (all)

接受管線輸入?

false

接受萬用字元?

true

-Confirm

在執行命令前先提示確認。

必要?

false

位置?

named

預設值

接受管線輸入?

false

接受萬用字元?

false

-WhatIf

說明執行命令時將會發生何種情況,但不會實際執行命令。

必要?

false

位置?

named

預設值

接受管線輸入?

false

接受萬用字元?

false

<CommonParameters>

這個 Cmdlet 支援一般參數:-Verbose、-Debug、-ErrorAction、-ErrorVariable、-OutBuffer 和 -OutVariable。如需詳細資訊,請參閱 about_Commonparameters.

輸入和輸出

輸入型別是可經由管道輸出至 Cmdlet 的物件型別。傳回型別則是 Cmdlet 所傳回的物件型別。

輸入

None

您無法經由管道將輸入輸出至這個 Cmdlet。

輸出

None 或 System.String

根據預設,New-ModuleManifest 不會產生任何輸出。不過,如果使用 PassThru 參數,則會產生表示模組資訊清單的 System.String 物件。

附註

模組資訊清單通常是選擇項。不過,若要匯出安裝在全域組件快取 (GAC) 中的組件,就需要模組資訊清單。

若要在 $pshome\Modules 目錄 (%Windir%\System32\WindowsPowerShell\v1.0\Modules) 中新增或變更檔案,請使用 [以系統管理員身分執行] 選項啟動 Windows PowerShell。

「工作階段」是指 Windows PowerShell 執行環境的執行個體。一個工作階段可以具有一種或多種工作階段狀態。根據預設,雖然一個工作階段只有一種全域工作階段狀態,不過每個匯入的模組都有自己的工作階段狀態。工作階段狀態可讓模組中的命令執行,而不會影響全域工作階段狀態。

「呼叫者的工作階段狀態」是指模組匯入其中的工作階段狀態。一般而言,它代表全域工作階段狀態,不過當模組匯入巢狀模組時,「呼叫者」就是模組而「呼叫者的工作階段狀態」則是模組的工作階段狀態。

範例 1

C:\PS>New-ModuleManifest

Path: C:\Users\User01\Documents\WindowsPowerShell\Modules\Test-Module\Test-Module.psd1
NestedModules[0]: BackgroundModule.psm1
Author: Jinghao Liu
CompanyName: Fabrikam, Inc.
Copyright: Copyright © 2009 Liu Jinghao. All rights reserved.
ModuleToProcess: TestModule.psm1
Description: Cmdlets to find common errors in scripts.
TypesToProcess[0]: TestTypes.ps1xml
FormatsToProcess[0]: TestFormat.ps1xml
RequiredAssemblies[0]: Test.dll
FileList[0]: Test-Module.psd1
FileList[1]: Test-Module.psm1
FileList[2]: BackgroundModule.psm1
FileList[3]: TestTypes.ps1xml
FileList[4]: TestFormat.ps1xml
FileList[5]: Test.dll
FileList[6]: TestIcon.ico

描述
-----------
這個命令會建立新的模組資訊清單。此 Cmdlet 會提示您指定所需的參數 (包括 Path 參數),並在指定的位置建立資訊清單檔案。

這個命令的輸出顯示提示的回應範例。若要使用預設值,請按 ENTER。

實際的提示,以及其處理加上引號及不加引號之文字的方式,需視執行 Windows PowerShell 的主程式而定。






範例 2

C:\PS>New-ModuleManifest -PowerShellVersion 1.0 -AliasesToExport JKBC, DRC, TAC

描述
-----------
這個命令會建立新的模組資訊清單。此命令包括 Cmdlet 不需要 (或提示要求) 的參數。您可以在出現提示時,加入其他資訊清單索引鍵值。






範例 3

C:\PS>New-ModuleManifest -RequiredModules FileTransfer,@{ModuleName="BackgroundModule";GUID="486569a2-2784-48bf-af15-70ba837a64d0";ModuleVersion="3.5"}

描述
-----------
在這個範例中,會示範如何使用 RequiredModules 參數值的字串和雜湊表格式。字串和雜湊表可用於同一個命令中。

這個命令會為需要 FileTransfer 模組的模組以及名為 "BackgroundModule" 的 (虛構) 模組建立模組資訊清單。

此命令會使用字串格式來指定 FileTransfer 模組的名稱,以及使用雜湊表格式來指定 BackgroundModule 的名稱、GUID 和版本。






請參閱




目錄