共用方式為

安裝 PowerShell 模組

建立 PowerShell 模組之後，您可能會想要在系統上安裝模組，讓或其他人可以使用它。 一般而言，這包括將模組檔案（即 .psm1、二進位元件、模組指令清單，以及任何其他相關聯的檔案）複製到該計算機上的目錄。 對於非常小型的專案，這可能就像使用 Windows 檔案總管將檔案複製並貼到單一遠端電腦上一樣簡單;不過，針對較大的解決方案，您可能想要使用更複雜的安裝程式。 無論您如何將模組放入系統，PowerShell 都可以使用一些技術，讓用戶尋找和使用模組。 因此，安裝的主要問題是確保PowerShell能夠找到您的模組。 如需詳細資訊，請參閱 匯入 PowerShell 模組。

安裝模組的規則

下列資訊與所有模塊有關，包括您為自己的用途建立的模組、您從其他合作物件取得的模組，以及您散發給其他人的模組。

在 PSModulePath 中安裝模組

盡可能將所有模組安裝在 PSModulePath 環境變數中所列的路徑，或將模組路徑新增至 PSModulePath 環境變數值。

PSModulePath 環境變數 （$Env:PSModulePath） 包含 Windows PowerShell 模組的位置。 Cmdlet 依賴此環境變數的值來尋找模組。

根據預設，PSModulePath 環境變數值包含下列系統和使用者模組目錄，但您可以新增和編輯值。

  • $PSHOME\Modules （%windir%\System32\WindowsPowerShell\v1.0\Modules）

    警告

    此位置保留給隨附於 Windows 的模組。 請勿將模組安裝至此位置。

  • $HOME\Documents\WindowsPowerShell\Modules （%HOMEDRIVE%%HOMEPATH%\Documents\WindowsPowerShell\Modules）

  • $Env:ProgramFiles\WindowsPowerShell\Modules （%ProgramFiles%\WindowsPowerShell\Modules）

    若要取得 PSModulePath 環境變數的值，請使用下列其中一個命令。

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

    若要將模組路徑新增至 PSModulePath 的值 環境變數值，請使用下列命令格式。 此格式會使用 System.Environment 類別的 SetEnvironmentVariable 方法，對 PSModulePath 環境變數進行會話無關的變更。

    #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之後，您應該廣播有關變更的環境訊息。 廣播變更可讓殼層等其他應用程式挑選變更。 若要廣播變更，請讓產品安裝程式代碼傳送 WM_SETTINGCHANGE 訊息，並將 lParam 設定為字串 “Environment”。 請務必在模組安裝程序代碼更新 PSModulePath之後傳送訊息。

使用正確的模組目錄名稱

格式正確的模組是儲存在與模組目錄中至少一個檔案基底名稱相同的目錄中的模組。 如果模組的格式不正確，Windows PowerShell 無法將其辨識為模組。

檔案的「基底名稱」是沒有擴展名的名稱。 在格式正確的模組中，包含模組檔案的目錄名稱必須符合模組中至少一個檔案的基底名稱。

例如，在範例 Fabrikam 模組中，包含模組檔案的目錄名為 “Fabrikam”，而且至少有一個檔案具有 “Fabrikam” 基底名稱。 在此情況下，Fabrikam.psd1 和 Fabrikam.dll 都有 “Fabrikam” 基底名稱。

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

不正確的安裝效果

如果模組的格式不正確，且其位置未包含在 PSModulePath 環境變數的值中，則 Windows PowerShell 的基本探索功能，例如下列專案無法運作。

  • 模組自動載入功能無法自動匯入模組。

  • Get-Module Cmdlet 的 ListAvailable 參數找不到模組。

  • Import-Module Cmdlet 找不到模組。 若要匯入模組，您必須提供根模組檔案或模組指令清單檔的完整路徑。

    除非將模組匯入會話，否則其他功能，例如下列功能無法運作。 在 PSModulePath 環境變數中格式正確的模組中，即使模組未匯入會話，這些功能仍可運作。

  • Get-Command Cmdlet 在模組中找不到命令。

  • Update-Help 和 Save-Help Cmdlet 無法更新或儲存模組的說明。

  • Show-Command Cmdlet 找不到並在模組中顯示命令。

    模組中的命令在 Windows PowerShell 整合式腳本環境 （ISE） 的 [Show-Command] 視窗中遺失。

安裝模組的位置

本節說明文件系統中安裝 Windows PowerShell 模組的位置。 位置取決於模組的使用方式。

安裝特定用戶的模組

如果您建立自己的模組，或從其他合作物件取得模組，例如 Windows PowerShell 社群網站，而且您希望模組僅供用戶帳戶使用，請在使用者特定的 Modules 目錄中安裝模組。

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

根據預設，使用者特定的Modules目錄會新增至 PSModulePath 環境變數的值。

在 Program Files 中為所有使用者安裝模組

如果您想要讓計算機上的所有用戶帳戶都能使用模組，請在 Program Files 位置安裝模組。

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

備註

Program Files 位置預設會在 Windows PowerShell 4.0 和更新版本中新增至 PSModulePath 環境變數的值。 針對舊版的 Windows PowerShell，您可以手動建立 Program Files 位置（%ProgramFiles%\WindowsPowerShell\Modules），並將此路徑新增至 PSModulePath 環境變數，如上所述。

在產品目錄中安裝模組

如果您要將模組散發給其他合作物件，請使用上述的預設 Program Files 位置，或建立您自己 %ProgramFiles% 目錄的公司特定或產品特定子目錄。

例如，虛構公司的 Fabrikam Technologies 正在為其 Fabrikam Manager 產品運送 Windows PowerShell 模組。 其模組安裝程式會在 Fabrikam Manager 產品子目錄中建立 Modules 子目錄。

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

若要讓 Windows PowerShell 模組探索功能尋找 Fabrikam 模組，Fabrikam 模組安裝程式會將模組位置新增至 PSModulePath 環境變數的值。

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

在通用檔案目錄中安裝模組

如果模組是由產品多個元件或產品的多個版本使用，請在 \Common Files\Modules 子目錄 %ProgramFiles%的模組特定子目錄中安裝模組。

在下列範例中，Fabrikam 模組會安裝在 %ProgramFiles%\Common Files\Modules 子目錄的 Fabrikam 子目錄中。 請注意，每個模組都位於Modules子目錄中自己的子目錄中。

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

然後，安裝程式可確保 PSModulePath 環境變數的值包含 Common Files\Modules 子目錄的路徑。

$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)

安裝模組的多個版本

若要安裝相同模組的多個版本，請使用下列程式。

  1. 為每個模組版本建立目錄。 在目錄名稱中包含版本號碼。
  2. 為每個模組版本建立模組指令清單。 在指令清單中 ModuleVersion 機碼的值中，輸入模組版本號碼。 將指令清單檔案 （.psd1） 儲存在模組的版本特定目錄中。
  3. 將模組根資料夾路徑新增至 PSModulePath 環境變數的值，如下列範例所示。

若要匯入模組的特定版本，使用者可以使用 Import-Module Cmdlet MinimumVersion 或 RequiredVersion 參數。

例如，如果 Fabrikam 模組可在 8.0 和 9.0 版中使用，Fabrikam 模組目錄結構可能會如下所示。

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 環境變數值。

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

這些步驟完成時，Get-Module Cmdlet 的 ListAvailable 參數會取得 Fabrikam 模組的兩個。 若要匯入特定模組，請使用 Import-Module Cmdlet 的 MinimumVersion 或 RequiredVersion 參數。

如果這兩個模組都匯入相同的會話，而模組包含具有相同名稱的 Cmdlet，則最後匯入的 Cmdlet 在會話中有效。

處理命令名稱衝突

當模組導出的命令與使用者會話中的命令具有相同名稱時，可能會發生命令名稱衝突。

當會話包含兩個具有相同名稱的命令時，Windows PowerShell 會執行優先的命令類型。 當會話包含兩個具有相同名稱和相同類型的命令時，Windows PowerShell 會執行最近新增至會話的命令。 若要執行預設未執行的命令，用戶可以使用模組名稱來限定命令名稱。

例如，如果會話包含 Get-Date 函式和 Get-Date Cmdlet，Windows PowerShell 預設會執行函式。 若要執行 Cmdlet，請在命令前面加上模組名稱，例如：

Microsoft.PowerShell.Utility\Get-Date

為了防止名稱衝突，模組作者可以使用模組指令清單中 DefaultCommandPrefix 索引鍵來指定從模組匯出之所有命令的名詞前置詞。

使用者可以使用 Import-Module Cmdlet 的 Prefix 參數來使用替代前置詞。 Prefix 參數的值優先於 DefaultCommandPrefix 索引鍵的值。

支援非 Windows 系統上的路徑

非 Windows 平臺會使用冒號 （:） 字元作為路徑分隔符，並使用正斜線 （/） 字元作為目錄分隔符。 [System.IO.Path] 類別具有靜態成員，可用來讓您的程式代碼在任何平台上運作：

  • [System.IO.Path]::PathSeparator - 傳回字元，用來分隔主機平臺之PATH環境變數中的路徑
  • [System.IO.Path]::DirectorySeparatorChar - 傳回字元，用來以主機平台的路徑分隔目錄名稱

當您建構路徑字串時，請使用這些靜態屬性來取代 ; 和 \ 字元。

另請參閱

關於指令優先順序

撰寫 Windows PowerShell 模組