Import-PSSession
將命令從另一個會話匯入至目前的會話。
語法
Import-PSSession
[-Prefix <String>]
[-DisableNameChecking]
[[-CommandName] <String[]>]
[-AllowClobber]
[-ArgumentList <Object[]>]
[-CommandType <CommandTypes>]
[-Module <String[]>]
[-FullyQualifiedModule <ModuleSpecification[]>]
[[-FormatTypeName] <String[]>]
[-Certificate <X509Certificate2>]
[-Session] <PSSession>
[<CommonParameters>]
Description
Cmdlet 會將 Import-PSSession
命令,例如 Cmdlet、函式和別名,從本機或遠端電腦上的 PSSession 匯入到目前的會話。 您可以匯入 Cmdlet 可在 PSSession 中找到的任何命令 Get-Command
。
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。
Cmdlet Import-PSSession
使用 Windows PowerShell 的隱含遠端功能。 當您將命令匯入目前工作階段時,它們會在原始工作階段或原始電腦上的類似工作階段中隱含執行。
從 Windows PowerShell 3.0 開始,您可以使用 Import-Module
Cmdlet 將模組從遠端會話匯入目前的作業階段。 此功能使用隱含遠端。 這相當於使用 Import-PSSession
將選取的模組從遠端會話匯入目前的會話。
範例
範例 1:從 PSSession 匯入所有命令
$S = New-PSSession -ComputerName Server01
Import-PSSession -Session $S
此命令會將 Server01 計算機上 PSSession 的所有命令匯入目前的會話,但目前會話中具有相同名稱的命令除外。
因為此命令不使用 CommandName 參數,所以也會匯入匯入命令所需的所有格式化數據。
範例 2:匯入以特定字串結尾的命令
$S = New-PSSession https://ps.testlabs.com/powershell
Import-PSSession -Session $S -CommandName *-test -FormatTypeName *
New-Test -Name Test1
Get-Test test1 | Run-Test
這些命令會將名稱為 「-test」 的命令從 PSSession 匯入本機會話,然後顯示如何使用匯入的 Cmdlet。
第一個命令會 New-PSSession
使用 Cmdlet 來建立 PSSession。 它會將 PSSession 儲存在 變數中 $S
。
第二個命令會 Import-PSSession
使用 Cmdlet,將 中的 $S
PSSession 命令匯入目前的會話。 它會使用 CommandName 參數來指定具有 Test 名詞和 FormatTypeName 參數的命令,以匯入 Test 命令的格式數據。
第三和第四個命令會使用目前會話中匯入的命令。 由於匯入的命令實際上會新增至目前的會話,因此您可以使用本機語法來執行它們。 您不需要使用 Invoke-Command
Cmdlet 來執行匯入的命令。
範例 3:從 PSSession 匯入 Cmdlet
$S1 = New-PSSession -ComputerName s1
$S2 = New-PSSession -ComputerName s2
Import-PSSession -Session s1 -Type cmdlet -Name New-Test, Get-Test -FormatTypeName *
Import-PSSession -Session s2 -Type Cmdlet -Name Set-Test -FormatTypeName *
New-Test Test1 | Set-Test -RunType Full
此範例示範您可以使用匯入的 Cmdlet,就像使用本機 Cmdlet 一樣。
這些命令會 New-Test
從 Server01 計算機上的 PSSession 匯入 和 Get-Test
Cmdlet,並從 Set-Test
Server02 電腦上的 PSSession 匯入 Cmdlet。
即使 Cmdlet 是從不同的 PSSession 匯入的,您也可以使用管線將物件從某個 Cmdlet 傳送到另一個 Cmdlet,而不會發生錯誤。
範例 4:以背景工作身分執行匯入的命令
$S = New-PSSession -ComputerName Server01
Import-PSSession -Session $S -CommandName *-test* -FormatTypeName *
$batch = New-Test -Name Batch -AsJob
Receive-Job $batch
此範例示範如何以背景工作的形式執行匯入的命令。
由於匯入的命令可能需要比本機命令更長的時間,因此將 Import-PSSession
AsJob 參數新增至每個匯入的命令。 AsJob 參數可讓您以背景工作的形式執行命令。
第一個命令會在 Server01 計算機上建立 PSSession,並將 PSSession 物件儲存在 變數中 $S
。
第二個命令會使用 Import-PSSession
將 中的 PSSession $S
測試 Cmdlet 匯入目前的會話。
第三個New-Test
命令會使用匯入 New-Test
Cmdlet 的 AsJob 參數,以背景工作的形式執行命令。 命令會儲存在變數中傳回的$batch
作業物件New-Test
。
第四個命令會 Receive-Job
使用 Cmdlet 來取得變數中 $batch
作業的結果。
範例 5:從 Windows PowerShell 模組匯入 Cmdlet 和函式
$S = New-PSSession -ComputerName Server01
Invoke-Command -Session $S {Import-Module TestManagement}
Import-PSSession -Session $S -Module TestManagement
此範例示範如何將遠端電腦上的 Windows PowerShell 模組中的 Cmdlet 和函式匯入目前的會話。
第一個命令會在 Server01 計算機上建立 PSSession,並將它儲存在變數中 $S
。
第二個Import-Module
命令會Invoke-Command
使用 Cmdlet 在 中的 $S
PSSession 中執行命令。
一般而言,模組會由 Import-Module
Windows PowerShell 配置檔中的命令新增至所有會話,但配置檔不會在 PSSessions 中執行。
第三個命令會使用的 Import-PSSession
Module 參數,將模組中的 Cmdlet 和函式匯入目前的會話。
範例 6:在暫存盤中建立模組
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_tcw1
zunz.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_tcw1
zunz.ttf
ModuleType : Script
PrivateData : {ImplicitRemoting}
AccessMode : ReadWrite
ExportedAliases : {}
ExportedCmdlets : {}
ExportedFunctions : {[Get-Date, Get-Date], [SearchHelp, SearchHelp]}
ExportedVariables : {}
NestedModules : {}
此範例示範如何在 Import-PSSession
磁碟上的暫存盤中建立模組。 它也會顯示所有命令都會在匯入目前會話之前轉換成函式。
此命令會 Import-PSSession
使用 Cmdlet 將 Cmdlet 和 SearchHelp 函式匯 Get-Date
入目前的會話。
Cmdlet 會 Import-PSSession
傳 回代表暫存模組的 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
此範例示範如何執行匯入命令所隱藏的命令。
第一個 Get-Date
命令會從變數中的 $S
PSSession 匯入 Cmdlet。 由於目前的會話包含 Get-Date
Cmdlet, 因此命令中需要 AllowClobber 參數。
第二個命令會使用 Cmdlet 的 Get-Command
All 參數來取得目前工作階段中的所有Get-Date
命令。 輸出會顯示會話包含原始 Get-Date
Cmdlet 和函 Get-Date
式。 函Get-Date
式會在中的 $S
PSSession 中執行匯入Get-Date
的 Cmdlet。
第三個命令會 Get-Date
執行命令。 因為函式的優先順序高於 Cmdlet,Windows PowerShell 會執行匯入 Get-Date
的函式,這會傳回 Julian 日期。
第四和第五個命令示範如何使用限定名稱來執行匯入命令所隱藏的命令。
第四個命令會取得將原始 Get-Date
Cmdlet 新增至目前會話的 Windows PowerShell 嵌入式管理單元名稱。
第五個Get-Date
命令會使用 Cmdlet 的Get-Date
嵌入式管理單元限定名稱來執行命令。
如需命令優先順序和隱藏命令的詳細資訊,請參閱 about_Command_Precedence。
範例 8:匯入名稱中有特定字串的命令
PS C:\> Import-PSSession -Session $S -CommandName **Item** -AllowClobber
此命令會匯入名稱包含 中 PSSession $S
之 Item 的命令。 因為命令包含 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
不會匯入與目前會話中命令同名的命令。
類型: | SwitchParameter |
Position: | Named |
預設值: | None |
必要: | False |
接受管線輸入: | False |
接受萬用字元: | False |
-ArgumentList
指定使用指定自變數所產生的命令陣列(參數值)。
例如,若要在的 PSSession $S
中匯入憑證 (Cert:) 磁碟驅動器中的 命令變體Get-Item
,請輸入 Import-PSSession -Session $S -Command Get-Item -ArgumentList cert:
。
類型: | Object[] |
別名: | Args |
Position: | Named |
預設值: | None |
必要: | False |
接受管線輸入: | False |
接受萬用字元: | False |
-Certificate
指定用來簽署格式檔案的客戶端憑證 (*。在建立的暫存模組 Import-PSSession
中,Format.ps1xml) 或腳本模組檔案 (.psm1)。
輸入包含憑證的變數,或取得憑證的命令或表達式。
若要尋找憑證,請使用 Get-PfxCertificate
Cmdlet 或使用 Get-ChildItem
Certificate (Cert:) 磁碟驅動器中的 Cmdlet。 如果憑證無效或沒有足夠的授權單位,則命令會失敗。
類型: | X509Certificate2 |
Position: | Named |
預設值: | None |
必要: | False |
接受管線輸入: | False |
接受萬用字元: | False |
-CommandName
指定具有指定名稱或名稱模式的命令。 允許通配符。 使用 CommandName 或其別名 Name。
根據預設, Import-PSSession
會從會話匯入所有命令,但目前會話中具有相同名稱的命令除外。 這可防止匯入的命令隱藏或取代會話中的命令。 若要匯入所有命令,即使是隱藏或取代其他命令的命令,請使用 AllowClobber 參數。
如果您使用 CommandName 參數,除非您使用 FormatTypeName 參數,否則不會匯入命令的格式檔案。 同樣地,如果您使用 FormatTypeName 參數,除非您使用 CommandName 參數,否則不會匯入任何命令。
類型: | String[] |
別名: | Name |
Position: | 2 |
預設值: | None |
必要: | False |
接受管線輸入: | False |
接受萬用字元: | False |
-CommandType
指定命令物件的類型。 預設值為 Cmdlet。 使用 CommandType 或其別名類型。 此參數可接受的值為:
Alias
:遠端會話中的 Windows PowerShell 別名。All
:遠端會話中的 Cmdlet 和函式。Application
:遠端會話中路徑中所列$env:path
路徑中 Windows-PowerShell 檔案以外的所有檔案,包括.txt、.exe和.dll檔案。Cmdlet
:遠端會話中的 Cmdlet。 “Cmdlet” 是預設值。ExternalScript
:遠端工作階段中Path環境變數 ($env:path
) 所列路徑中的 .ps1 檔案。Filter
和Function
:遠端會話中的 Windows PowerShell 函式。Script
:遠端工作階段中的文本區塊。
這些值會定義為旗標型列舉。 您可以將多個值結合在一起,以使用此參數來設定多個旗標。 這些值可以傳遞至 CommandType 參數做為值的陣列,或是這些值的逗號分隔字串。 Cmdlet 會使用二進位 OR 作業來合併值。 將值當做數位傳遞是最簡單的選項,也可讓您在值上使用 Tab 鍵自動完成。
類型: | CommandTypes |
別名: | Type |
接受的值: | Alias, Function, Filter, Cmdlet, ExternalScript, Application, Script, Workflow, Configuration, All |
Position: | Named |
預設值: | None |
必要: | False |
接受管線輸入: | False |
接受萬用字元: | False |
-DisableNameChecking
指出當您匯入名稱包含未核准動詞或禁止字元的 Cmdlet 或函式時,此 Cmdlet 會隱藏警告您訊息。
根據預設,當您匯入的模組匯出名稱中具有未核准動詞命令的 Cmdlet 或函式時,Windows PowerShell 會顯示下列警告訊息:
「警告:某些彙入的命令名稱包含未經核准的動詞,這可能會使其更容易探索。 如需詳細資料或類型 Get-Verb
,請使用 Verbose 參數來查看已核准的動詞清單。
此訊息只是警告。 完整模組仍會匯入,包括不符合規範的命令。 雖然訊息會顯示給模組使用者,但模組作者應該修正命名問題。
類型: | SwitchParameter |
Position: | Named |
預設值: | None |
必要: | False |
接受管線輸入: | False |
接受萬用字元: | False |
-FormatTypeName
指定指定之Microsoft .NET Framework 類型的格式化指示。 輸入類型名稱。 允許通配符。
此參數的值必須是匯入命令之會話中命令所 Get-FormatData
傳回的類型名稱。 若要取得遠端工作階段中的所有格式化資料, 請輸入 *
。
如果命令不包含 CommandName 或 FormatTypeName 參數,Import-PSSession
則會匯入遠端會話中命令所Get-FormatData
傳回之所有 .NET Framework 類型的格式化指示。
如果您使用 FormatTypeName 參數,除非您使用 CommandName 參數,否則不會匯入任何命令。
同樣地,如果您使用 CommandName 參數,除非使用 FormatTypeName 參數,否則不會匯入命令的格式檔案。
類型: | String[] |
Position: | 3 |
預設值: | None |
必要: | False |
接受管線輸入: | False |
接受萬用字元: | False |
-FullyQualifiedModule
此值可以是模組名稱、完整模組規格或模組檔案的路徑。
當值為路徑時,路徑可以是完整或相對路徑。 相對於包含 using 語句的腳本,會解析相對路徑。
當值是名稱或模組規格時,PowerShell 會 搜尋 PSModulePath 中的指定模組。
模組規格是具有下列索引鍵的哈希表。
ModuleName
- 必要 指定模組名稱。GUID
- 選擇性 指定模組的 GUID。- 也必須指定下列三個索引鍵中的至少一個。
ModuleVersion
- 指定模組的最低可接受的版本。MaximumVersion
- 指定模組的最大可接受的版本。RequiredVersion
- 指定模組的確切必要版本。 這無法與其他版本金鑰搭配使用。
您無法在與 Module 參數相同的命令中指定 FullyQualifiedModule 參數。 這兩個參數互斥。
類型: | ModuleSpecification[] |
Position: | Named |
預設值: | None |
必要: | False |
接受管線輸入: | False |
接受萬用字元: | False |
-Module
指定和陣列 Windows PowerShell 嵌入式管理單元和模組中的命令。 輸入嵌入式管理單元和模組名稱。 不允許通配符。
Import-PSSession
無法從嵌入式管理單元匯入提供者。
如需詳細資訊,請參閱 about_PSSnapins 和 about_Modules。
類型: | String[] |
別名: | PSSnapin |
Position: | Named |
預設值: | None |
必要: | False |
接受管線輸入: | False |
接受萬用字元: | False |
-Prefix
指定匯入命令名稱中名詞的前置詞。
使用此參數可避免會話中不同命令具有相同名稱時可能發生的名稱衝突。
例如,如果您指定 Remote 前置詞,然後匯 Get-Date
入 Cmdlet,則此 Cmdlet 在會話中已知為 Get-RemoteDate
,而且不會與原始 Get-Date
Cmdlet 混淆。
類型: | String |
Position: | Named |
預設值: | None |
必要: | False |
接受管線輸入: | False |
接受萬用字元: | False |
-Session
指定 從中匯入 Cmdlet 的 PSSession 。 輸入包含會話物件的變數,或取得會話物件的命令,例如 New-PSSession
或 Get-PSSession
命令。 您只能指定一個工作階段。 此為必要參數。
類型: | PSSession |
Position: | 0 |
預設值: | None |
必要: | True |
接受管線輸入: | False |
接受萬用字元: | False |
輸入
None
您無法使用管線將物件傳送至此 Cmdlet。
輸出
此 Cmdlet 會傳回與 Cmdlet 傳回的相同模組物件New-Module
Get-Module
。
不過,匯入的模組是暫時的,而且只存在於目前的會話中。 若要在磁碟上建立永久模組,請使用 Export-PSSession
Cmdlet。
備註
Import-PSSession
依賴PowerShell遠端基礎結構。 若要使用此 Cmdlet,計算機必須設定為 WS-Management 遠端處理。 如需詳細資訊,請參閱 about_Remote 和 about_Remote_Requirements。Import-PSSession
不會匯入變數或PowerShell提供者。- 當您匯入與目前會話中命令同名的命令時,匯入的命令可以隱藏會話中的別名、函式和 Cmdlet,而且它們可以取代會話中的函式和變數。 若要防止名稱衝突,請使用 Prefix 參數。 如需詳細資訊,請參閱 about_Command_Precedence。
Import-PSSession
將所有命令轉換成函式,再匯入函式。 因此,匯入的命令的行為會與保留原始命令類型時的行為稍有不同。 例如,如果您從 PSSession 匯入 Cmdlet,然後從模組或嵌入式管理單元匯入具有相同名稱的 Cmdlet,則從 PSSession 匯入的 Cmdlet 預設一律會執行,因為函式優先於 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-FormatData
、Select-Object
和Get-Help
Cmdlet 的Get-Command
PSSession 匯入命令。 - 匯入的命令與其他遠端命令具有相同的限制,包括無法使用使用者介面啟動程式,例如記事本。
- 由於 Windows PowerShell 設定檔不會在 PSSessions 中執行,因此設定檔新增至工作階段的命令不適用於
Import-PSSession
。 若要從配置檔匯入命令,請在匯入命令之前,先Invoke-Command
使用命令在 PSSession 中手動執行配置檔。 - 建立的
Import-PSSession
暫存模組可能包含格式化檔案,即使命令未匯入格式化數據也一樣。 如果命令未匯入格式化數據,所建立的任何格式化檔案都不會包含格式化數據。 - 若要使用
Import-PSSession
,目前會話中的執行原則不能為 [受限] 或 [全部簽署],因為建立的暫存模組Import-PSSession
包含這些原則所禁止的未簽署腳本檔案。 若要在不變更本機計算機的執行原則的情況下使用Import-PSSession
,請使用的Set-ExecutionPolicy
Scope 參數,為單一進程設定較不嚴格的執行原則。 - 在 Windows PowerShell 2.0 中,從另一個會話匯入之命令的說明主題不包含您使用 Prefix 參數指派的前置詞。 若要取得 Windows PowerShell 2.0 中匯入命令的說明,請使用原始的 (非前置詞) 命令名稱。
相關連結
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應