Register-PSSessionConfiguration

參考

模組:: Microsoft.PowerShell.Core

建立並登錄新的工作階段設定。

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

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

變數 $sessionParams 是包含所有參數值的哈希表。此哈希表會使用PowerShell展開傳遞至 Cmdlet。 Register-PSSessionConfiguration此命令會使用 SecurityDescritorSDDL 參數，在變數的值$sddl和 MaximumReceivedObjectSizeMB 參數中指定 SDDL，以增加物件大小限制。它也使用 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

啟用和停用工作階段設定，並判斷是否可以用於電腦上的遠端或本機工作階段。此參數可接受的值為：

已停用。停用工作階段設定。它不能用於電腦的遠端或本機存取。
本機。可讓本機計算機的使用者使用會話設定，在同一部計算機上建立本機回送會話，但拒絕存取遠端使用者。
遠端。允許本機和遠端使用者使用工作階段設定，在此電腦上建立工作階段與執行命令。

預設值為 Remote。

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

此參數是在 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:	Nullable<T>[Double]
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-MaximumReceivedObjectSizeMB

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

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

Type:	Nullable<T>[Double]
Position:	Named
Default value:	10
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ModulesToImport

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

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

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

此參數是在 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

指定設定的 Security Descriptor Definition Language (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

-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

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

Unknown
MTA
STA

Type:	ApartmentState
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 僅適用於 Windows 平臺。

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

此 Cmdlet 會產生 XML，此 XML 代表管理 (WS-Management) 外掛程式元件元件組態，並將 XML 傳送至 WS-Management，這會在本機計算機上註冊外掛程式 (New-Item wsman:\localhost\plugin) 。

工作階段設定物件的屬性取決於工作階段設定所設定的選項，以及這些選項的值。此外，使用工作階段設定檔的工作階段設定會有額外的屬性。

共用方式為

Register-PSSessionConfiguration

Syntax

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

Syntax

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

輸入

輸出

備註

相關連結

其他資源