Crea y registra una nueva configuración de sesión.

Sintaxis

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

Descripción

El cmdlet Register-PSSessionConfiguration crea y registra una nueva configuración de sesión en el equipo local. Es un cmdlet avanzado diseñado para que lo utilicen los administradores de sistemas a fin de administrar configuraciones de sesión personalizadas para sus usuarios.

Cada sesión remota de Windows PowerShell utiliza una configuración de sesión. Cuando los usuarios crean una sesión que se conecta al equipo, pueden seleccionar una configuración o utilizar las predeterminadas que se registran al habilitar la comunicación remota de Windows PowerShell. Los usuarios también pueden establecer la variable de preferencia $PSSessionConfigurationName, que especifica una configuración predeterminada para las sesiones creadas en la sesión actual.

La configuración de sesión configura el entorno de la sesión. La configuración se puede definir mediante un ensamblado que implemente una nueva clase de configuración y mediante un script que se ejecute en la sesión. La configuración puede determinar qué comandos están disponibles en la sesión, así como incluir opciones que protejan al equipo, tales como los que limitan la cantidad de datos que la sesión puede recibir remotamente en un mismo objeto o comando. Asimismo, se puede especificar un descriptor de seguridad que determine los permisos necesarios para utilizar la configuración.

Parámetros

-ApplicationBase <string>

Especifica la ruta de acceso al archivo de ensamblado (*.dll) especificado en el valor del parámetro AssemblyName. Este parámetro se utiliza cuando el valor del parámetro AssemblyName no incluye una ruta de acceso. La ubicación predeterminada es el directorio actual.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

Current directory

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-AssemblyName <string>

Especifica el nombre de un archivo de ensamblado (*.dll) en el que se define el tipo de configuración. Se puede especificar la ruta de acceso al archivo .dll en este parámetro o en el valor del parámetro ApplicationBase.

Este parámetro es obligatorio cuando se especifica el parámetro ConfigurationTypeName.

¿Requerido?

true

¿Posición?

2

Valor predeterminado

ninguno

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-ConfigurationTypeName <string>

Especifica el nombre completo del tipo de Microsoft .NET Framework que se utiliza para esta configuración. El tipo que se especifica debe implementar la clase System.Management.Automation.Remoting.PSSessionConfiguration.

Para especificar el archivo de ensamblado (.dll) que implementa el tipo de configuración, se utilizan los parámetros AssemblyBase y AssemblyName.

Crear un tipo permite controlar más aspectos de la configuración de sesión; por ejemplo, exponer u ocultar determinados parámetros de los cmdlets o establecer límites respecto del tamaño de los datos y de los objetos que los usuarios no puedan invalidar.

Si se omite este parámetro, se utiliza la clase DefaultRemotePowerShellConfiguration para la configuración de sesión.

¿Requerido?

true

¿Posición?

3

Valor predeterminado

System.Management.Automation.Remoting.PSSessionConfiguration

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-Force

Elimina todas las confirmaciones de usuario y reinicia el servicio WinRM sin pedir confirmación. Al reiniciar el equipo surte efecto el cambio de configuración.

Para evitar un reinicio y suprimir la confirmación de reinicio, utilice el parámetro NoServiceRestart.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-MaximumReceivedDataSizePerCommandMB <double>

Limita la cantidad de datos que se pueden enviar a este equipo en un mismo comando remoto. Especifique el tamaño de los datos en megabytes (MB). El valor predeterminado es 50 MB.

Si el límite del tamaño de datos se ha definido en el tipo de configuración especificada en el parámetro ConfigurationTypeName, se utilizará ese límite y se pasará por alto el valor de este parámetro.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

50

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-MaximumReceivedObjectSizeMB <double>

Limita la cantidad de datos que se pueden enviar a este equipo en un mismo objeto. Especifique el tamaño de los datos en megabytes (MB). El valor predeterminado es 10 MB.

Si el límite de tamaño de un objeto se ha definido en el tipo de configuración especificada en el parámetro ConfigurationTypeName, se utilizará ese límite y se pasará por alto el valor de este parámetro.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

10

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-Name <string>

Especifica el nombre de la configuración de sesión. Este parámetro es obligatorio.

¿Requerido?

true

¿Posición?

1

Valor predeterminado

ninguno

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-NoServiceRestart

No reinicia el servicio WinRM y suprime la confirmación para reiniciar el servicio.

De forma predeterminada, cuando se escribe un comando Register-PSSessionConfiguration se pide al usuario que reinicie el servicio WinRM a fin de que surta efecto la nueva configuración de sesión. Esta nueva configuración de sesión no surtirá efecto hasta que se reinicie el servicio WinRM.

Para reiniciar el servicio WinRM sin pedir confirmación, utilice el parámetro Force. Para reiniciar el servicio WinRM manualmente, utilice el cmdlet Restart-Service.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

False

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-ProcessorArchitecture <string>

Especifica una arquitectura de procesador para la configuración. Este valor determina si al utilizar la configuración se iniciará una versión de 32 ó 64 bits del proceso donde se hospeda Windows PowerShell. Los valores válidos son x86, AMD64 e IA64.

La arquitectura del procesador del equipo que hospeda la configuración de sesión determina el valor predeterminado.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

The processor architecture of the host computer.

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-SecurityDescriptorSDDL <string>

Especifica una cadena de Lenguaje de definición de descriptores de seguridad (SDDL, Security Descriptor Definition Language) para la configuración.

Esta cadena determina los permisos que se exigen para utilizar la nueva configuración de sesión. Para usar una configuración de sesión en una sesión, el usuario debe disponer como mínimo del permiso "Execute(Invoke)" respecto de esa configuración.

Si el descriptor de seguridad es complejo, puede ser más conveniente utilizar el parámetro ShowSecurityDescriptorUI en lugar de este. No se pueden usar los dos parámetros en el mismo comando.

Si se omite este parámetro, la cadena SDDL raíz del servicio de WinRM se utiliza para esta configuración. Para ver o cambiar la cadena SDDL raíz, se utiliza el proveedor WS-Management. Por ejemplo, "Get-Item wsman:\localhost\service\rootSDDL". Para obtener más información acerca del proveedor WS-Management, escriba "Get-Help wsman".

¿Requerido?

false

¿Posición?

named

Valor predeterminado

The value of the root SDDL

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-ShowSecurityDescriptorUI

Muestra una hoja de propiedades que ayuda a crear la cadena SDDL para la configuración de sesión. La hoja de propiedades aparece cuando se especifica el comando Register-PSSessionConfiguration y, a continuación, se reinicia el servicio WinRM.

Al establecer los permisos de la configuración, es preciso recordar que los usuarios deben disponer como mínimo del permiso "Execute(Invoke)" para utilizar la configuración de sesión en una sesión.

No se pueden utilizar el parámetro SecurityDescriptorSDDL y este en el mismo comando.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-StartupScript <string>

Especifica la ruta completa a un script de Windows PowerShell. El script especificado se ejecuta en la nueva sesión que utiliza la configuración de sesión.

Se puede utilizar el script para continuar configurando la sesión. Si el script genera un error (aunque no sea de terminación), la sesión no se crea y se produce un error en el comando New-PSSession.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-ThreadApartmentState <ApartmentState>

Determina el estado del apartamento de los subprocesos de la sesión. Los valores válidos son STA, MTA y Unknown. El valor predeterminado es Unknown.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

Unknown

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-ThreadOptions <PSThreadOptions>

Define cómo se crean y utilizan los subprocesos al ejecutar un comando en la sesión. Los valores válidos son Default, ReuseThread, UseCurrentThread y UseNewThread. El valor predeterminado es UseCurrentThread.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

UseCurrentThread

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-Confirm

Solicita confirmación antes de ejecutar el comando.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-WhatIf

Describe lo que ocurriría si se ejecutara el comando, sin ejecutarlo realmente.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

<CommonParameters>

Este cmdlet admite los parámetros comunes: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer y -OutVariable. Para obtener más información, vea about_Commonparameters.

Entradas y salidas

El tipo de entrada es el tipo de los objetos que se pueden canalizar al cmdlet. El tipo devuelto es el tipo de los objetos que el cmdlet devuelve.

Entradas

Ninguno

No se pueden canalizar entradas a este cmdlet.

Salidas

Microsoft.WSMan.Management.WSManConfigContainerElement

Notas

Para ejecutar este cmdlet en Windows Vista, Windows Server 2008 y versiones posteriores de Windows, se debe iniciar Windows PowerShell con la opción "Ejecutar como administrador".

Este cmdlet genera código XML que representa una configuración de complemento de Web Services for Management (WS-Management) y, a continuación, envía este código XML a WS-Management, que registra el complemento en el equipo local ("new-item wsman:\localhost\plugin").

Ejemplo 1

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".






Ejemplo 2

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.






Ejemplo 3

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.






Ejemplo 4

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.






Ejemplo 5

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.






Vea también




Tabla de contenido