Register-PSSessionConfiguration

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>]

Beschreibung

Dieses Cmdlet ist nur auf der Windows-Plattform verfügbar.

Das Register-PSSessionConfiguration Cmdlet erstellt und registriert eine neue Sitzungskonfiguration auf dem lokalen Computer. Dies ist ein erweitertes Cmdlet, mit dem Sie benutzerdefinierte Sitzungen für Remotebenutzer erstellen können.

Jede PowerShell-Sitzung (PSSession) verwendet eine Sitzungskonfiguration, auch als Endpunkt bezeichnet. Wenn Benutzer eine Sitzung erstellen, die eine Verbindung mit dem Computer herstellt, können sie eine Sitzungskonfiguration auswählen oder die Standardsitzungskonfiguration verwenden, die beim Aktivieren von PowerShell-Remoting registriert ist. Benutzer können auch die $PSSessionConfigurationName Einstellungsvariable festlegen, die eine Standardkonfiguration für Remotesitzungen angibt, die in der aktuellen Sitzung erstellt wurden.

Die Sitzungskonfiguration definiert die Umgebung für die Remotesitzung. Die Konfiguration kann festlegen, welche Befehle und Sprachelemente in der Sitzung verfügbar sind und Einstellungen zum Schutz des Computers enthalten, wie z. B. Beschränkungen der Datenmenge, die von der Sitzung remote in einem einzigen Objekt oder Befehl empfangen werden kann. Der Sicherheitsdeskriptor der Sitzungskonfiguration bestimmt, welche Benutzer über die Berechtigung zum Verwenden der Sitzungskonfiguration verfügen.

Sie können die Elemente der Konfiguration mit einer Assembly definieren, die eine neue Konfigurationsklasse implementiert, sowie mithilfe eines Skripts, das in der Sitzung ausgeführt wird. Ab PowerShell 3.0 können Sie auch eine Sitzungskonfigurationsdatei verwenden, um die Sitzungskonfiguration zu definieren.

Informationen zu Sitzungskonfigurationen finden Sie unter about_Session_Configurations. Informationen zu Sitzungskonfigurationsdateien finden Sie unter about_Session_Configuration_Files.

Beispiele

Beispiel 1: Registrieren einer NewShell-Sitzungskonfiguration

In diesem Beispiel registrieren wir die NewShell-Sitzungskonfiguration . Die Parameter "AssemblyName " und "ApplicationBase " geben den Speicherort der MyShell.dll-Datei an, die die Cmdlets und Anbieter in der Sitzungskonfiguration angibt. Der Parameter ConfigurationTypeName gibt die konfigurationsklasse an, die aus der Assembly verwendet werden soll.

$sessionConfiguration = @{
    Name='NewShell'
    ApplicationBase='c:\MyShells\'
    AssemblyName='MyShell.dll'
    ConfigurationTypeName='MyClass'
}
Register-PSSessionConfiguration @sessionConfiguration

Um diese Konfiguration zu verwenden, geben Sie New-PSSession -ConfigurationName newshell.

Beispiel 2: Registrieren einer MaintenanceShell-Sitzungskonfiguration

In diesem Beispiel wird die MaintenanceShell-Sitzungskonfiguration auf dem lokalen Computer registriert. Der Parameter StartupScript gibt das Maintenance.ps1 Skript an.

Register-PSSessionConfiguration -Name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1

Wenn ein Benutzer einen New-PSSession Befehl verwendet und die MaintenanceShell-Konfiguration auswählt, wird das Maintenance.ps1 Skript in der neuen Sitzung ausgeführt. Das Skript kann die Sitzung konfigurieren. Dazu gehören das Importieren von Modulen und das Festlegen der Ausführungsrichtlinie für die Sitzung. Wenn das Skript Fehler generiert, einschließlich nicht beendeter Fehler, schlägt der New-PSSession Befehl fehl.

Beispiel 3: Registrieren einer Sitzungskonfiguration

In diesem Beispiel wird die AdminShell-Sitzungskonfiguration registriert.

Die $sessionParams Variable ist eine Hashtabelle, die alle Parameterwerte enthält. Diese Hashtabelle wird mithilfe der PowerShell-Splatting an das Cmdlet übergeben. Der Register-PSSessionConfiguration Befehl verwendet den SecurityDescritorSDDL-Parameter , um die SDDL im Wert der $sddl Variablen und den Parameter MaximumReceivedObjectSizeMB anzugeben, um die Objektgröße zu erhöhen. Außerdem wird der StartupScript-Parameter verwendet, um ein Skript anzugeben, das die Sitzung konfiguriert.

$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

Beispiel 4: Zurückgeben eines Konfigurationscontainerelements

In diesem Beispiel wird gezeigt, wie die MaintenanceShell-Konfiguration registriert wird. Register-PSSessionConfiguration gibt ein WSManConfigContainerElement -Objekt zurück, das in der $s Variablen gespeichert ist. Format-List zeigt alle Eigenschaften des zurückgegebenen Objekts an. Die PSPath-Eigenschaft zeigt, dass das Objekt in einem Verzeichnis des WSMan:-Laufwerks gespeichert ist. Get-ChildItem (Alias dir) zeigt die Elemente im WSMan:\LocalHost\PlugIn Pfad an. Dazu gehören die neue MaintenanceShell-Konfiguration und die beiden Standardkonfigurationen, die in PowerShell enthalten sind.

$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}

Beispiel 5: Registrieren einer Sitzungskonfiguration mit einem Startskript

In diesem Beispiel erstellen und registrieren wir die WithProfile-Sitzungskonfiguration . Der StartupScript-Parameter leitet PowerShell an, um das angegebene Skript für jede Sitzung auszuführen, die die Sitzungskonfiguration verwendet.

Register-PSSessionConfiguration -Name WithProfile -StartupScript Add-Profile.ps1

Das Skript enthält einen einzelnen Befehl, der dot sourcing verwendet, um das CurrentUserAllHosts-Profil des Benutzers im aktuellen Bereich der Sitzung auszuführen.

Weitere Informationen zu Profilen finden Sie unter about_Profiles. Weitere Informationen zur Dot Sourcing finden Sie unter about_Scopes.

Parameter

-AccessMode

-ApplicationBase

-AssemblyName

-ConfigurationTypeName

-Confirm

-Force

-MaximumReceivedDataSizePerCommandMB

-MaximumReceivedObjectSizeMB

-ModulesToImport

-Name

-NoServiceRestart

-Path

-ProcessorArchitecture

-PSVersion

-RunAsCredential

-SecurityDescriptorSddl

-SessionTypeOption

-ShowSecurityDescriptorUI

-StartupScript

-ThreadApartmentState

-ThreadOptions

-TransportOption

-UseSharedProcess

-WhatIf

Eingaben

None

Sie können keine Objekte an dieses Cmdlet weiterleiten.

Ausgaben

WSManConfigContainerElement

Hinweise

Dieses Cmdlet ist nur auf Windows-Plattformen verfügbar.

Zum Ausführen dieses Cmdlets müssen Sie PowerShell mithilfe der Option "Als Administrator ausführen" starten.

Dieses Cmdlet generiert XML, das eine WS-Management-Plug-In-Konfiguration (Web Services for Management) darstellt, und sendet den XML-Code an WS-Management, der das Plug-In auf dem lokalen Computer registriert (New-Item wsman:\localhost\plugin).

Die Eigenschaften eines Sitzungskonfigurationsobjekts weichen hinsichtlich der für die Sitzungskonfiguration festgelegten Optionen sowie der Werte dieser Optionen ab. Sitzungskonfigurationen, die eine Sitzungskonfigurationsdatei verwenden, haben außerdem zusätzliche Eigenschaften.

Ähnliche Themen

• Disable-PSSessionConfiguration
• Enable-PSSessionConfiguration
• Get-PSSessionConfiguration
• New-PSSessionConfigurationFile
• Set-PSSessionConfiguration
• Test-PSSessionConfigurationFile
• Unregister-PSSessionConfiguration
• WSMan-Anbieter
• about_Session_Configurations
• about_Session_Configuration_Files