Register-PSSessionConfiguration

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

C:\PS>register-pssessionConfiguration -name NewShell -applicationBase c:\MyShells\ -assemblyName MyShell.dll -configurationTypeName MyClass

Descripción
-----------
Este comando registra la configuración de sesión de NewShell. Utiliza los parámetros ApplicationName y ApplicationBase para especificar la ubicación del archivo MyShell.dll, que especifica los cmdlets y proveedores en la configuración de sesión. También utiliza el parámetro ConfigurationTypeName para especificar una nueva clase que continúa configurando la sesión.

Para utilizar esta configuración, el usuario debe escribir "new-pssession -configurationname newshell".

C:\PS>register-pssessionConfiguration -name MaintenanceShell -startupScript c:\ps-test\Maintenance.ps1

Descripción
-----------
Este comando registra la configuración MaintenanceShell en el equipo local. El comando utiliza el parámetro StartupScript para especificar el script Maintenance.ps1.

Cuando un usuario utiliza un comando New-PSSession y selecciona la configuración MaintenanceShell, se ejecuta el script Maintenance.ps1 en la nueva sesión. El script puede configurar la sesión; esto incluye importar módulos, agregar complementos de Windows PowerShell y establecer la directiva de ejecución para la sesión. Si el script genera algún error, aunque no sea de terminación, se produce un error en el comando New-PSSession.

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

Descripción
-----------
En este ejemplo se registra la configuración de sesión AdminShell. 

El primer comando guarda una cadena SDDL personalizada en la variable $sddl. 

El segundo comando registra el nuevo shell. El comando utiliza el parámetro SecurityDescritorSDDL para especificar la cadena SDDL en el valor de la variable $sddl y el parámetro MaximumReceivedObjectSizeMB para aumentar el límite de tamaño de objeto. También utiliza el parámetro StartupScript para especificar un script que configura la sesión.

Como alternativa al uso del parámetro SecurityDescriptorSDDL, se puede utilizar el parámetro ShowSecurityDescriptorUI, que muestra una hoja de propiedades que se puede usar para establecer los permisos de la configuración de sesión. Al hacer clic en "Aceptar" en la hoja de propiedades, la herramienta genera una cadena SDDL para la configuración de sesión.

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

Descripción
-----------
En este ejemplo se muestra que un comando Register-PSSessionConfiguration devuelve un objeto WSManConfigContainerElement. También se muestra cómo buscar los elementos contenedores en la unidad WSMan:.

El primer comando utiliza el cmdlet Register-PSSessionConfiguration para registrar la configuración MaintenanceShell. Guarda el objeto devuelto por el cmdlet en la variable $s.

El segundo comando muestra el contenido de la variable $s. 

El tercer comando usa el método GetType y su propiedad FullName para mostrar el nombre de tipo del objeto que Register-PSSessionConfiguration devuelve.

El cuarto comando utiliza el cmdlet Format-List para mostrar una lista con todas las propiedades del objeto que Register-PSSessionConfiguration devuelve. La propiedad PSPath muestra que el objeto se almacena en un directorio de la unidad WSMan:.

El quinto comando utiliza el cmdlet Get-ChildItem para mostrar los elementos de la ruta de acceso WSMan:\LocalHost\PlugIn. Estos elementos son la nueva configuración MaintenanceShell y las dos configuraciones predeterminadas que se incluyen con Windows PowerShell.

C:\PS>register-pssessionconfiguration -name WithProfile -startupScript add-profile.ps1

# Add-Profile.ps1

. c:\users\admin01\documents\windowspowershell\profile.ps1

Descripción
-----------
Este comando crea y registra la configuración de sesión WithProfile en el equipo local. El comando utiliza el parámetro StartupScript para indicar a Windows PowerShell que ejecute el script especificado en todas las sesiones que utilicen la configuración de sesión.

Además, se muestra el contenido del script especificado, Add-Profile.ps1. El script contiene un solo comando que utiliza script prefijado por puntos para ejecutar el perfil CurrentUserAllHosts del usuario en el ámbito actual de la sesión.

Para obtener más información sobre perfiles, vea about_Profiles. Para obtener más información sobre los scripts prefijados por puntos, vea about_Scopes.