安裝 PowerShell 模組Installing a PowerShell Module

建立 PowerShell 模組之後,您可能會想要在系統上安裝模組,讓您或其他人可以使用它。After you have created your PowerShell module, you will likely want to install the module on a system, so that you or others may use it. 一般來說,這是由將模組檔案(即 .psm1 或二進位元件、模組資訊清單,以及任何其他相關聯的檔案)複製到該電腦上的目錄。Generally speaking, this consists of copying the module files (ie, the .psm1, or the binary assembly, the module manifest, and any other associated files) onto a directory on that computer. 對於非常小型的專案,這可能就像是將檔案以 Windows Explorer 複製並貼到單一遠端電腦一樣簡單;不過,對於較大型的解決方案,您可能會想要使用更複雜的安裝程式。For a very small project, this may be as simple as copying and pasting the files with Windows Explorer onto a single remote computer; however, for larger solutions you may wish to use a more sophisticated installation process. 無論您如何將模組放入系統,PowerShell 都可以使用一些技術,讓使用者尋找和使用您的模組。Regardless of how you get your module onto the system, PowerShell can use a number of techniques that will let users find and use your modules. 因此,安裝的主要問題是確保 PowerShell 能夠找到您的模組。Therefore, the main issue for installation is ensuring that PowerShell will be able to find your module. 如需詳細資訊,請參閱匯入 PowerShell 模組For more information, see Importing a PowerShell Module.

安裝模組的規則Rules for Installing Modules

下列資訊適用于所有模組,包括您為自己的用途所建立的模組、從其他方取得的模組,以及您散發給其他人的模組。The following information pertains to all modules, including modules that you create for your own use, modules that you get from other parties, and modules that you distribute to others.

在 PSModulePath 中安裝模組Install Modules in PSModulePath

盡可能將所有模組安裝在PSModulePath環境變數中所列的路徑,或將模組路徑新增至PSModulePath環境變數值。Whenever possible, install all modules in a path that is listed in the PSModulePath environment variable or add the module path to the PSModulePath environment variable value.

PSModulePath環境變數($Env:P smodulepath)包含 Windows PowerShell 模組的位置。The PSModulePath environment variable ($Env:PSModulePath) contains the locations of Windows PowerShell modules. Cmdlet 會依賴此環境變數的值來尋找模組。Cmdlets rely on the value of this environment variable to find modules.

根據預設, PSModulePath環境變數值包含下列系統和使用者模組目錄,但是您可以加入並編輯值。By default, the PSModulePath environment variable value contains the following system and user module directories, but you can add to and edit the value.

  • $PSHome\Modules (%Windir%\System32\WindowsPowerShell\v1.0\Modules)$PSHome\Modules (%Windir%\System32\WindowsPowerShell\v1.0\Modules)

    警告

    這個位置會保留給 Windows 隨附的模組。This location is reserved for modules that ship with Windows. 請勿將模組安裝到這個位置。Do not install modules to this location.

  • $Home\Documents\WindowsPowerShell\Modules (%UserProfile%\Documents\WindowsPowerShell\Modules)$Home\Documents\WindowsPowerShell\Modules (%UserProfile%\Documents\WindowsPowerShell\Modules)

  • $Env:ProgramFiles\WindowsPowerShell\Modules (%ProgramFiles%\WindowsPowerShell\Modules)$Env:ProgramFiles\WindowsPowerShell\Modules (%ProgramFiles%\WindowsPowerShell\Modules)

    若要取得PSModulePath環境變數的值,請使用下列其中一個命令。To get the value of the PSModulePath environment variable, use either of the following commands.

    $Env:PSModulePath
    [Environment]::GetEnvironmentVariable("PSModulePath")
    

    若要將模組路徑新增至PSModulePath環境變數值的值,請使用下列命令格式。To add a module path to value of the PSModulePath environment variable value, use the following command format. 此格式會使用system.object類別的SetEnvironmentVariable方法,對PSModulePath環境變數進行與會話無關的變更。This format uses the SetEnvironmentVariable method of the System.Environment class to make a session-independent change to the PSModulePath environment variable.

    #Save the current value in the $p variable.
    $p = [Environment]::GetEnvironmentVariable("PSModulePath")
    
    #Add the new path to the $p variable. Begin with a semi-colon separator.
    $p += ";C:\Program Files (x86)\MyCompany\Modules\"
    
    #Add the paths in $p to the PSModulePath value.
    [Environment]::SetEnvironmentVariable("PSModulePath",$p)
    
    

    重要

    將路徑新增至PSModulePath之後,您應該廣播有關此變更的環境訊息。Once you have added the path to PSModulePath, you should broadcast an environment message about the change. 廣播變更可讓其他應用程式(例如 shell)收取變更。Broadcasting the change allows other applications, such as the shell, to pick up the change. 若要廣播變更,請讓您的產品安裝程式碼傳送WM_SETTINGCHANGE訊息,其中 lParam 設定為「環境」字串。To broadcast the change, have your product installation code send a WM_SETTINGCHANGE message with lParam set to the string "Environment". 在您的模組安裝程式碼更新PSModulePath之後,請務必傳送該訊息。Be sure to send the message after your module installation code has updated PSModulePath.

使用正確的模組目錄名稱Use the Correct Module Directory Name

格式正確的模組是儲存在目錄中的模組,其名稱與模組目錄中至少一個檔案的基底名稱相同。A well-formed module is a module that is stored in a directory that has the same name as the base name of at least one file in the module directory. 如果模組的格式不正確,Windows PowerShell 就無法將它辨識為模組。If a module is not well-formed, Windows PowerShell does not recognize it as a module.

檔案的「基底名稱」是沒有副檔名的名稱。The "base name" of a file is the name without the file name extension. 在格式正確的模組中,包含模組檔案的目錄名稱必須符合模組中至少一個檔案的基底名稱。In a well-formed module, the name of the directory that contains the module files must match the base name of at least one file in the module.

例如,在範例 Fabrikam 模組中,包含模組檔案的目錄會命名為 "Fabrikam",而且至少有一個檔案包含 "Fabrikam" 基底名稱。For example, in the sample Fabrikam module, the directory that contains the module files is named "Fabrikam" and at least one file has the "Fabrikam" base name. 在此情況下,.psd1 和 Fabrikam 都會有 "Fabrikam" 基底名稱。In this case, both Fabrikam.psd1 and Fabrikam.dll have the "Fabrikam" base name.

C:\Program Files
  Fabrikam Technologies
    Fabrikam Manager
      Modules
        Fabrikam
          Fabrikam.psd1 (module manifest)
          Fabrikam.dll (module assembly)

安裝不正確的效果Effect of Incorrect Installation

如果模組的格式不正確,且其位置並未包含在PSModulePath環境變數的值中,則 Windows PowerShell 的基本探索功能(如下列)將無法運作。If the module is not well-formed and its location is not included in the value of the PSModulePath environment variable, basic discovery features of Windows PowerShell, such as the following, do not work.

  • 模組自動載入功能無法自動匯入模組。The Module Auto-Loading feature cannot import the module automatically.

  • 取得模組Cmdlet 的 ListAvailable 參數找不到模組。The ListAvailable parameter of the Get-Module cmdlet cannot find the module.

  • Import-module Cmdlet 找不到模組。The Import-Module cmdlet cannot find the module. 若要匯入模組,您必須提供根模組檔案或模組資訊清單檔案的完整路徑。To import the module, you must provide the full path to the root module file or module manifest file.

    除非將模組匯入會話,否則其他功能(例如下列)無法正常執行。Additional features, such as the following, do not work unless the module is imported into the session. PSModulePath環境變數中格式正確的模組中,即使模組未匯入會話,這些功能仍可運作。In well-formed modules in the PSModulePath environment variable, these features work even when the module is not imported into the session.

  • Get-Command Cmdlet 在模組中找不到命令。The Get-Command cmdlet cannot find commands in the module.

  • Update-helpSave-help Cmdlet 無法更新或儲存模組的說明。The Update-Help and Save-Help cmdlets cannot update or save help for the module.

  • 顯示命令Cmdlet 找不到並顯示模組中的命令。The Show-Command cmdlet cannot find and display the commands in the module.

    Windows PowerShell 整合式腳本環境(ISE)中的 Show-Command 視窗遺失模組中的命令。The commands in the module are missing from the Show-Command window in Windows PowerShell Integrated Scripting Environment (ISE).

模組的安裝位置Where to Install Modules

本節說明檔案系統中安裝 Windows PowerShell 模組的位置。This section explains where in the file system to install Windows PowerShell modules. 位置取決於模組的使用方式。The location depends on how the module is used.

為特定使用者安裝模組Installing Modules for a Specific User

如果您建立自己的模組,或從另一方取得模組,例如 Windows PowerShell 社區網站,而且您想要讓模組僅供您的使用者帳戶使用,請在您的使用者特定模組目錄中安裝模組。If you create your own module or get a module from another party, such as a Windows PowerShell community website, and you want the module to be available for your user account only, install the module in your user-specific Modules directory.

$home\Documents\WindowsPowerShell\Modules\<Module Folder>\<Module Files>

根據預設,會將使用者特定的模組目錄新增至PSModulePath環境變數的值。The user-specific Modules directory is added to the value of the PSModulePath environment variable by default.

針對 Program Files 中的所有使用者安裝模組Installing Modules for all Users in Program Files

如果您想要將模組提供給電腦上的所有使用者帳戶,請將模組安裝在 Program Files 位置。If you want a module to be available to all user accounts on the computer, install the module in the Program Files location.

$Env:ProgramFiles\WindowsPowerShell\Modules\<Module Folder>\<Module Files>

注意

在 Windows PowerShell 4.0 和更新版本中,預設會將 Program Files 位置新增至 PSModulePath 環境變數的值。The Program Files location is added to the value of the PSModulePath environment variable by default in Windows PowerShell 4.0 and later. 對於舊版的 Windows PowerShell,您可以手動建立程式檔案位置((%ProgramFiles%\WindowsPowerShell\Modules),並將此路徑新增至您的 PSModulePath 環境變數,如上所述。For earlier versions of Windows PowerShell, you can manually create the Program Files location ((%ProgramFiles%\WindowsPowerShell\Modules) and add this path to your PSModulePath environment variable as described above.

在產品目錄中安裝模組Installing Modules in a Product Directory

如果您要將課程模組散發給其他人,請使用上述的預設程式檔案位置,或建立您自己的公司專屬或產品特定的% ProgramFiles% 目錄子目錄。If you are distributing the module to other parties, use the default Program Files location described above, or create your own company-specific or product-specific subdirectory of the %ProgramFiles% directory.

例如,Fabrikam 技術是一家虛構的公司,它會為其 Fabrikam Manager 產品運送 Windows PowerShell 模組。For example, Fabrikam Technologies, a fictitious company, is shipping a Windows PowerShell module for their Fabrikam Manager product. 其模組安裝程式會在 Fabrikam Manager 產品子目錄中建立模組子目錄。Their module installer creates a Modules subdirectory in the Fabrikam Manager product subdirectory.

C:\Program Files
  Fabrikam Technologies
    Fabrikam Manager
      Modules
        Fabrikam
          Fabrikam.psd1 (module manifest)
          Fabrikam.dll (module assembly)

若要啟用 Windows PowerShell 模組探索功能以尋找 Fabrikam 模組,Fabrikam 模組安裝程式會將模組位置新增至PSModulePath環境變數的值。To enable the Windows PowerShell module discovery features to find the Fabrikam module, the Fabrikam module installer adds the module location to the value of the PSModulePath environment variable.

$p = [Environment]::GetEnvironmentVariable("PSModulePath")
$p += ";C:\Program Files\Fabrikam Technologies\Fabrikam Manager\Modules\"
[Environment]::SetEnvironmentVariable("PSModulePath",$p)

在通用檔案目錄中安裝模組Installing Modules in the Common Files Directory

如果產品的多個元件或產品的多個版本使用模組,請在%ProgramFiles%\Common Files\Modules 子目錄的模組特定子目錄中安裝模組。If a module is used by multiple components of a product or by multiple versions of a product, install the module in a module-specific subdirectory of the %ProgramFiles%\Common Files\Modules subdirectory.

在下列範例中,Fabrikam 模組會安裝在 %ProgramFiles%\Common Files\Modules 子目錄的 Fabrikam 子目錄中。In the following example, the Fabrikam module is installed in a Fabrikam subdirectory of the %ProgramFiles%\Common Files\Modules subdirectory. 請注意,每個模組都位於模組子目錄中自己的子目錄中。Note that each module resides in its own subdirectory in the Modules subdirectory.

C:\Program Files
  Common Files
    Modules
      Fabrikam
        Fabrikam.psd1 (module manifest)
        Fabrikam.dll (module assembly)

然後,安裝程式會確保PSModulePath環境變數的值包含 common files 模組子目錄的路徑。Then, the installer assures the value of the PSModulePath environment variable includes the path of the common files modules subdirectory.

$m = $env:ProgramFiles + '\Common Files\Modules'
$p = [Environment]::GetEnvironmentVariable("PSModulePath")
$q = $p -split ';'
if ($q -notContains $m) {
    $q += ";$m"
}
$p = $q -join ';'
[Environment]::SetEnvironmentVariable("PSModulePath", $p)

安裝多個版本的模組Installing Multiple Versions of a Module

若要安裝相同模組的多個版本,請使用下列程式。To install multiple versions of the same module, use the following procedure.

  1. 為每個模組版本建立一個目錄。Create a directory for each version of the module. 在目錄名稱中包含版本號碼。Include the version number in the directory name.
  2. 為模組的每個版本建立模組資訊清單。Create a module manifest for each version of the module. 在資訊清單中ModuleVersion索引鍵的值,輸入模組版本號碼。In the value of the ModuleVersion key in the manifest, enter the module version number. 將資訊清單檔案(. .psd1)儲存在模組的版本特定目錄中。Save the manifest file (.psd1) in the version-specific directory for the module.
  3. 將模組根資料夾路徑新增至PSModulePath環境變數的值,如下列範例所示。Add the module root folder path to the value of the PSModulePath environment variable, as shown in the following examples.

若要匯入特定版本的模組,終端使用者可以使用import-module Cmdlet 的 MinimumVersionRequiredVersion 參數。To import a particular version of the module, the end-user can use the MinimumVersion or RequiredVersion parameters of the Import-Module cmdlet.

例如,如果在8.0 和9.0 版中提供 Fabrikam 模組,Fabrikam 模組目錄結構可能如下所示。For example, if the Fabrikam module is available in versions 8.0 and 9.0, the Fabrikam module directory structure might resemble the following.

C:\Program Files
Fabrikam Manager
 Fabrikam8
   Fabrikam
     Fabrikam.psd1 (module manifest: ModuleVersion = "8.0")
     Fabrikam.dll (module assembly)
 Fabrikam9
   Fabrikam
     Fabrikam.psd1 (module manifest: ModuleVersion = "9.0")
     Fabrikam.dll (module assembly)

安裝程式會將這兩個模組路徑新增至PSModulePath環境變數值。The installer adds both of the module paths to the PSModulePath environment variable value.

$p = [Environment]::GetEnvironmentVariable("PSModulePath")
$p += ";C:\Program Files\Fabrikam\Fabrikam8;C:\Program Files\Fabrikam\Fabrikam9"
[Environment]::SetEnvironmentVariable("PSModulePath",$p)

當這些步驟完成時, get-help Cmdlet 的ListAvailable參數會取得這兩個 Fabrikam 模組。When these steps are complete, the ListAvailable parameter of the Get-Module cmdlet gets both of the Fabrikam modules. 若要匯入特定模組,請使用import-module Cmdlet 的 MinimumVersionRequiredVersion 參數。To import a particular module, use the MinimumVersion or RequiredVersion parameters of the Import-Module cmdlet.

如果這兩個模組都匯入相同的會話中,而且模組包含具有相同名稱的 Cmdlet,則最後匯入的 Cmdlet 就會在會話中生效。If both modules are imported into the same session, and the modules contain cmdlets with the same names, the cmdlets that are imported last are effective in the session.

處理命令名稱衝突Handling Command Name Conflicts

當模組匯出的命令與使用者會話中的命令同名時,可能會發生命令名稱衝突。Command name conflicts can occur when the commands that a module exports have the same name as commands in the user's session.

當會話包含兩個具有相同名稱的命令時,Windows PowerShell 會執行優先的命令類型。When a session contains two commands that have the same name, Windows PowerShell runs the command type that takes precedence. 當會話包含兩個具有相同名稱和相同類型的命令時,Windows PowerShell 會執行最近新增至會話的命令。When a session contains two commands that have the same name and the same type, Windows PowerShell runs the command that was added to the session most recently. 若要執行預設不會執行的命令,使用者可以使用模組名稱來限定命令名稱。To run a command that is not run by default, users can qualify the command name with the module name.

例如,如果會話包含 Get-Date 函式和 Get-Date Cmdlet,Windows PowerShell 預設會執行此功能。For example, if the session contains a Get-Date function and the Get-Date cmdlet, Windows PowerShell runs the function by default. 若要執行此 Cmdlet,請在命令前面加上模組名稱,例如:To run the cmdlet, preface the command with the module name, such as:

Microsoft.PowerShell.Utility\Get-Date

為避免名稱衝突,模組作者可以使用模組資訊清單中的DefaultCommandPrefix索引鍵,為從模組匯出的所有命令指定名詞前置詞。To prevent name conflicts, module authors can use the DefaultCommandPrefix key in the module manifest to specify a noun prefix for all commands exported from the module.

使用者可以使用 Import-Module Cmdlet 的prefix參數,以使用替代的前置詞。Users can use the Prefix parameter of the Import-Module cmdlet to use an alternate prefix. Prefix參數的值會優先于DefaultCommandPrefix索引鍵的值。The value of the Prefix parameter takes precedence over the value of the DefaultCommandPrefix key.

另請參閱See Also

about_Command_Precedenceabout_Command_Precedence

撰寫 Windows PowerShell 模組Writing a Windows PowerShell Module