Set-PSSessionConfiguration
Cambia las propiedades de una configuración de sesión registrada.
Syntax
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
El Set-PSSessionConfiguration
cmdlet cambia las propiedades de las configuraciones de sesión en el equipo local.
Utilice el parámetro Name para identificar la configuración de sesión que quiere cambiar. Utilice los otros parámetros para especificar los nuevos valores de 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 e intuitivo para establecer y cambiar las propiedades de las sesiones que utilizan 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, consulte about_Session_Configuration_Files.
Para obtener información sobre cómo crear y modificar un archivo de configuración de sesión, consulte el New-PSSessionConfigurationFile
cmdlet .
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 de la PSSession, como los módulos que están 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 Get-PSSessionConfiguration
cmdlet o el proveedor WSMan. Para obtener más información sobre el proveedor WSMan, escriba Get-Help WSMan
.
Ejemplos
Ejemplo 1: Cambiar el estado del apartamento del subproceso
PS C:\> Set-PSSessionConfiguration -Name "MaintenanceShell" -ThreadApartmentState STA
Este comando cambia el estado de apartamento de subproceso en la configuración de MaintenanceShell a STA. El cambio es efectivo al reiniciar el servicio WinRM .
Ejemplo 2: Create y cambiar 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 AdminConfig.ps1
script a la configuración. El cambio es efectivo al reiniciar WinRM.
El tercer comando quita el AdminConfig.ps1
script 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 3: Mostrar resultados
En este ejemplo se aumenta el valor de la propiedad MaximumReceivedObjectSizeMB a 20. Este comando también le pide que reinicie el servicio WinRM . El cambio no es efectivo hasta que se reinicie el servicio WinRM .
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 4: Mostrar resultados de diferentes maneras
En este ejemplo, Set-PSSessionConfiguration
cambia el script de inicio de 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í).
Get-PSSessionConfiguration
obtiene la configuración de la sesión 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 en una lista. A continuación, con el proveedor WSMan, se ven los parámetros de inicialización para la configuración de MaintenanceShell . Get-ChildItem
(alias dir
) obtiene los elementos secundarios en el nodo InitializationParameters del complemento MaintenanceShell . Para obtener más información sobre el proveedor WSMan, escriba Get-Help wsman
.
PS> 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
PS> Get-PSSessionConfiguration MaintenanceShell | Format-List -Property *
xmlns : https://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 : https://schemas.microsoft.com/powershell/MaintenanceShell
SupportsOptions : true
ExactMatch : true
Capability : {Shell}
Permission :
PS> dir 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 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 utilizar para el acceso remoto o local al equipo. Este valor establece la propiedad Enabled de la configuración de sesión (
WSMan:\<ComputerName>\PlugIn\<SessionConfigurationName>\Enabled
) en False. - 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 (Remotas). quita las entradas Deny_All y Network_Deny_All de los descriptores de seguridad de la configuración de sesión. Los usuarios de equipos locales y remotos pueden 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 habilita todas las configuraciones de sesión en el equipo y permite el acceso remoto a ellas, y el Disable-PSRemoting
cmdlet solo permite el acceso local a todas las configuraciones de sesión del equipo.
Este parámetro se introdujo en PowerShell 3.0.
Type: | PSSessionConfigurationAccessMode |
Accepted values: | Disabled, Local, Remote |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ApplicationBase
Especifica la ruta de acceso del archivo de ensamblado (*.dll) que se especifica en el valor del parámetro AssemblyName .
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | 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 .
Type: | String |
Position: | 1 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | 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 especificado debe implementar la clase System.Management.Automation.Remoting.PSSessionConfiguration.
Este parámetro es necesario cuando se especifica un nombre de ensamblado.
Type: | String |
Position: | 2 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Confirm
Le solicita su confirmación antes de ejecutar el cmdlet.
Type: | SwitchParameter |
Aliases: | cf |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Force
Suprime todas las solicitudes del 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, utilice el parámetro NoServiceRestart.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaximumReceivedDataSizePerCommandMB
Especifica el límite de 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. El valor de este parámetro se ha omitido.
Type: | Double |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaximumReceivedObjectSizeMB
Especifica los límites de la cantidad de datos que se pueden enviar a este equipo en cualquier objeto único. 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. El valor de este parámetro se ha omitido.
Type: | Double |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ModulesToImport
Especifica los módulos y complementos que se importan automáticamente a las sesiones que utilizan la configuración de sesión. Especifique los nombres de los módulos y complementos.
De forma predeterminada, solo el complemento Microsoft.PowerShell.Core se importa en sesiones, pero a menos que se excluyan los cmdlets, puede usar los Import-Module
cmdlets y Add-PSSnapin 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 los módulos o impedir que los usuarios los utilicen.
Los módulos especificados en este valor de parámetro reemplazan la lista de módulos especificados mediante el parámetro ModulesToImport del Register-PSSessionConfiguration
cmdlet .
Este parámetro se introdujo en PowerShell 3.0.
Type: | Object[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Name
Especifica el nombre de la configuración de sesión que quiere cambiar.
No puede utilizar este parámetro para cambiar el nombre de la configuración de sesión.
Type: | String |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-NoServiceRestart
No reinicia el servicio WinRM y suprime la solicitud 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 el servicio WinRM manualmente, use el Restart-Service
cmdlet .
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Path
Especifica la ruta de acceso de un archivo de configuración de sesión (.pssc), como uno creado por el New-PSSessionConfigurationFile
cmdlet . 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 New-PSSessionConfigurationFile
cmdlet .
Este parámetro se introdujo en PowerShell 3.0.
Type: | String |
Position: | Named |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | 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.
Type: | Version |
Aliases: | PowerShellVersion |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | 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.
Type: | PSCredential |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SecurityDescriptorSddl
Especifica una cadena del lenguaje de definición de descriptores de seguridad (SDDL) diferente 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 Execute(Invoke) 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 la cadena 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 utilizar ambos parámetros en el mismo comando.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SessionTypeOption
Especifica las 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 las opciones 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.
Type: | PSSessionTypeOption |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ShowSecurityDescriptorUI
Indica que este cmdlet es una hoja de propiedades que le ayuda a crear un nuevo SDDL para la configuración de sesión. La hoja de propiedades aparece después de ejecutar el Set-PSSessionConfiguration
comando y, a continuación, reinicia el servicio WinRM .
Al establecer permisos en la configuración, recuerde que los usuarios deben tener al menos permiso Execute(Invoke) para usar la configuración de sesión en una sesión.
No puede utilizar el parámetro SecurityDescriptorSDDL y este parámetro en el mismo comando.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-StartupScript
Especifica el script de inicio para la configuración. Escriba 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.
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 New-PSSession
comando.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ThreadApartmentState
Especifica la configuración de estado del apartamento para los subprocesos de la sesión. Los valores aceptables para este parámetro son: STA, MTA y Unknown. El valor predeterminado es Desconocido.
Type: | ApartmentState |
Accepted values: | STA, MTA, Unknown |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ThreadOptions
Especifica el valor de opciones de subproceso en la configuración. Esta opción de configuración define cómo se crean y se utilizan los subprocesos cuando se ejecuta un comando en la sesión. Los valores permitidos para este parámetro son los siguientes:
- Default
- ReuseThread
- UseCurrentThread
- UseNewThread
El valor predeterminado es UseCurrentThread.
Para obtener más información, vea Enumeración PSThreadOptions.
Type: | PSThreadOptions |
Accepted values: | Default, UseNewThread, ReuseThread, UseCurrentThread |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | 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 New-PSTransportOption
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 las opciones 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.
Type: | PSTransportOption |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-UseSharedProcess
Use solo un proceso para hospedar todas las sesiones iniciadas por el mismo usuario y use 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.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-WhatIf
Muestra lo que sucedería si se ejecutara el cmdlet. El cmdlet no se ejecuta.
Type: | SwitchParameter |
Aliases: | wi |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Entradas
None
No se puede canalizar la entrada a este cmdlet.
Salidas
Notas
Para ejecutar este cmdlet, inicie PowerShell mediante la opción Ejecutar como administrador.
El Set-PSSessionConfiguration
cmdlet no cambia el nombre de configuración y el proveedor WSMan no admite el Rename-Item
cmdlet . Para cambiar el nombre de una configuración de sesión, use el Unregister-PSSessionConfiguration
cmdlet para eliminar la configuración y, a continuación, use el Register-PSSessionConfiguration
cmdlet para crear y registrar una nueva configuración de sesión.
Puede usar el Set-PSSessionConfiguration
cmdlet para cambiar las configuraciones de sesión predeterminadas de Microsoft.PowerShell y Microsoft.PowerShell32. No están protegidas. Para revertir a la versión original de una configuración de sesión predeterminada, use el Unregister-PSSessionConfiguration
cmdlet para eliminar la configuración de sesión predeterminada y, a continuación, use el Enable-PSRemoting
cmdlet para restaurarla.
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.
Puede utilizar comandos en la unidad WSMan: para cambiar las propiedades de las configuraciones de sesión. Sin embargo, no puede usar la unidad 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 no tienen efecto. Para cambiar las propiedades introducidas en PowerShell 3.0, use la unidad WSMan: en PowerShell 3.0.
Vínculos relacionados
- Disable-PSSessionConfiguration
- Enable-PSSessionConfiguration
- Get-PSSessionConfiguration
- New-PSSessionConfigurationFile
- New-PSSessionOption
- New-PSTransportOption
- New-PSWorkflowExecutionOption
- Register-PSSessionConfiguration
- Test-PSSessionConfigurationFile
- Unregister-PSSessionConfiguration
- Proveedor de WSMan
- about_Session_Configurations
- about_Session_Configuration_Files