共用方式為

about_Modules

  • 發行項

簡短描述

說明如何安裝、匯入及使用PowerShell模組。

詳細描述

PowerShell 既是命令殼層，也是腳本語言。 PowerShell 中的命令會實作為腳本、函式或 Cmdlet。 語言包含 關鍵詞，可提供處理的結構和邏輯，以及其他資源，例如變數、提供者、別名。

模組是獨立的可重複使用單位，可包含 Cmdlet、提供者、函式、變數和其他資源。 根據預設，PowerShell 會在您第一次從模組使用命令時自動載入已安裝的模組。 您可以使用 變數 $PSModuleAutoloadingPreference來設定自動模組載入行為。 如需詳細資訊，請參閱 about_Preference_Variables。

您也可以在 PowerShell 工作階段期間手動載入或卸除模組。 若要載入或重載模組，請使用 Import-Module。 若要卸除模組，請使用 Remove-Module Cmdlet。

PowerShell 包含一組基底模組。 任何人都可以使用 C# 或 PowerShell 腳本語言本身來建立新的模組。 以 C# 撰寫為已編譯 .NET 元件的模組稱為原生模組。 以 PowerShell 撰寫的模組稱為腳本模組。

本文說明如何使用PowerShell模組。 如需如何建立 PowerShell 模組的詳細資訊，請參閱 撰寫 PowerShell 模組。

注意

在 PowerShell 3.0 之前，Cmdlet 和提供者會封裝在 PowerShell 嵌入式管理單元中。從 PowerShell 3.0 開始， 預設會將 Microsoft.PowerShell.Core 嵌入式管理單元新增至每個會話。 這是 PowerShell 中唯一剩餘的嵌入式管理單元。 所有其他嵌入式管理單元都已轉換成模組。 不再支援建立新的嵌入式管理單元。

默認模組位置

PowerShell 會將模組儲存在下列預設位置：

  • 在 Windows 上
    • 所有使用者範圍 - $env:ProgramFiles\PowerShell\Modules
    • 目前的使用者範圍 - $HOME\Documents\PowerShell\Modules
    • 隨附於 PowerShell 的模組 - $PSHOME\Modules
  • 在 Linux 和 macOS 上
    • 所有使用者範圍 - /usr/local/share/powershell/Modules
    • 目前的使用者範圍 - $HOME/.local/share/powershell/Modules
    • 隨附於 PowerShell 的模組 - $PSHOME/Modules

根據預設， Modules 目前用戶的資料夾不存在。 如果您使用 或 Install-PSResource在範圍Install-Module中CurrentUser安裝模組，這些 Cmdlet 會建立Modules目前使用者的資料夾。 如果資料夾不存在，您可以手動建立它。

使用下列指令建立 Modules 目前使用者的資料夾：

$folder = New-Item -Type Directory -Path $HOME\Documents\PowerShell\Modules

這些位置會自動包含在環境變數中 $env:PSModulePath 。 如需預設模組位置的詳細資訊，請參閱 about_PSModulePath。

模組自動載入

第一次從已安裝的模組執行命令時，PowerShell 會自動匯入該模組（載入） 該模組。 模組必須儲存在環境變數中指定的 $env:PSModulePath 位置。

模組自動載入可讓您在模組中使用命令，而不需要任何設定或設定檔組態。 下列每個範例都會讓 包含的 CimCmdlets 模組 Get-CimInstance匯入您的工作階段。

  • 執行命令

    Get-CimInstance Win32_OperatingSystem

  • 取得命令

    Get-Command Get-CimInstance

  • 取得命令的說明

    Get-Help Get-CimInstance

當您搭配通配符 （*） 使用 Get-Command 時，PowerShell 不會匯入任何模組。 您可以使用通配符進行命令探索，而不需要載入會話中可能不需要的模組。

手動匯入模組

當模組未安裝在環境變數所指定 $env:PSModulePath 的位置，或當模組以獨立 .dll 或 .psm1 檔案的形式提供，而不是封裝的模組時，需要手動匯入模組。

此外，使用 PowerShell 提供者的命令不會自動匯入模組。 例如，如果您使用需要 WSMan: 磁碟驅動器的命令，例如 Get-PSSessionConfiguration Cmdlet，您可能需要執行 Import-Module Cmdlet 來匯 入包含磁碟驅動器的 Microsoft.WSMan.Management 模組 WSMan: 。

您也可以變更在工作階段中匯入模組的方式。 例如，的 Import-Module Prefix 參數會將獨特的前置詞新增至從模組匯入之 Cmdlet 的名詞部分。 NoClobber 參數會防止模組新增命令，以隱藏或取代會話中的現有命令。 如需詳細資訊，請參閱 管理名稱衝突。

下列範例會將 BitsTransfer 模組匯入目前的工作階段。

Import-Module BitsTransfer

若要匯入不在 中的 $env:PSModulePath模組，請使用模組資料夾的完整路徑。 例如，若要將目錄中的 C:\ps-test TestCmdlets 模組新增至您的工作階段，請輸入：

Import-Module C:\ps-test\TestCmdlets

若要匯入模組資料夾中未包含的模組檔案，請使用命令中模組檔案的完整路徑。 例如，若要將目錄中的 TestCmdlets.dll 模組 C:\ps-test 新增至您的工作階段，請輸入：

Import-Module C:\ps-test\TestCmdlets.dll

如需將模組新增至會話的詳細資訊，請參閱 Import-Module。

在每個工作階段開始時匯入模組

Import-Module命令會將模組匯入您目前的PowerShell工作階段。 若要將模組匯入您啟動的每個 PowerShell 工作階段，請將 命令新增 Import-Module 至 PowerShell 配置檔。

如需配置檔的詳細資訊，請參閱 about_Profiles。

安裝已發佈的模組

已發佈的模組是可從已註冊存放庫取得的模組，例如 PowerShell 資源庫。 PowerShellGet 和 Microsoft.PowerShell.PSResourceGet 模組會提供 Cmdlet，以尋找、安裝 PowerShell 模組，以及將 PowerShell 模組發佈至已註冊的存放庫。

PowerShellGet 模組隨附於 PowerShell 5.0 和更新版本。 Microsoft.PowerShell.PSResourceGet 模組隨附於 PowerShell 7.4 和更新版本，而且是 PowerShell 的慣用套件管理員。 Microsoft.PowerShell.PSResourceGet 可以與舊版 PowerShell 上的 PowerShellGet 並存安裝。 Install-Module使用 或 Install-PSResource Cmdlet 從 PowerShell 資源庫 安裝模組。

 Get-Command Install-Module, Install-PSResource

CommandType  Name                Version    Source
-----------  ----                -------    ------
Function     Install-Module      2.9.0      PowerShellGet
Cmdlet       Install-PSResource  1.0.0      Microsoft.PowerShell.PSResourceGet

如需詳細資訊，請參閱 PowerShellGet 概觀。

手動安裝模組

您可以從另一個資料夾複製模組內容，以手動安裝模組。 該資料夾可以位於本機電腦上的另一個位置，或安裝在另一部電腦上。 若要手動安裝模組，請將整個模組資料夾複製到 包含在中的 $env:PSModulePath新位置。

在 PowerShell 中， Copy-Item 使用 Cmdlet。 例如，執行下列命令，從 C:\PSTest複製MyModule資料夾：

$modulePath = $HOME\Documents\PowerShell\Modules\MyModule
Copy-Item -Path C:\PSTest\MyModule\* -Destination $modulePath -Recurse

您可以在任何位置安裝模組，但將模組安裝在預設模組位置可讓模組更容易管理。

尋找已安裝的模組

Cmdlet Get-Module 會取得目前 PowerShell 工作階段中載入的 PowerShell 模組。

Get-Module

列出的模組可以包含從任何位置匯入的模組，而不只是從 $env:PSModulePath。

使用下列命令來列出 中 $env:PSModulePath安裝的模組：

Get-Module -ListAvailable

此命令會取得中 $env:PSModulePath安裝的所有模組，而不只是匯入目前會話的模組。 此命令不會列出安裝在其他位置的模組。

如需詳細資訊，請參閱 Get-Module。

列出模組中的命令

Get-Command使用 Cmdlet 來尋找所有可用的命令。 您可以使用 Cmdlet 的參數 Get-Command 來篩選命令，例如依模組、名稱和名詞。

若要尋找模組中的所有命令，請輸入：

Get-Command -Module <module-name>

例如，若要在 BitsTransfer 模組中尋找命令，請輸入：

Get-Command -Module BitsTransfer

如需 Cmdlet 的詳細資訊 Get-Command ，請參閱 Get-Command。

拿掉模組

當您移除模組時，模組新增的命令會從會話中刪除。 例如，下列命令會 從目前的會話中移除 BitsTransfer 模組。

Remove-Module BitsTransfer

拿掉模組會反轉匯入模組的作業。 拿掉模組並不會卸載模組。 如需詳細資訊，請參閱 Remove-Module。

您可以從模組和嵌入式管理單元將命令新增至您的工作階段。模組可以新增所有類型的命令，包括 Cmdlet、提供者和函式，以及變數、別名和 PowerShell 磁碟驅動器等專案。 嵌入式管理單元只能新增 Cmdlet 和提供者。

在從會話中移除模組之前，請使用下列命令來判斷您要移除的模組。

例如，使用下列命令來尋找 和 Get-Help Cmdlet 的來源Get-Date：

Get-Command Get-Date, Get-Help -All |
    Select-Object -Property Name, CommandType, Module ,PSSnapIn

下列輸出顯示 Get-Help Cmdlet 位於 Microsoft.PowerShell.Core 嵌入式管理單元中。 無法從會話中移除此嵌入式管理單元。

Name     CommandType Module                       PSSnapIn
----     ----------- ------                       --------
Get-Date    Function
Get-Date      Cmdlet Microsoft.PowerShell.Utility
Get-Help      Cmdlet                              Microsoft.PowerShell.Core

有兩個來源。Get-Date 其中一個是函式，另一個是 Microsoft.PowerShell.Utility 模組中的 Cmdlet。 您可以使用 移除模組 Remove-Module。 若要移除函式，您可以從磁碟驅動器中刪除它 Function: 。

Remove-Item Function:Get-Date

如需磁碟驅動器的詳細資訊 Function: ，請參閱 about_Function_Provider。

管理名稱衝突

當工作階段中的多個命令具有相同名稱時，就會發生名稱衝突。 當模組中的命令與會話中的命令或專案名稱相同時，匯入模組會導致名稱衝突。

Import-Module 可能會新增命令，以隱藏和取代目前會話中的命令。 名稱衝突可能會導致命令隱藏或取代。 當匯入的模組包含與會話中現有命令同名的命令時，就會發生命令取代。 新匯入的命令優先於現有的命令。

例如，當會話包含函式和具有相同名稱的 Cmdlet 時，PowerShell 預設會執行函式。 當會話包含具有相同名稱之相同類型的命令時，預設會執行最近新增的命令，例如具有相同名稱的兩個 Cmdlet。

如需詳細資訊，包括優先順序規則的說明，以及執行隱藏命令的指示，請參閱 about_Command_Precedence。

您可以藉由限定命令名稱來執行隱藏或取代的命令。 若要限定命令名稱，請新增包含所需命令版本的模組名稱。 例如：

Microsoft.PowerShell.Utility\Get-Date

使用模組名稱前置詞執行 Get-Date 可確保從 Microsoft.PowerShell.Utility 模組執行版本。

若要偵測名稱衝突，請使用 Cmdlet 的 Get-Command All 參數。 根據預設， Get-Command 只會取得當您輸入命令名稱時所執行的命令。 All 參數會取得會話中具有特定名稱的所有命令。

若要防止名稱衝突，請使用 Cmdlet 的 Import-Module NoClobber 或 Prefix 參數。 Prefix 參數會將前置詞新增至匯入命令的名稱，使其在會話中是唯一的。 NoClobber 參數不會匯入任何會隱藏或取代會話中現有命令的命令。

您也可以使用 的 Import-Module Alias、Cmdlet、Function 和 Variable 參數，只選取您想要匯入的命令，而且您可以排除導致會話中名稱衝突的命令。

模組作者可以使用模組指令清單的 DefaultCommandPrefix 屬性，將預設前置詞新增至所有命令名稱，以防止名稱衝突。 Prefix 參數的值優先於 DefaultCommandPrefix 的值。

另請參閱