關於模組

簡短描述

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

完整描述

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

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

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

什麼是模組？

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

模組自動載入

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

模組中的命令也比較容易找到。 Get-CommandCmdlet 現在會取得所有已安裝模組中的所有命令，即使它們尚未存在於會話中，因此您可以尋找命令並在不匯入的情況下使用它。

下列每個範例都會導致包含的模組匯 Get-Mailbox 入到您的會話中。

執行命令
```
Get-Mailbox -Identity Chris
```
取得命令
```
Get-Command Get-Mailbox
```
取得命令的說明
```
Get-Help Get-Mailbox
```

Get-Command包含萬用字元（*）的命令會被視為用於探索、不使用，而且不會匯入任何模組。

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

此外，使用 PowerShell 提供者的命令不會自動匯入模組。例如，如果您使用需要 WSMan：磁片磁碟機（例如 Cmdlet）的命令， Get-PSSessionConfiguration 您可能需要執行 Import-Module Cmdlet 來匯入包含該磁片磁碟機的Microsoft WSMan 管理模組 WSMan: 。

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

如何使用模組

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

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

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

如何安裝模組

如果您收到模組作為包含檔案的資料夾，您必須先將它安裝在電腦上，才能在 PowerShell 中使用。

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

使用下列命令，為目前的使用者建立模組目錄：

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

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

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

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

如何尋找已安裝的模組

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

Get-Module -ListAvailable

若要尋找已匯入您會話的模組，請在 PowerShell 命令提示字元中輸入：

Get-Module

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

如何尋找模組中的命令

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

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

Get-Command -Module <module-name>

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

Get-Command -Module BitsTransfer

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

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

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

從 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

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

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

以下是 PowerShell 模組的預設位置。從 PowerShell 4.0 開始，隨著 DSC 的引進，引進了新的預設模組和 DSC 資源資料夾。如需 DSC 的詳細資訊，請參閱about_DesiredStateConfiguration。

System： $PSHOME\Modules 或（ $env:windir\System32\WindowsPowerShell\v1.0\Modules ）系統模組是隨附于 Windows 和 PowerShell。

從 PowerShell 4.0 開始，當引進 PowerShell Desired State Configuration （DSC）時，PowerShell 隨附的 DSC 資源也會儲存在資料夾中 $PSHOME\Modules 的 $PSHOME\Modules\PSDesiredStateConfiguration\DSCResources 。
目前的使用者： $HOME\Documents\WindowsPowerShell\Modules （ $env:UserProfile\Documents\WindowsPowerShell\Modules ）

或

$HOME\My Documents\WindowsPowerShell\Modules ($env:UserProfile\My Documents\WindowsPowerShell\Modules)

這是在 PowerShell 4.0 之前，使用者新增模組的位置。

在 PowerShell 4.0 和更新版本的 PowerShell 中，使用者新增的模組和 DSC 資源會儲存在中 C:\Program Files\WindowsPowerShell\Modules 。電腦的所有使用者都可以存取此位置中的模組和 DSC 資源。這是必要的變更，因為 DSC 引擎會以本機系統的身分執行，而且無法存取使用者特定的路徑，例如 $home\Documents\WindowsPowerShell\Modules 。

從 PowerShell 5.0 開始，加上 PowerShellGet 模組和PowerShell 資源庫的社區和 Microsoft 建立的資源，此 Install-Module 命令預設會將模組和 DSC 資源安裝到 C:\Program Files\WindowsPowerShell\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"

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

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

此外，若要讓變更持續進行，您也可以使用system.object類別的SetEnvironmentVariable方法，將路徑新增至PSModulePath環境變數。

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

模組和名稱衝突

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

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

Hidden

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

已取代

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

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

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

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

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

模組作者可以使用模組資訊清單的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 嵌入式管理單元的詳細資訊，請參閱about_PSSnapins。

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

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

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

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

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

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

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

注意

遠端會話（包括使用 Cmdlet 啟動的會話） New-PSSession 是舊版的會話，其中內建命令會封裝在嵌入式管理單元中。

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

Microsoft.PowerShell.Archive
Microsoft.PowerShell.Core
Microsoft.PowerShell.Diagnostics
Microsoft.PowerShell.Host
Microsoft.PowerShell.Management
Microsoft.PowerShell.ODataUtils
Microsoft.PowerShell.Security
Microsoft.PowerShell.Utility
Microsoft.WSMan.Management
PackageManagement
PowerShellGet
PSDesiredStateConfiguration
PSReadline
PSScheduledJob
PSWorkflow
PSWorkflowUtility
ISE

記錄模組事件

從 PowerShell 3.0 開始，您可以將模組和嵌入式管理單元的LogPipelineExecutionDetails屬性設定為，以在 powershell 模組和嵌入式管理單元中記錄 Cmdlet 和函式的執行事件 $True 。您也可以使用群組原則設定 [開啟模組記錄]，在所有 PowerShell 會話中啟用模組記錄。如需詳細資訊，請參閱about_EventLogs和about_Group_Policy_Settings。