Import-PSSession

模块:

Microsoft.PowerShell.Utility

将另一个会话中的命令导入当前会话中。

语法

Import-PSSession
      [-Prefix <String>]
      [-DisableNameChecking]
      [[-CommandName] <String[]>]
      [-AllowClobber]
      [-ArgumentList <Object[]>]
      [-CommandType <CommandTypes>]
      [-Module <String[]>]
      [-FullyQualifiedModule <ModuleSpecification[]>]
      [[-FormatTypeName] <String[]>]
      [-Certificate <X509Certificate2>]
      [-Session] <PSSession>
      [<CommonParameters>]

说明

Import-PSSession cmdlet 可将本地或远程计算机上的 PSSession 中的命令（如 cmdlet、函数和别名）导入当前会话中。 可以导入 Get-Command cmdlet 可以在 PSSession 中找到的任何命令。

使用 Import-PSSession 命令来导入命令，这些命令来自自定义 shell（如 Microsoft Exchange Server shell），或者来自包括 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 导入所有命令

$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 将命令从 $S 的 PSSession 中导入当前会话。 它使用 CommandName 参数指定带有名词 Test 的命令，使用 FormatTypeName 参数来导入这些命令的格式设置数据。

第三个和第四个命令使用当前会话中导入的命令。 由于导入的命令实际添加到当前会话中，因此你将使用本地语法来运行它们。 无需使用 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。

这些命令从 Server01 计算机上的 PSSession 中导入 New-Test 和 Get-Test cmdlet，从 Server02 计算机上的 PSSession 中导入 Set-Test 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 将 $S 的 PSSession 中的 Test cmdlet 导入到当前会话中。

第三个命令使用导入的 New-Test cmdlet 的 AsJob 参数，将 New-Test 命令作为后台作业运行。 该命令将 New-Test 返回的作业对象保存在 $batch 变量中。

第四个命令使用 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 变量中。

第二个命令使用 Invoke-Command cmdlet 在 $S 的 PSSession 中运行 Import-Module 命令。

通常，通过 Windows PowerShell 配置文件中的 Import-Module 命令将该模块添加到所有会话中，但配置文件不会在 PSSession 中运行。

第三个命令使用 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 将 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 函数在 $S 的 PSSession 中运行导入的 Get-Date cmdlet。

第三个命令将运行 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

此命令从 $S 的 PSSession 中导入名称中包含“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

指定使用指定的参数（参数值）所得到的命令的数组。

例如，要导入 $S 的 PSSession 中证书 (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 或使用证书 (Cert:) 驱动器中的 Get-ChildItem 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 或其别名 Type。 此参数的可接受值为：

• Alias：远程会话中的 Windows PowerShell 别名。
• All：远程会话中的 cmdlet 和函数。
• Application：除远程会话的 Path 环境变量 ($env:path) 中列出的路径中的 Windows PowerShell 文件以外的所有文件，包括 .txt、.exe 和 .dll 文件。
• Cmdlet：远程会话中的 cmdlet。 默认值为“Cmdlet”。
• ExternalScript：在远程会话中的 Path 环境变量 ($env:path) 中列出的路径中的 .ps1 文件。
• Filter 和 Function：远程会话中的 Windows PowerShell 函数。
• Script：远程会话中的脚本块。

这些值定义为基于标志的枚举。 可以使用此参数将多个值组合在一起以设置多个标志。 可以将这些值作为值数组或这些值的逗号分隔字符串传递给 CommandType 参数。 该 cmdlet 将使用二进制或运算合并这些值。 将值作为数组传递是最简单的选项，此选项还支持对值使用 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 将显示以下警告消息：

“警告：一些导入的命令名称包括未经批准的谓词，这可能会使它们更难于发现。 请使用 Verbose 参数获取详细信息或者键入 Get-Verb 以查看批准的谓词列表。”

此消息只是警告。 仍将导入完整的模块，其中包括非一致性的命令。 尽管会向模块用户显示消息，但是模块作者应修复命名问题。

类型:	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 - 指定模块所需的确切版本。 这不能与其他版本键一起使用。

不能在同一命令中将 FullyQualifiedModule 参数指定为 Module 参数。 这两个参数相互排斥。

类型:	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。

输出

PSModuleInfo

此 cmdlet 返回 New-Module 和 Get-Module cmdlet 返回的相同模块对象。 但是，导入的模块是临时的并且仅在当前会话中存在。 若要在磁盘上创建一个永久模块，请使用 Export-PSSession cmdlet。

备注

Windows PowerShell 包含 Import-PSSession 的以下别名：

• ipsn

• 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-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 中导入命令的帮助，请使用原始（无前缀）的命令名称。

相关链接

• Export-PSSession