Compartir a través de

Register-PSSessionConfiguration

  • Referencia
Módulo:
Microsoft.PowerShell.Core

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

Sintaxis

Register-PSSessionConfiguration
        [-ProcessorArchitecture <String>]
        [-SessionType <PSSessionType>]
        [-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>]

Description

El Register-PSSessionConfiguration cmdlet crea y registra una nueva configuración de sesión en el equipo local. Se trata de un cmdlet avanzado que puede usar para crear sesiones personalizadas para usuarios remotos.

Cada sesión de PowerShell (PSSession) usa una configuración de sesión, también conocida como punto de conexión. Cuando los usuarios crean una sesión que se conecta al equipo, pueden seleccionar una configuración de sesión o usar la configuración de sesión predeterminada registrada al habilitar la comunicación remota de PowerShell. Los usuarios también pueden establecer la variable de preferencia $PSSessionConfigurationName, que especifica una configuración predeterminada para las sesiones remotas creadas en la sesión actual.

La configuración de sesión define el entorno de la sesión remota. La configuración puede determinar qué comandos y elementos de lenguaje están disponibles en la sesión, y puede incluir opciones de configuración para proteger el equipo, como las que limitan la cantidad de datos que la sesión puede recibir de forma remota en un solo objeto o comando. El descriptor de seguridad de la configuración de sesión determina qué usuarios tienen permiso para usar la configuración de sesión.

Puede definir los elementos de configuración usando un ensamblado que implementa una nueva clase de configuración y un script que se ejecuta en la sesión. A partir de PowerShell 3.0, también puede usar un archivo de configuración de sesión para definir la configuración de sesión.

Para obtener información sobre las configuraciones de sesión, consulte about_Session_Configurations. Para obtener información sobre los archivos de configuración de sesión, consulte about_Session_Configuration_Files.

Ejemplos

Ejemplo 1: Registro de una configuración de sesión de NewShell

En este ejemplo, registramos la configuración de la sesión de NewShell . Los parámetros AssemblyName y ApplicationBase especifican la ubicación del archivo MyShell.dll , que especifica los cmdlets y proveedores en la configuración de sesión. El parámetro ConfigurationTypeName especifica la clase de configuración que se va a usar desde el ensamblado.

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

Para usar esta configuración, escriba New-PSSession -ConfigurationName newshell.

Ejemplo 2: Registro de una configuración de sesión de MaintenanceShell

En este ejemplo se registra la configuración de sesión de MaintenanceShell en el equipo local. El parámetro StartupScript especifica el Maintenance.ps1 script.

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

Cuando un usuario usa un New-PSSession comando y selecciona la configuración de MaintenanceShell , el Maintenance.ps1 script se ejecuta en la nueva sesión. El script puede configurar la sesión. Esto incluye importar módulos y establecer la directiva de ejecución para la sesión. Si el script genera errores, incluidos los errores de no terminación, se produce un error en el New-PSSession comando.

Ejemplo 3: Registro de una configuración de sesión

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

La $sessionParams variable es una tabla hash que contiene todos los valores de parámetro. Esta tabla hash se pasa al cmdlet mediante la expansión de PowerShell. El Register-PSSessionConfiguration comando usa el parámetro SecurityDescritorSDDL para especificar el SDDL en el valor de la $sddl variable y el parámetro MaximumReceivedObjectSizeMB para aumentar el límite de tamaño del objeto. También usa el parámetro StartupScript para especificar un script que configure la sesión.

$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

Ejemplo 4: Devolver un elemento contenedor de configuración

En este ejemplo se muestra cómo registrar la configuración de MaintenanceShell . Register-PSSessionConfiguration devuelve un objeto WSManConfigContainerElement almacenado en la $s variable . Format-List muestra todas las propiedades del objeto devuelto. La propiedad PSPath muestra que el objeto se almacena en un directorio de la unidad WSMan: . Get-ChildItem (alias dir) muestra los elementos de la ruta de WSMan:\LocalHost\PlugIn acceso. Entre ellas se incluyen la nueva configuración de MaintenanceShell y las dos configuraciones predeterminadas que se incluyen con PowerShell.

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

Ejemplo 5: Registro de una configuración de sesión con un script de inicio

En este ejemplo, creamos y registramos la configuración de sesión withProfile . El parámetro StartupScript dirige PowerShell para ejecutar el script especificado para cualquier sesión que use la configuración de sesión.

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

El script contiene un único comando que usa dot sourcing para ejecutar el perfil CurrentUserAllHosts del usuario en el ámbito actual de la sesión.

Para obtener más información sobre los perfiles, consulte about_Profiles. Para obtener más información sobre el origen de puntos, consulte about_Scopes.

Parámetros

-AccessMode

Habilita y deshabilita la configuración de sesión y determina si se puede usar para sesiones locales o remotas en el equipo. Los valores permitidos para este parámetro son los siguientes:

  • Deshabilitado. deshabilita la configuración de sesión. No se puede usar para el acceso remoto o local al equipo.
  • Local. Permite a los usuarios del equipo local usar la configuración de sesión para crear una sesión de bucle invertido local en el mismo equipo, pero deniega el acceso a los usuarios remotos.
  • Remote (Remotas). Permite a los usuarios de equipos locales y remotos utilizar la configuración de sesión para crear sesiones y ejecutar comandos en este equipo.

El valor predeterminado es Remote.

Otros cmdlets pueden invalidar el valor de este parámetro más adelante. Por ejemplo, el Enable-PSRemoting cmdlet permite el acceso remoto a todas las configuraciones de sesión, el Enable-PSSessionConfiguration cmdlet habilita las configuraciones de sesión y el cmdlet impide el Disable-PSRemoting acceso remoto a todas las configuraciones de sesión.

Este parámetro se introdujo en PowerShell 3.0.

Tipo:PSSessionConfigurationAccessMode
Valores aceptados:Disabled, Local, Remote
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-ApplicationBase

Especifica la ruta de acceso del archivo de ensamblado (*.dll) especificado en el valor del parámetro AssemblyName . Use este parámetro cuando el valor del parámetro AssemblyName no incluya una ruta de acceso. El valor predeterminado es el directorio actual.

Tipo:String
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-AssemblyName

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

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

Tipo:String
Posición:1
Valor predeterminado:None
Requerido:True
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-ConfigurationTypeName

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

Para especificar el archivo de ensamblado (*.dll) que implementa el tipo de configuración, especifique los parámetros AssemblyName y ApplicationBase .

La creación de un tipo permite controlar más aspectos de la configuración de sesión, como exponer u ocultar determinados parámetros de cmdlets, o establecer límites de tamaño de datos y tamaño de objeto que los usuarios no pueden invalidar.

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

Tipo:String
Posición:2
Valor predeterminado:None
Requerido:True
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-Confirm

Le solicita su confirmación antes de ejecutar el cmdlet.

Tipo:SwitchParameter
Alias:cf
Posición:Named
Valor predeterminado:False
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-Force

Suprime todas las solicitudes de usuario y reinicia el servicio WinRM sin preguntar. Al reiniciar el servicio la configuración surte efecto.

Para evitar un reinicio y suprimir el mensaje de reinicio, especifique el parámetro NoServiceRestart .

Tipo:SwitchParameter
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-MaximumReceivedDataSizePerCommandMB

Especifica un límite para la cantidad de datos que se pueden enviar a este equipo en cualquier único comando remoto. Especifique el tamaño de los datos en megabytes (MB). El valor predeterminado es 50 MB.

Si se define un límite de tamaño de datos en el tipo de configuración especificado en el parámetro ConfigurationTypeName , se usa el límite del tipo de configuración y se omite el valor de este parámetro.

Tipo:Nullable<T>[Double]
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-MaximumReceivedObjectSizeMB

Especifica un límite para la cantidad de datos que se pueden enviar a este equipo en cualquier único objeto. Escriba el tamaño de los datos en megabytes. El valor predeterminado es 10 MB.

Si se define un límite de tamaño de objeto en el tipo de configuración especificado en el parámetro ConfigurationTypeName , se usa el límite del tipo de configuración y se omite el valor de este parámetro.

Tipo:Nullable<T>[Double]
Posición:Named
Valor predeterminado:10
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-ModulesToImport

Especifica los módulos que se importan automáticamente en sesiones que usan la configuración de sesión.

De forma predeterminada, solo Microsoft.PowerShell.Core se importa en sesiones. A menos que se excluyan los cmdlets, puede usar Import-Module para agregar módulos a la sesión.

Los módulos especificados en este valor de parámetro se importan además de los módulos especificados por el parámetro SessionType y los enumerados en la clave ModulesToImport en el archivo de configuración de sesión (New-PSSessionConfigurationFile). Sin embargo, la configuración del archivo de configuración de sesión puede ocultar los comandos exportados por los módulos o impedir que los usuarios los utilicen.

Este parámetro se introdujo en PowerShell 3.0.

Tipo:Object[]
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-Name

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

Tipo:String
Posición:0
Valor predeterminado:None
Requerido:True
Aceptar entrada de canalización:True
Aceptar caracteres comodín:False

-NoServiceRestart

La intención de este parámetro es evitar el reinicio del servicio WinRM . Esta funcionalidad no se implementa.

Esta funcionalidad se implementó en PowerShell 7.5.0-preview.4, pero no hay ningún plan para volver a migrar este cambio a Windows PowerShell 5.1.

Tipo:SwitchParameter
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-Path

Especifica la ruta de acceso y el nombre de archivo de configuración de una sesión (.pssc), como uno creado por New-PSSessionConfigurationFile. Si omite la ruta de acceso, el valor predeterminado es el directorio actual.

Este parámetro se introdujo en PowerShell 3.0.

Tipo:String
Posición:Named
Valor predeterminado:None
Requerido:True
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-ProcessorArchitecture

Determina si se inicia una versión de 32 o 64 bits del proceso de PowerShell en sesiones que usan esta configuración de sesión. Los valores aceptables para este parámetro son: x86 (32 bits) y AMD64 (64 bits). El valor predeterminado depende de la arquitectura de procesador del equipo que hospeda la configuración de sesión.

Puede utilizar este parámetro para crear una sesión de 32 bits en un equipo de 64 bits. Al intentar crear un proceso de 64 bits en un equipo de 32 bits se producirá un error.

Tipo:String
Alias:PA
Valores aceptados:x86, amd64
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-PSVersion

Especifica la versión de PowerShell en sesiones que usan esta configuración de sesión.

El valor de este parámetro tiene prioridad sobre el valor de la clave PowerShellVersion en el archivo de configuración de sesión.

Este parámetro se introdujo en PowerShell 3.0.

Tipo:Version
Alias:PowerShellVersion
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-RunAsCredential

Especifica las credenciales de los comandos de la sesión. De forma predeterminada, los comandos se ejecutan con los permisos del usuario actual.

Este parámetro se introdujo en PowerShell 3.0.

Tipo:PSCredential
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-SecurityDescriptorSddl

Especifica una cadena del lenguaje de definición de descriptores de seguridad (SDDL) para la configuración.

Esta cadena determina los permisos necesarios para usar la nueva configuración de sesión. Para usar una configuración de sesión en una sesión, los usuarios deben tener al menos el permiso Ejecutar (invocar) para la configuración.

Si el descriptor de seguridad es complejo, considere la posibilidad de usar el parámetro ShowSecurityDescriptorUI en lugar de este parámetro. No puede usar ambos parámetros en el mismo comando.

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

Tipo:String
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-SessionType

Especifica el tipo de sesión que se crea usando la configuración de sesión. Los valores permitidos para este parámetro son los siguientes:

  • Vacía. De forma predeterminada, no se agrega ningún módulo a la sesión. Use los parámetros de este cmdlet para agregar módulos, funciones, scripts y otras características a la sesión.
  • Predeterminada. Agrega Microsoft.PowerShell.Core a la sesión. Este módulo incluye el Import-Module cmdlet que los usuarios pueden usar para importar otros módulos a menos que se prohíbe explícitamente el cmdlet.
  • RestrictedRemoteServer. Incluye solo los siguientes cmdlets: Exit-PSSession, Get-Command, Get-FormatDataGet-Help, , Measure-Object, Out-Defaulty Select-Object. Utilice un script o ensamblado, o las claves del archivo de configuración de sesión, para agregar módulos, funciones, scripts y otras características a la sesión.

El valor predeterminado es Default.

El valor de este parámetro tiene prioridad sobre el valor de la clave SessionType en el archivo de configuración de sesión.

Este parámetro se introdujo en PowerShell 3.0.

Tipo:PSSessionType
Valores aceptados:DefaultRemoteShell, Workflow
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-SessionTypeOption

Especifica opciones específicas del tipo para la configuración de sesión. Escriba un objeto de opciones de tipo de sesión, como el objeto PSWorkflowExecutionOption que devuelve el New-PSWorkflowExecutionOption cmdlet.

Las opciones de las sesiones que utilizan la configuración de sesión están determinadas por los valores de las opciones de sesión y de las opciones de configuración de sesión. A menos que se especifique, las opciones establecidas en la sesión, como mediante el New-PSSessionOption cmdlet , tienen prioridad sobre las opciones establecidas en la configuración de sesión. Sin embargo, los valores de opción de sesión no pueden superar los valores máximos establecidos en la configuración de sesión.

Este parámetro se introdujo en PowerShell 3.0.

Tipo:PSSessionTypeOption
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-ShowSecurityDescriptorUI

Indica que este cmdlet muestra una hoja de propiedades que le ayuda a crear el SDDL para la configuración de sesión. La hoja de propiedades aparece después de escribir el Register-PSSessionConfiguration comando y, a continuación, reinicia el servicio WinRM .

Al establecer los permisos para la configuración, recuerde que los usuarios deben tener al menos permiso Ejecutar (invocar) para usar la configuración de sesión en una sesión.

No puede usar el parámetro SecurityDescriptorSDDL y este parámetro en el mismo comando.

Tipo:SwitchParameter
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-StartupScript

Especifica la ruta de acceso completa de un script de PowerShell. El script especificado se ejecuta en una nueva sesión que usa la configuración de sesión.

Puede usar el script para configurar además la sesión. Si el script genera un error, incluso un error de no terminación, la sesión no se crea y se produce un error en el New-PSSession comando.

Tipo:String
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-ThreadApartmentState

Especifica el estado de apartamento del módulo de subprocesos que se va a usar. Los valores aceptables son:

  • Unknown
  • MTA
  • STA
Tipo:ApartmentState
Valores aceptados:STA, MTA, Unknown
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-ThreadOptions

Especifica cómo se crean y usan los subprocesos cuando se ejecuta un comando en la sesión. Los valores permitidos para este parámetro son los siguientes:

  • Valor predeterminado
  • ReuseThread
  • UseCurrentThread
  • UseNewThread

El valor predeterminado es UseCurrentThread.

Para obtener más información, consulte Enumeración PSThreadOptions.

Tipo:PSThreadOptions
Valores aceptados:Default, UseNewThread, ReuseThread, UseCurrentThread
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-TransportOption

Especifica la opción de transporte.

Este parámetro se introdujo en PowerShell 3.0.

Tipo:PSTransportOption
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-UseSharedProcess

Utilice solo un proceso para hospedar todas las sesiones que inicia el mismo usuario y que usan la misma configuración de sesión. De forma predeterminada, cada sesión se hospeda en su propio proceso.

Este parámetro se introdujo en PowerShell 3.0.

Tipo:SwitchParameter
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-WhatIf

Muestra lo que sucedería si se ejecutara el cmdlet. El cmdlet no se ejecuta.

Tipo:SwitchParameter
Alias:wi
Posición:Named
Valor predeterminado:False
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

Entradas

None

No se pueden canalizar objetos a este cmdlet.

Salidas

WSManConfigContainerElement

Notas

Para ejecutar este cmdlet, debe iniciar PowerShell mediante la opción Ejecutar como administrador .

Este cmdlet genera XML que representa una configuración de complemento de servicios web para administración (WS-Management) y envía el XML a WS-Management, que registra el complemento en el equipo local (New-Item wsman:\localhost\plugin).

Las propiedades de un objeto de configuración de sesión varían según las opciones establecidas para la configuración de sesión y los valores de esas opciones. Además, las configuraciones de sesión que utilizan un archivo de configuración de sesión tienen propiedades adicionales.