了解 Windows PowerShell 模組Understanding a Windows PowerShell Module

模組是一組相關的 Windows PowerShell 功能,群組在一起成為方便的單元(通常儲存在單一目錄中)。A module is a set of related Windows PowerShell functionalities, grouped together as a convenient unit (usually saved in a single directory). 藉由定義一組相關的腳本檔案、元件和相關資源做為模組,您可以更輕鬆地參考、載入、保存和共用程式碼。By defining a set of related script files, assemblies, and related resources as a module, you can reference, load, persist, and share your code much easier than you would otherwise.

模組的主要用途是允許 Windows PowerShell 程式碼的模組化(例如,重複使用和抽象)。The main purpose of a module is to allow the modularization (ie, reuse and abstraction) of Windows PowerShell code. 例如,建立模組的最基本方式,就是將 Windows PowerShell 腳本儲存為 .psm1 檔案。For example, the most basic way of creating a module is to simply save a Windows PowerShell script as a .psm1 file. 這麼做可讓您控制腳本中包含的函式和變數(例如,建立公用或私用)。Doing so allows you to control (ie, make public or private) the functions and variables contained in the script. 將腳本儲存為 .psm1 檔案也可讓您控制特定變數的範圍。Saving the script as a .psm1 file also allows you to control the scope of certain variables. 最後,您也可以使用指令程式(如Install 模組)來組織、安裝和使用您的腳本作為較大型解決方案的建立區塊。Finally, you can also use cmdlets such as Install-Module to organize, install, and use your script as building blocks for larger solutions.

模組元件和類型Module Components and Types

模組是由四個基本元件所組成:A module is made up of four basic components:

  1. 某些程式碼檔案-通常是 PowerShell 腳本或受管理的 Cmdlet 元件。Some sort of code file - usually either a PowerShell script or a managed cmdlet assembly.

  2. 上述程式碼檔案可能需要的任何其他專案,例如其他元件、說明檔或腳本。Anything else that the above code file may need, such as additional assemblies, help files, or scripts.

  3. 描述上述檔案的資訊清單檔,以及儲存中繼資料,例如作者和版本設定資訊。A manifest file that describes the above files, as well as stores metadata such as author and versioning information.

  4. 目錄,其中包含上述所有內容,且位於 PowerShell 可合理尋找的位置。A directory that contains all of the above content, and is located where PowerShell can reasonably find it.

    請注意,這些元件本身都不是必要的。Note that none of these components, by themselves, are actually necessary. 例如,模組在技術上可能只是儲存在 .psm1 檔案中的腳本。For example, a module can technically be only a script stored in a .psm1 file. 您也可以有一個不是資訊清單檔案的模組,主要用於組織用途。You can also have a module that is nothing but a manifest file, which is used mainly for organizational purposes. 您也可以撰寫可動態建立模組的腳本,因此實際上不需要目錄來儲存任何專案。You can also write a script that dynamically creates a module, and as such doesn't actually need a directory to store anything in. 下列各節將說明您可以藉由混合和比對模組的不同可能元件來取得的模組類型。The following sections describe the types of modules you can get by mixing and matching the different possible parts of a module together.

腳本模組Script Modules

如其名稱所示,腳本模組是包含任何有效 Windows PowerShell 程式碼的檔案(. .psm1)。As the name implies, a script module is a file (.psm1) that contains any valid Windows PowerShell code. 腳本開發人員和系統管理員可以使用這種類型的模組來建立其成員包含函式、變數等的模組。Script developers and administrators can use this type of module to create modules whose members include functions, variables, and more. 就核心而言,腳本模組只是具有不同副檔名的 Windows PowerShell 腳本,可讓系統管理員在其上使用匯入、匯出和管理功能。At heart, a script module is simply a Windows PowerShell script with a different extension, which allows administrators to use import, export, and management functions on it.

此外,您可以使用資訊清單檔案,在模組中包含其他資源,例如資料檔案、其他相依模組或執行時間腳本。In addition, you can use a manifest file to include other resources in your module, such as data files, other dependent modules, or runtime scripts. 資訊清單檔案也適用于追蹤中繼資料,例如撰寫和版本設定資訊。Manifest files are also useful for tracking metadata such as authoring and versioning information.

最後,您必須將腳本模組儲存在 PowerShell 可合理探索的資料夾中,就像任何其他未動態建立的模組一樣。Finally, a script module, like any other module that isn't dynamically created, needs to be saved in a folder that PowerShell can reasonably discover. 通常,這是在 PowerShell 模組路徑上;但如有需要,您可以明確描述模組的安裝位置。Usually, this is on the PowerShell module path; but if necessary you can explicitly describe where your module is installed. 如需詳細資訊,請參閱如何撰寫 PowerShell 腳本模組For more information, see How to Write a PowerShell Script Module.

二進位模組Binary Modules

二進位模組」是一個 .NET Framework 元件(.dll),其中包含已編譯器代碼, C#例如。A binary module is a .NET Framework assembly (.dll) that contains compiled code, such as C#. Cmdlet 開發人員可以使用這種類型的模組來共用 Cmdlet、提供者等。Cmdlet developers can use this type of module to share cmdlets, providers, and more. (現有的嵌入式管理單元也可以當做二進位模組使用)。相較于腳本模組,二進位模組可讓您建立更快速或使用功能的 Cmdlet (例如多執行緒),這在 Windows PowerShell 腳本中的程式碼並不容易。(Existing snap-ins can also be used as binary modules.) Compared to a script module, a binary module allows you to create cmdlets that are faster or use features (such as multithreading) that are not as easy to code in Windows PowerShell scripts.

如同腳本模組,您可以包含資訊清單檔案來描述模組所使用的其他資源,以及追蹤模組的相關中繼資料。As with script modules, you can include a manifest file to describe additional resources that your module uses, and to track metadata about your module. 同樣地,您可能會在 PowerShell 模組路徑的某處資料夾中安裝您的二進位模組。Similarly, you probably should install your binary module in a folder somewhere along the PowerShell module path. 如需詳細資訊,請參閱如何撰寫 PowerShell 二進位模組For more information, see How to How to Write a PowerShell Binary Module.

資訊清單模組Manifest Modules

資訊清單模組是使用資訊清單檔來描述其所有元件的模組,但不會有任何類型的核心元件或腳本。A manifest module is a module that uses a manifest file to describe all of its components, but doesn't have any sort of core assembly or script. (正式地說,資訊清單模組會將資訊清單的 ModuleToProcessRootModule 元素保留為空白)。不過,您仍然可以使用模組的其他功能,例如載入相依元件或自動執行特定前置處理腳本的能力。(Formally, a manifest module leaves the ModuleToProcess or RootModule element of the manifest empty.) However, you can still use the other features of a module, such as the ability to load up dependent assemblies or automatically run certain pre-processing scripts. 您也可以使用資訊清單模組,將其他模組將使用的資源(例如,嵌套模組、元件、類型或格式)封裝成方便的方式。You can also use a manifest module as a convenient way to package up resources that other modules will use, such as nested modules, assemblies, types, or formats. 如需詳細資訊,請參閱如何撰寫 PowerShell 模組資訊清單For more information, see How to Write a PowerShell Module Manifest.

動態模組Dynamic Modules

動態模組是指未從檔案載入或儲存到檔案的模組。A dynamic module is a module that is not loaded from, or saved to, a file. 相反地,它們是由腳本以新的模組Cmdlet 來動態建立的。Instead, they are created dynamically by a script, using the New-Module cmdlet. 這種類型的模組可讓腳本建立不需要載入或儲存至持續性儲存體的隨選模組。This type of module enables a script to create a module on demand that does not need to be loaded or saved to persistent storage. 就本質而言,動態模組的目的是短期,因此 Get-Module Cmdlet 無法存取。By its nature, a dynamic module is intended to be short-lived, and therefore cannot be accessed by the Get-Module cmdlet. 同樣地,它們通常不需要模組資訊清單,也可能需要永久資料夾來儲存其相關的元件。Similarly, they usually do not need module manifests, nor do they likely need permanent folders to store their related assemblies.

模組資訊清單Module Manifests

模組資訊清單是包含雜湊表的 .psd1 檔案。A module manifest is a .psd1 file that contains a hash table. 雜湊表中的索引鍵和值會執行下列動作:The keys and values in the hash table do the following things:

  • 描述模組的內容和屬性。Describe the contents and attributes of the module.

  • 定義必要條件。Define the prerequisites.

  • 決定元件的處理方式。Determine how the components are processed.

    資訊清單對於模組並非必要。Manifests are not required for a module. 模組可以參考腳本檔案(ps1)、腳本模組檔案(. .psm1)、資訊清單檔案(. .psd1)、格式設定和類型檔案(. types.ps1xml)、Cmdlet 和提供者元件(.dll)、資源檔、說明檔、當地語系化檔案,或任何其他類型的檔或資源已配套為模組的一部分。Modules can reference script files (.ps1), script module files (.psm1), manifest files (.psd1), formatting and type files (.ps1xml), cmdlet and provider assemblies (.dll), resource files, Help files, localization files, or any other type of file or resource that is bundled as part of the module. 針對國際化腳本,模組資料夾也包含一組訊息目錄檔案。For an internationalized script, the module folder also contains a set of message catalog files. 如果您將資訊清單檔案新增至模組資料夾,您可以藉由參考資訊清單,將多個檔案當做單一單位來參考。If you add a manifest file to the module folder, you can reference the multiple files as a single unit by referencing the manifest.

    資訊清單本身會描述下列類別的資訊:The manifest itself describes the following categories of information:

  • 模組的相關中繼資料,例如模組版本號碼、作者和描述。Metadata about the module, such as the module version number, the author, and the description.

  • 匯入模組所需的必要條件,例如 Windows PowerShell 版本、common language runtime (CLR)版本和所需的模組。Prerequisites needed to import the module, such as the Windows PowerShell version, the common language runtime (CLR) version, and the required modules.

  • 處理指示詞,例如要處理的腳本、格式和類型。Processing directives, such as the scripts, formats, and types to process.

  • 要匯出之模組的成員限制,例如要匯出的別名、函式、變數和 Cmdlet。Restrictions on the members of the module to export, such as the aliases, functions, variables, and cmdlets to export.

    如需詳細資訊,請參閱如何撰寫 PowerShell 模組資訊清單For more information, see How to Write a PowerShell Module Manifest.

儲存和安裝模組Storing and Installing a Module

建立腳本、二進位或資訊清單模組之後,您可以將工作儲存在其他人可以存取的位置。Once you have created a script, binary, or manifest module, you can save your work in a location that others may access it. 例如,您的模組可以儲存在安裝 Windows PowerShell 的系統資料夾中,也可以儲存在使用者資料夾中。For example, your module can be stored in the system folder where Windows PowerShell is installed, or it can be stored in a user folder.

一般來說,您可以使用儲存在 $ENV:PSModulePath 變數中的其中一個路徑,判斷您應該在何處安裝模組。Generally speaking, you can determine where you should install your module by using one of the paths stored in the $ENV:PSModulePath variable. 使用其中一個路徑,表示當使用者在其程式碼中呼叫它時,PowerShell 可以自動尋找並載入您的模組。Using one of these paths means that PowerShell can automatically find and load your module when a user makes a call to it in their code. 如果您將模組儲存在其他位置,您可以在呼叫 Install-Module時,將模組的位置當做參數傳入,藉此明確地讓 PowerShell 知道。If you store your module somewhere else, you can explicitly let PowerShell know by passing in the location of your module as a parameter when you call Install-Module.

無論如何,資料夾的路徑是指模組的基底(ModuleBase),而腳本、二進位或資訊清單模組檔案的名稱應該與模組資料夾名稱相同,但有下列例外狀況:Regardless, the path of the folder is referred to as the base of the module (ModuleBase), and the name of the script, binary, or manifest module file should be the same as the module folder name, with the following exceptions:

  • New-Module Cmdlet 所建立的動態模組,可以使用 Cmdlet 的 Name 參數來命名。Dynamic modules that are created by the New-Module cmdlet can be named using the Name parameter of the cmdlet.

  • Import-Module assembly命令從元件物件匯入的模組會根據下列語法來命名: "dynamic_code_module_" + assembly.GetName()Modules imported from assembly objects by the Import-Module -Assembly command are named according to the following syntax: "dynamic_code_module_" + assembly.GetName().

    如需詳細資訊,請參閱安裝 PowerShell 模組修改 PSModulePath 安裝路徑For more information, see Installing a PowerShell Module and Modifying the PSModulePath Installation Path.

模組 Cmdlet 和變數Module Cmdlets and Variables

Windows PowerShell 會提供下列 Cmdlet 和變數,以建立和管理模組。The following cmdlets and variables are provided by Windows PowerShell for the creation and management of modules.

新模組Cmdlet 此 Cmdlet 會建立只存在於記憶體中的新動態模組。New-Module cmdlet This cmdlet creates a new dynamic module that exists only in memory. 模組是從腳本區塊所建立,而其匯出的成員(例如其函式和變數)會立即在會話中提供,直到會話關閉為止。The module is created from a script block, and its exported members, such as its functions and variables, are immediately available in the session and remain available until the session is closed.

New-modulemanifest Cmdlet:此 Cmdlet 會建立新的模組資訊清單(. .psd1)檔案、填入其值,並將資訊清單檔案儲存至指定的路徑。New-ModuleManifest cmdlet This cmdlet creates a new module manifest (.psd1) file, populates its values, and saves the manifest file to the specified path. 此 Cmdlet 也可以用來建立可手動填入的模組資訊清單範本。This cmdlet can also be used to create a module manifest template that can be filled in manually.

Import-module Cmdlet 這個 Cmdlet 會將一或多個模組新增至目前的會話。Import-Module cmdlet This cmdlet adds one or more modules to the current session.

Get-help Cmdlet 此 Cmdlet 會抓取已或可匯入目前會話之模組的相關資訊。Get-Module cmdlet This cmdlet retrieves information about the modules that have been or that can be imported into the current session.

Export-modulemember 指令程式此 Cmdlet 會指定從腳本模組(. .psm1)檔案或使用 New-Module Cmdlet 所建立的動態模組匯出的模組成員(例如 Cmdlet、函式、變數和別名)。Export-ModuleMember cmdlet This cmdlet specifies the module members (such as cmdlets, functions, variables, and aliases) that are exported from a script module (.psm1) file or from a dynamic module created by using the New-Module cmdlet.

Remove-Module Cmdlet 此 Cmdlet 會從目前的會話移除模組。Remove-Module cmdlet This cmdlet removes modules from the current session.

New-modulemanifest 指令程式此 Cmdlet 會驗證模組資訊清單是否已確實存在於指定的路徑中,藉由確認模組資訊清單檔案(. .psd1)中所列的檔案實際上是否在指定的路徑中,而能正確描述模組的元件。Test-ModuleManifest cmdlet This cmdlet verifies that a module manifest accurately describes the components of a module by verifying that the files that are listed in the module manifest file (.psd1) actually exist in the specified paths.

$PSScriptRoot 此變數包含執行腳本模組的目錄。$PSScriptRoot This variable contains the directory from which the script module is being executed. 它可讓腳本使用模組路徑來存取其他資源。It enables scripts to use the module path to access other resources.

$env:P SModulePath 此環境變數包含用來儲存 Windows PowerShell 模組的目錄清單。$env:PSModulePath This environment variable contains a list of the directories in which Windows PowerShell modules are stored. 當自動匯入模組並更新模組的說明主題時,Windows PowerShell 會使用此變數的值。Windows PowerShell uses the value of this variable when importing modules automatically and updating Help topics for modules.

另請參閱See Also

撰寫 Windows PowerShell 模組Writing a Windows PowerShell Module