Compartir a través de

Set-PSSessionConfiguration

  • Referencia
Módulo:
Microsoft.PowerShell.Core

Cambia las propiedades de una configuración de sesión registrada.

Sintaxis

Set-PSSessionConfiguration
   [-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>]
Set-PSSessionConfiguration
   [-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>]
Set-PSSessionConfiguration
   [-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

Este cmdlet solo está disponible en la plataforma Windows.

El cmdlet Set-PSSessionConfiguration cambia las propiedades de las configuraciones de sesión en el equipo local.

Use el parámetro Name para identificar la configuración de sesión que desea cambiar. Use los demás parámetros para especificar nuevos valores para las propiedades de la configuración de sesión. Para eliminar un valor de propiedad de la configuración y usar el valor predeterminado, escriba una cadena vacía ("") o un valor de $Null para el parámetro correspondiente.

A partir de PowerShell 3.0, puede usar un archivo de configuración de sesión para definir una configuración de sesión. Esta característica proporciona un método sencillo y reconocible para establecer y cambiar las propiedades de las sesiones que usan la configuración de sesión. Para especificar un archivo de configuración de sesión, use el parámetro Path de Set-PSSessionConfiguration. Para obtener información sobre los archivos de configuración de sesión, vea about_Session_Configuration_Files. Para obtener información sobre cómo crear y modificar un archivo de configuración de sesión, consulte el cmdlet New-PSSessionConfigurationFile.

Las configuraciones de sesión definen el entorno de sesiones remotas (PSSessions) que se conectan al equipo local. Cada PSSession usa una configuración de sesión. La configuración de sesión determina las características del PSSession, como los módulos disponibles en la sesión, los cmdlets que pueden ejecutarse, el modo de idioma, las cuotas y los tiempos de espera. El descriptor de seguridad de la configuración de sesión determina quién puede usar la configuración de sesión para conectarse al equipo local. Para obtener más información sobre las configuraciones de sesión, consulte about_Session_Configurations.

Para ver las propiedades de una configuración de sesión, use el cmdlet Get-PSSessionConfiguration o el proveedor WSMan. Para obtener más información sobre el proveedor WSMan, escriba Get-Help WSMan.

Ejemplos

Ejemplo 1: Creación y cambio de una configuración de sesión

En este ejemplo se muestra cómo agregar y quitar un script de inicio de una configuración.

El primer comando crea la configuración de AdminShell. El segundo comando agrega el script AdminConfig.ps1 a la configuración. El cambio es efectivo cuando se reinicia WinRM. El tercer comando quita el script AdminConfig.ps1 de la configuración.

Register-PSSessionConfiguration -Name "AdminShell" -AssemblyName "C:\Shells\AdminShell.dll" -ConfigurationTypeName "AdminClass"
Set-PSSessionConfiguration -Name "AdminShell" -StartupScript "AdminConfig.ps1"
Set-PSSessionConfiguration -Name "AdminShell" -StartupScript $Null

Ejemplo 2: Mostrar resultados

En este ejemplo se aumenta el valor de la propiedad maximumReceivedObjectSizeMB de a . Este comando también le pide que reinicie el servicio WinRM. El cambio no es efectivo hasta que se reinicie el servicio winRM de .

Set-PSSessionConfiguration -Name "IncObj" -MaximumReceivedObjectSizeMB 20

WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin\IncObj\InitializationParameters

ParamName                       ParamValue
---------                       ----------
psmaximumreceivedobjectsizemb   20

"Restart WinRM service"
WinRM service need to be restarted to make the changes effective. Do you want to run the command "restart-service winrm"?
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"): y

Ejemplo 3: Mostrar resultados de diferentes maneras

En este ejemplo, Set-PSSessionConfiguration cambia el script de inicio en la configuración de sesión de MaintenanceShell a Maintenance.ps1. La salida muestra el cambio y le pide que reinicie el servicio WinRM. La respuesta es y (sí).

obtiene la configuración de sesión de de MaintenanceShell. El operador de canalización (|) envía los resultados del comando a Format-List, que muestra todas las propiedades del objeto de configuración de una lista. A continuación, con el proveedor WSMan, se ven los parámetros de inicialización de la configuración de MaintenanceShell de . obtiene los elementos secundarios del nodo InitializationParameters de del complemento maintenanceShell de . Para obtener más información sobre el proveedor WSMan, escriba Get-Help wsman.

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

WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin\MaintenanceShell\InitializationParameters

ParamName            ParamValue
---------            ----------
startupscript        c:\ps-test\Mainte...

"Restart WinRM service"
WinRM service need to be restarted to make the changes effective. Do you want to run
the command "restart-service winrm"?
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"): y

Get-PSSessionConfiguration MaintenanceShell | Format-List -Property *

xmlns            : http://schemas.microsoft.com/wbem/wsman/1/config/PluginConfiguration
Name             : MaintenanceShell
Filename         : %windir%\system32\pwrshplugin.dll
SDKVersion       : 1
XmlRenderingType : text
lang             : en-US
PSVersion        : 2.0
startupscript    : c:\ps-test\Maintenance.ps1
ResourceUri      : http://schemas.microsoft.com/powershell/MaintenanceShell
SupportsOptions  : true
ExactMatch       : true
Capability       : {Shell}
Permission       :

Get-ChildItem WSMan:\localhost\Plugin\MaintenanceShell\InitializationParameters

ParamName     ParamValue
---------     ----------
PSVersion     2.0
startupscript c:\ps-test\Maintenance.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:

  • Disabled. Deshabilita la configuración de la sesión. No se puede usar para el acceso remoto o local al equipo. Este valor establece la propiedad Enabled de la configuración de sesión () en .
  • Local. Agrega una entrada Network_Deny_All al descriptor de seguridad de la configuración de sesión. Los usuarios del equipo local pueden usar la configuración de sesión para crear una sesión de bucle invertido local en el mismo equipo, pero a los usuarios remotos se les deniega el acceso.
  • Remote. Quita Deny_All y Network_Deny_All entradas de los descriptores de seguridad de la configuración de sesión. Los usuarios de equipos locales y remotos pueden 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 habilita todas las configuraciones de sesión en el equipo y permite el acceso remoto a ellas, y el cmdlet Disable-PSRemoting solo permite el acceso local a todas las configuraciones de sesión del equipo.

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) que se especifica en el valor del parámetro AssemblyName.

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 del ensamblado. Este cmdlet crea una configuración de sesión basada en una clase definida en un ensamblado.

Escriba el nombre de archivo o la ruta de acceso completa de un ensamblado .dll archivo que define una configuración de sesión. Si escribe solo el nombre de archivo, puede escribir la ruta de acceso en el valor del parámetro ApplicationBase.

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

-ConfigurationTypeName

Especifica el tipo de la configuración de sesión que se define en el ensamblado en el parámetro AssemblyName. El tipo que especifique debe implementar la clase System.Management.Automation.Remoting.PSSessionConfiguration.

Este parámetro es necesario cuando se especifica un nombre de ensamblado.

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

-Confirm

Le pide 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 del usuario y reinicia el servicio WinRM sin preguntar. Reiniciar el servicio hace que el cambio de configuración sea efectivo.

Para evitar un reinicio y suprimir el mensaje de reinicio, use 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 el límite de 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.

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. El valor de este parámetro se omite.

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 los límites de 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.

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. El valor de este parámetro se omite.

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

-ModulesToImport

Especifica los módulos y complementos que se importan automáticamente en sesiones que usan la configuración de sesión. Escriba los nombres del módulo y del complemento.

De forma predeterminada, solo se importa el módulo Microsoft.PowerShell.Core en sesiones, pero a menos que se excluyan los cmdlets, puede usar los cmdlets y para agregar módulos y complementos a la sesión.

Los módulos especificados en este valor de parámetro se importan además de los módulos especificados 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 módulos o impedir que los usuarios los usen.

Los módulos especificados en este valor de parámetro reemplazan la lista de módulos especificados por el parámetro ModulesToImport del cmdlet .

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 el nombre de la configuración de sesión que desea cambiar.

No puede usar este parámetro para cambiar el nombre de la configuración de sesión.

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

-NoServiceRestart

No reinicia el servicio WinRM y suprime el mensaje para reiniciar el servicio.

De forma predeterminada, al ejecutar Set-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 sin preguntar, use el parámetro Force . Para reiniciar manualmente el servicio winRM , use el cmdlet .

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 de un archivo de configuración de sesión (.pssc), como uno creado por el cmdlet New-PSSessionConfigurationFile. Si omite la ruta de acceso, el valor predeterminado es el directorio actual.

Para obtener información sobre cómo modificar un archivo de configuración de sesión, consulte el tema de ayuda del cmdlet New-PSSessionConfigurationFile.

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

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

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 diferente 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 Execute(Invoke) permiso para la configuración.

Para usar el descriptor de seguridad predeterminado para la configuración, escriba una cadena vacía ("") o un valor de $Null. El valor predeterminado es el SDDL raíz en la unidad WSMan:.

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

Tipo:String
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 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 con 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.

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

-ShowSecurityDescriptorUI

Cuando se usa este parámetro, el cmdlet abre una hoja de propiedades que le ayuda a crear un SDDL para la configuración de sesión. La hoja de propiedades aparece después de ejecutar el comando y, a continuación, reinicia el servicio winRM .

Al establecer permisos en la configuración, recuerde que los usuarios deben tener al menos Execute(Invoke) permiso 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 el script de inicio de la configuración. Escriba 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.

Para eliminar un script de inicio de una configuración de sesión, escriba una cadena vacía ("") o un valor de $Null.

Puede usar un script de inicio para configurar aún más la sesión de usuario. 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.

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
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-ThreadOptions

Especifica la configuración de opciones de subproceso en la configuración. Esta configuración define 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:

  • Default
  • 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 las opciones de transporte para la configuración de sesión. Escriba un objeto de opciones de transporte, como el objeto WSManConfigurationOption que devuelve el cmdlet New-PSTransportOption.

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

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

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

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 el cmdlet se ejecuta. 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

WSManConfigLeafElement

Notas

Este cmdlet solo está disponible en plataformas Windows.

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

El cmdlet Set-PSSessionConfiguration no cambia el nombre de configuración y el proveedor de WSMan no admite el cmdlet Rename-Item. Para cambiar el nombre de una configuración de sesión, use el cmdlet Unregister-PSSessionConfiguration para eliminar la configuración y, a continuación, use el cmdlet Register-PSSessionConfiguration para crear y registrar una nueva configuración de sesión.

Puede usar el cmdlet Set-PSSessionConfiguration para cambiar las configuraciones predeterminadas de Microsoft.PowerShell y Microsoft.PowerShell32 sesión. No están protegidos. Para revertir a la versión original de una configuración de sesión predeterminada, use el cmdlet Unregister-PSSessionConfiguration para eliminar la configuración de sesión predeterminada y, a continuación, use el cmdlet Enable-PSRemoting para restaurarla.

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

Puede usar comandos en la unidad de WSMan: para cambiar las propiedades de las configuraciones de sesión. Sin embargo, no puede usar la unidad de WSMan: en PowerShell 2.0 para cambiar las propiedades de configuración de sesión que se introducen en PowerShell 3.0, como OutputBufferingMode. Los comandos de Windows PowerShell 2.0 no generan un error, pero son ineficaces. Para cambiar las propiedades introducidas en PowerShell 3.0, use la unidad WSMan: en PowerShell 3.0 o posterior.