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 el 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 cada propiedad se puede 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 variable de $PSSessionOption 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 obtener más información sobre las configuraciones de sesión, consulte 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:00

Ejemplo 2: Configurar 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 $pso

El 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: Inicio de 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:00

Utilice 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 120000

Cuando 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 variable de $PSSessionOption 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

Este ejemplo muestra cómo usar un objeto SessionOption para satisfacer 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 $SkipCN

El 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 necesita 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 más información, consulte about_Hash_Tables, about_Session_Configurations y about_Automatic_Variables.

Type:PSPrimitiveDictionary
Position:Named
Default value:None
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
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
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 valor 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 de 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
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, 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, vea Información general sobre Setspn.

Este parámetro se incorporó en Windows PowerShell 3.0.

Type:SwitchParameter
Position:Named
Default value:None
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
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
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 omite este parámetro, el valor predeterminado es 209715200 bytes (o 200MB).

Type:Int32
Position:Named
Default value:209715200
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 todas las redirecciones.

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
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
Accept pipeline input:False
Accept wildcard characters:False

-NoEncryption

Desactiva el cifrado de datos.

Type:SwitchParameter
Position:Named
Default value:None
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
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)
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.

OperationTimeoutno 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)
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 o Drop invalida la opción de transporte del modo de almacenamiento en búfer de Block 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
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:

  • IEConfig
  • WinHttpConfig
  • AutoDetect
  • NoProxyServer
  • None

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

  • Basic
  • Digest
  • Negotiate

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
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 obtiene 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
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
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
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
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, como ja-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
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
Accept pipeline input:False
Accept wildcard characters:False

Entradas

None

No se puede canalizar la entrada a este cmdlet.

Salidas

PSSessionOption

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 $PSSessionOption variable, consulte 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.