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 将生成一个对象，该对象包含所有选项的默认值。由于可以编辑每个属性，因此可以将生成的对象用作模板，并为企业创建标准选项对象。

还可以在 $PSSessionOption 首选项变量中保存 SessionOption 对象。此变量的值为会话选项建立新的默认值。如果没有为会话设置会话选项，并且它们优先于在会话配置中设置的选项，但可以通过在创建会话的 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。

类型:	PSPrimitiveDictionary
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-CancelTimeout

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

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

类型:	Int32
别名:	CancelTimeoutMSec
Position:	Named
默认值:	60000
必需:	False
接受管道输入:	False
接受通配符:	False

-Culture

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

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

类型:	CultureInfo
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	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 分钟）。

类型:	Int32
别名:	IdleTimeoutMSec
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	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 中引入的。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-MaxConnectionRetryCount

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

为 PowerShell 版本 5.0 添加了此参数。

类型:	Int32
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-MaximumReceivedDataSizePerCommand

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

此选项旨在保护客户端计算机上的资源。

类型:	Int32
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-MaximumReceivedObjectSize

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

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

类型:	Int32
Position:	Named
默认值:	209715200
必需:	False
接受管道输入:	False
接受通配符:	False

-MaximumRedirection

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

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

类型:	Int32
Position:	Named
默认值:	5
必需:	False
接受管道输入:	False
接受通配符:	False

-NoCompression

关闭会话中的数据包压缩。压缩使用更多的处理器周期，但它使传输更快。

类型:	SwitchParameter
Position:	Named
默认值:	False
必需:	False
接受管道输入:	False
接受通配符:	False

-NoEncryption

关闭数据加密。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-NoMachineProfile

阻止加载用户的 Windows 用户配置文件。因此，会话的创建速度可能会更快，但特定于用户的注册表设置、环境变量和证书等项在会话中不可用。

类型:	SwitchParameter
Position:	Named
默认值:	False
必需:	False
接受管道输入:	False
接受通配符:	False

-OpenTimeout

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

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

类型:	Int32
别名:	OpenTimeoutMSec
Position:	Named
默认值:	180000 (3 minutes)
必需:	False
接受管道输入:	False
接受通配符:	False

-OperationTimeout

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

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

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

类型:	Int32
别名:	OperationTimeoutMSec
Position:	Named
默认值:	180000 (3 minutes)
必需:	False
接受管道输入:	False
接受通配符:	False

-OutputBufferingMode

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

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

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

Block。当输出缓冲区已满时，将挂起执行，直到缓冲区清除为止。
Drop。当输出缓冲区已满时，将继续执行。保存新输出后，将丢弃最早的输出。
None。未指定输出缓冲模式。

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

此参数是在 Windows PowerShell 3.0 中引入的。

类型:	OutputBufferingMode
接受的值:	None, Drop, Block
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-ProxyAccessType

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

IEConfig
WinHttpConfig
AutoDetect
NoProxyServer
None

默认值为 None。

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

类型:	ProxyAccessType
接受的值:	None, IEConfig, WinHttpConfig, AutoDetect, NoProxyServer
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-ProxyAuthentication

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

Basic
Digest
Negotiate

默认值为 Negotiate。

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

类型:	AuthenticationMechanism
接受的值:	Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos
Position:	Named
默认值:	Negotiate
必需:	False
接受管道输入:	False
接受通配符:	False

-ProxyCredential

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

类型:	PSCredential
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-SkipCACheck

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

仅当使用另一种机制信任远程计算机时使用此选项，例如远程计算机是物理安全隔离的网络的一部分，或者在 WinRM 配置中将远程计算机列为受信任主机时，才使用此选项。

类型:	SwitchParameter
Position:	Named
默认值:	False
必需:	False
接受管道输入:	False
接受通配符:	False

-SkipCNCheck

指定服务器的证书公用名（CN）不必与服务器的主机名匹配。此选项仅在使用 HTTPS 协议的远程作中使用。

仅对受信任的计算机使用此选项。

类型:	SwitchParameter
Position:	Named
默认值:	False
必需:	False
接受管道输入:	False
接受通配符:	False

-SkipRevocationCheck

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

类型:	SwitchParameter
Position:	Named
默认值:	False
必需:	False
接受管道输入:	False
接受通配符:	False

-UICulture

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

有效值包括：

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

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

类型:	CultureInfo
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-UseUTF16

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

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

输入

None

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

输出

PSSessionOption

备注

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

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

通过