Register-PSSessionConfiguration

參考

模組:: Microsoft.PowerShell.Core

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

語法

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

此範例會 註冊 AdminShell 會話設定。

變數 $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

啟用和停用會話組態，並判斷它是否可用於計算機上的遠端或本機會話。此參數可接受的值為：

Disabled。停用會話設定。它無法用於電腦的遠端或本機存取。
本機。可讓本機計算機的使用者使用會話設定，在同一部計算機上建立本機回送會話，但拒絕存取遠端使用者。
遠端。允許本機和遠端使用者使用會話設定來建立會話，並在這部計算機上執行命令。

預設值為 Remote。

其他 Cmdlet 稍後可以覆寫此參數的值。例如， Enable-PSRemoting Cmdlet 允許遠端訪問所有工作階段設定、 Enable-PSSessionConfiguration Cmdlet 啟用工作階段設定，而 Disable-PSRemoting Cmdlet 會防止遠端訪問所有工作階段設定。

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

類型:	PSSessionConfigurationAccessMode
接受的值:	Disabled, Local, Remote
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ApplicationBase

指定 AssemblyName 參數值中指定的元件檔路徑（*.dll）。當 AssemblyName 參數的值不包含路徑時，請使用此參數。預設值是目前的目錄。

類型:	String
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-AssemblyName

指定定義組態類型之元件檔的名稱（*.dll）。您可以在此參數或 ApplicationBase 參數的值中指定.dll的路徑。

當您指定 ConfigurationTypeName 參數時，需要此參數。

類型:	String
Position:	1
預設值:	None
必要:	True
接受管線輸入:	False
接受萬用字元:	False

-ConfigurationTypeName

指定用於此組態之Microsoft .NET Framework 類型的完整名稱。您指定的類型必須實 作 System.Management.Automation.Remoting.PSSessionConfiguration 類別。

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

建立類型可讓您控制會話設定的更多層面，例如公開或隱藏 Cmdlet 的特定參數，或設定使用者無法覆寫的數據大小和物件大小限制。

如果您省略此參數， 則會使用DefaultRemotePowerShellConfiguration 類別進行會話設定。

類型:	String
Position:	2
預設值:	None
必要:	True
接受管線輸入:	False
接受萬用字元:	False

-Confirm

執行 Cmdlet 之前先提示您確認。

類型:	SwitchParameter
別名:	cf
Position:	Named
預設值:	False
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Force

隱藏所有使用者提示，並在不提示的情況下重新啟動 WinRM 服務。重新啟動服務會讓設定變更生效。

若要防止重新啟動並隱藏重新啟動提示，請指定 NoServiceRestart 參數。

類型:	SwitchParameter
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-MaximumReceivedDataSizePerCommandMB

指定可在任何單一遠端命令中傳送至這部計算機的數據量限制。輸入以 MB 為單位的數據大小（MB）。預設值為 50 MB。

如果在 ConfigurationTypeName 參數中指定的組態類型中定義數據大小限制，則會使用組態類型的限制，並忽略此參數的值。

類型:	Nullable<T>[Double]
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-MaximumReceivedObjectSizeMB

指定任何單一物件中可以傳送至這部計算機之數據量的限制。輸入以 MB 為單位的數據大小。預設值為 10 MB。

如果在 ConfigurationTypeName 參數中指定的組態類型中定義物件大小限制，則會使用組態類型的限制，並忽略此參數的值。

類型:	Nullable<T>[Double]
Position:	Named
預設值:	10
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ModulesToImport

指定自動匯入至使用工作階段組態之工作階段的模組。

根據預設，只會 將 Microsoft.PowerShell.Core 匯入會話。除非排除 Cmdlet，否則您可以使用 Import-Module 將模組新增至會話。

除了 SessionType 參數所指定的模組，以及會話組態檔New-PSSessionConfigurationFile中 ModulesToImport 索引鍵中所列的模組之外，也會匯入此參數值中指定的模組。不過，會話組態檔中的設定可以隱藏模組導出的命令，或防止使用者使用它們。

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

類型:	Object[]
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Name

指定工作階段組態的名稱。此為必要參數。

類型:	String
Position:	0
預設值:	None
必要:	True
接受管線輸入:	True
接受萬用字元:	False

-NoServiceRestart

此參數的意圖是防止重新啟動 WinRM 服務。尚未實作這項功能。

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

類型:	SwitchParameter
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Path

指定工作階段組態檔的路徑和檔名（.pssc），例如由建立的路徑 New-PSSessionConfigurationFile和檔名。如果您省略路徑，預設值為目前目錄。

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

類型:	String
Position:	Named
預設值:	None
必要:	True
接受管線輸入:	False
接受萬用字元:	False

-ProcessorArchitecture

判斷在使用此會話設定的會話中，是否啟動 32 位或 64 位版本的 PowerShell 進程。此參數可接受的值為：x86 （32 位）和 AMD64 （64 位）。默認值取決於裝載會話組態之計算機的處理器架構。

您可以使用此參數在 64 位電腦上建立 32 位工作階段。嘗試在32位電腦上建立64位進程失敗。

類型:	String
別名:	PA
接受的值:	x86, amd64
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-PSVersion

指定使用此工作階段設定之工作階段中的 PowerShell 版本。

此參數的值優先於會話組態檔中的 PowerShellVersion 索引鍵值。

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

類型:	Version
別名:	PowerShellVersion
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-RunAsCredential

指定工作階段中命令的認證。根據預設，命令會以目前使用者的許可權執行。

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

類型:	PSCredential
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-SecurityDescriptorSddl

指定組態的安全性描述元定義語言（SDDL）字串。

此字串會決定使用新工作階段組態所需的許可權。若要在會話中使用會話組態，用戶必須至少有設定的執行（叫用）許可權。

如果安全性描述元很複雜，請考慮使用 ShowSecurityDescriptorUI 參數，而不是此參數。您無法在相同的命令中使用這兩個參數。

如果您省略此參數，WinRM 服務的根 SDDL 會用於此組態。若要檢視或變更根 SDDL，請使用 WSMan 提供者。例如 Get-Item wsman:\localhost\service\rootSDDL 。如需 WSMan 提供者的詳細資訊，請輸入 Get-Help wsman。

類型:	String
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-SessionTypeOption

指定工作階段組態的類型特定選項。輸入工作階段類型選項物件，例如 Cmdlet 傳回的 New-PSWorkflowExecutionOption PSWorkflowExecutionOption 物件。

使用會話設定的會話選項取決於會話選項的值和會話組態選項。除非指定，否則在會話中設定的選項，例如使用 New-PSSessionOption Cmdlet，優先於會話組態中設定的選項。不過，會話選項值不能超過會話組態中設定的最大值。

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

類型:	PSSessionTypeOption
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ShowSecurityDescriptorUI

指出此 Cmdlet 會顯示屬性表，可協助您建立會話設定的 SDDL。屬性表會出現在您輸入 Register-PSSessionConfiguration 命令之後，然後重新啟動 WinRM 服務。

設定組態的許可權時，請記住，使用者至少必須具有 [執行] （Invoke）許可權，才能在會話中使用會話組態。

您無法在 相同的命令中使用 SecurityDescriptorSDDL 參數和此參數。

類型:	SwitchParameter
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-StartupScript

指定 PowerShell 腳本的完整路徑。指定的文稿會在使用會話組態的新會話中執行。

您可以使用腳本來額外設定工作階段。如果腳本產生錯誤，即使是非終止錯誤，也不會建立會話，而且 New-PSSession 命令會失敗。

類型:	String
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ThreadApartmentState

指定要使用之線程模組的 Apartment 狀態。可接受的值為：

Unknown
MTA
STA

類型:	ApartmentState
接受的值:	STA, MTA, Unknown
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ThreadOptions

指定在會話中執行命令時，線程的建立和使用方式。此參數可接受的值為：

預設
ReuseThread
UseCurrentThread
UseNewThread

默認值為 UseCurrentThread。

如需詳細資訊，請參閱 PSThreadOptions 列舉。

類型:	PSThreadOptions
接受的值:	Default, UseNewThread, ReuseThread, UseCurrentThread
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-TransportOption

指定傳輸選項。

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

類型:	PSTransportOption
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-UseSharedProcess

只使用一個進程來裝載由相同用戶啟動的所有會話，並使用相同的會話設定。根據預設，每個會話都會裝載在其自己的進程中。

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

類型:	SwitchParameter
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-WhatIf

顯示執行 Cmdlet 後會發生的情況。 Cmdlet 未執行。

類型:	SwitchParameter
別名:	wi
Position:	Named
預設值:	False
必要:	False
接受管線輸入:	False
接受萬用字元:	False

輸入

None

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

輸出

WSManConfigContainerElement

備註

此 Cmdlet 僅適用於 Windows 平臺。

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

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

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

共用方式為

Register-PSSessionConfiguration

語法

Description

範例

範例 1：註冊 NewShell 會話設定

範例 2：註冊 MaintenanceShell 會話設定

範例 3：註冊會話設定

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

範例 5：使用啟動腳本註冊會話設定

參數

-AccessMode

-ApplicationBase

-AssemblyName

-ConfigurationTypeName

-Confirm

-Force

-MaximumReceivedDataSizePerCommandMB

-MaximumReceivedObjectSizeMB

-ModulesToImport

-Name

-NoServiceRestart

-Path

-ProcessorArchitecture

-PSVersion

-RunAsCredential

-SecurityDescriptorSddl

-SessionTypeOption

-ShowSecurityDescriptorUI

-StartupScript

-ThreadApartmentState

-ThreadOptions

-TransportOption

-UseSharedProcess

-WhatIf

輸入

輸出

備註

其他資源

共用方式為

Register-PSSessionConfiguration

語法

Description

範例

範例 1：註冊 NewShell 會話設定

範例 2：註冊 MaintenanceShell 會話設定

範例 3：註冊會話設定

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

範例 5：使用啟動腳本註冊會話設定

參數

-AccessMode

-ApplicationBase

-AssemblyName

-ConfigurationTypeName

-Confirm

-Force

-MaximumReceivedDataSizePerCommandMB

-MaximumReceivedObjectSizeMB

-ModulesToImport

-Name

-NoServiceRestart

-Path

-ProcessorArchitecture

-PSVersion

-RunAsCredential

-SecurityDescriptorSddl

-SessionTypeOption

-ShowSecurityDescriptorUI

-StartupScript

-ThreadApartmentState

-ThreadOptions

-TransportOption

-UseSharedProcess

-WhatIf

輸入

輸出

備註

相關連結

其他資源