New-PSSession

参考

模块:: Microsoft.PowerShell.Core

创建与本地或远程计算机的持续性连接。

语法

New-PSSession
   [[-ComputerName] <String[]>]
   [-Credential <PSCredential>]
   [-Name <String[]>]
   [-EnableNetworkAccess]
   [-ConfigurationName <String>]
   [-Port <Int32>]
   [-UseSSL]
   [-ApplicationName <String>]
   [-ThrottleLimit <Int32>]
   [-SessionOption <PSSessionOption>]
   [-Authentication <AuthenticationMechanism>]
   [-CertificateThumbprint <String>]
   [<CommonParameters>]

New-PSSession
   [-Credential <PSCredential>]
   [-Name <String[]>]
   [-EnableNetworkAccess]
   [-ConfigurationName <String>]
   [-ThrottleLimit <Int32>]
   [-ConnectionUri] <Uri[]>
   [-AllowRedirection]
   [-SessionOption <PSSessionOption>]
   [-Authentication <AuthenticationMechanism>]
   [-CertificateThumbprint <String>]
   [<CommonParameters>]

New-PSSession
   -Credential <PSCredential>
   [-Name <String[]>]
   [-ConfigurationName <String>]
   [-VMId] <Guid[]>
   [-ThrottleLimit <Int32>]
   [<CommonParameters>]

New-PSSession
   -Credential <PSCredential>
   [-Name <String[]>]
   [-ConfigurationName <String>]
   -VMName <String[]>
   [-ThrottleLimit <Int32>]
   [<CommonParameters>]

New-PSSession
   [[-Session] <PSSession[]>]
   [-Name <String[]>]
   [-EnableNetworkAccess]
   [-ThrottleLimit <Int32>]
   [<CommonParameters>]

New-PSSession
   [-Name <String[]>]
   [-ConfigurationName <String>]
   -ContainerId <String[]>
   [-RunAsAdministrator]
   [-ThrottleLimit <Int32>]
   [<CommonParameters>]

说明

New-PSSession cmdlet 在本地或远程计算机上创建 PowerShell 会话 (PSSession)。创建 PSSession 时，PowerShell 将建立与远程计算机的持久连接。

使用 PSSession 运行共享数据的多个命令，例如函数或变量的值。若要在 PSSession 从中运行命令，请使用 Invoke-Command cmdlet。若要使用 PSSession 与远程计算机直接交互，请使用 Enter-PSSession cmdlet。有关详细信息，请参阅 about_PSSessions。

可以在远程计算机上运行命令，而无需使用 Enter-PSSession 或 Invoke-Command 的 ComputerName 参数创建 PSSession。当你使用 ComputerName 参数时，PowerShell 将创建一个用于该命令的临时连接，然后该连接将关闭。

示例

示例 1：在本地计算机上创建会话

$s = New-PSSession

此命令在本地计算机上创建新的 PSSession，并将 PSSession 保存在 $s 变量中。

你现在可以使用此 PSSession 在本地计算机上运行命令。

示例 2：在远程计算机上创建会话

$Server01 = New-PSSession -ComputerName Server01

此命令在 Server01 计算机上创建新的 PSSession，并将其保存在 $Server01 变量中。

在创建多个 PSSession 对象时，将它们分配给具有有用名称的变量。这将帮助你在后续命令中管理 PSSession 对象。

示例 3：在多台计算机上创建会话

$s1, $s2, $s3 = New-PSSession -ComputerName Server01,Server02,Server03

此命令在 ComputerName 参数指定的每台计算机上创建一个 PSSession 对象（共三个）。

该命令使用赋值运算符 (=) 将新的 PSSession 对象分配给变量：$s1、$s2、$s3。它将 Server01 PSSession 分配给 $s1、将 Server02 PSSession 分配给 $s2、将 Server03 PSSession 分配给 $s3。

当你将多个对象分配给一系列变量时，PowerShell 会分别将每个对象分配给系列中的一个变量。如果对象多于变量，则所有剩余对象都将分配给最后一个变量。如果变量多于对象，则剩余变量为空 ($null)。

示例 4：使用指定的端口创建会话

New-PSSession -ComputerName Server01 -Port 8081 -UseSSL -ConfigurationName E12

此命令在 Server01 计算机上创建一个连接到服务器端口 8081 并使用 SSL 协议的新 PSSession。新的 PSSession 使用名为 E12 的备用会话配置。

在设置端口前，你必须将远程计算机上的 WinRM 侦听器配置为侦听端口 8081。有关详细信息，请参阅 Port 参数的说明。

示例 5：基于现有会话创建会话

New-PSSession -Session $s -Credential Domain01\User01

此命令创建与现有 PSSession 具有相同属性的 PSSession。当现有 PSSession 的资源耗尽，需要新的 PSSession 来分担一些需求时，你可以使用此命令格式。

该命令使用 New-PSSession 的 Session 参数指定在 $s 变量中保存的 PSSession。它使用 Domain1\Admin01 用户的凭据来完成命令。

示例 6：在不同的域中创建具有全局作用域的会话

$global:s = New-PSSession -ComputerName Server1.Domain44.Corpnet.Fabrikam.com -Credential Domain01\Admin01

此示例显示了如何创建一个在位于不同域中的计算机上具有全局作用域的 PSSession。

默认情况下，在命令行创建的 PSSession 对象是使用全局作用域创建的，而在脚本中创建的 PSSession 对象具有脚本作用域。

若要创建具有全局作用域的 PSSession，请创建一个新的 PSSession，然后将该 PSSession 存储在强制转换为全局作用域的变量中。在此示例下，$s 变量将强制转换为全局作用域。

该命令使用 ComputerName 参数指定远程计算机。由于计算机与用户帐户处于不同的域中，因此需指定计算机的全名以及用户的凭据。

示例 7：为许多计算机创建会话

$rs = Get-Content C:\Test\Servers.txt | New-PSSession -ThrottleLimit 50

此命令在 Servers.txt 文件中列出的每台计算机（共 200 台）上创建 PSSession，并将生成的 PSSession 保存在 $rs 变量中。 PSSession 对象的限制为 50。

当计算机名称存储在数据库、电子表格、文件文件中或以其他可转换为文本的格式存储时，可以使用此命令格式。

示例 8：使用 URI 创建会话

$s = New-PSSession -URI http://Server01:91/NewSession -Credential Domain01\User01

此命令在 Server01 计算机上创建 PSSession，并将其存储在 $s 变量中。它使用 URI 参数指定传输协议、远程计算机、端口和备用会话配置。它还使用 Credential 参数指定有权在远程计算机上创建会话的用户帐户。

示例 9：在一组会话中运行后台作业

$s = New-PSSession -ComputerName (Get-Content Servers.txt) -Credential Domain01\Admin01 -ThrottleLimit 16
Invoke-Command -Session $s -ScriptBlock {Get-Process PowerShell} -AsJob

这些命令可创建一组 PSSession 对象，然后在每个 PSSession 对象中运行后台作业。

第一个命令在 Servers.txt 文件中列出的每台计算机上创建一个新的 PSSession。它使用 New-PSSession cmdlet 创建 PSSession。 ComputerName 参数的值是一个命令，该命令使用 Get-Content cmdlet 获取 Servers.txt 文件的计算机名列表。

该命令使用 Credential 参数创建带有域管理员权限的 PSSession 对象，并且使用 ThrottleLimit 参数将该命令限制到 16 个并发连接。该命令将 PSSession 对象保存在 $s 变量中。

第二个命令使用 Invoke-Command cmdlet 的 AsJob 参数来启动在 $s 的每个 PSSession 对象中运行 Get-Process PowerShell 命令的后台作业。

有关 PowerShell 后台作业的详细信息，请参阅 about_Jobs 和 about_Remote_Jobs。

示例 10：使用计算机的 URI 为计算机创建会话

New-PSSession -ConnectionURI https://management.exchangelabs.com/Management

此命令创建连接到由 URI（而不是计算机名）指定的计算机的 PSSession 对象。

示例 11：创建会话选项

$so = New-PSSessionOption -SkipCACheck
New-PSSession -ConnectionUri https://management.exchangelabs.com/Management -SessionOption $so -Credential Server01\Admin01

此示例显示了如何创建会话选项对象，并使用 SessionOption 参数。

第一个命令使用 New-PSSessionOption cmdlet 创建会话选项。它将生成的 SessionOption 对象保存在 $so 变量中。

第二个命令在新会话中使用该选项。该命令使用 New-PSSession cmdlet 创建新会话。 SessionOption 参数的值为 $so 变量中的 SessionOption 对象。

参数

-AllowRedirection

指示此 cmdlet 允许将此连接重定向到备用统一资源标识符 (URI)。

使用 ConnectionURI 参数时，远程目标将返回一个指令，以重定向到不同的 URI。默认情况下，PowerShell 不会重定向连接，但可以使用此参数来重定向连接。

也可以通过更改 MaximumConnectionRedirectionCount 会话选项值，限制重定向连接的次数。使用 New-PSSessionOption cmdlet 的 MaximumRedirection 参数或设置 $PSSessionOption 首选项变量的 MaximumConnectionRedirectionCount 属性。默认值是 5。

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

-ApplicationName

指定连接 URI 的应用程序名称段。当命令中未使用 ConnectionURI 参数时，请使用此参数指定应用程序名称。

默认值为本地计算机上的 $PSSessionApplicationName 首选项变量的值。如果未定义此首选项变量，则默认值为 WSMAN。该值适用于大多数使用情况。有关详细信息，请参阅 about_Preference_Variables。

WinRM 服务使用应用程序名称来选择为连接请求提供服务的侦听器。此参数的值应与远程计算机上的侦听器的 URLPrefix 属性值相匹配。

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

-Authentication

指定用于对用户的凭据进行身份验证的机制。此参数的可接受值为：

Default
Basic
Credssp
Digest
Kerberos
Negotiate
NegotiateWithImplicitCredential

默认值为 Default。

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

注意

在凭据安全支持提供程序 (CredSSP) 身份验证中，用户凭据传递到远程计算机中以进行验证，这种验证用于要求对多个资源（例如访问远程网络共享）进行验证的命令。此机制增加了远程操作的安全风险。如果远程计算机的安全受到威胁，则传递给该计算机的凭据可用于控制网络会话。

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

-CertificateThumbprint

指定有权执行此操作的用户帐户的数字公钥证书 (X509)。输入证书的证书指纹。

在基于客户端证书的身份验证中使用证书。证书只能映射到本地用户帐户，而不适用于域帐户。

若要获取证书，请在 PowerShell Cert: 驱动器中使用 Get-Item 或 Get-ChildItem 命令。

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

-ComputerName

指定计算机的名称数组。此 cmdlet 创建与指定计算机的持续性连接 (PSSession)。如果输入多个计算机名称，New-PSSession 将创建多个 PSSession 对象，每台计算机一个。默认为本地计算机。

键入一台或多台远程计算机的 NetBIOS 名称、IP 地址或完全限定的域名。若要指定本地计算机，请键入计算机名称 localhost 或点 (.)。当计算机与用户处于不同的域中时，必须使用完全限定的域名。还可以通过管道将计算机名（括在引号中）传递给 New-PSSession。

若要在 ComputerName 参数的值中使用 IP 地址，该命令必须包括 Credential 参数。此外，必须为计算机配置 HTTPS 传输，或者必须在本地计算机上的 WinRM TrustedHosts 列表中包含远程计算机的 IP 地址。有关将计算机名称添加到 TrustedHosts 列表的说明，请参阅 about_Remote_Troubleshooting 中的“如何将计算机添加到受信任主机列表中”。

若要在 ComputerName 参数的值中包括本地计算机，则使用“以管理员身份运行”选项启动 Windows PowerShell。

类型:	String[]
别名:	Cn
Position:	0
默认值:	None
必需:	False
接受管道输入:	True
接受通配符:	False

-ConfigurationName

指定用于新 PSSession 的会话配置。

输入会话配置的配置名称或完全限定的资源 URI。如果只指定配置名称，则将在其前面预置以下架构 URI：http://schemas.microsoft.com/PowerShell。

会话的会话配置位于远程计算机上。如果远程计算机上不存在指定的会话配置，则该命令会失败。

默认值为本地计算机上的 $PSSessionConfigurationName 首选项变量的值。如果未设置此首选项变量，则默认值为 Microsoft.PowerShell。有关详细信息，请参阅 about_Preference_Variables。

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

-ConnectionUri

指定定义会话的连接终结点的 URI。 URI 必须完全限定。此字符串的格式如下：

<Transport>://<ComputerName>:<Port>/<ApplicationName>

默认值如下：

http://localhost:5985/WSMAN

如果未指定 ConnectionURI，则可以使用 UseSSL、ComputerName、Port 和 ApplicationName 参数来指定 ConnectionURI 值。

URI 的 Transport 段的有效值为 HTTP 和 HTTPS。如果使用传输段指定连接 URI，但不指定端口，将使用以下标准端口来创建会话：80 用于 HTTP，443 用于 HTTPS。若要使用 PowerShell 远程处理的默认端口，请指定端口 5985 用于 HTTP，或端口 5986 用于 HTTPS。

如果目标计算机将连接重定向到另一个 URI，PowerShell 将阻止重定向，除非在命令中使用 AllowRedirection 参数。

类型:	Uri[]
别名:	URI, CU
Position:	0
默认值:	None
必需:	True
接受管道输入:	True
接受通配符:	False

-ContainerId

指定容器的 ID 数组。此 cmdlet 启动与每个指定容器的交互式会话。使用 docker ps 命令获取容器 ID 的列表。有关详细信息，请参阅 docker ps 命令的帮助。

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

-Credential

指定有权执行此操作的用户帐户。默认为当前用户。

键入用户名（如 User01 或 Domain01\User01），或输入 Get-Credential cmdlet 生成的 PSCredential 对象。如果键入用户名，系统会提示输入密码。

凭据存储在 PSCredential 对象中，密码存储为 SecureString。

注意

有关 SecureString 数据保护的详细信息，请参阅 SecureString 的安全性如何？。

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

-EnableNetworkAccess

指示此 cmdlet 将交互式安全令牌添加到环回会话。通过交互式令牌，你可以在环回会话中运行用于获取其他计算机中的数据的命令。例如，你可以在该会话中运行用于将 XML 文件从远程计算机复制到本地计算机的命令。

环回会话是在同一计算机上开始并终止的 PSSession。若要创建环回会话，请省略 ComputerName 参数或将其值设置为点 (.)、localhost 或本地计算机的名称。

默认情况下，此 cmdlet 使用网络令牌创建环回会话，该令牌提供的权限可能不足以对远程计算机进行身份验证。

EnableNetworkAccess 参数仅在环回会话中有效。如果在远程计算机上创建会话时使用 EnableNetworkAccess，该命令将成功，但会忽略此参数。

通过用于将会话凭据委派给其他计算机的 Authentication 参数的 CredSSP 值，还可以在环回会话中进行远程访问。

若要保护计算机免受恶意访问，断开连接的具有交互式令牌（使用 EnableNetworkAccess 参数创建）的环回会话只能通过创建该会话的计算机重新连接。断开连接的使用 CredSSP 身份验证的会话可通过其他计算机重新连接。有关详细信息，请参阅 Disconnect-PSSession。

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

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

-Name

指定 PSSession 的友好名称。

使用其他 cmdlet（例如 Get-PSSession 和 Enter-PSSession）时，你可以使用该名称引用 PSSession。对于计算机或当前会话，该名称无需是唯一的。

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

-Port

指定远程计算机上用于此连接的网络端口。若要连接到一台远程计算机，则必须在该连接所用的端口上侦听远程计算机。默认端口为 5985（HTTP 的 WinRM 端口）和 5986（HTTPS 的 WinRM 端口）。

使用其他端口之前，必须在远程计算机上配置 WinRM 侦听器，才能在该端口上进行侦听。使用以下命令配置侦听器：

winrm delete winrm/config/listener?Address=*+Transport=HTTP
winrm create winrm/config/listener?Address=*+Transport=HTTP @{Port="\<port-number\>"}

除非必要，否则不要使用 Port 参数。命令中的端口设置适用于运行该命令的所有计算机或会话。备用端口设置可能会阻止在所有计算机上运行该命令。

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

-RunAsAdministrator

指示 PSSession 以管理员身份运行。

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

-Session

指定 PSSession 对象的数组，此 cmdlet 会将其用作新 PSSession 的模型。此参数创建与指定的 PSSession 对象具有相同属性的新 PSSession 对象。

输入一个变量，其中包含 PSSession 对象或创建或获取 PSSession 的命令，例如 New-PSSession 或 Get-PSSession 命令。

生成的 PSSession 对象与原有 PSSession 具有相同的计算机名称、应用程序名称、连接 URI、端口、配置名称、中止值和安全套接字层 (SSL) 值，但具有不同显示名称、ID 和实例 ID (GUID)。

类型:	PSSession[]
Position:	0
默认值:	None
必需:	False
接受管道输入:	True
接受通配符:	False

-SessionOption

为该会话指定高级选项。输入 SessionOption 对象（例如使用 New-PSSessionOption cmdlet 创建的对象），或输入哈希表，其中的键是会话选项名称，而值是会话选项值。

这些选项的默认值由 $PSSessionOption 首选项变量的值（如果已设置）确定。否则，通过在会话配置中设置的选项创建默认值。

会话选项值优先于在 $PSSessionOption 首选项变量和会话配置中设置的会话的默认值。但是，它们不优先于在会话配置中设置的最大值、配额或限制。

有关包含默认值的会话选项的说明，请参阅 New-PSSessionOption。有关 $PSSessionOption 首选项变量的信息，请参阅 about_Preference_Variables。有关会话配置的详细信息，请参阅 about_Session_Configurations。

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

-ThrottleLimit

指定为运行此命令可建立的并发连接的最大数目。如果省略此参数或输入 0（零）值，则使用默认值 32。

节流限制仅适用于当前命令，而不适用于会话或计算机。

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

-UseSSL

指示此 cmdlet 使用 SSL 协议来建立与远程计算机的连接。默认情况下，不使用 SSL。

WS-Management 对通过网络传输的所有 PowerShell 内容进行加密。 UseSSL 参数提供额外的保护措施，它通过 HTTPS 连接而不是 HTTP 连接来发送数据。

如果使用此参数，但 SSL 在用于命令的端口上不可用，则命令将失败。

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

-VMId

指定虚拟机 ID 的数组。此 cmdlet 启动与每个指定虚拟机的 PowerShell Direct 交互式会话。有关详细信息，请参阅使用 PowerShell 自动化和管理虚拟机。

使用 Get-VM 查看 Hyper-V 主机上可用的虚拟机。

类型:	Guid[]
别名:	VMGuid
Position:	0
默认值:	None
必需:	True
接受管道输入:	True
接受通配符:	False

-VMName

指定一个虚拟机的名称数组。此 cmdlet 启动与每个指定虚拟机的 PowerShell Direct 交互式会话。有关详细信息，请参阅使用 PowerShell 自动化和管理虚拟机。