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
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
這些命令會從 PSSession 將名稱結尾為 "-test" 的命令匯入本機工作階段,然後顯示如何使用匯入的 Cmdlet。
第一個命令會 New-PSSession
使用 Cmdlet 來建立 PSSession。 它會將 PSSession 儲存在變數中 $S
。
第二個命令會使用 Cmdlet, Import-PSSession
將 中的 PSSession $S
命令匯入目前的會話。 它使用 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。
即使是從不同的 PSSession 匯入 Cmdlet,您還是可以使用管線將物件從一個 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
中的 Test 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 在 中的 PSSession $S
中執行命令。
一般而言,模組會由 Import-Module
Windows PowerShell 配置檔中的命令新增至所有會話,但配置檔不會在 PSSessions 中執行。
第三個命令會使用的 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_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
式會在的 PSSession $S
中執行匯入Get-Date
的 Cmdlet。
第三個 Get-Date
命令會執行命令。 因為函式優先於 Cmdlet,所以 Windows PowerShell 會執行匯入Get-Date
的函式,這會傳回 Julian 日期。
第四個和第五個命令示範如何使用限定的名稱執行被匯入的命令隱藏的命令。
第四個命令會取得將原始 Get-Date
Cmdlet 新增至目前會話之 Windows PowerShell 嵌入式管理單元的名稱。
第五個命令會使用 Cmdlet 的 Get-Date
嵌入式管理單元限定名稱來執行 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
不會匯入與目前會話中命令同名的命令。
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ArgumentList
指定命令陣列,這個陣列會使用指定的自變數 (參數值) 。
例如,若要在的 PSSession $S
中匯入憑證 (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) 或腳本模組檔案, (.psm1) 建立 Import-PSSession
的暫存模組中。
輸入包含憑證的變數,或可取得憑證的命令或運算式。
若要尋找憑證,請使用 Get-PfxCertificate
Cmdlet 或使用 Get-ChildItem
憑證 (Cert:) 磁碟驅動器中的 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。 此參數可接受的值為:
Alias
:遠端工作階段中的 Windows PowerShell 別名。All
:遠端會話中的 Cmdlet 和函式。Application
:Windows-PowerShell 路徑中所列路徑中的所有檔案, (遠端會話中) ) ,包括 .txt$env:path
、.exe 和 .dll 檔案。Cmdlet
:遠端會話中的 Cmdlet。 "Cmdlet" 為預設值。ExternalScript
:路徑環境變數中所列路徑中的 .ps1 檔案, (遠端會話中)$env:path
。Filter
和Function
:遠端工作階段中的 Windows PowerShell 函式。Script
:遠端工作階段中的文本區塊。
這些值會定義為旗標型列舉。 您可以使用此參數將多個值結合在一起,以設定多個旗標。 這些值可以傳遞至 CommandType 參數做為值的陣列,或是這些值的逗號分隔字串。 Cmdlet 會使用二進位 OR 作業來合併值。 將值當做數位傳遞是最簡單的選項,也可讓您在值上使用 Tab 鍵自動完成。
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 會顯示下列警告訊息:
「警告:某些彙入的命令名稱包含未核准的動詞,這可能會讓它們更容易探索。 如需詳細資訊或類型 Get-Verb
,請使用 Verbose 參數來查看已核准的動詞清單。」
這則訊息只是一個警告。 模組仍然完整匯入,包括不合格的命令。 雖然訊息是顯示給模組的使用者,但命名的問題應該由模組作者修正。
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
此值可以是模組名稱、完整模組規格或模組檔案的路徑。
當值為路徑時,路徑可以是完整或相對路徑。 相對於包含 using 語句的腳本,會解析相對路徑。
當值為名稱或模組規格時,PowerShell 會搜尋 PSModulePath 中的指定模組。
模組規格是具有下列索引鍵的哈希表。
ModuleName
- 必填 指定模組名稱。GUID
- 選 指定模組的 GUID。- 此外,至少必須指定下列三個索引鍵的其中一個。
ModuleVersion
- 指定模組的最低可接受版本。MaximumVersion
- 指定模組可接受的最大版本。RequiredVersion
- 指定模組的確切必要版本。 這無法與其他版本金鑰搭配使用。
您無法在與 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。
輸出
此 Cmdlet 會傳回和 Get-Module
Cmdlet 傳回的相同模組物件New-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。 相反地,如果您將某個別名匯入具有相同別名名稱的工作階段,則會一律使用原始的別名,因為別名優先於函式。 如需詳細資訊,請參閱 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
,目前會話中的執行原則不可為 Restricted 或 AllSigned,因為建立的暫存模組Import-PSSession
包含這些原則禁止的未簽署腳本檔案。 若要在不變更本機計算機的執行原則的情況下使用Import-PSSession
,請使用的Set-ExecutionPolicy
Scope 參數,為單一進程設定較不嚴格的執行原則。 - 在 Windows PowerShell 2.0 中,從另一個工作階段匯入命令的說明主題不包含您使用 Prefix 參數指派的首碼。 若要取得在 Windows PowerShell 2.0 中匯入命令的說明,請使用原始 (未加上首碼) 的命令名稱。