New-PSSessionOption
创建一个包含 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。
类型: | 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。
输出
备注
如果未在命令中使用 SessionOption 参数来创建 PSSession,则会话选项由 $PSSessionOption
首选项变量的属性值确定(如果已设置)。 有关 $PSSessionOption
变量的详细信息,请参阅 about_Preference_Variables。
会话配置对象的属性会根据为会话配置设置的选项以及这些选项的值而有所不同。 此外,使用会话配置文件的会话配置还具有其他属性。