共用方式為

關於_模組

簡短描述

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

完整描述

模組是包含PowerShell成員（如 cmdlet、提供程式、函數、工作流、變數和別名）的包。

編寫命令的人可以使用模組來組織他們的命令並與他人共用。 接收模組的人可以將模組中的命令添加到他們的PowerShell會話中，並像使用內置命令一樣使用它們。

本主題介紹如何使用PowerShell模組。 有關如何編寫 PowerShell 模組的資訊，請參閱 編寫 PowerShell 模組。

什麼是模組？

模組是包含PowerShell成員（如 cmdlet、提供程式、函數、工作流、變數和別名）的包。 此包的成員可以在PowerShell腳本、編譯的 DLL 或兩者的組合中實現。 這些檔通常分組到一個目錄中。 有關更多資訊，請參閱 SDK 文件中的 瞭解 Windows PowerShell 模組 。

模組自動載入

從 PowerShell 3.0 開始，當您首次在已安裝的模組中運行任何命令時，PowerShell 會自動導入模組。 現在，您可以在模組中使用這些命令，而無需進行任何設置或配置檔配置，因此在將模組安裝到計算機上后，無需管理模組。

模組中的命令也更容易找到。 現在，cmdlet Get-Command 可以獲取所有已安裝模組中的所有命令，即使它們尚未在會話中。 您可以找到一個命令並使用它，而無需導入，無需先導入模組。

以下每個示例都會導致將包含 Get-CimInstance的 CimCmdlets 模組導入到工作階段中。

  • 執行命令

    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: 模組。

您仍然可以運行命令 Import-Module 來導入模組，並使用 $PSModuleAutoloadingPreference 該變數來啟用、禁用和配置模組的自動導入。 如需詳細資訊，請參閱 about_Preference_Variables。

如何使用模組

要使用模組，請執行以下任務：

  1. 安裝模組。 （這通常是為您完成的。
  2. 找到模組添加的命令。
  3. 使用模組添加的命令。

本主題說明如何執行這些任務。 它還包括有關管理模組的其他有用資訊。

如何安裝模組

如果您以資料夾的形式接收模組，其中包含檔，則需要先將其安裝在您的電腦上，然後才能在PowerShell中使用它。

大多數模組都是為您安裝的。 PowerShell 附帶了幾個預安裝的模組，有時稱為 核心 模組。 在基於 Windows 的電腦上，如果作系統附帶的功能具有用於管理這些功能的 cmdlet，則會預安裝這些模組。 安裝 Windows 功能時，例如，通過使用伺服器管理器中的「添加角色和功能精靈」或「控制面板」中的「打開或關閉 Windows 功能」對話框，將安裝屬於該功能的任何 PowerShell 模組。 許多其他模組都來自安裝模組的安裝程式或 Setup 程式。

使用以下命令為目前使用者建立 Modules 目錄：

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

將整個module資料夾複製到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

您可以在任何位置安裝模組，但將模組安裝在預設模組位置可讓模組更容易管理。 有關預設模組位置的詳細資訊，請參閱 模組和 DSC 資源位置以及 PSModulePath 部分。

如何查找已安裝的模組

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

Get-Module -ListAvailable

要查找已導入到會話中的模組，請在 PowerShell 提示符下鍵入：

Get-Module

有關 Get-Module cmdlet 的詳細資訊，請參閱 Get-Module。

如何在模組中查找命令

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

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

Get-Command -Module <module-name>

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

Get-Command -Module BitsTransfer

如需 Get-Command Cmdlet 的詳細資訊，請參閱 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

要匯入模組資料夾中未包含的模組檔，請在命令中使用模組檔的完全限定路徑。

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

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 位於使用者配置檔中 Documents 位置的資料夾。 該位置的具體路徑因 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 配置檔，或使用控制面板中的系統更改註冊表中 PSModulePath 環境變數的值。

此外，若要使更改持久化，還可以使用 System.Environment 類的 SetEnvironmentVariable 方法向 PSModulePath 環境變數添加 Path。

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

模組和名稱衝突

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

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

隱藏

如果命令不是鍵入命令名稱時運行的命令，則該命令處於隱藏狀態，但您可以使用其他方法運行該命令，例如，使用命令名稱所在的模組或管理單元的名稱限定命令名稱。

取代

如果命令因被同名命令覆蓋而無法運行，則會替換該命令。 即使刪除導致衝突的模組，也無法運行替換的命令，除非重新啟動會話。

Import-Module 可能會新增命令，以隱藏和取代目前會話中的命令。 此外，會話中的命令可以隱藏模組添加的命令。

若要偵測名稱衝突，請使用 Cmdlet 的 Get-Command 參數。 從 PowerShell 3.0 開始， Get-Command 僅獲取在鍵入命令名稱時運行的命令。 All 參數會取得工作階段中具有特定名稱的所有命令。

若要防止名稱衝突，請使用 NoClobber 或 PrefixImport-Module Cmdlet 的參數。 Prefix 參數為導入的命令的名稱添加前綴，以便它們在會話中是唯一的。 NoClobber 參數不會導入任何會隱藏或替換會話中現有命令的命令。

您也可以使用 Alias、Cmdlet、Function和 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 命令命名規則。 如果導入的模組導出的名稱中包含未經批准的動詞的 cmdlet 或函數，則 Import-Module cmdlet 將顯示以下警告消息。

警告：某些彙入的命令名稱包含未經核准的動詞命令，這可能會使其更容易探索。 如需詳細資訊或類型 Get-Verb，請使用 Verbose 參數來查看已核准的動詞清單。

此訊息只是警告。 完整模組仍會匯入，包括不符合規範的命令。 雖然訊息會顯示給模組使用者，但模組作者應該修正命名問題。

若要禁止顯示警告消息，請使用 cmdlet 的 Import-Module 參數。

內置模組和管理單元

在 PowerShell 2.0 和 PowerShell 3.0 及更高版本的舊式主機程式中，隨 PowerShell 一起安裝的核心命令打包在管理單元中，這些管理單元會自動添加到每個 PowerShell 會話中。

從 PowerShell 3.0 開始，對於實現 InitialSessionState.CreateDefault2 初始會話狀態 API 的主機程式，預設情況下，Microsoft.PowerShell.Core 管理單元將添加到每個會話中。 模組在首次使用時自動載入。

備註

遠程會話（包括使用 New-PSSession cmdlet 啟動的工作階段）是舊式會話，其中內置命令打包在管理單元中。

以下模組（或管理單元）隨 PowerShell 一起安裝。

  • CimCmdlets
  • Microsoft.PowerShell.存檔
  • Microsoft.PowerShell.Core
  • Microsoft.PowerShell.Diagnostics
  • Microsoft.PowerShell.主機
  • Microsoft.PowerShell.Management
  • Microsoft.PowerShell.Security
  • Microsoft.PowerShell.Utility
  • Microsoft.WSMan.Management
  • 套件管理
  • PowerShellGet
  • PSDesiredStateConfiguration
  • PS 診斷
  • PSReadline

記錄模組事件

從 PowerShell 3.0 開始，您可以通過將模組和管理單元的 $True 屬性設置為 來記錄 PowerShell 模組和管理單元中 cmdlet 和函數的執行事件。 您還可以使用組策略設置「打開模組紀錄記錄」 在所有 PowerShell 工作階段中啟用模組紀錄記錄。 有關詳細資訊，請參閱日誌記錄和組策略文章。

另請參閱

  • Last updated on