Compartir a través de


New-PSSessionOption

Crea un objeto que contiene opciones avanzadas para una PSSession.

Sintaxis

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 cmdlet New-PSSessionOption 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 de cmdlets que crean un 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 preferencia $PSSessionOption. 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 preferencia de $PSSessionOption, consulte about_Preference_Variables.

Cuando se usa un objeto sessionOption de 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 variable de preferencia $PSSessionOption y en la configuración de sesión. Sin embargo, no tienen prioridad sobre los valores máximos, cuotas o 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: 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 de 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 variable $pso. El segundo comando usa el cmdlet New-PSSession para crear una sesión en el equipo remoto Server01. El comando usa el objeto SessionOption en el valor de la variable $pso como valor del parámetro sessionOption del comando.

Ejemplo 3: Iniciar una sesión interactiva

Este comando usa el cmdlet Enter-PSSession 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 comando New-PSSessionOption que tiene los parámetros NoEncryption y noCompression.

El comando New-PSSessionOption se incluye entre paréntesis para asegurarse de que se ejecuta antes del comando Enter-PSSession.

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

Use este método para crear un objeto de sesión estándar para su empresa y, a continuación, crear versiones personalizadas de él para usos concretos.

Ejemplo 5: Crear una variable de preferencia

Este comando crea una variable de preferencia $PSSessionOption.

$PSSessionOption = New-PSSessionOption -OpenTimeOut 120000

Cuando la variable de preferencia $PSSessionOption se establece en la sesión, establece valores predeterminados para las opciones de las sesiones que se crean con los cmdlets New-PSSession, Enter-PSSessiony Invoke-Command.

Para que la variable $PSSessionOption 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 preferencia de $PSSessionOption, consulte about_Preference_Variables. Para obtener más información sobre los perfiles, vea 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 de 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 $SkipCN

El primer comando usa el cmdlet New-PSSessionOption para crear un objeto SessionOption que tenga la propiedad SkipCNCheck. El comando guarda el objeto de sesión resultante en la variable $skipCN.

El segundo comando usa el cmdlet New-PSSession para crear una nueva sesión en un equipo remoto. La variable check $skipCN 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 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 cmdlet New-PSSessionOption 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 variable $team. Para obtener más información sobre las tablas hash, consulte about_Hash_Tables.

A continuación, el cmdlet New-PSSessionOption, mediante el parámetro applicationArguments , crea un objeto SessionOption guardado en la variable $team. Cuando New-PSSessionOption crea el objeto de opción de sesión, convierte automáticamente la tabla hash en el valor de la parámetro ApplicationArguments en un PrimitiveDictionary para que los datos se puedan transmitir de forma confiable a la sesión remota.

El cmdlet New-PSSession inicia una sesión en el equipo Server01. Usa el parámetro SessionOption para incluir las opciones en la variable $teamOption.

El cmdlet Invoke-Command muestra que los datos de la variable $team están disponibles para los comandos de la sesión remota. Los datos aparecen en la propiedad ApplicationArguments de la variable automática $PSSenderInfo.

El Invoke-Command final 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 la sesión, pueden encontrar este diccionario en la propiedad ApplicationArguments de la variable automática $PSSenderInfo. Puede usar este parámetro para enviar datos a la sesión remota.

Para obtener más información, vea about_Hash_Tables, about_Session_Configurationsy about_Automatic_Variables.

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

-CancelTimeout

Determina cuánto tiempo espera PowerShell para que una operación de cancelación (CTRL+C) finalice 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.

Tipo:Int32
Alias:CancelTimeoutMSec
Posición:Named
Valor predeterminado:60000
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-Culture

Especifica la referencia cultural que se va a usar para la sesión. Escriba un nombre de referencia cultural en formato <languagecode2>-<country/regioncode2> (como ja-JP), una variable que contenga un objeto CultureInfo o un comando que obtenga un objeto CultureInfo.

El valor predeterminado es $Nully la referencia cultural establecida en el sistema operativo se usa en la sesión.

Tipo:CultureInfo
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín: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 expire 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 la sesión no ha agotado el tiempo de espera.

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 del IdleTimeoutMs propiedad 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 MaxIdleTimeoutMs propiedad de la configuración de la sesión, se produce un error en el comando para crear una sesión.

El valor de IdleTimeoutMs del configuración de sesión de de Microsoft.PowerShell predeterminado es 7200000 milisegundos (2 horas). Su valor de 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, consulte Disconnect-PSSession y Connect-PSSession.

En Windows PowerShell 2.0, el valor predeterminado del parámetro IdleTimeout es 240000 (4 minutos).

Tipo:Int32
Alias:IdleTimeoutMSec
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín: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 que un cliente que use un SPN no predeterminado se autentique en un equipo remoto que use la autenticación Kerberos.

La opción está diseñada para empresas en las que se ejecutan varios servicios que admiten la autenticación Kerberos en diferentes 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 mediante Setspn.exe, que están registrados en diferentes cuentas de usuario y pueden distinguir entre ellos incluyendo el número de puerto en el SPN.

Para obtener más información, consulte Información general de Setspn.

Este parámetro se introdujo en Windows PowerShell 3.0.

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

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

-MaximumReceivedDataSizePerCommand

Especifica el número máximo de bytes que el equipo local puede recibir del equipo remoto en un solo comando. Escriba 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 en el equipo cliente.

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

-MaximumReceivedObjectSize

Especifica el tamaño máximo de un objeto que el equipo local puede recibir del equipo remoto. Esta opción está diseñada para proteger los recursos en el equipo cliente. Escriba un valor en bytes.

En Windows PowerShell 2.0, si 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).

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

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

-NoCompression

Desactiva la compresión de paquetes en la sesión. La compresión usa más ciclos de procesador, pero hace que la transmisión sea más rápida.

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

-NoEncryption

Desactiva el cifrado de datos.

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

-NoMachineProfile

Impide cargar el perfil de usuario de Windows del usuario. Como resultado, la sesión podría crearse más rápido, pero la configuración del Registro específica del usuario, elementos como variables de entorno y certificados no están disponibles en la sesión.

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

-OpenTimeout

Determina cuánto tiempo espera el equipo cliente para que se establezca la conexión de sesión. Cuando expire el intervalo, se produce un error en el comando para establecer la conexión. 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.

Tipo:Int32
Alias:OpenTimeoutMSec
Posición:Named
Valor predeterminado:180000 (3 minutes)
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-OperationTimeout

Determina el tiempo máximo 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 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.

Tipo:Int32
Alias:OperationTimeoutMSec
Posición:Named
Valor predeterminado:180000 (3 minutes)
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-OutputBufferingMode

Determina cómo se administra la salida del comando en 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 del 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 aceptables para este parámetro son:

  • Block. Cuando el búfer de salida está lleno, la ejecución se suspende hasta que se borra el búfer.
  • Drop. Cuando el búfer de salida está lleno, la ejecución continúa. A medida que se guarda la nueva salida, se descarta la salida más antigua.
  • None. No se especifica 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, consulte New-PSTransportOption.

Este parámetro se introdujo en Windows PowerShell 3.0.

Tipo:OutputBufferingMode
Valores aceptados:None, Drop, Block
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-ProxyAccessType

Determina qué mecanismo se usa para resolver el nombre de host. Los valores aceptables para este parámetro son:

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

Tipo:ProxyAccessType
Valores aceptados:None, IEConfig, WinHttpConfig, AutoDetect, NoProxyServer
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-ProxyAuthentication

Especifica el método de autenticación que se usa para la resolución de proxy. Los valores aceptables para este parámetro son:

  • Basic
  • Digest
  • Negotiate

El valor predeterminado es Negotiate.

Para obtener más información sobre los valores de este parámetro, vea AuthenticationMechanism Enumeration.

Tipo:AuthenticationMechanism
Valores aceptados:Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos
Posición:Named
Valor predeterminado:Negotiate
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-ProxyCredential

Especifica las credenciales que se van a usar para la autenticación de proxy. Escriba una variable que contenga un objeto PSCredential o un comando que obtenga un objeto de PSCredential, como un comando Get-Credential. Si no se establece esta opción, no se especifica ninguna credencial.

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

Use esta opción solo cuando el equipo remoto sea de confianza mediante otro mecanismo, como cuando el equipo remoto forma parte de una red que es físicamente segura y aislada o cuando el equipo remoto aparece como un host de confianza en una configuración de WinRM.

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

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

-SkipRevocationCheck

No valida el estado de revocación del certificado de servidor.

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

-UICulture

Especifica la referencia cultural de la interfaz de usuario que se va a usar para la sesión.

Entre los valores válidos se incluyen:

  • Un nombre de referencia cultural en formato de <languagecode2>-<country/regioncode2>, como ja-JP
  • Variable que contiene un objeto cultureInfo de
  • Comando que obtiene un objeto cultureInfo de , 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.

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

-UseUTF16

Indica que este cmdlet codifica la solicitud en formato UTF16 en lugar del formato UTF8.

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

Entradas

None

No se pueden canalizar objetos 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 variable de preferencia $PSSessionOption, si se establece. Para obtener más información sobre la variable de $PSSessionOption, vea about_Preference_Variables.

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.