Register-PSSessionConfiguration

Sintaxis

NameParameterSet (Es el valor predeterminado).

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

AssemblyNameParameterSet

Register-PSSessionConfiguration
    [-Name] <String>
    [-AssemblyName] <String>
    [-ConfigurationTypeName] <String>
    [-ProcessorArchitecture <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>]

SessionConfigurationFile

Register-PSSessionConfiguration
    [-Name] <String>
    -Path <String>
    [-ProcessorArchitecture <String>]
    [-RunAsCredential <PSCredential>]
    [-ThreadApartmentState <ApartmentState>]
    [-ThreadOptions <PSThreadOptions>]
    [-AccessMode <PSSessionConfigurationAccessMode>]
    [-UseSharedProcess]
    [-StartupScript <String>]
    [-MaximumReceivedDataSizePerCommandMB <Double>]
    [-MaximumReceivedObjectSizeMB <Double>]
    [-SecurityDescriptorSddl <String>]
    [-ShowSecurityDescriptorUI]
    [-Force]
    [-NoServiceRestart]
    [-TransportOption <PSTransportOption>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Description

Ejemplos

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

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

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

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

Ejemplo 3: Registro de una configuración de 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

$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

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

Parámetros

-AccessMode

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

• Deshabilitado. Deshabilita la configuración de la 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.
• Remoto. Permite a los usuarios locales y remotos usar 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 cmdlet Enable-PSRemoting permite el acceso remoto a todas las configuraciones de sesión, el cmdlet Enable-PSSessionConfiguration habilita las configuraciones de sesión y el cmdlet Disable-PSRemoting impide el acceso remoto a todas las configuraciones de sesión.

Este parámetro se introdujo en PowerShell 3.0.

Propiedades del parámetro

Conjuntos de parámetros

-ApplicationBase

Especifica la ruta de acceso del archivo de ensamblado (*.dll) que se especifica 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.

Propiedades del parámetro

Conjuntos de parámetros

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

Propiedades del parámetro

Conjuntos de parámetros

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

Propiedades del parámetro

Conjuntos de parámetros

-Confirm

Le pide confirmación antes de ejecutar el cmdlet.

Propiedades del parámetro

Conjuntos de parámetros

-Force

Suprime todas las solicitudes de usuario y reinicia el servicio de winRM de sin preguntar. Reiniciar el servicio hace que el cambio de configuración sea efectivo.

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

Propiedades del parámetro

Conjuntos de parámetros

-MaximumReceivedDataSizePerCommandMB

Especifica un límite para la cantidad de datos que se pueden enviar a este equipo en cualquier único comando remoto. Escriba 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.

Propiedades del parámetro

Conjuntos de parámetros

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

Propiedades del parámetro

Conjuntos de parámetros

-ModulesToImport

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

De forma predeterminada, solo se importa microsoft.PowerShell.Core en las 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 el ModulesToImport clave del 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 módulos o impedir que los usuarios los usen.

Este parámetro se introdujo en PowerShell 3.0.

Propiedades del parámetro

Conjuntos de parámetros

-Name

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

Propiedades del parámetro

Conjuntos de parámetros

-NoServiceRestart

No reinicia el servicio WinRM y suprime la solicitud para reiniciar el servicio.

De forma predeterminada, al ejecutar un comando Register-PSSessionConfiguration, se le pedirá que reinicie el servicio WinRM para que la nueva configuración de sesión sea efectiva. Hasta que se reinicie el servicio WinRM, la nueva configuración de sesión no es efectiva.

Para reiniciar el servicio winRM de sin preguntar, especifique el parámetro Force. Para reiniciar manualmente el servicio winRM , use el cmdlet .

Esta funcionalidad se implementó en PowerShell 7.5.0-preview.4.

Propiedades del parámetro

Conjuntos de parámetros

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

Propiedades del parámetro

Conjuntos de parámetros

-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 viene determinado por la arquitectura de procesador del equipo que hospeda la configuración de sesión.

Puede usar este parámetro para crear una sesión de 32 bits en un equipo de 64 bits. Se produce un error en los intentos de crear un proceso de 64 bits en un equipo de 32 bits.

Propiedades del parámetro

Conjuntos de parámetros

-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 del PowerShellVersion clave en el archivo de configuración de sesión.

Este parámetro se introdujo en PowerShell 3.0.

Propiedades del parámetro

Conjuntos de parámetros

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

Propiedades del parámetro

Conjuntos de parámetros

-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 del servicio winRM para esta configuración. Para ver o cambiar el SDDL raíz, use 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.

Propiedades del parámetro

Conjuntos de parámetros

-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 cmdlet New-PSWorkflowExecutionOption.

Las opciones de sesiones que usan la configuración de sesión se determinan mediante los valores de las opciones de sesión y las opciones de configuración de sesión. A menos que se especifique, las opciones establecidas en la sesión, como mediante el cmdlet New-PSSessionOption, 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.

Propiedades del parámetro

Conjuntos de parámetros

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

Propiedades del parámetro

Conjuntos de parámetros

-StartupScript

Especifica la ruta de acceso completa de un script de PowerShell. El script especificado se ejecuta en la nueva sesión que usa la configuración de la 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 comando New-PSSession.

Propiedades del parámetro

Conjuntos de parámetros

-ThreadApartmentState

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

• Desconocido
• MTA
• STA

Propiedades del parámetro

Conjuntos de parámetros

-ThreadOptions

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

• Predeterminado
• ReuseThread
• UseCurrentThread
• UseNewThread

El valor predeterminado es UseCurrentThread.

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

Propiedades del parámetro

Conjuntos de parámetros

-TransportOption

Especifica la opción de transporte.

Este parámetro se introdujo en PowerShell 3.0.

Propiedades del parámetro

Conjuntos de parámetros

-UseSharedProcess

Use solo un proceso para hospedar todas las sesiones iniciadas por el mismo usuario y usar 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.

Propiedades del parámetro

Conjuntos de parámetros

-WhatIf

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

Propiedades del parámetro

Conjuntos de parámetros

CommonParameters

Entradas

None

Salidas

WSManConfigContainerElement

Notas

Vínculos relacionados

• Disable-PSSessionConfiguration
• Enable-PSSessionConfiguration
• Get-PSSessionConfiguration
• New-PSSessionConfigurationFile
• Set-PSSessionConfiguration
• Test-PSSessionConfigurationFile
• Unregister-PSSessionConfiguration
• Proveedor WSMan
• acerca_de_las_Configuraciones_de_Sesión
• about_Session_Configuration_Files