Import-PSSession
將另一個工作階段的命令匯入目前的工作階段。
Syntax
Import-PSSession
[-Prefix <String>]
[-DisableNameChecking]
[[-CommandName] <String[]>]
[-AllowClobber]
[-ArgumentList <Object[]>]
[-CommandType <CommandTypes>]
[-Module <String[]>]
[-FullyQualifiedModule <ModuleSpecification[]>]
[[-FormatTypeName] <String[]>]
[-Certificate <X509Certificate2>]
[-Session] <PSSession>
[<CommonParameters>]
Description
Import-PSSession Cmdlet 會將命令,例如 Cmdlet、函式和別名,從本機或遠端電腦上的 PSSession 匯入到目前的會話。 您可以匯入 Get-Command Cmdlet 可在 PSSession 中找到的任何命令。
使用 Import-PSSession 命令可從自訂殼層 (例如 Microsoft Exchange Server 殼層),或從包含 Windows PowerShell 模組和嵌入式管理單元或不在目前工作階段的其他元素的工作階段匯入命令。
若要匯入命令,請先使用 New-PSSession Cmdlet 來建立 PSSession。 然後,使用 Import-PSSession Cmdlet 匯入命令。 根據預設,Import-PSSession 會匯入除了與目前工作階段中具有相同命令名稱以外的所有命令。 若要匯入所有命令,請使用 AllowClobber 參數。
您可以使用匯入的命令,就像您使用工作階段中的任何命令一樣。 當您使用匯入的命令時,匯入的命令部份會隱含地在從匯入的工作階段中執行。 不過,遠端操作則會完全由 Windows PowerShell 處理。 您甚至不需要知道這些操作,不過必須讓其他工作階段 (PSSession) 的連線保持開啟。 如果您關閉它,匯入的命令就不再可用。
因為匯入的命令可能會比本機命令需要花費較長的時間,所以 Import-PSSession 會對每個匯入的命令加入 AsJob 參數。 此參數可讓您以 Windows PowerShell 背景工作方式執行命令。 如需詳細資訊,請參閱 about_Jobs。
當您使用 Import-PSSession 時,Windows PowerShell 會將匯入的命令加入只存在於您工作階段中的暫存模組,並且傳回代表該模組的物件。 若要建立可在未來會話中使用的持續性模組,請使用 Export-PSSession Cmdlet。
Import-PSSession Cmdlet 會使用 Windows PowerShell 的隱含遠端執行功能。 當您將命令匯入目前的工作階段時,它們會在原始工作階段或原始電腦上的類似工作階段中隱含執行。
從 Windows PowerShell 3.0 開始,您可以使用 Import-Module Cmdlet,將模組從遠端會話匯入目前會話。 這項功能使用隱含的遠端執行功能。 它等同於使用 Import-PSSession 將遠端工作階段中選取的模組匯入目前的工作階段。
範例
範例 1:從 PSSession 匯入所有命令
PS C:\> $S = New-PSSession -ComputerName Server01
PS C:\> Import-PSSession -Session $S
此命令將 Server01 電腦上 PSSession 的所有命令 (除了與目前工作階段中具有相同命令名稱的命令) 匯入目前的工作階段。
因為此命令沒有使用 CommandName 參數,所以它也會將匯入命令所需的所有格式化資料匯入。
範例 2:匯入以特定字串結尾的命令
PS C:\> $S = New-PSSession https://ps.testlabs.com/powershell
PS C:\> Import-PSSession -Session $S -CommandName *-test -FormatTypeName *
PS C:\> New-Test -Name Test1
PS C:\> Get-Test test1 | Run-Test
這些命令會從 PSSession 將名稱結尾為 "-test" 的命令匯入本機工作階段,然後顯示如何使用匯入的 Cmdlet。
第一個命令會使用 New-PSSession Cmdlet 來建立 PSSession。 它會將 PSSession 儲存在$S變數中。
第二個命令會使用 Import-PSSession Cmdlet,將命令從 $S 中的 PSSession 匯入目前會話。 它使用 CommandName 參數指定具有 Test 名詞的命令,以及使用 FormatTypeName 參數匯入各種 Test 命令的格式化資料。
第三個和第四個命令在目前的工作階段中使用匯入的命令。 因為匯入的命令已經實際新增到目前的工作階段中,所以您要使用本機語法執行它們。 您不需要使用 Invoke-Command Cmdlet 來執行匯入的命令。
範例 3:從 PSSession 匯入 Cmdlet
PS C:\> $S1 = New-PSSession -ComputerName s1
PS C:\> $S2 = New-PSSession -ComputerName s2
PS C:\> Import-PSSession -Session s1 -Type cmdlet -Name New-Test, Get-Test -FormatTypeName *
PS C:\> Import-PSSession -Session s2 -Type Cmdlet -Name Set-Test -FormatTypeName *
PS C:\> New-Test Test1 | Set-Test -RunType Full
此範例示範使用匯入的 Cmdlet 就如同使用本機 Cmdlet 一樣。
這些命令從 Server01 電腦的 PSSession 匯入 New-Test 和 Get-Test Cmdlet,以及從 Server02 電腦的 PSSession 匯入 Set-Test Cmdlet。
即使是從不同的 PSSession 匯入 Cmdlet,您還是可以使用管線將物件從一個 Cmdlet 傳送到另一個 Cmdlet 而不會發生錯誤。
範例 4:以背景工作身分執行匯入的命令
PS C:\> $S = New-PSSession -ComputerName Server01
PS C:\> Import-PSSession -Session $S -CommandName *-test* -FormatTypeName *
PS C:\> $batch = New-Test -Name Batch -AsJob
PS C:\> Receive-Job $batch
此範例示範如何以背景工作的方式執行匯入的命令。
因為匯入的命令可能會比本機命令需要花費較長的時間,所以 Import-PSSession 會對每個匯入的命令加入 AsJob 參數。 AsJob 參數可讓您以背景工作的方式執行命令。
第一個命令會在 Server01 計算機上建立 PSSession,並將 PSSession 物件儲存在 $S 變數中。
第二個命令會使用 Import-PSSession 將測試 Cmdlet 從 $S 中的 PSSession 匯入至目前的會話。
第三個命令使用匯入的 New-Test Cmdlet 的 AsJob 參數,以背景工作的方式執行 New-Test 命令。 命令會將 New-Test 傳回的工作物件儲存在 $batch 變數中。
第四個命令會使用 Receive-Job Cmdlet 來取得$batch變數中作業的結果。
範例 5:從 Windows PowerShell 模組匯入 Cmdlet 和函式
PS C:\> $S = New-PSSession -ComputerName Server01
PS C:\> Invoke-Command -Session $S {Import-Module TestManagement}
PS C:\> Import-PSSession -Session $S -Module TestManagement
此範例示範如何從遠端電腦的 Windows PowerShell 模組將 Cmdlet 和函式匯入目前的工作階段。
第一個命令會在 Server01 計算機上建立 PSSession,並將它儲存在$S變數中。
第二個命令會使用 Invoke-Command Cmdlet,在 psSession $S 中執行 Import-Module 命令。
Import-Module 命令通常會將 Windows PowerShell 設定檔中的模組新增到所有工作階段,但是並不會在 PSSession 中執行設定檔。
第三個命令使用 Import-PSSession 的 Module 參數將模組中的 Cmdlet 與函式匯入目前的工作階段。
範例 6:Create 暫存盤中的模組
PS C:\> Import-PSSession $S -CommandName Get-Date, SearchHelp -FormatTypeName * -AllowClobber
Name : tmp_79468106-4e1d-4d90-af97-1154f9317239_tcw1zunz.ttf
Path : C:\Users\User01\AppData\Local\Temp\tmp_79468106-4e1d-4d90-af97-1154f9317239_tcw1zunz.ttf\tmp_79468106-4e1d-4d90-af97-1154f9317239_
tcw1zunz.ttf.psm1
Description : Implicit remoting for http://server01.corp.fabrikam.com/wsman
Guid : 79468106-4e1d-4d90-af97-1154f9317239
Version : 1.0
ModuleBase : C:\Users\User01\AppData\Local\Temp\tmp_79468106-4e1d-4d90-af97-1154f9317239_tcw1zunz.ttf
ModuleType : Script
PrivateData : {ImplicitRemoting}
AccessMode : ReadWrite
ExportedAliases : {}
ExportedCmdlets : {}
ExportedFunctions : {[Get-Date, Get-Date], [SearchHelp, SearchHelp]}
ExportedVariables : {}
NestedModules : {}
此範例顯示 Import-PSSession 在磁碟上的暫存檔案中建立模組。 它也會顯示所有命令在匯入目前工作階段之前,都已轉換成函式。
此命令會使用 Import-PSSession Cmdlet,將 Get-Date Cmdlet 和 SearchHelp 函式匯入目前的會話。
Import-PSSession Cmdlet 傳回代表暫存模組的 PSModuleInfo 物件。 Path 屬性的值顯示 Import-PSSession 在暫存位置中建立了指令碼模組 (.psm1) 檔案。 ExportedFunctions 屬性顯示 Get-Date Cmdlet 與 SearchHelp 函式兩者都已匯入成為函式。
範例 7:執行匯入命令所隱藏的命令
PS C:\> Import-PSSession $S -CommandName Get-Date -FormatTypeName * -AllowClobber
PS C:\> Get-Command Get-Date -All
CommandType Name Definition
----------- ---- ----------
Function Get-Date ...
Cmdlet Get-Date Get-Date [[-Date] <DateTime>] [-Year <Int32>] [-Month <Int32>]
PS C:\> Get-Date
09074
PS C:\> (Get-Command -Type Cmdlet -Name Get-Date).PSSnapin.Name
Microsoft.PowerShell.Utility
PS C:\> Microsoft.PowerShell.Utility\Get-Date
Sunday, March 15, 2009 2:08:26 PM
此範例示範如何執行被匯入的命令隱藏的命令。
第一個命令會從 $S 變數中的 PSSession 匯入 Get-Date Cmdlet。 因為目前的工作階段包含 Get-Date Cmdlet,所以命令中必須要有 AllowClobber 參數。
第二個命令會使用 Get-Command Cmdlet 的 All 參數來取得目前工作階段中的所有 Get-Date 命令。 輸出顯示工作階段包含原始的 Get-Date Cmdlet 和 Get-Date 函式。 Get-Date 函式會在 PSSession 中執行匯入的 Get-Date Cmdlet,$S。
第三個命令執行 Get-Date 命令。 因為函式優先於 Cmdlet,所以 Windows PowerShell 會執行匯入的 Get-Date 函式並傳回凱薩曆日期。
第四個和第五個命令示範如何使用限定的名稱執行被匯入的命令隱藏的命令。
第四個命令取得已將原始 Get-Date Cmdlet 加入目前工作階段的 Windows PowerShell 嵌入式管理單元名稱。
第五個命令使用 Get-Date Cmdlet 的嵌入式管理單元限定名稱執行 Get-Date 命令。
如需有關命令優先順序和隱藏命令的詳細資訊,請參閱 about_Command_Precedence。
範例 8:匯入名稱中有特定字串的命令
PS C:\> Import-PSSession -Session $S -CommandName *Item* -AllowClobber
此命令會從 PSSession 匯入名稱包含 「Item」 的命令,$S。 因為命令包含 CommandName 參數,但不包含 FormatTypeData 參數,所以只會匯入命令。
當您使用 Import-PSSession 在遠端電腦上執行命令,且在目前工作階段中已經有命令的格式化資料時,請使用此命令。
範例 9:使用 Module 參數來探索哪些命令已匯入工作階段
PS C:\> $M = Import-PSSession -Session $S -CommandName *bits* -FormatTypeName *bits*
PS C:\> Get-Command -Module $M
CommandType Name
----------- ----
Function Add-BitsFile
Function Complete-BitsTransfer
Function Get-BitsTransfer
Function Remove-BitsTransfer
Function Resume-BitsTransfer
Function Set-BitsTransfer
Function Start-BitsTransfer
Function Suspend-BitsTransfer
此命令示範如何使用 Get-Command 的 Module 參數,找出 Import-PSSession 命令將哪些命令匯入工作階段。
第一個命令會使用 Import-PSSession Cmdlet,從$S變數的 PSSession 匯入名稱包含 “bits” 的命令。 Import-PSSession 命令傳回一個暫存模組,而且命令將模組儲存在 $m 變數中。
第二個命令會使用 Get-Command Cmdlet 來取得模組在 $M 變數中導出的命令。
Module 參數會使用設計來做為模組名稱的字串值。 不過,當您送出模組物件時,Windows PowerShell 會對模組物件使用 ToString 方法,傳回模組名稱。
Get-Command 命令相當於 Get-Command $M.Name
”
參數
-AllowClobber
指出此 Cmdlet 會匯入指定的命令,即使它們的名稱與目前會話中的命令相同也一樣。
如果您匯入與目前工作階段中的命令同名的命令,匯入的命令將會隱藏或取代原始命令。 如需詳細資訊,請參閱 about_Command_Precedence。
根據預設,Import-PSSession 不會匯入與目前工作階段中的命令具有相同名稱的命令。
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ArgumentList
指定命令陣列,這個陣列會使用指定的自變數 (參數值) 。
例如,若要在 $S 的 PSSession 中匯入憑證 (Cert:) 磁碟驅動器中 Get-Item 命令的變體,請輸入 Import-PSSession -Session $S -Command Get-Item -ArgumentList cert:
。
Type: | Object[] |
Aliases: | Args |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Certificate
指定用來簽署格式檔案 (*.Format.ps1xml),或是簽署由 Import-PSSession 建立之暫存模組中的指令碼模組檔案 (.psm1) 的用戶端憑證。
輸入包含憑證的變數,或可取得憑證的命令或運算式。
若要尋找憑證,請使用 Get-PfxCertificate Cmdlet,或使用憑證 (Cert:) 磁碟驅動器中的 Get-ChildItem Cmdlet。 若憑證無效或權限不足,則命令會失敗。
Type: | X509Certificate2 |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-CommandName
指定具有指定名稱或名稱模式的命令。 允許使用萬用字元。 使用 CommandName 或其別名 Name。
根據預設,Import-PSSession 會從工作階段中匯入除了與目前工作階段中具有相同命令名稱以外的所有命令。 這可防止匯入的命令隱藏或取代工作階段中的命令。 若要匯入所有命令,包含那些會隱藏或取代其他命令的命令,請使用 AllowClobber 參數。
您使用 CommandName 參數時,除非您使用 FormatTypeName 參數,否則不會匯入命令的格式設定檔案。 同樣地,使用 FormatTypeName 參數時,除非您使用 CommandName 參數,否則不會匯入任何命令。
Type: | String[] |
Aliases: | Name |
Position: | 2 |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-CommandType
指定命令物件的類型。 預設值為 Cmdlet。 使用 CommandType 或它的別名 Type。 此參數可接受的值為:
- 別名。 遠端工作階段中的 Windows PowerShell 別名。
- 全部。 遠端工作階段中的 Cmdlet 與函式。
- 應用程式。 除了在遠端工作階段中,Path 環境變數 ($env:path) 所列出路徑裡的 Windows PowerShell 檔案以外的所有檔案,包括 .txt、.exe 和 .dll 檔案。
- Cmdlet。 遠端工作階段中的 Cmdlet。 "Cmdlet" 為預設值。
- ExternalScript。 在遠端工作階段中,Path 環境變數 ($env:path) 所列出路徑裡的 .ps1 檔案。
- 篩選和函式。 遠端工作階段中的 Windows PowerShell 函式。
- 指令碼: 遠端工作階段中的指令碼區塊。
Type: | CommandTypes |
Aliases: | Type |
Accepted values: | Alias, Function, Filter, Cmdlet, ExternalScript, Application, Script, Workflow, Configuration, All |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-DisableNameChecking
表示此 Cmdlet 會在匯入名稱包含未核准的動詞或禁止字元的 Cmdlet 或函式時,隱藏警告您的訊息。
根據預設,當您匯入的模組匯出名稱中有未核准動詞命令的 Cmdlet 或函式時,Windows PowerShell 會顯示下列警告訊息:
「警告:某些彙入的命令名稱包含未核准的動詞,這可能會讓它們更容易探索。 請使用 Verbose 參數取得詳細資訊,或輸入 Get-Verb 查看核准的動詞清單。」
這則訊息只是一個警告。 模組仍然完整匯入,包括不合格的命令。 雖然訊息是顯示給模組的使用者,但命名的問題應該由模組作者修正。
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-FormatTypeName
指定指定 Microsoft .NET Framework 類型的格式化指示。 輸入類型名稱。 允許使用萬用字元。
這個參數的值必須是從中匯入命令之來源工作階段中的 Get-FormatData 命令所傳回之類型的名稱。 若要取得遠端工作階段中的所有格式設定資料,請輸入 *。
如果命令不包含 CommandName 或 FormatTypeName 參數,Import-PSSession 會匯入遠端會話中 Get-FormatData 命令所傳回之所有 .NET Framework 類型的格式化指示。
如果您使用 FormatTypeName 參數,除非使用 CommandName 參數,否則不會匯入任何命令。
同樣地,如果您使用 CommandName 參數,除非使用 FormatTypeName 參數,否則不會匯入命令的格式化檔案。
Type: | String[] |
Position: | 3 |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-FullyQualifiedModule
Specifies modules with names that are specified in the form of ModuleSpecification objects (described in the Remarks section of ModuleSpecification Constructor (Hashtable) in the MSDN library). 例如, FullyQualifiedModule 參數接受以 @{ModuleName = “modulename” 格式指定的模組名稱;ModuleVersion = “version_number”} 或 @{ModuleName = “modulename”;ModuleVersion = “version_number”;Guid = “GUID”}。 ModuleName 和 ModuleVersion 是必要參數,但 Guid 是選擇性參數。
您無法在與 Module 參數相同的命令中指定 FullyQualifiedModule 參數;這兩個參數互斥。
Type: | ModuleSpecification[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Module
指定 Windows PowerShell 嵌入式管理單元和模組中的命令陣列。 請輸入嵌入式管理單元和模組名稱。 不允許使用萬用字元。
Import-PSSession 無法從嵌入式管理單元匯入提供者。
如需詳細資訊,請參閱 about_PSSnapins和 about_Modules。
Type: | String[] |
Aliases: | PSSnapin |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Prefix
指定匯入命令名稱中名詞的前置詞。
使用此參數來避免工作階段中不同命令具有相同名稱時可能會發生的名稱衝突。
例如,如果您指定 Remote 前置詞,然後匯入 Get-Date Cmdlet,則此 Cmdlet 會在會話中稱為 Get-RemoteDate,而不會與原始 Get-Date Cmdlet 混淆。
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Session
指定匯入 Cmdlet 的 PSSession 。 輸入包含會話物件的變數,或取得會話物件的命令,例如 New-PSSession 或 Get-PSSession 命令。 您只能指定一個工作階段。 此為必要參數。
Type: | PSSession |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
輸入
None
您無法使用管線將物件傳送至此 Cmdlet。
輸出
Import-PSSession 會傳回 New-Module 和 Get-Module Cmdlet 傳回的相同模組物件。 不過,匯入的模組是暫時性的,而且只存在於目前的工作階段。 若要在磁碟上建立永久模組,請使用 Export-PSSession Cmdlet。
備註
- Import-PSSession 依賴 Windows PowerShell 遠端基礎結構。 若要使用此 Cmdlet,電腦必須設定 WS-Management 遠端執行功能。 如需詳細資訊,請參閱about_Remote和about_Remote_Requirements。
- Import-PSSession 不會匯入變數或 Windows PowerShell 提供者。
- 當您匯入與目前工作階段中具有相同命令名稱的命令時,匯入的命令可以隱藏工作階段中的別名、函式和 Cmdlet,而且可以取代工作階段中的函式和變數。 若要避免名稱衝突,請使用 Prefix 參數。 如需詳細資訊,請參閱 about_Command_Precedence。
- Import-PSSession 會在匯入命令之前,將所有命令轉換成函式。 如此一來,匯入的命令行為會變得與保持其原始命令類型時有點不同。 例如,如果您從 PSSession 匯入 Cmdlet,然後從模組或嵌入式管理單元匯入具有相同名稱的 Cmdlet,則從 PSSession 匯入的命令預設一律都會執行,因為函式優先於 Cmdlet。 相反地,如果您將某個別名匯入具有相同別名名稱的工作階段,則會一律使用原始的別名,因為別名優先於函式。 如需詳細資訊,請參閱 about_Command_Precedence。
- Import-PSSession 會使用 Write-Progress Cmdlet 來顯示命令的進度。 當命令執行時,您可以看到進度列。
- 若要尋找要匯入的命令, Import-PSSession 會使用 Invoke-Command Cmdlet 在 PSSession 中執行 Get-Command 命令。 若要取得命令的格式設定數據,它會使用 Get-FormatData Cmdlet。 當您執行 Import-PSSession 命令時,可能會看到來自這些 Cmdlet 的錯誤訊息。 此外, Import-PSSession 無法從不包含 Get-Command、Get-FormatData、Select-Object 和 Get-Help Cmdlet 的 PSSession 匯入命令。
- 匯入的命令與其他遠端命令具有相同的限制,包括無法以使用者介面啟動程式,例如「記事本」。
- 由於 Windows PowerShell 設定檔不是在 PSSession 中執行,因此設定檔新增到工作階段中的命令並無法供 Import-PSSession 使用。 若要從設定檔匯入命令,請在匯入命令之前,使用 Invoke-Command 命令在 PSSession 中手動執行設定檔。
- Import-PSSession 建立的暫存模組可能會包含格式化檔案,即使命令沒有匯入格式化資料。 如果命令不會匯入格式設定資料,所建立的任何格式檔案都將不會包含格式設定資料。
- 若要使用 Import-PSSession,目前工作階段中的執行原則不能是 Restricted 或 AllSigned,因為 Import-PSSession 建立的暫存模組會包含這些原則所禁止的未簽署指令碼檔案。 若要使用 Import-PSSession 而不變更本機計算機的執行原則,請使用 Set-ExecutionPolicy 的 Scope 參數,為單一進程設定較不嚴格的執行原則。
- 在 Windows PowerShell 2.0 中,從另一個工作階段匯入命令的說明主題不包含您使用 Prefix 參數指派的首碼。 若要取得在 Windows PowerShell 2.0 中匯入命令的說明,請使用原始 (未加上首碼) 的命令名稱。