Register-PSSessionConfiguration

模組:

Microsoft.PowerShell.Core Module

建立並註冊新的會話設定。

語法

NameParameterSet (預設值)

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

AssemblyNameParameterSet

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

SessionConfigurationFile

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

Description

此 Cmdlet 只能在 Windows 平臺上使用。

指令長程式會在 Register-PSSessionConfiguration 本地電腦上建立並註冊新的會話設定。 這是一個進階的指令檔，可以用來為遠端使用者建立自訂會話。

每個 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：註冊會話設定

此範例登錄 AdminShell 會話設定。

變 $sessionParams 數是一個包含所有參數值的雜湊表。 此雜湊表會透過 PowerShell splatting 傳遞給 cmdlet。 指令使用 Register-PSSessionConfigurationSecurityDescriptorSDDL 參數指定變數值 $sddl 中的 SDDL，並使用 MaximumReceivedObjectSizeMB 參數來增加物件大小限制。 它也會使用 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回傳一個儲存在變數中的 $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

啟用與停用會話設定，並判斷該設定是否可用於電腦上的遠端或本地會話。 此參數可接受的值為：

• Disabled. 停用會話設定。 它無法用於遠端或本地存取電腦。
• 本機。 允許本地電腦使用者使用會話設定在同一台電腦上建立本地迴圈會話，但拒絕遠端使用者的存取。
• 遠端。 允許本地及遠端使用者使用會話設定建立會話並在此電腦上執行指令。

預設值為遠端。

其他指令小程式之後可以覆寫此參數的值。 例如， Enable-PSRemoting cmdlet 允許遠端存取所有會話組態， Enable-PSSessionConfiguration cmdlet 啟用會話組態，而 Disable-PSRemoting cmdlet 則防止遠端存取所有會話組態。

此參數是在 PowerShell 3.0 中引進的。

參數屬性

類型:	PSSessionConfigurationAccessMode
預設值:	None
接受的值:	Disabled, Local, Remote
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-ApplicationBase

指定 AssemblyName 參數值中指定的組合檔*.dll路徑（） 當 AssemblyName 參數的值沒有包含路徑時，可以使用這個參數。 預設值是目前的目錄。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

NameParameterSet

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

AssemblyNameParameterSet

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-AssemblyName

指定一個組合檔的名稱（*.dll），其中定義了組態類型。 你可以在這個參數或 ApplicationBase 參數的值中指定 .dll 的路徑。

當你指定 ConfigurationTypeName 參數時，這個參數是必須的。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

AssemblyNameParameterSet

Position:	1
必要:	True
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-ConfigurationTypeName

指定用於此配置的 Microsoft .NET Framework 類型的完全限定名稱。 你指定的類型必須實作 System.Management.Automation.Remoting.PSSessionConfiguration 類別。

若要指定實作該組態類型的組合檔*.dll（），請指定 AssemblyName 與 ApplicationBase 參數。

建立型別可以讓你控制更多會話設定的面向，例如暴露或隱藏 cmdlet 的某些參數，或設定使用者無法覆蓋的資料大小與物件大小限制。

若省略此參數， DefaultRemotePowerShellConfiguration 類別將用於會話設定。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

AssemblyNameParameterSet

Position:	2
必要:	True
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Confirm

在執行 Cmdlet 之前，提示您進行確認。

參數屬性

類型:	SwitchParameter
預設值:	False
支援萬用字元:	False
不要顯示:	False
別名:	參見

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Force

會抑制所有使用者提示，並在不提示的情況下重新啟動 WinRM 服務。 重新啟動服務後，設定變更才會有效。

為了防止重新啟動並抑制重新啟動提示，請指定 NoServiceRestart 參數。

參數屬性

類型:	SwitchParameter
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-MaximumReceivedDataSizePerCommandMB

規定任何單一遠端指令可傳送至此電腦的資料量限制。 輸入資料大小（MB）。 預設是 50 MB。

如果在 ConfigurationTypeName 參數中指定的設定類型中定義了資料大小限制，則會使用該設定類型的限制，而忽略該參數的值。

參數屬性

類型:	Nullable<T>[Double]
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-MaximumReceivedObjectSizeMB

規定任何單一物件可傳送至此電腦的資料量上限。 輸入資料大小（以兆位元組為單位）。 預設是 10 MB。

如果在 ConfigurationTypeName 參數中指定的設定類型中定義了物件大小限制，則會使用該設定類型的限制，而忽略該參數的值。

參數屬性

類型:	Nullable<T>[Double]
預設值:	10
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-ModulesToImport

指定會自動匯入使用該會話設定的會話中的模組。

預設情況下只有 Microsoft。PowerShell.Core 會匯入到 sessions。 除非 cmdlet 被排除，否則你可以用來 Import-Module 將模組加入 session 中。

此參數值中指定的模組，是匯入於由 SessionType 參數指定的模組，以及會話設定檔中New-PSSessionConfigurationFileModulesToImport 鍵中列出的模組。 然而，會話設定檔中的設定可能會隱藏模組匯出的指令，或阻止使用者使用這些指令。

此參數是在 PowerShell 3.0 中引進的。

參數屬性

類型:	Object[]
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

NameParameterSet

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

AssemblyNameParameterSet

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Name

指定會話設定的名稱。 此為必要參數。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	0
必要:	True
來自管線的值:	False
來自管線按屬性名稱的值:	True
來自剩餘引數的值:	False

-NoServiceRestart

它不會重新啟動 WinRM 服務，並且會抑制重新啟動服務的提示。

預設情況下，執行 Register-PSSessionConfiguration 指令時會提示重新啟動 WinRM 服務，以使新的會話設定有效。 在 WinRM 服務重新啟動之前，新的會話設定無法生效。

若要在不提示的情況下重新啟動 WinRM 服務，請指定 Force 參數。 若要手動重新啟動 WinRM 服務，請使用 Restart-Service cmdlet。

此功能在 PowerShell 7.5.0-preview.4 中實作。

參數屬性

類型:	SwitchParameter
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Path

指定會話設定檔（.pssc）的路徑與檔名，例如由 New-PSSessionConfigurationFile。 如果你省略路徑，預設就是目前的目錄。

此參數是在 PowerShell 3.0 中引進的。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

SessionConfigurationFile

Position:	Named
必要:	True
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-ProcessorArchitecture

判斷使用 Session 配置的會話中，是啟動 32 位元還是 64 位元版本的 PowerShell 程序。 此參數的可接受值為：x86（32位元）與AMD64（64位元）。 預設值由承載會話設定的電腦的處理器架構決定。

你可以利用這個參數在 64 位元電腦上建立一個 32 位元的工作階段。 嘗試在 32 位元電腦上建立 64 位元程序失敗。

參數屬性

類型:	String
預設值:	None
接受的值:	x86, amd64
支援萬用字元:	False
不要顯示:	False
別名:	PA

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-PSVersion

指定使用此會話設定的 PowerShell 版本。

此參數的值優先於會話設定檔中 PowerShellVersion 鍵值。

此參數是在 PowerShell 3.0 中引進的。

參數屬性

類型:	Version
預設值:	None
支援萬用字元:	False
不要顯示:	False
別名:	PowerShellVersion

參數集

NameParameterSet

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

AssemblyNameParameterSet

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-RunAsCredential

指定會話中指令的憑證。 預設情況下，指令執行時會保留當前使用者的權限。

此參數是在 PowerShell 3.0 中引進的。

參數屬性

類型:	PSCredential
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-SecurityDescriptorSddl

指定一個安全描述符定義語言（SDDL）字串用於配置。

此字串決定使用新會話設定所需的權限。 要在會話中使用會話設定，使用者至少必須擁有該設定的執行（呼叫）權限。

如果安全描述符很複雜，建議使用 ShowSecurityDescriptorUI 參數代替此參數。 你不能同時用同一個指令同時使用兩個參數。

若省略此參數，則使用 WinRM 服務的根 SDDL 來進行此設定。 要查看或更改根 SDDL，請使用 WSMan 提供者。 例如 Get-Item WSMan:\localhost\service\rootSDDL 。 欲了解更多WSMan供應商資訊，請輸入 Get-Help WSMan。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-SessionTypeOption

指定會話設定的類型專屬選項。 輸入一個會話型態的選項物件，例如 psworkflowExecutionOption 物件， New-PSWorkflowExecutionOption 該指令長會回傳它。

使用會話設定的會話選項由會話選項的值與會話設定選項決定。 除非特別指定，會話中設定的選項（例如使用 New-PSSessionOption 指令碼）會優先於會話設定中的選項。 然而，會話選項的值不能超過會話設定中設定的最大值。

此參數是在 PowerShell 3.0 中引進的。

參數屬性

類型:	PSSessionTypeOption
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

NameParameterSet

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

AssemblyNameParameterSet

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-ShowSecurityDescriptorUI

表示這個 cmdlet 顯示一個屬性表，幫助你建立會話設定的 SDDL。 屬性表會在你輸入 Register-PSSessionConfiguration 指令後，然後重新啟動 WinRM 服務後出現。

在設定設定權限時，請記得使用者至少必須擁有執行（呼叫）權限，才能在會話中使用該會話設定。

你不能在同一指令中使用 SecurityDescriptorSDDL 參數和這個參數。

參數屬性

類型:	SwitchParameter
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-StartupScript

指定 PowerShell 腳本的完整限定路徑。 指定的腳本會在使用該會話設定的新工作階段中執行。

你也可以用腳本來額外設定會話。 如果腳本產生錯誤，即使是無法終止的錯誤，會話就不會被建立，指令 New-PSSession 也會失敗。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-ThreadApartmentState

指定要使用的執行緒模組的公寓狀態。 可接受的值為：

• Unknown
• MTA
• STA

參數屬性

類型:	ApartmentState
預設值:	None
接受的值:	STA, MTA, Unknown
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-ThreadOptions

規定執行緒在會話中執行指令時如何建立與使用。 此參數可接受的值為：

• Default
• 重用串
• 使用CurrentThread
• 使用新討論串

預設值為 UseCurrentThread。

欲了解更多資訊，請參閱 PSThreadOptions 列舉。

參數屬性

類型:	PSThreadOptions
預設值:	None
接受的值:	Default, UseNewThread, ReuseThread, UseCurrentThread
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-TransportOption

指定運輸選項。

此參數是在 PowerShell 3.0 中引進的。

參數屬性

類型:	PSTransportOption
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-UseSharedProcess

只用一個程序來承載所有由同一使用者啟動且使用相同會話設定的會話。 預設情況下，每個會話都以自己的程序承載。

此參數是在 PowerShell 3.0 中引進的。

參數屬性

類型:	SwitchParameter
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-WhatIf

顯示 Cmdlet 執行時會發生什麼事。 該 Cmdlet 未被執行。

參數屬性

類型:	SwitchParameter
預設值:	False
支援萬用字元:	False
不要顯示:	False
別名:	威斯康辛

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

CommonParameters

此 cmdlet 支援常見參數：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。 如需詳細資訊，請參閱 about_CommonParameters。

輸入

None

您不能將物件透過管道傳送到此 Cmdlet。

輸出

WSManConfigContainerElement

備註

此 Cmdlet 僅適用於 Windows 平臺。

要執行這個 cmdlet，你必須透過以 管理員身份執行 選項啟動 PowerShell。

此指令集產生代表 Web Services for Management （WS-Management） 外掛設定的 XML，並將 XML 傳送至 WS-Management，WS-Management 會在本地電腦New-Item WSMan:\localhost\plugin上註冊該外掛。

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

相關連結

• 停用-PSSession設定配置
• 啟用 PSSessionConfiguration
• Get-PSSessionConfiguration (取得 PSSession 設定)
• New-PSSessionConfigurationFile (建立新的 PSSession 設定檔)
• Set-PSSessionConfiguration
• Test-PSSessionConfigurationFile
• 取消註冊-PSSessionConfiguration (Unregister-PSSessionConfiguration)
• WSMan 提供者
• 關於會話設定
• 關於_會話_配置_文件