關於模組

發行項
05/09/2024

簡短描述

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

完整描述

模組是包含PowerShell命令的套件，例如 Cmdlet、提供者、函式、工作流程、變數和別名。

撰寫命令者可以使用模組來組織其命令，並與其他人分享。人員接收模組的人員可以將模組中的命令新增至其PowerShell作業階段，並使用它們就像內建命令一樣。

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

什麼是模組？

模組是命令的套件。會話中的所有 Cmdlet 和提供者都會由模組或嵌入式管理單元新增。

模組自動載入

從 PowerShell 3.0 開始，PowerShell 會在您第一次在已安裝的模組中執行任何命令時自動匯入模組。您現在可以使用模組中的命令，而不需要任何設定或設定檔設定，因此在電腦上安裝模組之後不需要進行管理。

模組中的命令也比較容易找到。 Cmdlet Get-Command 現在會取得所有已安裝模組中的所有命令，即使它們還不在會話中，您仍可找到命令，並在不匯入的情況下使用它。

下列每個範例都會讓包含的 CimCmdlets 模組 Get-CimInstance匯入您的工作階段。

執行命令
```
Get-CimInstance Win32_OperatingSystem
```
取得命令
```
Get-Command Get-CimInstance
```
取得命令的說明
```
Get-Help Get-CimInstance
```

Get-Command 包含通配符 (*) 命令會被視為用於探索、不使用，也不會匯入任何模組。

只會自動匯入儲存在 PSModulePath 環境變數所指定位置的模組。其他位置中的模組必須藉由執行 Import-Module Cmdlet 來匯入。

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

您仍然可以執行 Import-Module 命令來匯入模組，並使用 $PSModuleAutoloadingPreference 變數來啟用、停用和設定模組的自動匯入。如需詳細資訊，請參閱 about_Preference_Variables。

如何使用模組

若要使用模組，請執行下列工作：

安裝模組 (這通常會為您完成)。
尋找模組所新增的命令。
使用模組所新增的命令。

此主題說明如何執行這些工作。它也包含管理模組的其他實用資訊。

如何安裝模組

如果您收到模組作為其中檔案的資料夾，您必須先在計算機上安裝該模組，才能在 PowerShell 中使用。

大部分的模組會為您安裝。 PowerShell 隨附數個預安裝模塊，有時稱為核心模組。在 Windows 電腦上，如果操作系統隨附的功能具有 Cmdlet 來管理它們，這些模組就會預安裝。當您安裝 Windows 功能時，例如，使用伺服器管理員中的 [新增角色及功能精靈]，或控制台中的 [開啟或關閉 Windows 功能] 對話框，就會安裝屬於此功能的任何 PowerShell 模組。其他許多模組則包含在安裝模組的安裝程式或 Setup 程式中。

使用下列命令來建立目前使用者的 Modules 目錄：

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

將整個模組資料夾複製到 Modules 目錄中。您可以使用任何方法來複製資料夾，包括 Windows 檔案總管和 Cmd.exe，以及 PowerShell。在 PowerShell 中， Copy-Item 使用 Cmdlet。例如，若要將 MyModule 資料夾從 C:\ps-test\MyModule 複製到 Modules 目錄，請輸入：

Copy-Item -Path C:\ps-test\MyModule -Destination `
    $HOME\Documents\PowerShell\Modules

您可以在任何位置安裝模組，但在預設模組位置安裝模組可讓您更輕鬆地管理模組。如需默認模組位置的詳細資訊，請參閱 Module和 DSC Resource Locations 和 PSModulePath 一節。

如何尋找已安裝的模組

若要尋找已安裝在預設模組位置，但尚未匯入到您工作階段的模組，請輸入：

Get-Module -ListAvailable

若要尋找已匯入工作階段的模組，請在 PowerShell 提示字元中輸入：

Get-Module

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

如何在模組中尋找命令

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

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

Get-Command -Module <module-name>

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

Get-Command -Module BitsTransfer

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

如何取得模組中命令的說明

如果模組包含其導出命令的說明檔， Get-Help Cmdlet 會顯示 [說明] 主題。使用您用來取得 PowerShell 中任何命令的說明的相同 Get-Help 命令格式。

從 PowerShell 3.0 開始，您可以下載模組的說明檔，並下載說明檔的更新，使其永遠不會過時。

若要取得模組中之命令的說明，請輸入：

Get-Help <command-name>

若要在模組中取得命令的線上說明，請輸入：

Get-Help <command-name> -Online

若要下載並安裝模組中命令的說明檔，請輸入：

Update-Help -Module <module-name>

如需詳細資訊，請參閱 Get-Help 和 Update-Help。

如何匯入模組

您可能必須匯入模組或匯入模組檔案。當模組未安裝在 PSModulePath 環境變數 $env:PSModulePath所指定的位置，或模組是由檔案所組成，例如 .dll 或 .psm1 檔案，而不是傳遞為資料夾的一般模組時，則需要匯入。

您也可以選擇匯入模組，以便使用命令的參數 Import-Module ，例如 Prefix 參數，這會將所有匯入命令的名詞名稱或 NoClobber 參數新增特殊前置詞，以防止模組新增會隱藏或取代會話中現有命令的命令。

若要匯入 Import-Module 模組，請使用 Cmdlet。

若要將 PSModulePath 位置中的模組匯入到目前的工作階段，請使用下列命令格式。

Import-Module <module-name>

例如，下列命令會將 BitsTransfer 模組匯入目前的工作階段。

Import-Module BitsTransfer

若要匯入不在預設模組位置中的模組，請在命令中使用模組資料夾的完整路徑。

例如，若要將目錄中的 TestCmdlets 模組 C:\ps-test 新增至您的工作階段，請輸入：

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。

如何移除模組

當您移除模組時，會從工作階段刪除模組所加入的命令。

若要從會話中移除模組，請使用下列命令格式。

Remove-Module <module-name>

例如，下列命令會從目前的會話中移除 BitsTransfer 模組。

Remove-Module BitsTransfer

移除模組會反轉匯入模組的作業。移除模組並不會解除安裝模組。如需詳細資訊，請參閱 Remove-Module。

模組和 DSC 資源位置，以及 PSModulePath

$env:PSModulePath環境變數包含搜尋以尋找模組和資源的資料夾位置清單。

根據預設，指派給 $env:PSModulePath 的有效位置為：

全系統位置： $PSHOME\Modules

這些資料夾包含隨附於 Windows 和 PowerShell 的模組。

PowerShell 隨附的 DSC 資源會儲存在 $PSHOME\Modules\PSDesiredStateConfiguration\DSCResources 資料夾中。
使用者特定的模組：這些模組是由使用者安裝在用戶範圍中的模組。 Install-Module 具有 Scope 參數，可讓您指定模組是否已針對目前使用者或所有使用者安裝。如需詳細資訊，請參閱 Install-Module。

Windows 上使用者特定的 CurrentUser 位置是 PowerShell\Modules 位於使用者配置檔中 [檔 ] 位置的資料夾。該位置的特定路徑會因 Windows 版本而異，以及您是否使用資料夾重新導向。 Microsoft OneDrive 也可以變更 Documents 資料夾的位置。

根據預設，在 Windows 10 上，該位置為 $HOME\Documents\PowerShell\Modules。在 Linux 或 Mac 上， CurrentUser 位置為 $HOME/.local/share/powershell/Modules。

注意

您可以使用下列命令來驗證 Documents 資料夾的位置： [Environment]::GetFolderPath('MyDocuments')。
AllUsers 位置位於 $env:PROGRAMFILES\PowerShell\Modules Windows 上。在 Linux 或 Mac 上，模組會儲存在 /usr/local/share/powershell/Modules。

注意

若要在 $env:Windir\System32 目錄中新增或變更檔案，請使用 [ 以系統管理員身分執行 ] 選項啟動 PowerShell。

您可以變更 PSModulePath 環境變數 $Env:PSModulePath的值，來變更系統上的預設模組位置。 PSModulePath 環境變數是以Path環境變數模型化，而且具有相同的格式。

若要檢視預設模組位置，請輸入：

$Env:PSModulePath

若要新增預設模組位置，請使用下列命令格式。

$Env:PSModulePath = $Env:PSModulePath + ";<path>"

命令中的分號 (;) 會將新路徑與清單中前面的路徑分開。

例如，若要新增 C:\ps-test\Modules 目錄，請輸入：

$Env:PSModulePath + ";C:\ps-test\Modules"

若要在 Linux 或 MacOS 上新增預設模組位置，請使用下列命令格式：

$Env:PSModulePath += ":<path>"

例如，若要將 /usr/local/Fabrikam/Modules 目錄新增至 PSModulePath 環境變數的值，請輸入：

$Env:PSModulePath += ":/usr/local/Fabrikam/Modules"

在 Linux 或 MacOS 上，命令中的冒號 (:) 會將新路徑與清單中前面的路徑分開。

當您將路徑新增至 PSModulePath 時， Get-Module 命令 Import-Module 會包含該路徑中的模組。

您所設定的值只會影響目前的工作階段。若要持續變更，請將命令新增至 PowerShell 配置檔，或使用控制台中的 System 來變更登錄中 PSModulePath 環境變數的值。

此外，若要持續變更，您也可以使用 System.Environment 類別的 SetEnvironmentVariable 方法，將 Path 新增至 PSModulePath 環境變數。

如需 PSModulePath 變數的詳細資訊，請參閱 about_Environment_Variables。

模組和名稱衝突

工作階段中的多個命令擁有相同名稱時，會發生名稱衝突。當模組中的命令與工作階段中的命令或項目擁有相同的名稱時，匯入模組會造成名稱衝突。

名稱衝突可能會導致隱藏或取代命令。

Hidden

當某個命令不是您輸入命令名稱時執行的命令，但是您可以使用其他方法 (例如，使用起源自該命令之模組或嵌入式管理單元的名稱限定命令名稱) 執行它時，就會隱藏該命令。

已取代

當您因為具有相同名稱的命令覆寫某個命令而無法執行時，會取代該命令。即使您移除造成衝突的模組，除非您重新啟動工作階段，否則還是無法執行遭到取代的命令。

Import-Module 可能會新增命令，以隱藏和取代目前會話中的命令。此外，您工作階段中的命令可以隱藏模組所加入的命令。

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

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

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

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

即使隱藏某個命令，您還是可以透過使用起源自該命令之模組或嵌入式管理單元的名稱限定命令名稱來執行。

當會話包含具有相同名稱的命令時，PowerShell 命令優先順序規則會決定執行哪一個命令。

例如，當會話包含相同名稱的函式和 Cmdlet 時，PowerShell 預設會執行函式。當工作階段預設包含具有相同名稱之相同類型的命令 (例如，具有相同名稱的兩個 Cmdlet) 時，它會執行最近加入的命令。

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

模組與嵌入式管理單元

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

從您的工作階段移除模組或嵌入式管理單元之前，請使用下列命令判斷將會移除哪些命令。

若要在工作階段中尋找 Cmdlet 的來源，請使用下列命令格式：

Get-Command <cmdlet-name> | Format-List -Property verb,noun,pssnapin,module

例如，若要尋找 Cmdlet 的來源 Get-Date ，請輸入：

Get-Command Get-Date | Format-List -Property verb,noun,module

模組導出的命令應遵循 PowerShell 命令命名規則。如果您彙入的模組會匯出名稱中有未核准動詞的 Cmdlet 或函式， Import-Module Cmdlet 會顯示下列警告訊息。

警告：某些彙入的命令名稱包含未核准的動詞，這可能會讓它們更容易探索。請使用 Verbose 參數取得詳細資訊，或輸入 Get-Verb 查看核准的動詞清單。

這則訊息只是一個警告。模組仍然完整匯入，包括不合格的命令。雖然訊息是顯示給模組的使用者，但命名的問題應該由模組作者修正。

若要隱藏警告訊息，請使用 Cmdlet 的 Import-ModuleDisableNameChecking 參數。

內建模組和嵌入式管理單元

在 PowerShell 2.0 和舊版主機程式中，PowerShell 3.0 和更新版本中，隨 PowerShell 一起安裝的核心命令會封裝在自動新增至每個 PowerShell 會話的嵌入式管理單元中。

從 PowerShell 3.0 開始，針對實 InitialSessionState.CreateDefault2 作初始會話狀態 API 的主機程式，預設會將 Microsoft.PowerShell.Core 嵌入式管理單元新增至每個會話。第一次使用時，會自動載入模組。

注意

遠程會話，包括使用 New-PSSession Cmdlet 啟動的工作階段，是舊式會話，內建命令會封裝在嵌入式管理單元中。

下列模組 (或嵌入式管理單元) 會隨 PowerShell 一起安裝。

CimCmdlets
Microsoft.PowerShell.Archive
Microsoft.PowerShell.Core
Microsoft.PowerShell.Diagnostics
Microsoft.PowerShell.Host
Microsoft.PowerShell.Management
Microsoft.PowerShell.Security
Microsoft.PowerShell.Utility
Microsoft.WSMan.Management
PackageManagement
PowerShellGet
PSDesiredStateConfiguration
PSDiagnostics
PSReadline

記錄模組事件

從 PowerShell 3.0 開始，您可以將模組的 LogPipelineExecutionDetails 屬性設定為 $True，以記錄 PowerShell 模組和嵌入式管理單元中 Cmdlet 和函式的執行事件。您也可以使用群組原則設定開啟模組記錄，在所有 PowerShell 工作階段中啟用模組記錄。如需詳細資訊，請參閱記錄和組策略文章。