Erstellt und registriert eine neue Sitzungskonfiguration. (Register-PSSessionConfiguration)
NAMERegister-PSSessionConfigurationÜBERSICHTErstellt und registriert eine neue Sitzungskonfiguration.SYNTAXRegister-PSSessionConfiguration [-AssemblyName] <string> [-ConfigurationTypeName] <string> [-ApplicationBase <string>] [-Name] <string> [-Force] [-MaximumReceivedDataSizePerCommandMB <double>] [-MaximumReceivedObjectSizeMB <double>] [-NoServiceRestart] [-ProcessorArchitecture <string>] [-SecurityDescriptorSDDL <string>] [-ShowSecurityDescriptorUI] [-StartupScript <string>] [-ThreadApartmentState {STA | MTA | Unknown}] [-ThreadOptions {Default | UseNewThread | ReuseThread | UseCurrentThread}] [-Confirm] [-WhatIf] [<CommonParameters>]BESCHREIBUNGUm eine neue Sitzungskonfiguration auf dem lokalen Computer zu erstellen und zu registrieren, verwenden Sie das Cmdlet "Register-PSSessionConfiguration". Dieses erweiterte Cmdlet wurde für Systemadministratoren entwickelt, die damit benutzerdefinierte Sitzungskonfigurationen für ihre Benutzer verwalten können. Bei jeder Windows PowerShell-Remotesitzung wird eine Sitzungskonfiguration verwendet. Wenn Benutzer eine Sitzung erstellen, die eine Verbindung mit dem Computer herstellt, können sie eine Konfiguration auswählen oder die Standardkonfigurationen verwenden, die beim Aktivieren von Windows PowerShell-Remoting registriert werden. Benutzer können auch die Einstellungsvariable "$PSSessionConfigurationName" festlegen, die eine Standardkonfiguration für die in der aktuellen Sitzung erstellten Sitzungen angibt. Die Sitzungskonfiguration konfiguriert die Umgebung für die Sitzung. Sie können die Konfiguration mit einer Assembly definieren, die eine neue Konfigurationsklasse implementiert, und mit einem Skript, das in der Sitzung ausgeführt wird. Mit der Konfiguration können die Befehle bestimmt werden, die in der Sitzung verfügbar sind. Außerdem kann die Konfiguration Einstellungen enthalten, die den Computer schützen, beispielsweise Einstellungen, die die Datenmenge begrenzen, die von der Sitzung in einem einzelnen Objekt oder einem einzelnen Befehl remote empfangen werden können. Sie können auch eine Sicherheitsbeschreibung angeben, die die Berechtigungen bestimmt, die erforderlich sind, um die Konfiguration zu verwenden.PARAMETER-ApplicationBase <string> Gibt den Pfad zur Assemblydatei (*.dll) an, die im Wert des AssemblyName-Parameters angegeben ist. Verwenden Sie diesen Parameter, wenn der Wert des AssemblyName-Parameters keinen Pfad enthält. Der Standardwert ist das aktuelle Verzeichnis. Erforderlich? false Position? named Standardwert Aktuelles Verzeichnis Pipelineeingaben akzeptieren?false Platzhalterzeichen akzeptieren?false -AssemblyName <string> Gibt den Namen einer Assemblydatei (* .dll) an, in der der Konfigurationstyp definiert wird. Sie können den Pfad zur DLL in diesem Parameter oder im Wert des ApplicationBase-Parameters angeben. Dieser Parameter ist erforderlich, wenn der ConfigurationTypeName-Parameter angegeben wird. Erforderlich? true Position? 2 Standardwert Keiner Pipelineeingaben akzeptieren?false Platzhalterzeichen akzeptieren?false -ConfigurationTypeName <string> Gibt den vollqualifizierten Namen des Microsoft .NET Framework-Typs an, der für diese Konfiguration verwendet wird. Der angegebene Typ muss die System.Management.Automation.Remoting.PSSessionConfiguration-Klasse implementieren. Um die Assemblydatei (.dll) anzugeben, die den Konfigurationstyp implementiert, verwenden Sie den AssemblyName-Parameter und den AssemblyBase-Parameter. Durch die Typerstellung können Sie mehr Aspekte der Sitzungskonfiguration steuern, z. B. das Verfügbarmachen oder Ausblenden bestimmter Cmdletparameter oder das Festlegen von Größenbeschränkungen für Daten und Objekte, die von den Benutzern nicht überschrieben werden können. Wenn Sie diesen Parameter nicht angeben, wird die DefaultRemotePowerShellConfiguration-Klasse für die Sitzungskonfiguration verwendet. Erforderlich? true Position? 3 Standardwert System.Management.Automation.Remoting.PSSessionConfiguration Pipelineeingaben akzeptieren?false Platzhalterzeichen akzeptieren?false -Force [<SwitchParameter>] 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> Schränkt die Datenmenge ein, 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> Schränkt die Datenmenge ein, 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 einen Namen für die Sitzungskonfiguration an. Dieser Parameter ist erforderlich. Erforderlich? true Position? 1 Standardwert Keiner Pipelineeingaben akzeptieren?false Platzhalterzeichen akzeptieren?false -NoServiceRestart [<SwitchParameter>] Startet den WinRM-Dienst nicht neu und unterdrückt die Aufforderung zum erneuten Starten des Diensts. Wenn Sie einen Register-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 False Pipelineeingaben akzeptieren?false Platzhalterzeichen akzeptieren?false -ProcessorArchitecture <string> Gibt eine Prozessorarchitektur für die Konfiguration an. Dieser Wert bestimmt, ob bei Verwendung der Konfiguration eine 32-Bit- oder 64-Bit-Version des Prozesses, der Windows PowerShell hostet, gestartet wird. Gültige Werte sind "x86", "AMD64" und "IA64". Der Standardwert wird von der Prozessorarchitektur des Computers bestimmt, der die Sitzungskonfiguration hostet. Erforderlich? false Position? named Standardwert Die Prozessorarchitektur des Hostcomputers. Pipelineeingaben akzeptieren?false Platzhalterzeichen akzeptieren?false -SecurityDescriptorSDDL <string> Gibt eine 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. 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. Wenn Sie diesen Parameter nicht angeben, wird die Stamm-SDDL für den WinRM-Dienst für diese Konfiguration verwendet. Um die Stamm-SDDL anzuzeigen oder zu ändern, verwenden Sie den WS-Verwaltungsanbieter. Beispielsweise "get-item wsman:\localhost\service\rootSDDL". Um weitere Informationen zum WS-Verwaltungsanbieter zu erhalten, geben Sie "get-help wsman" ein. Erforderlich? false Position? named Standardwert Der Wert der Stamm-SDDL. Pipelineeingaben akzeptieren?false Platzhalterzeichen akzeptieren?false -ShowSecurityDescriptorUI [<SwitchParameter>] Zeigt ein Eigenschaftenblatt an, das Sie bei der Erstellung der SDDL für die Sitzungskonfiguration unterstützt. Das Eigenschaftenblatt wird angezeigt, nachdem Sie den Register-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> Gibt den vollqualifizierten Pfad zu einem Windows PowerShell-Skript an. Das angegebene Skript wird in der neuen Sitzung ausgeführt, die die Sitzungskonfiguration verwendet. Sie können die Sitzung mithilfe des Skripts 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> Bestimmt den Apartmentzustand der Threads in der Sitzung. Gültige Werte sind "STA", "MTA" und "Unknown". Der Standardwert ist "Unknown". Erforderlich? false Position? named Standardwert Unknown Pipelineeingaben akzeptieren?false Platzhalterzeichen akzeptieren?false -ThreadOptions <PSThreadOptions> 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 UseCurrentThread Pipelineeingaben akzeptieren?false Platzhalterzeichen akzeptieren?false -Confirm [<SwitchParameter>] Fordert Sie vor der Ausführung des Befehls zur Bestätigung auf. Erforderlich? false Position? named Standardwert Pipelineeingaben akzeptieren?false Platzhalterzeichen akzeptieren?false -WhatIf [<SwitchParameter>] 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 folgende allgemeine Parameter: "Verbose", "Debug", "ErrorAction", "ErrorVariable", "WarningAction", "WarningVariable", "OutBuffer" und "OutVariable". Weitere Informationen erhalten Sie mit dem Befehl "get-help about_commonparameters".EINGABENKeiner Eingaben können nicht über die Pipeline an dieses Cmdlet übergeben werden.AUSGABENMicrosoft.WSMan.Management.WSManConfigContainerElementHINWEISESie müssen Windows PowerShell mit der Option "Als Administrator ausführen" starten, um dieses Cmdlet unter Windows Vista, Windows Server 2008 und höheren Versionen von Windows auszuführen. Dieses Cmdlet generiert XML, die die Konfiguration eines WS-Verwaltung-Plug-Ins (Web Services for Management) darstellt, und sendet die XML an die WS-Verwaltung. Dort wird das Plug-In auf dem lokalen Computer ("new-item wsman:\localhost\plugin") registriert.Beispiele
BEISPIEL 1C:\PS>register-pssessionConfiguration -name NewShell -applicationBase c:\MyShells\ -assemblyName MyShell.dll -configurationTypeName MyClass Beschreibung ----------- Mit diesem Befehl wird die NewShell-Sitzungskonfiguration registriert. Er verwendet den ApplicationName-Parameter und den ApplicationBase-Parameter, um den Speicherort der Datei "MyShell.dll" anzugeben, die die Cmdlets und Anbieter in der Sitzungskonfiguration festlegt. Darüber hinaus verwendet er den ConfigurationTypeName-Parameter, um eine neue Klasse zur weiteren Konfiguration der Sitzung anzugeben. Um diese Konfiguration zu verwenden, würden Benutzer "new-pssession -configurationname newshell" eingeben.BEISPIEL 2C:\PS>register-pssessionConfiguration -name MaintenanceShell -startupScript c:\ps-test\Maintenance.ps1 Beschreibung ----------- Mit diesem Befehl wird die MaintenanceShell-Konfiguration auf dem lokalen Computer registriert. Der Befehl gibt das Skript "Maintenance.ps1" mithilfe des StartupScript-Parameters an. Wenn ein Benutzer einen New-PSSession-Befehl verwendet und die MaintenanceShell-Konfiguration auswählt, wird das Skript "Maintenance.ps1" in der neuen Sitzung ausgeführt. Das Skript ist in der Lage, die Sitzung zu konfigurieren, z. B. Module zu importieren, Windows PowerShell-Snap-Ins hinzuzufügen und die Ausführungsrichtlinie für die Sitzung festzulegen. Wenn das Skript Fehler generiert, einschließlich Fehler ohne Abbruch, führt der New-PSSession-Befehl zu einem Fehler.BEISPIEL 3C:\PS>$sddl = "O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;FA;GA;;;WD)(AU;FA;SA;GWGX;;WD)" C:\PS> register-pssessionconfiguration -name AdminShell -securityDescriptorSDDL $sddl -maximumReceivedObjectSizeMB 20 -startupScript c:\scripts\AdminShell.ps1 Beschreibung ----------- In diesem Beispiel wird die AdminShell-Sitzungskonfiguration registriert. Der erste Befehl speichert eine benutzerdefinierte SDDL in der Variablen "$sddl". Mit dem zweiten Befehl wird die neue Shell registriert. Der Befehl gibt die SDDL im Wert der Variablen "$sddl" und den MaximumReceivedObjectSizeMB-Parameter zur Erweiterung der Objektgrößenbeschränkung mithilfe des SecurityDescritorSDDL-Parameters an. Darüber hinaus gibt er mithilfe des StartupScript-Parameters ein Skript an, das die Sitzung konfiguriert. Als Alternative zum SecurityDescriptorSDDL-Parameter können Sie den ShowSecurityDescriptorUI-Parameter verwenden, der ein Eigenschaftenblatt anzeigt, mit dem Sie Berechtigungen für die Sitzungskonfiguration festlegen können. Wenn Sie im Eigenschaftenblatt auf "OK" klicken, generiert das Tool eine SDDL für die Sitzungskonfiguration.BEISPIEL 4C:\PS>$s = register-pssessionConfiguration -name MaintenanceShell -startupScript c:\ps-test\Maintenance.ps1 C:\PS> $s WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin Name Type Keys ---- ---- ---- MaintenanceShell Container {Name=MaintenanceShell} C:\PS> $s.getType().fullname TypeName: Microsoft.WSMan.Management.WSManConfigContainerElement C:\PS> $s | format-list -property * 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 C:\PS> dir wsman:\localhost\plugin Name Type Keys ---- ---- ---- MaintenanceShell Container {Name=MaintenanceShell} microsoft.powershell Container {Name=microsoft.powershell} microsoft.powershell32 Container {Name=microsoft.powershell32} Beschreibung ----------- Dieses Beispiel zeigt, dass ein Register-PSSessionConfiguration-Befehl ein WSManConfigContainerElement zurückgibt. Es veranschaulicht außerdem, wie Sie die Containerelemente im Laufwerk "WSMan:" finden. Der erste Befehl verwendet das Cmdlet "Register-PSSessionConfiguration", um die MaintenanceShell-Konfiguration zu registrieren. Das vom Cmdlet zurückgegebene Objekt wird in der Variablen "$j" gespeichert. Der zweite Befehl zeigt den Inhalt der Variablen "$s" an. Der dritte Befehl zeigt den Typnamen des Objekts, das von Register-PSSessionConfiguration zurückgegeben wird, mithilfe der GetType-Methode und ihrer FullName-Eigenschaft an. Der vierte Befehl verwendet das Cmdlet "Format-List", um alle Eigenschaften des Objekts anzuzeigen, die von Register-PSSessionConfiguration in einer Liste zurückgegeben werden. Die PSPath-Eigenschaft zeigt, dass das Objekt in einem Verzeichnis des Laufwerks "WSMan:" gespeichert wird. Der fünfte Befehl verwendet das Cmdlet "Get-ChildItem", um die Elemente im Pfad "WSMan:\LocalHost\PlugIn" anzuzeigen. Diese schließen die neue MaintenanceShell-Konfiguration und die beiden Standardkonfigurationen ein, die mit Windows PowerShell ausgeliefert werden.BEISPIEL 5C:\PS>register-pssessionconfiguration -name WithProfile -startupScript add-profile.ps1 # Add-Profile.ps1 . c:\users\admin01\documents\windowspowershell\profile.ps1 Beschreibung ----------- Mit diesem Befehl wird die WithProfile-Sitzungskonfiguration erstellt und auf dem lokalen Computer registriert. Der Befehl weist Windows PowerShell mit dem StartupScript-Parameter an, das angegebene Skript in einer beliebigen Sitzung auszuführen, die die Sitzungskonfiguration verwendet. Der Inhalt des angegebenen Skripts "Add-Profile.ps1" wird ebenfalls angezeigt. Das Skript enthält einen einzelnen Befehl, der die DOT-Quellentnahme verwendet, um das CurrentUserAllHosts-Profil des Benutzers im aktuellen Bereich der Sitzung auszuführen. Weitere Informationen über Profile finden Sie unter "about_Profiles". Weitere Informationen zur DOT-Quellentnahme finden Sie unter "about_Scopes". VERWANDTE LINKS Online version: http://go.microsoft.com/fwlink/?LinkID=144306 (möglicherweise auf Englisch) about_Session_Configurations Disable-PSSessionConfiguration Enable-PSSessionConfiguration Get-PSSessionConfiguration Set-PSSessionConfiguration Unregister-PSSessionConfiguration WS-Management Provider C:\Windows>powershell get-help Unregister-PSSessionConfiguration -full
Microsoft Windows [Version 10.0.19045.3693]
Copyright (c) 2023 Microsoft Corporation.
ColorConsole [Version 3.7.1000] PowerShell 2.0-Export
