Set-PSSessionConfiguration

Artikel
10/30/2009

Ändert die Eigenschaften einer registrierten Sitzungskonfiguration.

Syntax

Set-PSSessionConfiguration [-AssemblyName] <string> [-ConfigurationTypeName] <string> [-Name] <string> [-ApplicationBase <string>] [-Force] [-MaximumReceivedDataSizePerCommandMB <double>] [-MaximumReceivedObjectSizeMB <double>] [-NoServiceRestart] [-SecurityDescriptorSDDL <string>] [-ShowSecurityDescriptorUI] [-StartupScript <string>] [-ThreadApartmentState {<STA> | <MTA> | <Unknown>}] [-ThreadOptions {<Default> | <UseNewThread> | <ReuseThread> | <UseCurrentThread>}] [-Confirm] [-WhatIf] [<CommonParameters>]

Beschreibung

Das Cmdlet "Set-PSSessionConfiguration" ändert die Eigenschaften der registrierten Sitzungskonfigurationen auf dem lokalen Computer. Dieses erweiterte Cmdlet wurde für Systemadministratoren entwickelt, die damit benutzerdefinierte Sitzungskonfigurationen für ihre Benutzer verwalten können.

Identifizieren Sie die Konfiguration, die Sie ändern möchten, mithilfe des Name-Parameters. Verwenden Sie die anderen Parameter, um neue Werte für die Eigenschaften der Sitzungskonfiguration anzugeben. Um einen Eigenschaftenwert aus der Konfiguration zu löschen (und den Standardwert zu verwenden), geben Sie eine leere Zeichenfolge ("") oder den Wert "$null" für den entsprechenden Parameter ein.

Um die Eigenschaften einer Sitzungskonfiguration anzuzeigen, verwenden Sie das Cmdlet "Get-PSSessionConfiguration" oder den WS-Verwaltungsanbieter. Um weitere Informationen zum WS-Verwaltungsanbieter zu erhalten, geben Sie "Get-Help wsman" ein.

Parameter

-ApplicationBase <string>

Ändert den Pfad zur Assemblydatei (*.dll), die im Wert des AssemblyName-Parameters angegeben ist.

Erforderlich?	false
Position?	named
Standardwert
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-AssemblyName <string>

Gibt eine andere Assemblydatei für die Konfiguration an. Geben Sie den Pfad (optional) und den Dateinamen einer Assemblydatei (.dll) ein, die den Konfigurationstyp definiert.

Wenn Sie nur den Namen eingeben, können Sie den Pfad im Wert des ApplicationBase-Parameters eingeben.

Erforderlich?	true
Position?	2
Standardwert
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-ConfigurationTypeName <string>

Gibt einen anderen Konfigurationstyp für die Konfiguration an. Der angegebene Typ muss die System.Management.Automation.Remoting.PSSessionConfiguration-Klasse implementieren.

Wenn Sie "$null" oder eine leere Zeichenfolge eingeben, wird die DefaultRemotePowerShellConfiguration-Klasse für die Sitzungskonfiguration verwendet.

Erforderlich?	true
Position?	3
Standardwert
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-Force

Unterdrückt alle Benutzeraufforderungen und startet den WinRM-Dienst ohne Aufforderung neu. Durch erneutes Starten des Diensts wird die Konfigurationsänderung wirksam.

Verwenden Sie den NoServiceRestart-Parameter, um einen Neustart zu verhindern und die Aufforderung zum Neustart zu unterdrücken.

Erforderlich?	false
Position?	named
Standardwert
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-MaximumReceivedDataSizePerCommandMB <double>

Ändert die Beschränkung der Datenmenge, die in jedem einzelnen Remotebefehl an diesen Computer gesendet werden kann. Geben Sie die Datengröße in Megabytes (MB) ein. Der Standardwert ist 50 MB.

Wenn eine Datengrößenbeschränkung im Konfigurationstyp definiert wird, der im ConfigurationTypeName-Parameter angegeben ist, wird der Grenzwert im Konfigurationstyp verwendet und der Wert dieses Parameters ignoriert.

Erforderlich?	false
Position?	named
Standardwert	50
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-MaximumReceivedObjectSizeMB <double>

Ändert die Beschränkungen der Datenmenge, die in jedem einzelnen Objekt an diesen Computer gesendet werden kann. Geben Sie die Datengröße in Megabytes (MB) ein. Der Standardwert ist 10 MB.

Wenn eine Objektgrößenbeschränkung im Konfigurationstyp definiert wird, der im ConfigurationTypeName-Parameter angegeben ist, wird der Grenzwert im Konfigurationstyp verwendet und der Wert dieses Parameters ignoriert.

Erforderlich?	false
Position?	named
Standardwert	10
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-Name <string>

Gibt den Namen der Sitzungskonfiguration an, die Sie ändern möchten.

Sie können den Namen der Sitzungskonfiguration nicht mithilfe dieses Parameters ändern.

Erforderlich?	true
Position?	1
Standardwert
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-NoServiceRestart

Startet den WinRM-Dienst nicht neu und unterdrückt die Aufforderung zum erneuten Starten des Diensts.

Wenn Sie einen Set-PSSessionConfiguration-Befehl eingeben, werden Sie standardmäßig aufgefordert, den WinRM-Dienst neu zu starten, damit die neue Sitzungskonfiguration wirksam wird. Die neue Sitzungskonfiguration wird erst mit dem Neustart des WinRM-Diensts wirksam.

Verwenden Sie den Force-Parameter, um den WinRM-Dienst ohne Aufforderung neu zu starten. Verwenden Sie das Cmdlet "Restart-Service", um den WinRM-Dienst manuell neu zu starten.

Erforderlich?	false
Position?	named
Standardwert
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-SecurityDescriptorSDDL <string>

Gibt eine andere SDDL (Security Descriptor Definition Language)-Zeichenfolge für die Konfiguration an.

Diese Zeichenfolge bestimmt die Berechtigungen, die zur Verwendung der neuen Sitzungskonfiguration erforderlich sind. Um in einer Sitzung eine Sitzungskonfiguration zu verwenden, müssen Benutzer mindestens über die Berechtigung "Execute(Invoke)" für die Konfiguration verfügen.

Um die Standardsicherheitsbeschreibung für die Konfiguration zu verwenden, geben Sie eine leere Zeichenfolge ("") oder den Wert "$null" ein. Der Standardwert ist die Stamm-SDDL im Laufwerk "WSMan:".

Wenn die Sicherheitsbeschreibung komplex ist, sollten Sie erwägen, anstelle dieses Parameters den ShowSecurityDescriptorUI-Parameter zu verwenden. Die beiden Parameter können nicht zusammen im selben Befehl verwendet werden.

Erforderlich?	false
Position?	named
Standardwert
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-ShowSecurityDescriptorUI

Zeigt ein Eigenschaftenblatt an, das Sie bei der Erstellung einer neuen SDDL für die Sitzungskonfiguration unterstützt. Das Eigenschaftenblatt wird angezeigt, nachdem Sie den Set-PSSessionConfiguration-Befehl eingegeben und den WinRM-Dienst neu gestartet haben.

Beachten Sie beim Festlegen der Berechtigungen für die Konfiguration, dass Benutzer mindestens die Berechtigung "Execute(Invoke)" benötigen, um die Sitzungskonfiguration in einer Sitzung zu verwenden.

Sie können den SecurityDescriptorSDDL-Parameter und diesen Parameter nicht im gleichen Befehl verwenden.

Erforderlich?	false
Position?	named
Standardwert
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-StartupScript <string>

Fügt das Startskript für die Konfiguration hinzu oder ändert es. Geben Sie den vollqualifizierten Pfad zu einem Windows PowerShell-Skript ein. Das angegebene Skript wird in der neuen Sitzung ausgeführt, die die Sitzungskonfiguration verwendet.

Um ein Startskript aus einer Sitzungskonfiguration zu löschen, geben Sie eine leere Zeichenfolge ("") oder den Wert "$null" ein.

Sie können die Benutzersitzung mithilfe eines Startskripts weiter konfigurieren. Wenn das Skript einen Fehler (sogar einen Fehler ohne Abbruch) generiert, wird die Sitzung nicht erstellt, und der New-PSSession-Befehl des Benutzers führt zu einem Fehler.

Erforderlich?	false
Position?	named
Standardwert
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-ThreadApartmentState <ApartmentState>

Ändert die Apartmentzustandeinstellung für die in der Sitzung enthaltenen Threads. Gültige Werte sind "STA", "MTA" und "Unknown". Der Standardwert ist "Unknown".

Erforderlich?	false
Position?	named
Standardwert	ApartmentState.Unknown
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-ThreadOptions <PSThreadOptions>

Ändert die Einstellung für Threadoptionen in der Konfiguration. Diese Einstellung legt fest, wie Threads erstellt und beim Ausführen eines Befehls in der Sitzung verwendet werden. Gültige Werte sind "Default", "ReuseThread", "UseCurrentThread" und "UseNewThread". Der Standardwert ist "UseCurrentThread".

Erforderlich?	false
Position?	named
Standardwert	PSThreadOptions.UserCurrentThread
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-Confirm

Fordert Sie vor der Ausführung des Befehls zur Bestätigung auf.

Erforderlich?	false
Position?	named
Standardwert
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

-WhatIf

Beschreibt die Auswirkungen einer Ausführung des Befehls, ohne den Befehl tatsächlich auszuführen.

Erforderlich?	false
Position?	named
Standardwert
Pipelineeingaben akzeptieren?	false
Platzhalterzeichen akzeptieren?	false

<CommonParameters>

Dieses Cmdlet unterstützt die folgenden allgemeinen Parameter: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer und -OutVariable. Weitere Informationen finden Sie unter about_Commonparameters.

Eingaben und Ausgaben

Der Eingabetyp ist der Typ der Objekte, die über die Pipeline an das Cmdlet übergeben werden können. Der Rückgabetyp ist der Typ der Objekte, die das Cmdlet zurückgibt.

Eingaben

Keiner

Eingaben können nicht über die Pipeline an dieses Cmdlet übergeben werden.

Ausgaben

Microsoft.WSMan.Management.WSManConfigLeafElement

Hinweise

Sie müssen Windows PowerShell mit der Option "Als Administrator ausführen" öffnen, um dieses Cmdlet unter Windows Vista, Windows Server 2008 und höheren Versionen von Windows auszuführen.

Das Cmdlet "Set-PSSessionConfiguration" ändert den Konfigurationsnamen nicht, und der WS-Verwaltungsanbieter bietet keine Unterstützung für das Cmdlet "Rename-Item". Um den Namen einer Konfiguration zu ändern, verwenden Sie das Cmdlet "Unregister-PSSessionConfiguration" zum Löschen der Konfiguration und dann das Cmdlet "Register-PSSessionConfiguration" zum Erstellen und Registrieren einer neuen Sitzungskonfiguration.

Sie können das Cmdlet "Set-PSSessionConfiguration" verwenden, um die Microsoft.PowerShell- und Microsoft.PowerShell32-Standardsitzungskonfiguration zu ändern. Diese sind nicht geschützt. Um die Originalversion einer Standardsitzungskonfiguration wiederherzustellen, verwenden Sie das Cmdlet "Unregister-PSSessionConfiguration" zum Löschen der Standardsitzungskonfiguration und dann das Cmdlet "Enable-PSRemoting" zur Wiederherstellung.

Beispiel 1

C:\PS>set-pssessionconfiguration -name MaintenanceShell -threadApartmentState STA

Beschreibung
-----------
Mit diesem Befehl wird der Threadapartmentzustand in der MaintenanceShell-Konfiguration in STA geändert. Die Änderung wird mit dem Neustart des WinRM-Diensts wirksam.

Beispiel 2

C:\PS>register-pssessionconfiguration -name AdminShell -assemblyName c:\shells\AdminShell.dll -configurationType AdminClass

C:\PS> set-pssessionconfiguration -name AdminShell -startupScript AdminConfig.ps1

C:\PS> set-pssessionconfiguration -name AdminShell -startupScript $null

Beschreibung
-----------
Dieses Beispiel zeigt, wie Sie eine Sitzungskonfiguration erstellen und dann ändern.

Der erste Befehl erstellt mit dem Cmdlet "Register-PSSessionConfiguration" die AdminShell-Konfiguration. 

Im zweiten Befehl wird der Konfiguration mit dem Cmdlet "Set-PSSessionConfiguration" das Skript "AdminConfig.ps1" hinzugefügt. Die Änderung wird mit dem Neustart von WinRM wirksam.

Mit dem dritten Befehl wird das Skript "AdminConfig.ps1" aus der Konfiguration entfernt. Er verwendet das Cmdlet "Set-PSSessionConfiguration" mit dem Wert "$null" für den StartupScript-Parameter.

Beispiel 3

C:\PS>Set-PSSessionConfiguration -name foo -MaximumReceivedObjectSizeMB 20

   WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin\foo\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

Beschreibung
-----------
Dieses Beispiel enthält eine Beispielausgabe des Cmdlets "Set-PSSessionConfiguration". 

Mit dem Befehl "Set-PSSessionConfiguration" in diesem Beispiel wird der Wert der MaximumReceivedObjectSizeMB-Eigenschaft auf 20 erhöht. 

Der Befehl "Set-PSSessionConfiguration" gibt ein Microsoft.WSMan.Management.WSManConfigLeafElement-Objekt zurück, das den Parameternamen und neuen Wert anzeigt.

Außerdem werden Sie aufgefordert, den WinRM-Dienst neu zu starten. Die Set-PSSessionConfiguration-Änderung ist erst wirksam, wenn der WinRM-Dienst neu gestartet wird.

Beispiel 4

C:\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


C:\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       :


C:\PS> dir wsman:\localhost\plugin\MaintenanceShell\InitializationParameters

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

Beschreibung
-----------
Mit diesem Befehl werden andere Methoden zum Anzeigen der Ergebnisse eines Set-PSSessionConfiguration-Befehls veranschaulicht.

Mit dem ersten Befehl wird das Cmdlet "Set-PSSessionConfiguration" verwendet, um das Startskript in der MaintenanceShell-Konfiguration in "Maintenance.ps1" zu ändern. Die Ausgabe dieses Befehls zeigt die Änderung an und fordert Sie auf, den WinRM-Dienst neu zu starten. Die Antwort ist "J" (Ja).

Der zweite Befehl verwendet das Cmdlet "Get-PSSessionConfiguration", um die MaintenanceShell-Sitzungskonfiguration abzurufen. Der Befehl verwendet einen Pipelineoperator (|), um die Ergebnisse des Befehls an das Cmdlet "Format-List" zu senden, das alle Eigenschaften des Sitzungskonfigurationsobjekts in einer Liste anzeigt.

Der dritte Befehl verwendet den WS-Verwaltungsanbieter, um die Initialisierungsparameter für die MaintenanceShell-Konfiguration anzuzeigen. Der Befehl verwendet das Cmdlet "Get-ChildItem" (alias = dir), um die untergeordneten Elemente im InitializationParameters-Knoten für das MaintenanceShell-Plug-In abzurufen.

Um weitere Informationen zum WS-Verwaltungsanbieter zu erhalten, geben Sie "get-help wsman" ein.

Siehe auch

Konzepte

about_Session_Configurations
Disable-PSSessionConfiguration
Enable-PSSessionConfiguration
Get-PSSessionConfiguration
Register-PSSessionConfiguration
Unregister-PSSessionConfiguration
WSMan Provider

Freigeben über