Register-PSSessionConfiguration

参考

模块:: Microsoft.PowerShell.Core

创建并注册新的会话配置。

语法

Register-PSSessionConfiguration
        [-ProcessorArchitecture <String>]
        [-SessionType <PSSessionType>]
        [-Name] <String>
        [-ApplicationBase <String>]
        [-RunAsCredential <PSCredential>]
        [-ThreadApartmentState <ApartmentState>]
        [-ThreadOptions <PSThreadOptions>]
        [-AccessMode <PSSessionConfigurationAccessMode>]
        [-UseSharedProcess]
        [-StartupScript <String>]
        [-MaximumReceivedDataSizePerCommandMB <Double>]
        [-MaximumReceivedObjectSizeMB <Double>]
        [-SecurityDescriptorSddl <String>]
        [-ShowSecurityDescriptorUI]
        [-Force]
        [-NoServiceRestart]
        [-PSVersion <Version>]
        [-SessionTypeOption <PSSessionTypeOption>]
        [-TransportOption <PSTransportOption>]
        [-ModulesToImport <Object[]>]
        [-WhatIf]
        [-Confirm]
        [<CommonParameters>]

Register-PSSessionConfiguration
        [-ProcessorArchitecture <String>]
        [-Name] <String>
        [-AssemblyName] <String>
        [-ApplicationBase <String>]
        [-ConfigurationTypeName] <String>
        [-RunAsCredential <PSCredential>]
        [-ThreadApartmentState <ApartmentState>]
        [-ThreadOptions <PSThreadOptions>]
        [-AccessMode <PSSessionConfigurationAccessMode>]
        [-UseSharedProcess]
        [-StartupScript <String>]
        [-MaximumReceivedDataSizePerCommandMB <Double>]
        [-MaximumReceivedObjectSizeMB <Double>]
        [-SecurityDescriptorSddl <String>]
        [-ShowSecurityDescriptorUI]
        [-Force]
        [-NoServiceRestart]
        [-PSVersion <Version>]
        [-SessionTypeOption <PSSessionTypeOption>]
        [-TransportOption <PSTransportOption>]
        [-ModulesToImport <Object[]>]
        [-WhatIf]
        [-Confirm]
        [<CommonParameters>]

Register-PSSessionConfiguration
        [-ProcessorArchitecture <String>]
        [-Name] <String>
        [-RunAsCredential <PSCredential>]
        [-ThreadApartmentState <ApartmentState>]
        [-ThreadOptions <PSThreadOptions>]
        [-AccessMode <PSSessionConfigurationAccessMode>]
        [-UseSharedProcess]
        [-StartupScript <String>]
        [-MaximumReceivedDataSizePerCommandMB <Double>]
        [-MaximumReceivedObjectSizeMB <Double>]
        [-SecurityDescriptorSddl <String>]
        [-ShowSecurityDescriptorUI]
        [-Force]
        [-NoServiceRestart]
        [-TransportOption <PSTransportOption>]
        -Path <String>
        [-WhatIf]
        [-Confirm]
        [<CommonParameters>]

说明

cmdlet Register-PSSessionConfiguration 在本地计算机上创建并注册新的会话配置。这是一个高级 cmdlet，可用于为远程用户创建自定义会话。

PSSession) (每个 PowerShell 会话都使用会话配置，也称为终结点。当用户创建连接到计算机的会话时，可以选择会话配置或使用启用 PowerShell 远程处理时注册的默认会话配置。用户还可以设置 $PSSessionConfigurationName 首选项变量，它指定在当前会话中创建的远程会话的默认配置。

会话配置可定义远程会话的环境。此配置可以确定会话中可使用哪些命令和语言元素，它可以包含用于保护计算机的设置，如用于限制单个对象或命令中会话可以远程接收的数据量的设置。会话配置的安全描述符确定哪些用户有权使用会话配置。

通过使用可实现新的配置类的程序集以及在会话中运行的脚本，可以定义配置的元素。从 PowerShell 3.0 开始，还可以使用会话配置文件来定义会话配置。

有关会话配置的信息，请参阅 about_Session_Configurations。有关会话配置文件的信息，请参阅 about_Session_Configuration_Files。

示例

示例 1：注册 NewShell 会话配置

在此示例中，我们将注册 NewShell 会话配置。 AssemblyName 和 ApplicationBase 参数指定 MyShell.dll 文件的位置，该文件指定会话配置中的 cmdlet 和提供程序。 ConfigurationTypeName 参数指定要从程序集中使用的配置类。

$sessionConfiguration = @{
    Name='NewShell'
    ApplicationBase='c:\MyShells\'
    AssemblyName='MyShell.dll'
    ConfigurationTypeName='MyClass'
}
Register-PSSessionConfiguration @sessionConfiguration

若要使用此配置，请键入 New-PSSession -ConfigurationName newshell。

示例 2：注册 MaintenanceShell 会话配置

此示例在本地计算机上注册 MaintenanceShell 会话配置。 StartupScript 参数指定Maintenance.ps1脚本。

Register-PSSessionConfiguration -Name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1

当用户使用 New-PSSession 命令并选择 MaintenanceShell 配置时，脚本 Maintenance.ps1 在新会话中运行。脚本可以配置会话。这包括导入模块和设置会话的执行策略。如果脚本生成任何错误（包括非终止错误），则 New-PSSession 命令将失败。

示例 3：注册会话配置

此示例注册 AdminShell 会话配置。

变量 $sessionParams 是包含所有参数值的哈希表。此哈希表使用 PowerShell 展开传递到 cmdlet。该 Register-PSSessionConfiguration 命令使用 SecurityDescritorSDDL 参数在变量的值 $sddl 中指定 SDDL，并使用 MaximumReceivedObjectSizeMB 参数来增加对象大小限制。它还使用 StartupScript 参数来指定用于配置会话的脚本。

$sddl = "O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;FA;GA;;;WD)(AU;FA;SA;GWGX;;WD)"
$sessionParams = @{
    Name="AdminShell"
    SecurityDescriptorSDDL=$sddl
    MaximumReceivedObjectSizeMB=20
    StartupScript="C:\scripts\AdminShell.ps1"
}
Register-PSSessionConfiguration @sessionParams

示例 4：返回配置容器元素

此示例演示如何注册 MaintenanceShell 配置。 Register-PSSessionConfiguration返回存储在变量中的 $sWSManConfigContainerElement 对象。 Format-List 显示返回的对象的所有属性。 PSPath 属性显示该对象存储在 WSMan: 驱动器的目录中。 Get-ChildItem (别名 dir) 显示路径中的 WSMan:\LocalHost\PlugIn 项。其中包括新的 MaintenanceShell 配置和 PowerShell 附带的两个默认配置。

$s = Register-PSSessionConfiguration -Name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1
$s | Format-List -Property *
dir WSMan:\LocalHost\Plugin

PSPath            : Microsoft.WSMan.Management\WSMan::localhost\Plugin\MaintenanceShell
PSParentPath      : Microsoft.WSMan.Management\WSMan::localhost\Plugin
PSChildName       : MaintenanceShell
PSDrive           : WSMan
PSProvider        : Microsoft.WSMan.Management\WSMan
PSIsContainer     : True
Keys              : {Name=MaintenanceShell}
Name              : MaintenanceShell
TypeNameOfElement : Container

Name                      Type                 Keys
----                      ----                 ----
MaintenanceShell          Container            {Name=MaintenanceShell}
microsoft.powershell      Container            {Name=microsoft.powershell}
microsoft.powershell32    Container            {Name=microsoft.powershell32}

示例 5：使用启动脚本注册会话配置

在此示例中，我们将创建并注册 WithProfile 会话配置。 StartupScript 参数指示 PowerShell 为使用该会话配置的任何会话运行指定的脚本。

Register-PSSessionConfiguration -Name WithProfile -StartupScript Add-Profile.ps1

该脚本包含单个命令，该命令使用点 (.) 来获得来源，以在会话的当前作用域中运行用户的 CurrentUserAllHosts 配置文件。

有关配置文件的详细信息，请参阅 about_Profiles。有关使用点 (.) 来获得来源的详细信息，请参阅 about_Scopes。

参数

-AccessMode

启用和禁用会话配置，并确定它是否可以用于计算机上的远程或本地会话。此参数的可接受值为：

已禁用。禁用会话配置。它不能用于对计算机的远程或本地访问。
Local。允许本地计算机的用户使用会话配置在同一台计算机上创建本地环回会话，但拒绝远程用户访问。
远程。允许本地和远程用户使用会话配置创建会话并在此计算机上运行命令。

默认值为 Remote。

其他 cmdlet 稍后可以替代此参数的值。例如， Enable-PSRemoting cmdlet 允许远程访问所有会话配置， Enable-PSSessionConfiguration cmdlet 允许会话配置，cmdlet Disable-PSRemoting 阻止远程访问所有会话配置。

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

Type:	PSSessionConfigurationAccessMode
Accepted values:	Disabled, Local, Remote
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ApplicationBase

指定 assemblyName 参数的值中指定的程序集文件 (*.dll) 的路径。如果 AssemblyName 参数的值不包括路径，则使用此参数。默认为当前目录。

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

-AssemblyName

指定定义配置类型的程序集文件 (*.dll) 的名称。可以在此参数或 ApplicationBase 参数的值中指定 .dll 的路径。

指定 ConfigurationTypeName 参数时，此参数是必需的。

Type:	String
Position:	1
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-ConfigurationTypeName

指定用于此配置的 Microsoft .NET Framework 类型的完全限定的名称。指定的类型必须实现 System.Management.Automation.Remoting.PSSessionConfiguration 类。

若要指定实现配置类型的程序集文件 (*.dll) ，请指定 AssemblyName 和 ApplicationBase 参数。

创建类型可以控制会话配置的更多方面，例如公开或隐藏 cmdlet 的某些参数，或设置用户无法替代的数据大小和对象大小限制。

如果省略此参数，则 DefaultRemotePowerShellConfiguration 类将用于会话配置。

Type:	String
Position:	2
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Confirm

提示你在运行 cmdlet 之前进行确认。

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

-Force

取消所有用户提示，并在不提示的情况下重启 WinRM 服务。重新启动服务可使配置更改生效。

若要阻止重启并禁止重启提示，请指定 NoServiceRestart 参数。

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

-MaximumReceivedDataSizePerCommandMB

指定可在任何一个远程命令中发送到此计算机的数据量限制。输入数据大小（以兆字节 (MB) 为单位）。默认值为 50 MB。

如果在 ConfigurationTypeName 参数中指定的配置类型中定义数据大小限制，则将使用配置类型中的限制并忽略此参数的值。

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

-MaximumReceivedObjectSizeMB

指定可在任何单个对象中发送到此计算机的数据量限制。输入数据大小（以 MB 为单位）。默认值为 10 MB。

如果在 ConfigurationTypeName 参数中指定的配置类型中定义对象大小限制，则将使用配置类型中的限制并忽略此参数的值。

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

-ModulesToImport

指定自动导入到使用会话配置的会话中的模块。

默认情况下，仅 Microsoft.PowerShell.Core 导入到会话中。除非排除 cmdlet，否则可以使用 Import-Module 将模块添加到会话。

除 SessionType 参数指定的模块和会话配置文件New-PSSessionConfigurationFile的 ModulesToImport 键中列出的模块 () 外，还会导入此参数值中指定的模块。但是，会话配置文件中的设置可以隐藏模块所导出的命令或阻止用户使用它们。

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

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

-Name

指定会话配置的名称。此参数是必需的。

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

-NoServiceRestart

不重启 WinRM 服务，并取消提示重启服务。

默认情况下，运行 Register-PSSessionConfiguration 命令时，系统会提示重启 WinRM 服务以使新会话配置生效。在 重新启动 WinRM 服务之前，新会话配置将无效。

若要在无提示的情况下重启 WinRM 服务，请指定 Force 参数。若要手动重启 WinRM 服务，请使用 Restart-Service cmdlet。

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

-Path

指定会话配置文件 (.pssc) 的路径和文件名，例如由 New-PSSessionConfigurationFile创建的会话配置文件。如果省略路径，则默认路径为当前目录。

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

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

-ProcessorArchitecture

确定是在使用此会话配置的会话中启动 32 位还是 64 位版本的 PowerShell 进程。此参数的可接受值为：x86 (32 位) 和 AMD64 (64 位) 。默认值由托管该会话配置的计算机的处理器体系结构确定。

可使用此参数在 64 位计算机上创建 32 位会话。尝试在 32 位计算机上创建 64 位进程将失败。

Type:	String
Aliases:	PA
Accepted values:	x86, amd64
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-PSVersion

指定使用此会话配置的会话中的 PowerShell 版本。

此参数的值优先于会话配置文件中 PowerShellVersion 键的值。

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

Type:	Version
Aliases:	PowerShellVersion
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-RunAsCredential

指定会话中命令的凭据。默认情况下，在当前用户授权下运行命令。

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

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

-SecurityDescriptorSddl

指定用于配置的安全描述符定义语言 (SDDL) 字符串。

此字符串确定使用新的会话配置所需的权限。若要在会话中使用会话配置，用户必须至少具有该配置的“执行 (调用) 权限。

如果安全描述符较复杂，请考虑使用 ShowSecurityDescriptorUI 参数，而不是此参数。不能在同一命令中同时使用这两个参数。

如果省略此参数，则 WinRM 服务的根 SDDL 将用于此配置。若要查看或更改根 SDDL，请使用 WSMan 提供程序。例如，Get-Item wsman:\localhost\service\rootSDDL。有关 WSMan 提供程序的详细信息，请键入 Get-Help wsman。

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

-SessionType

指定通过使用该会话配置创建的会话的类型。此参数的可接受值为：

空白。默认情况下，不会向会话添加任何模块。使用此 cmdlet 的参数将模块、函数、脚本和其他功能添加到会话。
默认。将 Microsoft.PowerShell.Core 添加到会话。此模块包含 Import-Module 用户可用于导入其他模块的 cmdlet，除非显式禁止该 cmdlet。
RestrictedRemoteServer。仅包含以下 cmdlet：Exit-PSSession、、Get-Command、Get-FormatDataGet-Help、Measure-Object、 Out-Default和 Select-Object。使用脚本或程序集，或者会话配置文件中的键，来将模块、函数、脚本和其他功能添加到会话。

默认值为 Default。

此参数的值优先于会话配置文件中 SessionType 键的值。

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

Type:	PSSessionType
Accepted values:	DefaultRemoteShell, Workflow
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SessionTypeOption

为会话配置指定特定于类型的选项。输入会话类型选项对象，例如 cmdlet 返回的 New-PSWorkflowExecutionOptionPSWorkflowExecutionOption 对象。

使用会话配置的会话选项由会话选项和会话配置选项的值确定。除非指定，否则会话中设置的选项（例如通过使用 New-PSSessionOption cmdlet）优先于会话配置中设置的选项。但是，会话选项的值不能超过在会话配置中设置的最大值。

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

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

-ShowSecurityDescriptorUI

指示此 cmdlet 显示一个属性表，该表可帮助你为会话配置创建 SDDL。输入 Register-PSSessionConfiguration 命令并重启 WinRM 服务后，将显示属性表。

设置配置的权限时，请记住，用户必须至少具有执行 (调用) 权限才能在会话中使用会话配置。

不能在同一命令中使用 SecurityDescriptorSDDL 参数和此参数。

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

-StartupScript

指定 PowerShell 脚本的完全限定路径。指定的脚本在使用会话配置的新会话中运行。

可以使用脚本来额外配置会话。如果脚本生成错误，甚至是非终止错误，则不会创建会话， New-PSSession 并且命令将失败。

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

-ThreadApartmentState

指定会话中线程的单元状态。此参数的可接受值为：STA、MTA 和 Unknown。默认值是“未知”。

Type:	ApartmentState
Accepted values:	STA, MTA, Unknown
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ThreadOptions

指定命令在会话中运行时如何创建和使用线程。此参数的可接受值为：

Default
ReuseThread
UseCurrentThread
UseNewThread

默认值为 UseCurrentThread。

有关详细信息，请参阅 PSThreadOptions 枚举。

Type:	PSThreadOptions
Accepted values:	Default, UseNewThread, ReuseThread, UseCurrentThread
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-TransportOption

指定传输选项。

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

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

-UseSharedProcess

仅使用一个进程来托管由同一用户启动的所有会话，并使用相同的会话配置。默认情况下，每个会话都托管在其自身进程中。

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

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

-WhatIf

显示运行该 cmdlet 时会发生什么情况。此 cmdlet 未运行。

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

输入

None

不能通过管道将输入传递给此 cmdlet。

输出

WSManConfigContainerElement

备注

若要运行此 cmdlet，必须使用“ 以管理员身份运行” 选项启动 PowerShell。

此 cmdlet 生成表示 Web Services for Management (WS-Management) 插件配置的 XML，并将 XML 发送到 WS-Management，后者在本地计算机上注册插件 (New-Item wsman:\localhost\plugin) 。

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

通过

Register-PSSessionConfiguration

语法

说明

示例

示例 1：注册 NewShell 会话配置

示例 2：注册 MaintenanceShell 会话配置

示例 3：注册会话配置

示例 4：返回配置容器元素

示例 5：使用启动脚本注册会话配置

参数

-AccessMode

-ApplicationBase

-AssemblyName

-ConfigurationTypeName

-Confirm

-Force

-MaximumReceivedDataSizePerCommandMB

-MaximumReceivedObjectSizeMB

-ModulesToImport

-Name

-NoServiceRestart

-Path

-ProcessorArchitecture

-PSVersion

-RunAsCredential

-SecurityDescriptorSddl

-SessionType

-SessionTypeOption

-ShowSecurityDescriptorUI

-StartupScript

-ThreadApartmentState

-ThreadOptions

-TransportOption

-UseSharedProcess

-WhatIf

输入

输出

备注

相关链接

其他资源