Set-PSSessionConfiguration

參考

模組:: Microsoft.PowerShell.Core

變更已註冊會話組態的屬性。

語法

Set-PSSessionConfiguration
   [-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>]

Set-PSSessionConfiguration
   [-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>]

Set-PSSessionConfiguration
   [-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

Set-PSSessionConfiguration Cmdlet 會變更本機電腦上的會話設定屬性。

使用 Name 參數來識別您想要變更的工作階段組態。使用其他參數來指定會話組態屬性的新值。若要從組態中刪除屬性值，並使用預設值，請輸入空字串（“”）或對應參數的 $Null 值。

從 PowerShell 3.0 開始，您可以使用工作階段組態檔來定義工作階段組態。這項功能提供簡單且可探索的方法，可用來設定和變更使用會話設定的會話屬性。若要指定會話組態檔，請使用 Set-PSSessionConfiguration的 Path 參數。如需工作階段組態檔的相關信息，請參閱 about_Session_Configuration_Files。如需如何建立和修改會話組態檔的相關信息，請參閱 New-PSSessionConfigurationFile Cmdlet。

會話設定會定義連線到本機計算機的遠端會話環境（PSSessions）。每個 PSSession 都會使用會話設定。會話組態會決定 PSSession的功能，例如會話中可用的模組、允許執行的 Cmdlet、語言模式、配額和逾時。會話設定的安全性描述元會決定誰可以使用會話組態來連線到本機計算機。如需工作階段組態的詳細資訊，請參閱 about_Session_Configurations。

若要查看會話設定的屬性，請使用 Get-PSSessionConfiguration Cmdlet 或 WSMan 提供者。如需 WSMan 提供者的詳細資訊，請輸入 Get-Help WSMan。

範例

範例 1：變更線程 Apartment 狀態

PS C:\> Set-PSSessionConfiguration -Name "MaintenanceShell" -ThreadApartmentState STA

此命令會將 MaintenanceShell 組態中的線程 Apartment 狀態變更為 STA。當您重新啟動 WinRM 服務時，變更有效。

範例 2：建立和變更會話設定

此範例示範如何新增和移除組態中的啟動腳本。

第一個命令會建立 AdminShell 組態。第二個命令會將 AdminConfig.ps1 腳本新增至組態。當您重新啟動 WinRM時，變更有效。第三個命令會從組態中移除 AdminConfig.ps1 腳本。

Register-PSSessionConfiguration -Name "AdminShell" -AssemblyName "C:\Shells\AdminShell.dll" -ConfigurationTypeName "AdminClass"
Set-PSSessionConfiguration -Name "AdminShell" -StartupScript "AdminConfig.ps1"
Set-PSSessionConfiguration -Name "AdminShell" -StartupScript $Null

範例 3：顯示結果

本範例會將 MaximumReceivedObjectSizeMB 屬性的值增加到 20。此命令也會提示您重新啟動 WinRM 服務。在重新啟動 WinRM 服務之前，變更才會生效。

Set-PSSessionConfiguration -Name "IncObj" -MaximumReceivedObjectSizeMB 20

WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin\IncObj\InitializationParameters

ParamName                       ParamValue
---------                       ----------
psmaximumreceivedobjectsizemb   20

"Restart WinRM service"
WinRM service need to be restarted to make the changes effective. Do you want to run the command "restart-service winrm"?
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"): y

範例 4：以不同方式顯示結果

在這裡範例中，Set-PSSessionConfiguration 將 MaintenanceShell 中的啟動文稿 工作階段組態變更為 Maintenance.ps1。輸出會顯示變更，並提示您重新啟動 WinRM 服務。回應為「y」（是）。

Get-PSSessionConfiguration 取得 MaintenanceShell 工作階段組態。管線運算子（|）會將命令的結果傳送至 Format-List，這會在清單中顯示組態物件的所有屬性。接下來，使用 WSMan 提供者，我們檢視 MaintenanceShell 組態的初始化參數。 Get-ChildItem（別名 dir）會取得 MaintenanceShell 外掛程式之 InitializationParameters 節點中的子專案。如需 WSMan 提供者的詳細資訊，請輸入 Get-Help wsman。

PS> Set-PSSessionConfiguration -Name "MaintenanceShell" -StartupScript "C:\ps-test\Maintenance.ps1"

WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin\MaintenanceShell\InitializationParameters

ParamName            ParamValue
---------            ----------
startupscript        c:\ps-test\Mainte...

"Restart WinRM service"
WinRM service need to be restarted to make the changes effective. Do you want to run
the command "restart-service winrm"?
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"): y

PS> Get-PSSessionConfiguration MaintenanceShell | Format-List -Property *

xmlns            : https://schemas.microsoft.com/wbem/wsman/1/config/PluginConfiguration
Name             : MaintenanceShell
Filename         : %windir%\system32\pwrshplugin.dll
SDKVersion       : 1
XmlRenderingType : text
lang             : en-US
PSVersion        : 2.0
startupscript    : c:\ps-test\Maintenance.ps1
ResourceUri      : https://schemas.microsoft.com/powershell/MaintenanceShell
SupportsOptions  : true
ExactMatch       : true
Capability       : {Shell}
Permission       :

PS> dir WSMan:\localhost\Plugin\MaintenanceShell\InitializationParameters

ParamName     ParamValue
---------     ----------
PSVersion     2.0
startupscript c:\ps-test\Maintenance.ps1

參數

-AccessMode

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

禁用。停用會話設定。它無法用於電腦的遠端或本機存取。這個值會將會話組態的 Enabled 屬性設定（WSMan:\<ComputerName>\PlugIn\<SessionConfigurationName>\Enabled）設定為 False。
當地。將 Network_Deny_All 專案新增至會話設定的安全性描述元。本機計算機的使用者可以使用會話設定，在同一部計算機上建立本機回送會話，但遠端使用者遭到拒絕存取。
遠端。從會話組態的安全性描述項中移除 Deny_All 和 Network_Deny_All 專案。本機和遠端電腦的使用者可以使用會話設定來建立會話，並在這部計算機上執行命令。

預設值為 Remote。

其他 Cmdlet 稍後可以覆寫此參數的值。例如，Enable-PSRemoting Cmdlet 會啟用電腦上的所有會話設定，並允許遠端訪問它們，而 Disable-PSRemoting Cmdlet 只允許本機存取電腦上的所有會話設定。

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

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

-ApplicationBase

指定元件檔的路徑（*.dll），這個路徑指定於 AssemblyName 參數的值中。

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

-AssemblyName

指定元件名稱。此 Cmdlet 會根據元件中定義的類別來建立會話組態。

輸入定義會話組態之元件 .dll 檔名或完整路徑。如果您只輸入檔名，您可以在 applicationBase 參數的值中輸入路徑。

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

-ConfigurationTypeName

指定 AssemblyName 參數中元件中定義的會話組態類型。您指定的類型必須實作 System.Management.Automation.Remoting.PSSessionConfiguration 類別。

當您指定元件名稱時，需要此參數。

類型:	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 參數中指定的組態類型中定義數據大小限制，則會使用組態類型的限制。這個參數的值會被忽略。

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

-MaximumReceivedObjectSizeMB

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

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

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

-ModulesToImport

指定自動匯入會話組態的模組和嵌入式管理單元。輸入模組和嵌入式管理單元名稱。

根據預設，只有 Microsoft.PowerShell.Core 嵌入式管理單元會匯入會話，但除非排除 Cmdlet，否則您可以使用 Import-Module 和 Add-PSSnapin Cmdlet 將模組和嵌入式管理單元新增至會話。

除了工作階段組態檔中指定的模組之外，這個參數值中指定的模組也會匯入（New-PSSessionConfigurationFile）。不過，會話組態檔中的設定可以隱藏模組導出的命令，或防止使用者使用它們。

此參數值中指定的模組會使用 Register-PSSessionConfiguration Cmdlet 的 ModulesToImport 參數來取代指定的模組清單。

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

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

-Name

指定您想要變更的工作階段組態名稱。

您無法使用此參數來變更工作階段組態的名稱。

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

-NoServiceRestart

不會重新啟動 WinRM 服務，並隱藏重新啟動服務的提示。

根據預設，當您執行 Set-PSSessionConfiguration時，系統會提示您重新啟動 WinRM 服務，讓新的會話設定生效。在重新啟動 WinRM 服務之前，新的工作階段設定無效。

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

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

-Path

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

如需如何修改會話組態檔的資訊，請參閱 New-PSSessionConfigurationFile Cmdlet 的說明主題。

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

類型:	String
Position:	Named
預設值:	None
必要:	True
接受管線輸入:	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）字串。

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

若要使用組態的預設安全性描述元，請輸入空字串（“”）或 $Null的值。預設值是 WSMan：磁碟驅動器中的根 SDDL。

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

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

-SessionTypeOption

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

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

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

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

-ShowSecurityDescriptorUI

指出這個 Cmdlet 是一個屬性表，可協助您為工作階段設定建立新的 SDDL。屬性表會出現在執行 Set-PSSessionConfiguration 命令之後，然後重新啟動 WinRM 服務。

當您將許可權設定為組態時，請記住使用者至少必須具有Execute（Invoke）許可權，才能在會話中使用會話組態。

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

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

-StartupScript

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

若要從會話組態中刪除啟動腳本，請輸入空字串串（“”）或 $Null的值。

您可以使用啟動文稿進一步設定使用者工作階段。如果腳本產生錯誤，即使是非終止錯誤，也不會建立會話，且 New-PSSession 命令失敗。

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

-ThreadApartmentState

指定工作階段中線程的 Apartment 狀態設定。此參數可接受的值為：STA、MTA 和 Unknown。預設值為 Unknown。

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

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

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

輸出

WSManConfigLeafElement

備註

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

Set-PSSessionConfiguration Cmdlet 不會變更組態名稱，而且 WSMan 提供者不支援 Rename-Item Cmdlet。若要變更會話組態的名稱，請使用 Unregister-PSSessionConfiguration Cmdlet 來刪除組態，然後使用 Register-PSSessionConfiguration Cmdlet 來建立及註冊新的會話組態。

您可以使用 Set-PSSessionConfiguration Cmdlet 來變更預設的 Microsoft.PowerShell 和 Microsoft.PowerShell32 會話組態。它們不受保護。若要還原為預設會話組態的原始版本，請使用 Unregister-PSSessionConfiguration Cmdlet 來刪除預設會話組態，然後使用 Enable-PSRemoting Cmdlet 還原它。

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

您可以使用 WSMan：磁碟驅動器中的命令來變更工作階段組態的屬性。不過，您無法使用 PowerShell 2.0 中的 WSMan：磁碟驅動器來變更 PowerShell 3.0 中引進的工作階段設定屬性，例如 OutputBufferingMode。 Windows PowerShell 2.0 命令不會產生錯誤，但它們無效。若要變更 PowerShell 3.0 中引進的屬性，請使用 PowerShell 3.0 中的 WSMan：磁碟驅動器。

共用方式為

Set-PSSessionConfiguration

語法

Description

範例

範例 1：變更線程 Apartment 狀態

範例 2：建立和變更會話設定

範例 3：顯示結果

範例 4：以不同方式顯示結果

參數

-AccessMode

-ApplicationBase

-AssemblyName

-ConfigurationTypeName

-Confirm

-Force

-MaximumReceivedDataSizePerCommandMB

-MaximumReceivedObjectSizeMB

-ModulesToImport

-Name

-NoServiceRestart

-Path

-PSVersion

-RunAsCredential

-SecurityDescriptorSddl

-SessionTypeOption

-ShowSecurityDescriptorUI

-StartupScript

-ThreadApartmentState

-ThreadOptions

-TransportOption

-UseSharedProcess

-WhatIf

輸入

輸出

備註

其他資源

共用方式為

Set-PSSessionConfiguration

語法

Description

範例

範例 1：變更線程 Apartment 狀態

範例 2：建立和變更會話設定

範例 3：顯示結果

範例 4：以不同方式顯示結果

參數

-AccessMode

-ApplicationBase

-AssemblyName

-ConfigurationTypeName

-Confirm

-Force

-MaximumReceivedDataSizePerCommandMB

-MaximumReceivedObjectSizeMB

-ModulesToImport

-Name

-NoServiceRestart

-Path

-PSVersion

-RunAsCredential

-SecurityDescriptorSddl

-SessionTypeOption

-ShowSecurityDescriptorUI

-StartupScript

-ThreadApartmentState

-ThreadOptions

-TransportOption

-UseSharedProcess

-WhatIf

輸入

輸出

備註

相關連結

其他資源