Export-PSSession

导出来自其他会话的命令,并将它们保存到 PowerShell 模块中。

语法

Export-PSSession
      [-OutputModule] <String>
      [-Force]
      [-Encoding <Encoding>]
      [[-CommandName] <String[]>]
      [-AllowClobber]
      [-ArgumentList <Object[]>]
      [-CommandType <CommandTypes>]
      [-Module <String[]>]
      [-FullyQualifiedModule <ModuleSpecification[]>]
      [[-FormatTypeName] <String[]>]
      [-Certificate <X509Certificate2>]
      [-Session] <PSSession>
      [<CommonParameters>]

说明

Export-PSSession cmdlet 从本地或远程计算机上的其他 PowerShell 会话 (PSSession) 获取 cmdlet、函数、别名和其他命令类型,并将它们保存在 PowerShell 模块中。 若要将来自模块的命令添加到当前会话,请使用 Import-Module cmdlet。

与将命令从另一个 PSSession 导入当前会话的 Import-PSSession 不同,Export-PSSession 将命令保存在模块中。 这些命令不会被导入到当前会话中。

若要导出命令,请使用 New-PSSession cmdlet 创建包含要导出的命令的 PSSession。 然后使用 Export-PSSession cmdlet 导出命令。

为了防止命令名称冲突,Export-PSSession 默认会导出所有命令,但当前会话中存在的命令除外。 可以使用 CommandName 参数指定要导出的命令

Export-PSSession cmdlet 使用 PowerShell 的隐式远程处理功能。 将命令导入当前会话后,它们将在原始会话或原始计算机上的类似会话中隐式运行。

示例

示例 1:从 PSSession 导出命令

此示例创建从本地计算机到 Server01 计算机的新 PSSession。 除当前会话中存在的命令外,所有命令都将导出到本地计算机上名为 Server01 的模块中。 导出内容包括命令的格式数据。

$S = New-PSSession -ComputerName Server01
Export-PSSession -Session $S -OutputModule Server01

New-PSSession 命令在 Server01 计算机上创建一个 PSSession。 PSSession 存储在 $S 变量中。 Export-PSSession 命令将 $S 变量的命令和格式数据导出到 Server01 模块中。

示例 2:导出 Get 和 Set 命令

此示例从服务器导出所有 GetSet 命令。

$S = New-PSSession -ConnectionUri https://exchange.microsoft.com/mailbox -Credential exchangeadmin01@hotmail.com -Authentication Negotiate
Export-PSSession -Session $S -Module exch* -CommandName Get-*, Set-* -FormatTypeName * -OutputModule $PSHOME\Modules\Exchange -Encoding ASCII

这些命令将 GetSet 命令从远程计算机上的 Microsoft Exchange Server 管理单元导出到本地计算机上的 $PSHOME\Modules 目录下的 Exchange 模块中。 通过将模块置于 $PSHOME\Modules 目录中,计算机上的所有用户都可对它进行访问。

示例 3:从远程计算机导出命令

此示例将 cmdlet 从远程计算机上的 PSSession 导出,并将它们保存在本地计算机上的某个模块中。 模块中的 cmdlet 将添加到当前会话,以便可以使用它们。

$S = New-PSSession -ComputerName Server01 -Credential Server01\User01
Export-PSSession -Session $S -OutputModule TestCmdlets -Type Cmdlet -CommandName *test* -FormatTypeName *
Remove-PSSession $S
Import-Module TestCmdlets
Get-Help Test*
Test-Files

New-PSSession 命令在 Server01 计算机上创建 PSSession,并将其保存在 $S 变量中。 Export-PSSession 命令将名称以“Test”开头的 cmdlet 从 $S 中的 PSSession 导出到本地计算机上的 TestCmdlets 模块中。

Remove-PSSession cmdlet 从当前会话删除 $S 中的 PSSession。 此命令显示了 PSSession 使用从会话导入的命令时无需处于活动状态。 Import-Module cmdlet 将 TestCmdlets 模块中的 cmdlet 添加到当前会话。 该命令可以随时在任何会话中运行。

Get-Help cmdlet 获取名称以 Test 开头的 cmdlet 的帮助。 将模块中的命令添加到当前会话后,可以使用 Get-HelpGet-Command cmdlet 了解导入的命令。 Test-Files cmdlet 已从 Server01 计算机导出,并已添加到会话中。 Test-Files cmdlet 在导入命令的计算机上的远程会话中运行。 PowerShell 基于 TestCmdlets 模块中存储的信息创建会话。

示例 4:当前会话中的 export 和 clobber 命令

此示例将存储在变量中的命令导出到当前会话。

Export-PSSession -Session $S -AllowClobber -OutputModule AllCommands

Export-PSSession 命令将 $S 变量中 PSSession 的所有命令和所有格式数据都导出到当前会话中。 AllowClobber 参数包含与当前会话中的命令同名的命令

示例 5:从关闭的 PSSession 导出命令

此示例演示当创建导出命令的 PSSession 关闭时如何使用特殊选项运行导出的命令。

如果导入模块时原始远程会话已关闭,则该模块将使用连接到发起端计算机的任何已打开的远程会话。 如果当前没有与发起端计算机建立会话,则模块将重新建立会话。

若要在远程会话中运行带有特殊选项的导出命令,必须在导入模块之前创建带有这些选项的远程会话。 将 New-PSSession cmdlet 与 SessionOption 参数结合使用

$Options = New-PSSessionOption -NoMachineProfile
$S = New-PSSession -ComputerName Server01 -SessionOption $Options
Export-PSSession -Session $S -OutputModule Server01
Remove-PSSession $S
New-PSSession -ComputerName Server01 -SessionOption $Options
Import-Module Server01

New-PSSessionOption cmdlet 创建一个 PSSessionOption 对象,并将该对象保存在 $Options 变量中。 New-PSSession 命令在 Server01 计算机上创建一个 PSSession。 SessionOption 参数使用存储在 $Options 中的对象。 会话存储在 $S 变量中。

Export-PSSession cmdlet 将命令从 $S 中的 PSSession 导出到 Server01 模块。 Remove-PSSession cmdlet 删除 $S 变量中的 PSSession。

New-PSSession cmdlet 创建一个连接到 Server01 计算机的新 PSSession。 SessionOption 参数使用存储在 $Options 中的对象。 Import-Module cmdlet 从 Server01 模块导入命令。 模块中的命令在 Server01 计算机上的 PSSession 中运行。

参数

-AllowClobber

导出指定命令,即使它们与当前会话中的命令同名。

如果导出与当前会话中的命令同名的命令,则导出的命令会隐藏或替换原始命令。 有关详细信息,请参阅 about_Command_Precedence

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ArgumentList

将使用指定的参数(参数值)所得到的命令的变体导出。

例如,要导出 $S 中 PSSession 中证书 (Cert:) 驱动器中 Get-Item 命令的变体,请键入 Export-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

指定用于对 Export-PSSession 所创建的模块中的格式文件 (*.Format.ps1xml) 或脚本模块文件 (.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

默认情况下,Export-PSSession 导出 PSSession 中的所有命令,但与当前会话中的命令同名的命令除外。 这可以防止命令被隐藏或被当前会话中的命令替换。 若要导出所有命令(甚至是那些隐藏或替换其他命令的命令),请使用 AllowClobber 参数

如果使用 CommandName 参数,则将不导出命令的格式设置文件,除非使用 FormatTypeName 参数。 同样,如果使用 FormatTypeName 参数,则将不导出命令,除非使用 CommandName 参数

Type:String[]
Aliases:Name
Position:2
Default value:All commands in the session.
Required:False
Accept pipeline input:False
Accept wildcard characters:True

-CommandType

仅导出指定类型的命令对象。 使用 CommandType 或其别名 Type

此参数的可接受值如下所示:

  • Alias:当前会话中的所有 PowerShell 别名。
  • All:所有命令类型。 它等效于 Get-Command -Name *
  • Application:位于 Path 环境变量 ($env:path) 所列路径中的所有 PowerShell 文件以外的文件,包括 .txt、.exe 和 .dll 文件。
  • Cmdlet:当前会话中的 cmdlet。 默认值为 Cmdlet。
  • Configuration:PowerShell 配置。 有关详细信息,请参阅 about_Session_Configurations
  • ExternalScript:位于 Path 环境变量 ($env:path) 所列路径中的所有 .ps1 文件。
  • FilterFunction:所有 PowerShell 函数。
  • Script:当前会话中的脚本块。
  • Workflow:PowerShell 工作流。 有关详细信息,请参阅 about_Workflows

这些值定义为基于标志的枚举。 可以使用此参数将多个值组合在一起以设置多个标志。 可以将这些值作为值数组或这些值的逗号分隔字符串传递给 CommandType 参数。 该 cmdlet 将使用二进制或运算合并这些值。 将值作为数组传递是最简单的选项,此选项还支持对值使用 Tab 自动补全。

Type:CommandTypes
Aliases:Type
Accepted values:Alias, All, Application, Cmdlet, Configuration, ExternalScript, Filter, Function, Script, Workflow
Position:Named
Default value:All commands in the session.
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Encoding

指定目标文件的编码类型。 默认值为 utf8NoBOM

此参数的可接受值如下所示:

  • ascii:对 ASCII(7 位)字符集使用编码。
  • ansi:对当前区域性的 ANSI 代码页使用编码。 此选项是在 PowerShell 7.4 中添加的。
  • bigendianunicode:使用 big-endian 字节顺序以 UTF-16 格式进行编码。
  • bigendianutf32:使用 big-endian 字节顺序以 UTF-32 格式进行编码。
  • oem:对 MS-DOS 和控制台程序使用默认编码。
  • unicode:使用 little-endian 字节顺序以 UTF-16 格式进行编码。
  • utf7:采用 UTF-7 格式编码。
  • utf8:采用 UTF-8 格式编码。
  • utf8BOM:使用字节顺序标记 (BOM) 以 UTF-8 格式进行编码
  • utf8NoBOM:不使用字节顺序标记 (BOM) 以 UTF-8 格式进行编码
  • utf32:采用 UTF-32 格式编码。

从 PowerShell 6.2 开始,Encoding 参数还允许注册代码页的数字 ID(如 -Encoding 1251)或已注册代码页的字符串名称(如 -Encoding "windows-1251")。 有关详细信息,请参阅 Encoding.CodePage .NET 文档。

从 PowerShell 7.4 开始,可以使用 Encoding 参数的 Ansi 值来传递当前区域性 ANSI 代码页的数字 ID,而无需手动指定它。

注意

UTF-7* 不再推荐使用。 从 PowerShell 7.1 起,如果为 Encoding 参数指定 utf7,则会编写警告。

Type:Encoding
Accepted values:ASCII, BigEndianUnicode, BigEndianUTF32, OEM, Unicode, UTF7, UTF8, UTF8BOM, UTF8NoBOM, UTF32
Position:Named
Default value:UTF8NoBOM
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Force

即使该文件具有只读属性,也会覆盖一个或多个现有输出文件。

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-FormatTypeName

仅导出指定 Microsoft .NET Framework 类型的格式指令。 输入类型名称。 默认情况下,Export-PSSession 将导出所有 .NET Framework 类型的格式指令,这些类型不在 System.Management.Automation 命名空间中

此参数的值必须是一个类型的名称,该类型由导出这些命令的会话中的 Get-FormatData 命令返回。 若要获取远程会话中的所有格式数据,请键入 *

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

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

Type:ModuleSpecification[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Module

仅将指定的 PowerShell 管理单元和模块中的命令导出。 输入管理单元和模块的名称。 不允许使用通配符。

有关详细信息,请参阅 Import-Moduleabout_PSSnapins

Type:String[]
Aliases:PSSnapin
Position:Named
Default value:All commands in the session.
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-OutputModule

指定由 Export-PSSession 创建的模块的可选路径和名称。 默认路径为 $HOME\Documents\WindowsPowerShell\Modules。 此参数是必需的。

如果已存在 Export-PSSession 所创建的模块子目录或任何文件,则该命令将失败。 若要覆盖现有文件,请使用 Force 参数

Type:String
Aliases:PSPath, ModuleName
Position:1
Default value:$HOME\Documents\WindowsPowerShell\Modules
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Session

指定要从中导出命令的 PSSession。 输入一个包含会话对象的变量或一个可获取会话对象的命令,如 Get-PSSession 命令。 此参数是必需的。

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

输入

None

不能通过管道将对象传递给此 cmdlet。

输出

FileInfo

此 cmdlet 返回包含它所创建的模块的文件列表。

备注

Export-PSSession 依赖于 PowerShell 远程处理基础结构。 若要使用此 cmdlet,必须对计算机进行相应配置以进行远程处理。 有关详细信息,请参阅 about_Remote_Requirements

不能使用 Export-PSSession 导出 PowerShell 提供程序。

导出的命令在从中导出这些命令的 PSSession 中隐式运行。 远程运行这些命令的详细信息完全由 PowerShell 进行处理。 可以像运行本地命令那样运行导出的命令。

Export-ModuleMember 捕获和保存它所导出的模块中的 PSSession 的相关信息。 如果在导入模块时从中导出命令的 PSSession 已关闭,并且同一台计算机上没有活动的 PSSession,则该模块中的命令将尝试重新创建 PSSession。 如果重新创建 PSSession 的尝试失败,则导出的命令将不会运行。

Export-ModuleMember 捕获并保存在模块中的会话信息不包括会话选项,例如在 $PSSessionOption 首选项变量中指定的会话选项,或使用 New-PSSessionEnter-PSSessionInvoke-Command cmdlet 的 SessionOption 参数指定的会话选项。 如果在导入模块时原始 PSSession 已关闭,则该模块将使用同一台计算机上的另一个 PSSession(如果存在)。 若要启用导入的命令以在正确配置的会话中运行,请在导入模块之前使用所需选项来创建 PSSession。

为了查找要导出的命令,Export-PSSession 将使用 Invoke-Command cmdlet 在 PSSession 中运行 Get-Command 命令。 为了获取和保存命令的格式数据,它将使用 Get-FormatDataExport-FormatData cmdlet。 运行 Export-PSSession 命令时,你可能会看到来自 Invoke-CommandGet-CommandGet-FormatDataExport-FormatData 的错误消息。 此外,Export-PSSession 无法从不包含 Get-CommandGet-FormatDataSelect-ObjectGet-Help cmdlet 的会话导出命令。

Export-PSSession 使用 Write-Progress cmdlet 来显示命令的进度。 该命令正在运行时,你可能会看到进度条。

导出的命令与其他远程命令具有相同的限制(包括无法启动具有用户界面的程序,如记事本)。

因为 PowerShell 配置文件不在 PSSession 中运行,所以配置文件添加到会话的命令无法用于 Export-PSSession。 若要从配置文件导出命令,请在导出命令之前使用 Invoke-Command 命令在 PSSession 中手动运行该配置文件。

Export-PSSession 创建的模块可能包含格式设置文件,即使该命令不导入格式数据也是如此。 如果该命令不导入格式数据,则创建的任何格式设置文件都不包含格式数据。