Register-PSSessionConfiguration

Syntax

Register-PSSessionConfiguration
        [-ProcessorArchitecture <String>]
        [-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>]

Description

此 Cmdlet 僅適用於 Windows 平臺。

Cmdlet Register-PSSessionConfiguration 會在本機計算機上建立並註冊新的會話設定。 這是一個進階 Cmdlet，可用來為遠端使用者建立自定義會話。

每個 PowerShell 會話 （PSSession） 都會使用會話設定，也稱為端點。 當使用者建立連線到計算機的會話時，他們可以選取會話組態，或使用啟用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：註冊會話設定

此範例會註冊 管理員 Shell 工作階段組態。

變數 $sessionParams 是包含所有參數值的哈希表。 此哈希表會使用 PowerShell Splatting 傳遞至 Cmdlet。 此命令 Register-PSSessionConfiguration 會使用 SecurityDescritorSDDL 參數，在變數的值 $sddl 和 MaximumReceivedObjectSizeMB 參數中指定 SDDL，以增加物件大小限制。 它也會使用 StartupScript 參數來指定設定工作階段的腳本。

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

範例 4：傳回組態容器專案

此範例示範如何註冊 MaintenanceShell 組態。 Register-PSSessionConfiguration會傳回儲存在變數中的 $s WSManConfigContainerElement 物件。 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

-ApplicationBase

-AssemblyName

-ConfigurationTypeName

-Confirm

-Force

-MaximumReceivedDataSizePerCommandMB

-MaximumReceivedObjectSizeMB

-ModulesToImport

-Name

-NoServiceRestart

-Path

-ProcessorArchitecture

-PSVersion

-RunAsCredential

-SecurityDescriptorSddl

-SessionTypeOption

-ShowSecurityDescriptorUI

-StartupScript

-ThreadApartmentState

-ThreadOptions

-TransportOption

-UseSharedProcess

-WhatIf

輸入

None

您無法使用管線將物件傳送至此 Cmdlet。

輸出

WSManConfigContainerElement

備註

此 Cmdlet 僅適用於 Windows 平臺。

若要執行此 Cmdlet，您必須使用 [ 以系統管理員 身分執行] 選項啟動 PowerShell。

此 Cmdlet 會產生 XML，代表 Web Services for Management （WS-Management） 外掛程式組態，並將 XML 傳送至 WS-Management，這會在本機電腦上註冊外掛程式 。New-Item wsman:\localhost\plugin

會話組態對象的屬性會隨著會話組態和這些選項的值所設定的選項而有所不同。 此外，使用會話組態檔的會話組態也有其他屬性。

相關連結

• Disable-PSSessionConfiguration
• Enable-PSSessionConfiguration
• Get-PSSessionConfiguration
• New-PSSessionConfigurationFile
• Set-PSSessionConfiguration
• Test-PSSessionConfigurationFile
• Unregister-PSSessionConfiguration
• WSMan 提供者
• about_Session_Configurations
• about_Session_Configuration_Files