New-PSSessionOption

  • 参考
模块:
Microsoft.PowerShell.Core

创建一个包含 PSSession 高级选项的对象。

语法

New-PSSessionOption
   [-MaximumRedirection <Int32>]
   [-NoCompression]
   [-NoMachineProfile]
   [-Culture <CultureInfo>]
   [-UICulture <CultureInfo>]
   [-MaximumReceivedDataSizePerCommand <Int32>]
   [-MaximumReceivedObjectSize <Int32>]
   [-OutputBufferingMode <OutputBufferingMode>]
   [-MaxConnectionRetryCount <Int32>]
   [-ApplicationArguments <PSPrimitiveDictionary>]
   [-OpenTimeout <Int32>]
   [-CancelTimeout <Int32>]
   [-IdleTimeout <Int32>]
   [-ProxyAccessType <ProxyAccessType>]
   [-ProxyAuthentication <AuthenticationMechanism>]
   [-ProxyCredential <PSCredential>]
   [-SkipCACheck]
   [-SkipCNCheck]
   [-SkipRevocationCheck]
   [-OperationTimeout <Int32>]
   [-NoEncryption]
   [-UseUTF16]
   [-IncludePortInSPN]
   [<CommonParameters>]

说明

New-PSSessionOption cmdlet 创建一个对象，该对象包含用户管理的会话的高级选项 (PSSession)。 可以将对象用作 cmdlet 的 SessionOption 参数的值，这些参数创建 PSSession，例如 New-PSSession、Enter-PSSession 和 Invoke-Command。

如果没有参数，New-PSSessionOption 将生成一个对象，该对象包含所有选项的默认值。 由于每个属性都是可编辑的，因此你可以将生成的对象用作模板，并为你的企业创建标准选项对象。

还可以将 SessionOption 对象保存在 $PSSessionOption 首选项变量中。 会话选项的新的默认值由此变量的值建立。 在未为该会话设置会话选项时它们是有效的，并且优先于在会话配置中设置的选项，但可以通过在创建会话的 cmdlet 中指定会话选项或 SessionOption 对象来替代这些选项。 有关 $PSSessionOption 首选项变量的信息，请参阅 about_Preference_Variables。

在创建会话的 cmdlet 中使用 SessionOption 对象时，会话选项值优先于在 $PSSessionOption 首选项变量和会话配置中设置的会话的默认值。 但是，它们不优先于在会话配置中设置的最大值、配额或限制。 有关会话配置的详细信息，请参阅 about_Session_Configurations。

示例

示例 1：创建默认会话选项

此命令使用默认值创建 SessionOption 对象。

New-PSSessionOption

MaximumConnectionRedirectionCount : 5
NoCompression                     : False
NoMachineProfile                  : False
ProxyAccessType                   : IEConfig
ProxyAuthentication               : Negotiate
ProxyCredential                   :
SkipCACheck                       : False
SkipCNCheck                       : False
SkipRevocationCheck               : False
OperationTimeout                  : 00:03:00
NoEncryption                      : False
UseUTF16                          : False
Culture                           :
UICulture                         :
MaximumReceivedDataSizePerCommand :
MaximumReceivedObjectSize         :
ApplicationArguments              :
OpenTimeout                       : 00:03:00
CancelTimeout                     : 00:01:00
IdleTimeout                       : 00:04:00

示例 2：使用会话选项对象配置会话

此示例演示如何使用 SessionOption 对象配置会话。

$pso = New-PSSessionOption -Culture "fr-fr" -MaximumReceivedObjectSize 10MB
New-PSSession -ComputerName Server01 -SessionOption $pso

第一个命令创建一个新的 SessionOption 对象，并将其保存在 $pso 变量的值中。 第二个命令使用 New-PSSession cmdlet 在 Server01 远程计算机上创建会话。 该命令使用 $pso 变量的值中的 SessionOption 对象作为命令的 SessionOption 参数的值。

示例 3：启动交互式会话

此命令使用 Enter-PSSession cmdlet 来启动与 Server01 计算机的交互式会话。

Enter-PSSession -ComputerName Server01 -SessionOption (New-PSSessionOption -NoEncryption -NoCompression)

SessionOption 参数的值是具有 NoEncryption 和 NoCompression 参数的 New-PSSessionOption 命令。

将 New-PSSessionOption 命令用括号括起，以确保它在 Enter-PSSession 命令之前运行。

示例 4：修改会话选项对象

此示例演示如何修改 SessionOption 对象。 所有属性都具有读/写值。

$a = New-PSSessionOption
$a.OpenTimeout

Days              : 0
Hours             : 0
Minutes           : 3
Seconds           : 0
Milliseconds      : 0
Ticks             : 1800000000
TotalDays         : 0.00208333333333333
TotalHours        : 0.05
TotalMinutes      : 3
TotalSeconds      : 180
TotalMilliseconds : 180000

$a.UICulture = (Get-UICulture)
$a.OpenTimeout = (New-Timespan -Minutes 4)
$a.MaximumConnectionRedirectionCount = 1
$a

MaximumConnectionRedirectionCount : 1
NoCompression                     : False
NoMachineProfile                  : False
ProxyAccessType                   : IEConfig
ProxyAuthentication               : Negotiate
ProxyCredential                   :
SkipCACheck                       : False
SkipCNCheck                       : False
SkipRevocationCheck               : False
OperationTimeout                  : 00:03:00
NoEncryption                      : False
UseUTF16                          : False
Culture                           :
UICulture                         : en-US
MaximumReceivedDataSizePerCommand :
MaximumReceivedObjectSize         :
ApplicationArguments              :
OpenTimeout                       : 00:04:00
CancelTimeout                     : 00:01:00
IdleTimeout                       : 00:04:00

使用此方法为你的企业创建标准会话对象，然后针对特定用途创建该对象的自定义版本。

示例 5：创建首选项变量

此命令创建 $PSSessionOption 首选项变量。

$PSSessionOption = New-PSSessionOption -OpenTimeOut 120000

在会话中设置 $PSSessionOption 首选项变量时，它会为使用 New-PSSession、Enter-PSSession 和 Invoke-Command cmdlet 创建的会话中的选项建立默认值。

若要使 $PSSessionOption 变量在所有会话中都可用，请将其添加到 PowerShell 会话和 PowerShell 配置文件。

有关 $PSSessionOption 首选项变量的信息，请参阅 about_Preference_Variables。 有关配置文件的详细信息，请参阅 about_Profiles。

示例 6：满足远程会话配置的要求

此示例演示如何使用 SessionOption 对象来满足远程会话配置的要求。

$skipCN = New-PSSessionOption -SkipCNCheck
New-PSSession -ComputerName 171.09.21.207 -UseSSL -Credential Domain01\User01 -SessionOption $SkipCN

第一个命令使用 New-PSSessionOption cmdlet 创建具有 SkipCNCheck 属性的 SessionOption 对象。 该命令将生成的会话对象保存在 $skipCN 变量中。

第二个命令使用 New-PSSession cmdlet 在远程计算机上创建新会话。 $skipCN 检查变量用于 SessionOption 参数的值。

由于计算机由其 IP 地址标识，所以 ComputerName 参数的值与用于安全套接字层 (SSL) 的证书中的任何公用名都不匹配。 因此，SkipCNCheck 选项是必需的。

示例 7：使参数可用于远程会话

此示例演示如何使用 New-PSSessionOption cmdlet 的 ApplicationArguments 参数使其他数据可用于远程会话。

$team = @{Team="IT"; Use="Testing"}
$TeamOption = New-PSSessionOption -ApplicationArguments $team
$s = New-PSSession -ComputerName Server01 -SessionOption $TeamOption
Invoke-Command -Session $s {$PSSenderInfo.ApplicationArguments}

Name                 Value
----                 -----
Team                 IT
Use                  Testing
PSVersionTable       {CLRVersion, BuildVersion, PSVersion, WSManStackVersion...}

Invoke-Command -Session $s {
  if ($PSSenderInfo.ApplicationArguments.Use -ne "Testing") {
    .\logFiles.ps1
  }
  else {
    "Just testing."
  }
}

Just testing.

第一个命令创建一个包含两个键的哈希表，Team 和 Use。 该命令将哈希表保存在 $team 变量中。 有关哈希表的详细信息，请参阅 about_Hash_Tables。

接下来，New-PSSessionOption cmdlet 使用 ApplicationArguments 参数创建保存在 $team 变量中的 SessionOption 对象。 New-PSSessionOption 创建会话选项对象时，它会自动将 ApplicationArguments 参数的值中的哈希表转换为 PrimitiveDictionary，以便数据能够可靠地传输到远程会话。

New-PSSession cmdlet 在 Server01 计算机上启动会话。 它使用 SessionOption 参数将选项包含在 $teamOption 变量中。

Invoke-Command cmdlet 演示 $team 变量中的数据可用于远程会话中的命令。 数据显示在 $PSSenderInfo 自动变量的 ApplicationArguments 属性中。

最终 Invoke-Command 显示如何使用数据。

参数

-ApplicationArguments

指定发送到远程会话的 PrimitiveDictionary。 远程会话中的命令和脚本（包括会话配置中的启动脚本）可以在 $PSSenderInfo 自动变量的 ApplicationArguments 属性中找到此字典。 你可以使用此参数来将数据发送到远程会话。

有关详细信息，请参阅 about_Hash_Tables、about_Session_Configurations 和 about_Automatic_Variables。

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

-CancelTimeout

确定 PowerShell 等待取消操作 (CTRL+C) 在结束操作之前多长时间。 输入一个值（以毫秒为单位）。

默认值为 60000（一分钟）。 值为 0（零）表示无超时；该命令无限期继续。

Type:Int32
Aliases:CancelTimeoutMSec
Position:Named
Default value:60000
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Culture

指定要用于会话的区域性。 以 <languagecode2>-<country/regioncode2> 格式（如 ja-JP）输入区域性名称，该变量包含 CultureInfo 对象，或获取 CultureInfo 对象的命令。

默认值为 $Null，在会话中使用操作系统中设置的区域性。

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

-IdleTimeout

确定当远程计算机没有从本地计算机接收任何通信时，会话保持打开状态的时长。 这包括检测信号。 当时间间隔已过时，该会话将关闭。

如果你想要断开连接会话并将其重新连接，则空闲超时值非常重要。 仅当该会话未超时时，才可以重新连接。

输入一个值（以毫秒为单位）。 最小值为 60000（1 分钟）。 最大值是会话配置的 MaxIdleTimeoutms 属性的值。 默认值 -1 不会设置空闲超时。

该会话将使用在会话选项中设置的空闲超时（如果有）。 如果未设置 (-1)，会话将使用会话配置的 IdleTimeoutMs 属性的值或 WSMan shell 超时值 (WSMan:\<ComputerName>\Shell\IdleTimeout)，以最短为准。

如果会话选项中设置的空闲超时超出了会话配置的 MaxIdleTimeoutMs 属性的值，则创建会话的命令将失败。

默认 Microsoft.PowerShell 会话配置的 IdleTimeoutMs 值为 7200000 毫秒（2 小时）。 其 MaxIdleTimeoutMs 值为 2147483647 毫秒（>24 天）。 WSMan shell 空闲超时 (WSMan:\<ComputerName>\Shell\IdleTimeout) 的默认值为 7200000 毫秒（2 小时）。

从会话断开连接或重新连接到会话时，也可以更改会话的空闲超时值。 有关详细信息，请参阅 Disconnect-PSSession 和 Connect-PSSession。

在 Windows PowerShell 2.0 中，IdleTimeout 参数的默认值为 240000（4 分钟）。

Type:Int32
Aliases:IdleTimeoutMSec
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-IncludePortInSPN

包括用于 Kerberos 身份验证的服务主体名称 (SPN) 中的端口号，例如 HTTP://<ComputerName>:5985。 此选项允许客户端使用非默认 SPN 对使用 Kerberos 身份验证的远程计算机进行身份验证。

该选项旨在用于为在不同的用户帐户下运行的支持 Kerberos 身份验证的多个服务的企业。 例如，允许 Kerberos 身份验证的 IIS 应用程序可能需要将默认 SPN 注册到不同于计算机帐户的用户帐户。 在这种情况下，PowerShell 远程处理无法使用 Kerberos 进行身份验证，因为它需要一个已注册到计算机帐户的 SPN。 为了解决此问题，管理员可以创建注册到不同用户帐户的其他 SPN（例如通过使用 Setspn.exe），并且可以通过将端口号包含在 SPN 中来区分它们。

有关详细信息，请参阅 Setspn 概述。

已在 Windows PowerShell 3.0 中引入了此参数。

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

-MaxConnectionRetryCount

指定当当前尝试因网络问题而失败时，PowerShell 尝试连接到目标计算机的次数。 默认值为 5。

此参数已在 PowerShell 5.0 中添加。

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

-MaximumReceivedDataSizePerCommand

指定本地计算机在单个命令中可从远程计算机接收到的最大字节数。 输入一个值（以字节为单位）。 默认情况下，没有数据大小限制。

此选项专门用于保护客户端计算机上的资源。

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

-MaximumReceivedObjectSize

指定本地计算机可从远程计算机接收到的最大对象大小。 此选项专门用于保护客户端计算机上的资源。 输入一个值（以字节为单位）。

在 Windows PowerShell 2.0 中，如果省略此参数，则没有对象大小限制。 从 Windows PowerShell 3.0 开始，如果省略此参数，则默认值为 209715200 字节（或 200MB）。

Type:Int32
Position:Named
Default value:209715200
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaximumRedirection

确定在连接失败之前，PowerShell 将该连接重定向到备用统一资源标识符 (URI) 的次数。 默认值是 5。 值为 0（零）会阻止所有重定向。

只有在创建会话的命令中使用 AllowRedirection 参数时，才会在会话中使用此选项。

Type:Int32
Position:Named
Default value:5
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-NoCompression

关闭会话中的数据包压缩。 压缩会占用更多的处理器周期，但可以提高传输速度。

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

-NoEncryption

关闭数据加密。

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

-NoMachineProfile

阻止加载用户的 Windows 用户配置文件。 这样做可以加快创建会话的速度，但不能在该会话使用特定于用户的注册表设置、环境变量等项以及证书。

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

-OpenTimeout

确定客户端计算机等待建立会话连接的时长。 当时间间隔到期时，用于建立该连接的命令将失败。 输入一个值（以毫秒为单位）。

默认值为 180000（3 分钟）。 值为 0（零）表示无超时；该命令无限期继续。

Type:Int32
Aliases:OpenTimeoutMSec
Position:Named
Default value:180000 (3 minutes)
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-OperationTimeout

确定 WinRM 在启动连接超时之前从实时连接等待正连接测试的最长时间。有关 WinRM 的详细信息，请参阅 Windows 远程管理文档。

OperationTimeout不对远程会话中运行的命令或进程施加时间限制，并且不影响 SSH 等其他远程处理协议。

默认值为 180000（3 分钟）。 值为 0（零）表示没有超时。

Type:Int32
Aliases:OperationTimeoutMSec
Position:Named
Default value:180000 (3 minutes)
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-OutputBufferingMode

当输出缓冲区时已满时，确定如何在断开连接的会话中管理命令输出。

如果未在会话或会话配置中设置输出缓冲模式，则默认值为 Block。 用户还可以在断开会话连接时更改输出缓冲模式。

如果省略此参数，则 SessionOption 对象的 OutputBufferingMode 的值为 None。 Block 或 Drop 的值将替代会话配置中设置的输出缓冲模式传输选项。 此参数的可接受值为：

  • Block。 当输出缓冲区已满时，将挂起执行，直到清除此缓冲区。
  • Drop。 当输出缓冲区已满时，执行将继续。 由于已保存新的输出，因此将丢弃最早的输出。
  • None。 未指定任何输出缓冲模式。

有关输出缓冲模式传输选项的详细信息，请参阅 New-PSTransportOption。

已在 Windows PowerShell 3.0 中引入了此参数。

Type:OutputBufferingMode
Accepted values:None, Drop, Block
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ProxyAccessType

确定用于解析主机名的机制。 此参数的可接受值为：

  • IEConfig
  • WinHttpConfig
  • AutoDetect
  • NoProxyServer
  • None

默认值是 None。

有关此参数的值的信息，请参阅 ProxyAccessType 枚举。

Type:ProxyAccessType
Accepted values:None, IEConfig, WinHttpConfig, AutoDetect, NoProxyServer
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ProxyAuthentication

指定用于代理解析的身份验证方法。 此参数的可接受值为：

  • Basic
  • Digest
  • Negotiate

默认值为 Negotiate。

有关此参数的值的详细信息，请参阅 AuthenticationMechanism 枚举。

Type:AuthenticationMechanism
Accepted values:Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos
Position:Named
Default value:Negotiate
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ProxyCredential

指定用于代理身份验证的凭据。 输入一个变量，其中包含 PSCredential 对象或获取 PSCredential 对象的命令，例如 Get-Credential 命令。 如果未设置此选项，则不指定任何凭据。

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

-SkipCACheck

指定当它通过 HTTPS 进行连接时，客户端不会验证服务器证书是否由受信任的证书颁发机构 (CA) 签名。

仅当远程计算机通过其他机制受信任（例如远程计算机所属的网络在物理上是安全的并已隔离，或者远程计算机在 WinRM 配置中列为受信任主机）时才使用此选项。

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

-SkipCNCheck

指定服务器的证书公用名 (CN) 无需与服务器的主机名相匹配。 仅在使用 HTTPS 协议的远程操作中使用此选项。

仅将此选项用于受信任的计算机。

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

-SkipRevocationCheck

不验证服务器证书的吊销状态。

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

-UICulture

指定用于会话的 UI 区域性。

有效值包括：

  • 采用 <languagecode2>-<country/regioncode2> 格式的区域性名称，例如 ja-JP
  • 包含 CultureInfo 对象的变量
  • 获取 CultureInfo 对象的命令，例如 Get-Culture

默认值为 $null，创建会话时在操作系统中设置的 UI 区域性。

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

-UseUTF16

指示此 cmdlet 以 UTF16 格式而不是 UTF8 格式对请求进行编码。

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

输入

None

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

输出

PSSessionOption

备注

如果未在命令中使用 SessionOption 参数来创建 PSSession，则会话选项由 $PSSessionOption 首选项变量的属性值确定（如果已设置）。 有关 $PSSessionOption 变量的详细信息，请参阅 about_Preference_Variables。

会话配置对象的属性会根据为会话配置设置的选项以及这些选项的值而有所不同。 此外，使用会话配置文件的会话配置还具有其他属性。