New-PSSessionOption
Crea un objeto que contiene las opciones avanzadas de una PSSession.
Syntax
New-PSSessionOption
[-MaximumRedirection <Int32>]
[-NoCompression]
[-NoMachineProfile]
[-Culture <CultureInfo>]
[-UICulture <CultureInfo>]
[-MaximumReceivedDataSizePerCommand <Int32>]
[-MaximumReceivedObjectSize <Int32>]
[-OutputBufferingMode <OutputBufferingMode>]
[-MaxConnectionRetryCount <Int32>]
[-ApplicationArguments <PSPrimitiveDictionary>]
[-OpenTimeout <Int32>]
[-CancelTimeout <Int32>]
[-IdleTimeout <Int32>]
[-ProxyAccessType <ProxyAccessType>]
[-ProxyAuthentication <AuthenticationMechanism>]
[-ProxyCredential <PSCredential>]
[-SkipCACheck]
[-SkipCNCheck]
[-SkipRevocationCheck]
[-OperationTimeout <Int32>]
[-NoEncryption]
[-UseUTF16]
[-IncludePortInSPN]
[<CommonParameters>] Description
El New-PSSessionOption cmdlet crea un objeto que contiene opciones avanzadas para una sesión administrada por el usuario (PSSession). Puede usar el objeto como valor del parámetro SessionOption de cmdlets que crean una PSSession, como New-PSSession, Enter-PSSessiony Invoke-Command.
Sin parámetros, New-PSSessionOption genera un objeto que contiene los valores predeterminados para todas las opciones. Dado que todas las propiedades se pueden editar, puede usar el objeto resultante como plantilla y crear objetos de opción estándar para su empresa.
También puede guardar un objeto SessionOption en la variable de $PSSessionOption preferencia. Los valores de esta variable establecen nuevos valores predeterminados para las opciones de sesión. Son eficaces cuando no se establecen opciones de sesión para la sesión y tienen prioridad sobre las opciones establecidas en la configuración de sesión, pero puede invalidarlos especificando opciones de sesión o un objeto SessionOption en un cmdlet que crea una sesión. Para obtener más información sobre la $PSSessionOption variable de preferencia, consulte about_Preference_Variables.
Cuando se usa un objeto SessionOption en un cmdlet que crea una sesión, los valores de opción de sesión tienen prioridad sobre los valores predeterminados de las sesiones establecidas en la $PSSessionOption variable de preferencia y en la configuración de sesión. Sin embargo, no tienen precedencia sobre los valores máximos, las cuotas o los límites establecidos en la configuración de sesión. Para más información sobre las configuraciones de sesión, vea about_Session_Configurations.
Ejemplos
Ejemplo 1: Crear una opción de sesión predeterminada
Este comando crea un objeto SessionOption con los valores predeterminados.
New-PSSessionOption
MaximumConnectionRedirectionCount : 5
NoCompression : False
NoMachineProfile : False
ProxyAccessType : IEConfig
ProxyAuthentication : Negotiate
ProxyCredential :
SkipCACheck : False
SkipCNCheck : False
SkipRevocationCheck : False
OperationTimeout : 00:03:00
NoEncryption : False
UseUTF16 : False
Culture :
UICulture :
MaximumReceivedDataSizePerCommand :
MaximumReceivedObjectSize :
ApplicationArguments :
OpenTimeout : 00:03:00
CancelTimeout : 00:01:00
IdleTimeout : 00:04:00Ejemplo 2: Configuración de una sesión mediante un objeto de opción de sesión
En este ejemplo se muestra cómo usar un objeto SessionOption para configurar una sesión.
$pso = New-PSSessionOption -Culture "fr-fr" -MaximumReceivedObjectSize 10MB
New-PSSession -ComputerName Server01 -SessionOption $psoEl primer comando crea un nuevo objeto SessionOption y lo guarda en el valor de la $pso variable. El segundo comando usa el New-PSSession cmdlet para crear una sesión en el equipo remoto Server01. El comando usa el objeto SessionOption en el valor de la $pso variable como valor del parámetro SessionOption del comando.
Ejemplo 3: Iniciar una sesión interactiva
Este comando usa el Enter-PSSession cmdlet para iniciar una sesión interactiva con el equipo Server01.
Enter-PSSession -ComputerName Server01 -SessionOption (New-PSSessionOption -NoEncryption -NoCompression)El valor del parámetro SessionOption es un New-PSSessionOption comando que tiene los parámetros NoEncryption y NoCompression .
El New-PSSessionOption comando se incluye entre paréntesis para asegurarse de que se ejecuta antes del Enter-PSSession comando.
Ejemplo 4: Modificación de un objeto de opción de sesión
En este ejemplo se muestra que puede modificar el objeto SessionOption . Todas las propiedades tienen valores de lectura y escritura.
$a = New-PSSessionOption
$a.OpenTimeout
Days : 0
Hours : 0
Minutes : 3
Seconds : 0
Milliseconds : 0
Ticks : 1800000000
TotalDays : 0.00208333333333333
TotalHours : 0.05
TotalMinutes : 3
TotalSeconds : 180
TotalMilliseconds : 180000
$a.UICulture = (Get-UICulture)
$a.OpenTimeout = (New-Timespan -Minutes 4)
$a.MaximumConnectionRedirectionCount = 1
$a
MaximumConnectionRedirectionCount : 1
NoCompression : False
NoMachineProfile : False
ProxyAccessType : IEConfig
ProxyAuthentication : Negotiate
ProxyCredential :
SkipCACheck : False
SkipCNCheck : False
SkipRevocationCheck : False
OperationTimeout : 00:03:00
NoEncryption : False
UseUTF16 : False
Culture :
UICulture : en-US
MaximumReceivedDataSizePerCommand :
MaximumReceivedObjectSize :
ApplicationArguments :
OpenTimeout : 00:04:00
CancelTimeout : 00:01:00
IdleTimeout : 00:04:00Utilice este método para crear un objeto de sesión estándar para la empresa y crear después versiones personalizadas del mismo para usos concretos.
Ejemplo 5: Crear una variable de preferencia
Este comando crea una $PSSessionOption variable de preferencia.
$PSSessionOption = New-PSSessionOption -OpenTimeOut 120000Cuando la $PSSessionOption variable de preferencia se establece en la sesión, establece valores predeterminados para las opciones de las sesiones que se crean con los New-PSSessioncmdlets , Enter-PSSessiony Invoke-Command .
Para que la $PSSessionOption variable esté disponible en todas las sesiones, agréguela a la sesión de PowerShell y al perfil de PowerShell.
Para obtener más información sobre la $PSSessionOption variable de preferencia, consulte about_Preference_Variables.
Para obtener más información sobre los perfiles, consulte about_Profiles.
Ejemplo 6: Cumplir los requisitos de una configuración de sesión remota
En este ejemplo se muestra cómo usar un objeto SessionOption para cumplir los requisitos de una configuración de sesión remota.
$skipCN = New-PSSessionOption -SkipCNCheck
New-PSSession -ComputerName 171.09.21.207 -UseSSL -Credential Domain01\User01 -SessionOption $SkipCNEl primer comando usa el New-PSSessionOption cmdlet para crear un objeto SessionOption que tenga la propiedad SkipCNCheck . El comando guarda el objeto de sesión resultante en la $skipCN variable .
El segundo comando usa el New-PSSession cmdlet para crear una nueva sesión en un equipo remoto. La $skipCN variable check se usa en el valor del parámetro SessionOption .
Dado que el equipo se identifica mediante su dirección IP, el valor del parámetro ComputerName no coincide con ninguno de los nombres comunes del certificado que se usa para Capa de sockets seguros (SSL). Como resultado, se requiere la opción SkipCNCheck .
Ejemplo 7: Hacer que los argumentos estén disponibles para una sesión remota
En este ejemplo se muestra cómo usar el parámetro ApplicationArguments del New-PSSessionOption cmdlet para que los datos adicionales estén disponibles para la sesión remota.
$team = @{Team="IT"; Use="Testing"}
$TeamOption = New-PSSessionOption -ApplicationArguments $team
$s = New-PSSession -ComputerName Server01 -SessionOption $TeamOption
Invoke-Command -Session $s {$PSSenderInfo.ApplicationArguments}
Name Value
---- -----
Team IT
Use Testing
PSVersionTable {CLRVersion, BuildVersion, PSVersion, WSManStackVersion...}
Invoke-Command -Session $s {
if ($PSSenderInfo.ApplicationArguments.Use -ne "Testing") {
.\logFiles.ps1
}
else {
"Just testing."
}
}
Just testing.El primer comando crea una tabla hash con dos claves, Team y Use. El comando guarda la tabla hash en la $team variable . Para obtener más información sobre las tablas hash, consulte about_Hash_Tables.
A continuación, el New-PSSessionOption cmdlet, mediante el parámetro ApplicationArguments , crea un objeto SessionOption guardado en la $team variable . Cuando New-PSSessionOption crea el objeto de opción de sesión, convierte automáticamente la tabla hash en el valor del parámetro ApplicationArguments en un PrimitiveDictionary para que los datos se puedan transmitir de forma confiable a la sesión remota.
El New-PSSession cmdlet inicia una sesión en el equipo Server01. Usa el parámetro SessionOption para incluir las opciones en la $teamOption variable.
El Invoke-Command cmdlet muestra que los datos de la $team variable están disponibles para los comandos de la sesión remota. Los datos aparecen en la propiedad ApplicationArguments de la $PSSenderInfo variable automática.
La final Invoke-Command muestra cómo se pueden usar los datos.
Parámetros
-ApplicationArguments
Especifica un PrimitiveDictionary que se envía a la sesión remota. Los comandos y scripts de la sesión remota, incluidos los scripts de inicio de la configuración de sesión, pueden encontrar este diccionario en la propiedad ApplicationArguments de la $PSSenderInfo variable automática. Puede usar este parámetro para enviar datos a la sesión remota.
Para obtener más información, consulte about_Hash_Tables, about_Session_Configurations y about_Automatic_Variables.
| Type: | PSPrimitiveDictionary |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-CancelTimeout
Determina cuánto tiempo espera PowerShell a que finalice una operación de cancelación (CTRL+C) antes de finalizarla. Escriba un valor en milisegundos.
El valor predeterminado es 60000 (un minuto). Un valor de 0 (cero) significa que no se agota el tiempo de espera; el comando continúa indefinidamente.
| Type: | Int32 |
| Aliases: | CancelTimeoutMSec |
| Position: | Named |
| Default value: | 60000 |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Culture
Especifica la referencia cultural que se usará para la sesión. Escriba un nombre de referencia cultural en <languagecode2>-<country/regioncode2> formato (como ja-JP), una variable que contiene un objeto CultureInfo o un comando que obtiene un objeto CultureInfo .
El valor predeterminado es $Nully la referencia cultural establecida en el sistema operativo se usa en la sesión.
| Type: | CultureInfo |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-IdleTimeout
Determina cuánto tiempo permanece abierta la sesión si el equipo remoto no recibe ninguna comunicación del equipo local. Esto incluye la señal de latido. Cuando expira el intervalo, se cierra la sesión.
El valor de tiempo de espera de inactividad es de importancia importante si piensa desconectar y volver a conectarse a una sesión. Solo puede volver a conectarse si no se ha agotado el tiempo de espera de la sesión.
Escriba un valor en milisegundos. El valor mínimo es 60000 (1 minuto). El máximo es el valor de la propiedad MaxIdleTimeoutms de la configuración de sesión. El valor predeterminado, -1, no establece un tiempo de espera de inactividad.
La sesión usa el tiempo de espera de inactividad establecido en las opciones de sesión, si existe. Si no se establece ninguno (-1), la sesión usa el valor de la propiedad IdleTimeoutMs de la configuración de sesión o el valor de tiempo de espera del shell de WSMan (WSMan:\<ComputerName>\Shell\IdleTimeout), lo que sea más corto.
Si el tiempo de espera de inactividad establecido en las opciones de sesión supera el valor de la propiedad MaxIdleTimeoutMs de la configuración de sesión, se produce un error en el comando para crear una sesión.
El valor IdleTimeoutMs de la configuración de sesión predeterminada de Microsoft.PowerShell es 7200000 milisegundos (2 horas). Su valor MaxIdleTimeoutMs es 2147483647 milisegundos (>24 días). El valor predeterminado del tiempo de espera de inactividad del shell WSMan (WSMan:\<ComputerName>\Shell\IdleTimeout) es 7200000 milisegundos (2 horas).
El valor de tiempo de espera de inactividad de una sesión también se puede cambiar al desconectar de una sesión o volver a conectarse a una sesión. Para obtener más información, vea Disconnect-PSSession y Connect-PSSession.
En Windows PowerShell 2.0, el valor predeterminado del parámetro IdleTimeout es 240000 (4 minutos).
| Type: | Int32 |
| Aliases: | IdleTimeoutMSec |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-IncludePortInSPN
Incluye el número de puerto en el nombre de entidad de seguridad de servicio (SPN) usado para la autenticación Kerberos, por ejemplo, HTTP://<ComputerName>:5985. Esta opción permite a un cliente que usa un SPN no predeterminado autenticarse en un equipo remoto que usa la autenticación Kerberos.
La opción está diseñada para empresas donde se ejecutan varios servicios que admiten la autenticación Kerberos con distintas cuentas de usuario. Por ejemplo, una aplicación IIS que permite la autenticación Kerberos puede requerir que el SPN predeterminado se registre en una cuenta de usuario que difiere de la cuenta de equipo. En tales casos, la comunicación remota de PowerShell no puede usar Kerberos para autenticarse porque requiere un SPN registrado en la cuenta de equipo. Para resolver este problema, los administradores pueden crear diferentes SPN, como, por ejemplo, mediante Setspn.exe, que están registrados en diferentes cuentas de usuario y pueden distinguir entre ellos mediante la inclusión del número de puerto en el SPN.
Para obtener más información, consulte Información general sobre Setspn.
Este parámetro se incorporó en Windows PowerShell 3.0.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-MaxConnectionRetryCount
Especifica el número de veces que PowerShell intenta realizar una conexión a una máquina de destino si se produce un error en el intento actual debido a problemas de red. El valor predeterminado es 5.
Este parámetro se agregó para PowerShell versión 5.0.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-MaximumReceivedDataSizePerCommand
Especifica el número máximo de bytes que el equipo local puede recibir desde el equipo remoto en un solo comando. Especifique un valor en bytes. De forma predeterminada, no hay ningún límite de tamaño de datos.
Esta opción está diseñada para proteger los recursos del equipo cliente.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-MaximumReceivedObjectSize
Especifica el tamaño máximo de un objeto que el equipo local puede recibir desde el equipo remoto. Esta opción está diseñada para proteger los recursos del equipo cliente. Especifique un valor en bytes.
En Windows PowerShell 2.0, si se omite este parámetro, no hay ningún límite de tamaño de objeto. A partir de Windows PowerShell 3.0, si se omite este parámetro, el valor predeterminado es 209715200 bytes (o 200MB).
| Type: | Int32 |
| Position: | Named |
| Default value: | 209715200 |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-MaximumRedirection
Determina cuántas veces PowerShell redirige una conexión a un identificador uniforme de recursos (URI) alternativo antes de que se produzca un error en la conexión. El valor predeterminado es 5. Un valor de 0 (cero) impide toda la redirección.
Esta opción solo se usa en la sesión cuando se usa el parámetro AllowRedirection en el comando que crea la sesión.
| Type: | Int32 |
| Position: | Named |
| Default value: | 5 |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-NoCompression
Desactiva la compresión de paquetes en la sesión. La compresión usa más ciclos de procesador, pero acelera la transmisión.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-NoEncryption
Desactiva el cifrado de datos.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-NoMachineProfile
Evita que se cargue el perfil de usuario de Windows. Como resultado, la sesión se podría crear más rápidamente, pero la configuración del Registro específica del usuario, los elementos como las variables de entorno y los certificados no están disponibles en la sesión.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-OpenTimeout
Determina cuánto tiempo espera el equipo cliente para que se establezca la conexión de la sesión. Cuando el intervalo expira, el comando de establecimiento de la conexión produce un error. Escriba un valor en milisegundos.
El valor predeterminado es 180000 (3 minutos). Un valor de 0 (cero) significa que no se agota el tiempo de espera; el comando continúa indefinidamente.
| Type: | Int32 |
| Aliases: | OpenTimeoutMSec |
| Position: | Named |
| Default value: | 180000 (3 minutes) |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-OperationTimeout
Determina el tiempo máximo en que WinRM espera pruebas de conexión positivas desde una conexión activa antes de iniciar un tiempo de espera de conexión. Para obtener más información sobre WinRM, consulte la documentación de administración remota de Windows.
OperationTimeout no impone un límite de tiempo en los comandos o procesos que se ejecutan en una sesión remota y no afecta a otros protocolos de comunicación remota como SSH.
El valor predeterminado es 180000 (3 minutos). Un valor de 0 (cero) significa que no se agota el tiempo de espera.
| Type: | Int32 |
| Aliases: | OperationTimeoutMSec |
| Position: | Named |
| Default value: | 180000 (3 minutes) |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-OutputBufferingMode
Determina cómo se administra el resultado del comando en las sesiones desconectadas cuando el búfer de salida se llena.
Si el modo de almacenamiento en búfer de salida no está establecido en la sesión o en la configuración de la sesión, el valor predeterminado es Block. Los usuarios también pueden cambiar el modo de almacenamiento en búfer de salida al desconectar la sesión.
Si omite este parámetro, el valor de OutputBufferingMode del objeto SessionOption es None. Un valor de Block o Drop invalida la opción de transporte del modo de almacenamiento en búfer de salida establecida en la configuración de sesión. Los valores permitidos para este parámetro son los siguientes:
Block. cuando el búfer de salida está lleno, la ejecución se suspende hasta que el búfer se vacíe.Drop. cuando el búfer de salida está lleno, la ejecución continúa. Conforme se guarda el nuevo resultado, se descarta el resultado más antiguo.None. no se ha especificado ningún modo de almacenamiento en búfer de salida.
Para obtener más información sobre la opción de transporte del modo de almacenamiento en búfer de salida, vea New-PSTransportOption.
Este parámetro se incorporó en Windows PowerShell 3.0.
| Type: | OutputBufferingMode |
| Accepted values: | None, Drop, Block |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ProxyAccessType
Determina qué mecanismo se usa para resolver el nombre de host. Los valores permitidos para este parámetro son los siguientes:
IEConfigWinHttpConfigAutoDetectNoProxyServerNone
El valor predeterminado es None.
Para obtener información sobre los valores de este parámetro, vea ProxyAccessType (enumeración).
| Type: | ProxyAccessType |
| Accepted values: | None, IEConfig, WinHttpConfig, AutoDetect, NoProxyServer |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ProxyAuthentication
Especifica el método de autenticación que se usa para la resolución de proxy. Los valores permitidos para este parámetro son los siguientes:
BasicDigestNegotiate
El valor predeterminado es Negotiate.
Para obtener más información sobre los valores de este parámetro, vea AuthenticationMechanism (enumeración).
| Type: | AuthenticationMechanism |
| Accepted values: | Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos |
| Position: | Named |
| Default value: | Negotiate |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ProxyCredential
Especifica las credenciales que se usarán para la autenticación de proxy. Escriba una variable que contenga un objeto PSCredential o un comando que obtenga un objeto PSCredential, como un Get-Credential comando. Si no se establece esta opción, no se especifica ninguna credencial.
| Type: | PSCredential |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SkipCACheck
Especifica que cuando se conecta a través de HTTPS, el cliente no valida que el certificado de servidor esté firmado por una entidad de certificación (CA) de confianza.
Utilice esta opción solo si el equipo remoto es de confianza mediante otro mecanismo, por ejemplo, cuando el equipo remoto es parte de una red que es físicamente segura y aislada o cuando el equipo remoto está designado como host de confianza en una configuración de WinRM.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SkipCNCheck
Especifica que el nombre común (CN) del certificado del servidor no tiene que coincidir con el nombre de host del servidor. Esta opción solo se usa en operaciones remotas que usan el protocolo HTTPS.
Use esta opción solo para equipos de confianza.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SkipRevocationCheck
No valida el estado de revocación del certificado del servidor.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-UICulture
Especifica la referencia cultural de la interfaz de usuario que se usará para la sesión.
Los valores válidos son:
- Un nombre de referencia cultural en
<languagecode2>-<country/regioncode2>formato, comoja-JP - Variable que contiene un objeto CultureInfo
- Comando que obtiene un objeto CultureInfo , como
Get-Culture
El valor predeterminado es $nully la referencia cultural de la interfaz de usuario que se establece en el sistema operativo cuando se crea la sesión.
| Type: | CultureInfo |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-UseUTF16
Indica que este cmdlet codifica la solicitud en formato UTF16 en lugar del formato UTF8.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Entradas
None
No se pueden canalizar objetos a este cmdlet.
Salidas
Notas
Si el parámetro SessionOption no se usa en un comando para crear una PSSession, las opciones de sesión se determinan mediante los valores de propiedad de la $PSSessionOption variable de preferencia, si se establece. Para obtener más información sobre la variable $PSSessionOption, vea about_Preference_Variables.
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.
Vínculos relacionados
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de