共用方式為


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

第二個命令會 Import-PSSession 使用 Cmdlet,將 中的 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 將 測試 Cmdlet 從 中的 $S PSSession 匯入至目前的會話。

第三個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 在 的 $SPSSession 中執行命令。

一般而言,模組會由 Import-Module Windows PowerShell 配置檔中的命令新增至所有會話,但配置檔不會在 PSSessions 中執行。

第三個命令會使用的 Import-PSSessionModule 參數,將模組中的 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-CommandAll 參數來取得目前工作階段中的所有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 嵌入式管理單元的名稱。

第五個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-CommandModule 參數,找出命令將哪些命令匯入會話Import-PSSession

第一個命令會 Import-PSSession 使用 Cmdlet,從變數中的 PSSession 匯入名稱包含 “bits” 的 $S 命令。 此命令 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
  • FilterFunction:遠端工作階段中的 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 傳回的類型名稱。 若要取得遠端工作階段中的所有格式化資料, 請輸入 *

如果命令不包含 CommandNameFormatTypeName 參數,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

指定模組,其名稱是以 ModuleSpecification 物件的形式指定, (PowerShell SDK 中 ModuleSpecification 建構函式 (哈希表) 中所述。 例如, FullyQualifiedModule 參數接受以下列格式指定的模組名稱:

  • @{ModuleName = "modulename"; ModuleVersion = "version_number"}
  • @{ModuleName = "modulename"; ModuleVersion = "version_number"; Guid = "GUID"}.

ModuleNameModuleVersion 是必要參數,但 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_PSSnapinsabout_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-PSSessionGet-PSSession 命令。 您只能指定一個工作階段。 此為必要參數。

Type:PSSession
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

輸入

None

您無法使用管線將物件傳送至此 Cmdlet。

輸出

PSModuleInfo

Import-PSSession會傳回和 Get-Module Cmdlet 傳回的相同模組物件New-Module。 不過,匯入的模組是暫時性的,而且只存在於目前的工作階段。 若要在磁碟上建立永久模組,請使用 Export-PSSession Cmdlet。

備註

  • Import-PSSession 依賴PowerShell遠端基礎結構。 若要使用此 Cmdlet,電腦必須設定 WS-Management 遠端執行功能。 如需詳細資訊,請參閱 about_Remoteabout_Remote_Requirements
  • Import-PSSession 不會匯入變數或PowerShell提供者。
  • 當您匯入與目前工作階段中具有相同命令名稱的命令時,匯入的命令可以隱藏工作階段中的別名、函式和 Cmdlet,而且可以取代工作階段中的函式和變數。 若要避免名稱衝突,請使用 Prefix 參數。 如需詳細資訊,請參閱 about_Command_Precedence
  • Import-PSSession 先將所有命令轉換成函式,再匯入它們。 如此一來,匯入的命令行為會變得與保持其原始命令類型時有點不同。 例如,如果您從 PSSession 匯入 Cmdlet,然後從模組或嵌入式管理單元匯入具有相同名稱的 Cmdlet,則從 PSSession 匯入的命令預設一律都會執行,因為函式優先於 Cmdlet。 相反地,如果您將某個別名匯入具有相同別名名稱的工作階段,則會一律使用原始的別名,因為別名優先於函式。 如需詳細資訊,請參閱 about_Command_Precedence
  • Import-PSSessionWrite-Progress 使用 Cmdlet 來顯示命令的進度。 當命令執行時,您可以看到進度列。
  • 若要尋找要匯入的命令, Import-PSSession 請使用 Invoke-Command Cmdlet 在 PSSession 中執行 Get-Command 命令。 若要取得命令的格式數據,它會使用 Get-FormatData Cmdlet。 當您執行 Import-PSSession 命令時,可能會看到來自這些 Cmdlet 的錯誤訊息。 此外,Import-PSSession也無法從不包含 、 Get-FormatDataSelect-ObjectGet-Help Cmdlet 的 Get-CommandPSSession 匯入命令。
  • 匯入的命令與其他遠端命令具有相同的限制,包括無法以使用者介面啟動程式,例如「記事本」。
  • 因為 Windows PowerShell 設定檔不會在 PSSessions 中執行,所以設定檔新增至工作階段的命令不適用於 Import-PSSession。 若要從配置檔匯入命令,請在匯入命令之前,使用 Invoke-Command 命令在 PSSession 中手動執行設定檔。
  • 建立的 Import-PSSession 暫存模組可能包含格式化檔案,即使命令未匯入格式化數據也一樣。 如果命令不會匯入格式設定資料,所建立的任何格式檔案都將不會包含格式設定資料。
  • 若要使用 Import-PSSession,目前會話中的執行原則不可為 Restricted 或 AllSigned,因為建立的暫存模組 Import-PSSession 包含這些原則禁止的未簽署腳本檔案。 若要在不變更本機計算機的執行原則的情況下使用 Import-PSSession ,請使用的 Set-ExecutionPolicyScope 參數,為單一進程設定較不嚴格的執行原則。
  • 在 Windows PowerShell 2.0 中,從另一個工作階段匯入命令的說明主題不包含您使用 Prefix 參數指派的首碼。 若要取得在 Windows PowerShell 2.0 中匯入命令的說明,請使用原始 (未加上首碼) 的命令名稱。