共用方式為


Register-PSSessionConfiguration

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

語法

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 Cmdlet 會在本機電腦上建立並註冊新的會話設定。 這是一個進階 Cmdlet,可用來為遠端使用者建立自定義會話。

每個 PowerShell 工作階段 (PSSession) 都會使用工作階段設定,也稱為端點。 當使用者建立連線到計算機的會話時,他們可以選取會話組態,或使用啟用PowerShell遠程時註冊的預設會話設定。 使用者也可以設定$PSSessionConfigurationName喜好設定變數,指定目前會話中建立之遠程會話的預設組態。

會話組態會定義遠程會話的環境。 組態可以判斷會話中可用的命令和語言元素,而且可以包含保護計算機的設定,例如限制會話可以在單一物件或命令中遠端接收的數據量。 會話組態的安全性描述元會決定哪些用戶有權使用會話設定。

您可以使用實作新組態類別的元件,以及使用在會話中執行的腳本,來定義組態的專案。 從 PowerShell 3.0 開始,您也可以使用工作階段組態檔來定義工作階段組態。

如需工作階段組態的相關信息,請參閱 about_Session_Configurations。 如需工作階段組態檔的相關資訊,請參閱 about_Session_Configuration_Files

範例

範例 1:註冊 NewShell 會話設定

在此範例中,我們會註冊 NewShell 會話組態。 AssemblyNameApplicationBase 參數會指定 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 物件。 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 中引進的。

參數屬性

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

參數集

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

-ApplicationBase

指定元件檔的路徑(*.dll),這個路徑指定於 AssemblyName 參數的值中。 當 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),請指定 AssemblyNameApplicationBase 參數。

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

如果您省略此參數,DefaultRemotePowerShellConfiguration 類別會用於會話組態。

參數屬性

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

參數集

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

-Confirm

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

參數屬性

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

參數集

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

-Force

隱藏所有使用者提示,並重新啟動 WinRM 服務,而不提示。 重新啟動服務會讓設定變更生效。

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

參數屬性

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

參數集

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

-MaximumReceivedDataSizePerCommandMB

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

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

參數屬性

類型:

Nullable<T>[Double]

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

參數集

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

-MaximumReceivedObjectSizeMB

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

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

參數屬性

類型:

Nullable<T>[Double]

預設值:10
支援萬用字元:False
不要顯示:False

參數集

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

-ModulesToImport

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

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

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

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

參數屬性

類型: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

判斷在使用此會話設定的會話中,是否啟動 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

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

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

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

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

您不能在相同的命令中使用 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

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

  • 未知
  • MTA
  • STA

參數屬性

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

參數集

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

-ThreadOptions

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

  • 預設
  • 重用線程
  • 使用當前線程
  • 使用新線程

預設值為 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 執行時會發生什麼事。 指令未執行。

參數屬性

類型: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。

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

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