Import-Module

發行項
10/30/2009

將模組新增至目前工作階段。

語法

Import-Module [-Name] <string[]> [-Alias <string[]>] [-ArgumentList <Object[]>] [-AsCustomObject] [-Cmdlet <string[]>] [-Force] [-Function <string[]>] [-Global] [-PassThru] [-Prefix <string>] [-Variable <string[]>] [-Version <Version>] [<CommonParameters>]

Import-Module [-Assembly] <Assembly[]> [-Alias <string[]>] [-ArgumentList <Object[]>] [-AsCustomObject] [-Cmdlet <string[]>] [-Force] [-Function <string[]>] [-Global] [-PassThru] [-Prefix <string>] [-Variable <string[]>] [-Version <Version>] [<CommonParameters>]

Import-Module [-ModuleInfo] <PSModuleInfo[]> [-Alias <string[]>] [-ArgumentList <Object[]>] [-AsCustomObject] [-Cmdlet <string[]>] [-Force] [-Function <string[]>] [-Global] [-PassThru] [-Prefix <string>] [-Variable <string[]>] [-Version <Version>] [<CommonParameters>]

描述

Import-Module Cmdlet 會將一個或多個模組新增至目前的工作階段。

模組是一種封裝，其中包含可用於 Windows PowerShell 的成員 (例如 Cmdlet、提供者、指令碼、函數、變數，以及其他工具與檔案)。匯入模組之後，您就可以在工作階段中使用模組成員。

若要匯入模組，請使用 Name、Assembly 或 ModuleInfo 參數識別要匯入的模組。根據預設，雖然 Import-Module 會匯入模組所匯出的所有成員，不過您可以使用 Alias、Function、Cmdlet 和 Variable 參數來限制要匯入的成員。

Import-Module 只會將模組匯入至目前的工作階段。若要將模組匯入至所有工作階段，請將 Import-Module 命令新增至 Windows PowerShell 設定檔。如需設定檔的詳細資訊，請參閱 about_Profiles。

如需模組的詳細資訊，請參閱 about_Modules。

參數

-Alias <string[]>

只將指定的別名從模組匯入至目前的工作階段。請輸入以逗號分隔的別名清單。允許使用萬用字元。

某些模組會在您匯入時，自動將選取的別名匯出至工作階段。此參數可讓您從匯出的別名中進行選擇。

必要?	false
位置?	named
預設值
接受管線輸入?	false
接受萬用字元?	true

-ArgumentList <Object[]>

指定 Import-Module 命令執行期間傳遞至指令碼模組的引數 (參數值)。此參數只有當您匯入指令碼模組時才有效。

您也可以利用內建的別名 "args" 來參照 ArgumentList。如需詳細資訊，請參閱 about_Aliases。

必要?	false
位置?	named
預設值
接受管線輸入?	false
接受萬用字元?	false

-AsCustomObject

傳回自訂物件，其成員表示已匯入的模組成員。此參數只適用於指令碼模組。

使用 AsCustomObject 參數時，Import-Module 會將模組成員匯入至工作階段，然後傳回 PSCustomObject 物件而非 PSModuleInfo 物件。您可以將自訂物件儲存到變數中，並使用點標記法來叫用成員。

必要?	false
位置?	named
預設值
接受管線輸入?	false
接受萬用字元?	false

-Assembly <Assembly[]>

匯入在指定之組件物件中實作的 Cmdlet 和提供者。請輸入包含組件物件的變數，或輸入可建立組件物件的命令。您也可以經由管道將組件物件輸出至 Import-Module。

使用此參數時，只會匯入指定之已編譯組件所實作的 Cmdlet 和提供者。如果模組包含其他檔案，這些檔案並不會匯入，因此您可能會遺漏模組的重要成員。請使用此參數來偵錯及測試模組，或是依照模組作者的指示使用此參數。

必要?	true
位置?	1
預設值
接受管線輸入?	true (ByValue)
接受萬用字元?	false

-Cmdlet <string[]>

只將指定的 Cmdlet 從模組匯入至目前的工作階段。請輸入 Cmdlet 的清單。允許使用萬用字元。

某些模組會在您匯入時，自動將選取的 Cmdlet 匯出至工作階段。此參數可讓您從匯出的 Cmdlet 中進行選擇。

必要?	false
位置?	named
預設值
接受管線輸入?	false
接受萬用字元?	true

-Force

重新匯入模組及其成員，即使該模組或其成員具有唯讀的存取模式也一樣。

必要?	false
位置?	named
預設值	False
接受管線輸入?	false
接受萬用字元?	false

-Function <string[]>

只將指定的函數從模組匯入至目前的工作階段。請輸入函數的清單。允許使用萬用字元。

某些模組會在您匯入時，自動將選取的函數匯出至工作階段。此參數可讓您從匯出的函數中進行選擇。

必要?	false
位置?	named
預設值
接受管線輸入?	false
接受萬用字元?	true

-Global

當這個參數用於指令碼模組 (.psm1) 時，它會將模組匯入全域工作階段狀態中。

此參數只有當它出現在指令碼模組時才有效。否則，系統會忽略此參數。

根據預設，指令碼模組中的命令 (包括巢狀模組中的命令) 都會匯入呼叫者的工作階段狀態中。若要限制模組所匯出的命令，請在指令碼模組中使用 Export-ModuleMember 命令。

必要?	false
位置?	named
預設值
接受管線輸入?	false
接受萬用字元?	false

-ModuleInfo <PSModuleInfo[]>

指定要匯入的模組物件。請輸入包含模組物件的變數，或輸入可取得模組物件的命令，例如 "Get-Module -listavailable" 命令。您也可以經由管道將模組物件輸出至 Import-Module。

必要?	true
位置?	1
預設值
接受管線輸入?	true (ByValue)
接受萬用字元?	false

-Name <string[]>

指定要匯入的模組名稱。請輸入模組的名稱或模組中檔案的名稱，例如 .psd1、.psm1、.dll 或 .ps1 檔案。檔案路徑為選擇項。不允許使用萬用字元。您也可以經由管道將模組名稱和檔案名稱輸出至 Import-Module。

如果您省略路徑，Import-Module 就會在 PSModulePath 環境變數 ($env:PSModulePath) 中儲存的路徑內尋找模組。

請盡可能單獨指定模組名稱。當您指定檔案名稱時，只會匯入該檔案中實作的成員。如果模組包含其他檔案，這些檔案並不會匯入，因此您可能會遺漏模組的重要成員。

必要?	true
位置?	1
預設值
接受管線輸入?	true (ByValue)
接受萬用字元?	false

-PassThru

傳回表示已匯入之模組的物件。根據預設，此 Cmdlet 不會產生任何輸出。

附註

-- 當您透過 PassThru 參數，經由管道將 "Get-Module -listavailable" 命令的輸出輸出至 Import-Module 命令時，Import-Module 會傳回 Get-Module 傳遞給它的物件，但不會更新該物件，因此便尚未填入 Exported 和 NestedModules 屬性。

-- 當您使用 Prefix 參數指定成員的首碼時，首碼並不會出現在模組物件屬性的成員名稱中。物件會記錄套用首碼之前匯出的項目。

必要?	false
位置?	named
預設值
接受管線輸入?	false
接受萬用字元?	false

-Prefix <string>

將指定的首碼新增至已匯入之模組成員名稱中的名詞。

請使用此參數避免名稱衝突，當工作階段中不同成員具有相同名稱時，便可能發生此衝突。這個參數不會變更模組，也不會影響模組為了自行使用而匯入的檔案 (稱為「巢狀模組」)。它只會影響目前工作階段中成員的名稱。

例如，如果您指定首碼 "UTC"，然後匯入 Get-Date Cmdlet，則工作階段會將此 Cmdlet 識別為 Get-UTCDate，以免與原始的 Get-Date Cmdlet 混淆。

必要?	false
位置?	named
預設值
接受管線輸入?	false
接受萬用字元?	false

-Variable <string[]>

只將指定的變數從模組匯入至目前的工作階段。請輸入變數的清單。允許使用萬用字元。

某些模組會在您匯入時，自動將選取的變數匯出至工作階段。此參數可讓您從匯出的變數中進行選擇。

必要?	false
位置?	named
預設值
接受管線輸入?	false
接受萬用字元?	true

-Version <Version>

指定要匯入的模組版本。當系統有相同模組的不同版本時，請使用這個參數。

必要?	false
位置?	named
預設值
接受管線輸入?	false
接受萬用字元?	false

<CommonParameters>

這個 Cmdlet 支援一般參數：-Verbose、-Debug、-ErrorAction、-ErrorVariable、-OutBuffer 和 -OutVariable。如需詳細資訊，請參閱 about_Commonparameters.

輸入和輸出

輸入型別是可經由管道輸出至 Cmdlet 的物件型別。傳回型別則是 Cmdlet 所傳回的物件型別。

輸入

System.String、System.Management.Automation.PSModuleInfo 或 System.Reflection.Assembly

您可經由管道將模組名稱、模組物件或組件物件輸出至 Import-Module。

輸出

無、System.Management.Automation.PSModuleInfo 或 System.Management.Automation.PSCustomObject

根據預設，Import-Module 不會產生任何輸出。如果使用 PassThru 參數，它會產生代表模組的 System.Management.Automation.PSModuleInfo 物件。如果使用 AsCustomObject 參數，則會產生 PSCustomObject 物件。

附註

您也可以利用 Import-Module 的別名 ("ipmo") 來表示此 Cmdlet。如需詳細資訊，請參閱 about_Aliases。

您必須先將模組目錄複製到本機電腦可存取的目錄，然後才能匯入模組。如需詳細資訊，請參閱 about_Modules。

由於模組成員會在自己的私人模組工作階段狀態中執行，因此它們用於內部處理的命令不會影響您的工作階段狀態。

如果您將相同名稱和相同類型的成員匯入至工作階段，Windows PowerShell 預設會使用最後匯入的成員。變數和別名都會被取代，而且其原始項目也會變成無法存取。新成員只會「遮蔽」函數、Cmdlet 和提供者，而且您可以利用嵌入式管理單元、模組或函數路徑來限定命令名稱，以便存取這些項目。

若要更新已經從模組匯入之命令的格式化資料，請使用 Update-FormatData Cmdlet。Update-FormatData 也會在工作階段中更新從模組匯入之命令的格式化資料。如果模組的格式化檔案已變更，您就可以執行 Update-FormatData 命令來更新匯入命令的格式化資料。不過，您不需要再次匯入模組。

若要匯入 Import-PSSession 或 Export-PSSession 所建立的模組，目前工作階段中的執行原則不得為 Restricted 或 AllSigned，因為 Import-PSSession 和 Export-PSSession 所建立的模組包含這些原則禁止使用的未經簽署指令碼檔案。若要使用 Import-Module 而不變更本機電腦的執行原則，請使用 Set-ExecutionPolicy 的 Scope 參數，針對單一處理序設定限制較少的執行原則。

範例 1

C:\PS>import-module -name BitsTransfer

描述
-----------
這個命令會將 BitsTransfer 模組的成員都匯入至目前的工作階段。

Name 參數名稱 (-Name) 為選擇項，可以省略。

根據預設，Import-Module 不會在匯入模組時產生任何輸出。若要要求輸出，請使用 PassThru 或 AsCustomObject 參數，或是 Verbose 一般參數。

範例 2

C:\PS>get-module -listAvailable | import-module

描述
-----------
這個命令會將 PSModulePath 環境變數 ($env:psmodulepath) 所指定之路徑中的所有可用模組匯入至目前的工作階段。

範例 3

C:\PS>$m = get-module -ListAvailable BitsTransfer, ServerBackup

C:\PS> import-module -moduleInfo $m

描述
-----------
這個命令會將 BitsTransfer 和 ServerBackup 模組的成員都匯入至目前的工作階段。

第一個命令會使用 Get-Module Cmdlet 取得表示 BitsTransfer 和 ServerBackup 模組的 PSModuleInfo 物件，並將這些物件儲存在 $m 變數中。您必須指定 ListAvailable 參數，才能取得尚未匯入至工作階段的模組。

第二個命令會使用 Import-Module 的 ModuleInfo 參數，將模組匯入至目前的工作階段。

這些命令等同於使用管線運算子 (|) 將 Get-Module 命令的輸出傳送給 Import-Module。

範例 4

C:\PS>import-module -name c:\ps-test\modules\test -verbose

VERBOSE: Loading module from path 'C:\ps-test\modules\Test\Test.psm1'.
VERBOSE: Exporting function 'my-parm'.
VERBOSE: Exporting function 'get-parm'.
VERBOSE: Exporting function 'get-spec'.
VERBOSE: Exporting function 'get-specDetails'.

描述
-----------
這個命令會使用明確的路徑，識別要匯入的模組。

它也會使用 Verbose 一般參數，取得已從模組匯入的項目清單。如果沒有使用 Verbose、PassThru 或 AsCustomObject 參數，Import-Module 就不會在匯入模組時產生任何輸出。

範例 5

C:\PS>import-module BitsTransfer -cmdlet Add-BitsTransferFile, Get-BitsTransfer

C:\PS> get-module BitsTransfer

Name              : BitsTransfer
Path              : C:\Windows\system32\WindowsPowerShell\v1.0\Modules\BitsTransfer\BitsTransfer.psd1
Description       :
Guid              : 8fa5064b-8479-4c5c-86ea-0d311fe48875
Version           : 1.0.0.0
ModuleBase        : C:\Windows\system32\WindowsPowerShell\v1.0\Modules\BitsTransfer
ModuleType        : Manifest
PrivateData       :
AccessMode        : ReadWrite
ExportedAliases   : {}
ExportedCmdlets   : {[Add-BitsTransfer, Add-BitsTransfer], [Complete-BitsTransfer, Complete-BitsTransfer], [Get-BitsTransfer, Get-BitsTransfer], [Rem
                    ove-BitsTransfer, Remove-BitsTransfer]...}
ExportedFunctions : {}
ExportedVariables : {}
NestedModules     : {Microsoft.BackgroundIntelligentTransfer.Management}


C:\PS> get-command -module BitsTransfer

CommandType Name                Definition
----------- ----                ----------
Cmdlet      Add-BitsTransfer    Add-BitsTransfer [-BitsJob] <BitsJob[]> [-Source] <String[]> [[-Destination] <String[]>] [-Verbose] [-Debug] [-ErrorA...
Cmdlet      Get-BitsTransfer    Get-BitsTransfer [[-Name] <String[]>] [-AllUsers] [-Verbose] [-Debug] [-ErrorAction <ActionPreference>] [-WarningActi...

描述
-----------
這個範例會示範如何限制匯入工作階段的模組成員，以及這個命令對於工作階段的作用。

第一個命令只會從 BitsTransfer 模組匯入 Add-BitsTransfer 和 Get-BitsTransfer Cmdlet。此命令會使用 Cmdlet 參數來限制模組所匯入的 Cmdlet。您也可以使用 Alias、Variable 和 Function 參數來限制模組所匯入的其他成員。

第二個命令會使用 Get-Module Cmdlet 來取得代表 BitsTransfer 模組的物件。ExportedCmdlets 屬性會列出模組所匯出的所有 Cmdlet，即使沒有全部匯入也一樣。

第三個命令會使用 Get-Command Cmdlet 的 Module 參數來取得已從 BitsTransfer 模組匯入的命令。結果確認只有匯入 Add-BitsTransfer 和 Get-BitsTransfer Cmdlet。

範例 6

C:\PS>import-module BitsTransfer -prefix PS -passthru

Name              : bitstransfer
Path              : C:\Windows\system32\WindowsPowerShell\v1.0\Modules\bitstransfer\bitstransfer.psd1
Description       :
Guid              : 8fa5064b-8479-4c5c-86ea-0d311fe48875
Version           : 1.0.0.0
ModuleBase        : C:\Windows\system32\WindowsPowerShell\v1.0\Modules\bitstransfer
ModuleType        : Manifest
PrivateData       :
AccessMode        : ReadWrite
ExportedAliases   : {}
ExportedCmdlets   : {[Add-BitsTransfer, Add-BitsTransfer], [Remove-BitsTransfer, Remove-BitsTransfer], [Complete-BitsTransfer, Complete-BitsTransfer]
                    , [Get-BitsTransfer, Get-BitsTransfer]...}
ExportedFunctions : {}
ExportedVariables : {}
NestedModules     : {Microsoft.BackgroundIntelligentTransfer.Management}


C:\PS> get-command -module bitstransfer

CommandType     Name                        Definition
-----------     ----                        ----------
Cmdlet          Add-PSBitsTransfer          Add-PSBitsTransfer [-BitsJob] <BitsJob[]> [-Source] <String[]> ...
Cmdlet          Complete-PSBitsTransfer     Complete-PSBitsTransfer [-BitsJob] <BitsJob[]> [-Verbose] [-Deb...
Cmdlet          Get-PSBitsTransfer          Get-PSBitsTransfer [[-Name] <String[]>] [-AllUsers] [-Verbose] ...
Cmdlet          Remove-PSBitsTransfer       Remove-PSBitsTransfer [-BitsJob] <BitsJob[]> [-Verbose] [-Debug...
Cmdlet          Resume-PSBitsTransfer       Resume-PSBitsTransfer [-BitsJob] <BitsJob[]> [-Asynchronous] [-...
Cmdlet          Set-PSBitsTransfer          Set-PSBitsTransfer [-BitsJob] <BitsJob[]> [-DisplayName <String...
Cmdlet          Start-PSBitsTransfer        Start-PSBitsTransfer [[-Source] <String[]>] [[-Destination] <St...
Cmdlet          Suspend-PSBitsTransfer      Suspend-PSBitsTransfer [-BitsJob] <BitsJob[]> [-Verbose] [-Debu...

描述
-----------
這些命令會將 BitsTransfer 模組匯入至目前的工作階段、將首碼新增至成員名稱，然後顯示加上首碼的成員名稱。

第一個命令會使用 Import-Module Cmdlet 匯入 BitsTransfer 模組，並使用 Prefix 參數將 PS 首碼新增至從模組匯入的所有成員，以及使用 PassThru 參數傳回表示已匯入之模組的模組物件。

此命令傳回的模組物件具有 ExportedCmdlets 屬性，它會列出已匯出的成員。首碼不會出現在 Cmdlet 名稱中，因為成員是在匯出之後 (但在匯入之前) 才套用首碼。

第二個命令會使用 Get-Command Cmdlet 取得已經從模組匯入的成員，並使用 Module 參數指定模組。輸出顯示模組成員都已正確加上首碼。

您所使用的首碼只會套用至目前工作階段中的成員，它並不會變更模組。

範例 7

C:\PS>get-module -list | format-table -property name, moduletype -auto

Name          ModuleType
----          ----------
Show-Calendar     Script
BitsTransfer    Manifest
PSDiagnostics   Manifest
TestCmdlets       Script

C:\PS> $a = import-module -name Show-Calendar -asCustomObject

C:\PS> $a | get-member 


   TypeName: System.Management.Automation.PSCustomObject

Name          MemberType   Definition
----          ----------   ----------
Equals        Method       bool Equals(System.Object obj)
GetHashCode   Method       int GetHashCode()
GetType       Method       type GetType()
ToString      Method       string ToString()
Show-Calendar ScriptMethod System.Object Show-Calendar();

C:\PS> $a."show-calendar"()

描述
-----------
這些命令會示範如何取得及使用 Import-Module 傳回的自訂物件。

自訂物件包括綜合成員，其代表每個已匯入的模組成員。例如，模組中的 Cmdlet 和函數會轉換成自訂物件的指令碼方法。

自訂物件在撰寫指令碼時非常有用。當匯入的多個物件具有相同名稱時，自訂物件也很有用。使用物件的指令碼方法等同於指定已匯入成員的完整名稱，包括其模組名稱。

AsCustomObject 參數只能與指令碼模組一起使用，因此首要工作是判斷哪個可用模組是指令碼模組。

第一個命令會使用 Get-Module Cmdlet 取得可用的模組，並使用管線運算子 (|) 將模組物件傳遞至 Format-Table Cmdlet，而此 Cmdlet 會將每個模組的 Name 和 ModuleType 列在一份表格中。

第二個命令會使用 Import-Module Cmdlet 匯入 Show-Calendar 指令碼模組，並使用 AsCustomObject 參數來要求自訂物件，再將產生的自訂物件儲存在 $a 變數中。

第三個命令會使用管線運算子將 $a 變數傳送給 Get-Member Cmdlet，此 Cmdlet 會取得 $a 中 PSCustomObject 的屬性和方法。輸出顯示 Show-Calendar 指令碼方法。

最後一個命令會使用 Show-Calendar 指令碼方法。因為方法名稱包含連字號，所以必須置於引號中。

範例 8

C:\PS>import-module BitsTransfer

C:\PS> import-module BitsTransfer -force -prefix PS

描述
-----------
這個範例會示範如何在您將模組重新匯入相同的工作階段時使用 Import-Module 的 Force 參數。

第一個命令會匯入 BitsTransfer 模組。第二個命令會再次匯入此模組，但這次會使用 Prefix 參數。

第二個命令也會包含 Force 參數，以便移除模組，然後再次匯入。如果沒有使用此參數，工作階段的每個 BitsTransfer Cmdlet 都會包含兩個複本：一個具有標準名稱，而另一個具有加上首碼的名稱。

範例 9

C:\PS>get-date

Saturday, September 12, 2009 6:47:04 PM

C:\PS> import-module TestModule

C:\PS> get-date
09255

C:\PS> get-command get-date | format-table -property commandtype, name, pssnapin, module -auto

CommandType  Name       pssnapin                       Module
-----------  ----       --------                       ------
   Function  Get-Date                                  TestModule
     Cmdlet  Get-Date   Microsoft.PowerShell.Utility


C:\PS> Microsoft.PowerShell.Utility\get-date

Saturday, September 12, 2009 6:33:23 PM

描述
-----------
這個範例會示範如何執行匯入之命令已經隱藏的命令。

第一個命令會執行 Windows PowerShell 隨附的 Get-Date Cmdlet。它會傳回具有目前日期的 DateTime 物件。

第二個命令會匯入 TestModule 模組。這個模組包含名為 Get-Date 的函數，可傳回 Julian 日期。

第三個命令會再次執行 Get-Date 命令。因為函數的優先順序高於 Cmdlet，所以系統會執行 TestModule 模組的 Get-Date 函數而非 Get-Date Cmdlet。

第四個命令顯示，工作階段中存在兩個 Get-Date 命令：TestModule 模組的函數以及 Microsoft.PowerShell.Utility 嵌入式管理單元的 Cmdlet。

第五個命令會使用嵌入式管理單元名稱來限定命令名稱，藉以執行隱藏的 Cmdlet。

如需 Windows PowerShell 中命令優先順序的詳細資訊，請參閱 about_command_precedence。

請參閱

概念

Get-Module
New-Module
Remove-Module
Export-ModuleMember
about_Modules

共用方式為