Compartir a través de

New-PSSession

  • Artículo

Crea una conexión persistente con un equipo local o remoto.

Sintaxis

New-PSSession [[-ComputerName] <string[]>] [-ApplicationName <string>] [-Authentication {<Default> | <Basic> | <Negotiate> | <NegotiateWithImplicitCredential> | <Credssp> | <Digest> | <Kerberos>}] [-CertificateThumbprint <string>] [-ConfigurationName <string>] [-Credential <PSCredential>] [-Name <string[]>] [-Port <int>] [-SessionOption <PSSessionOption>] [-UseSSL] [-ThrottleLimit <int>] [<CommonParameters>]

New-PSSession [[-Session] <PSSession[]>] [-Name <string[]>] [-ThrottleLimit <int>] [<CommonParameters>]

New-PSSession [-ConnectionURI] <Uri[]> [-AllowRedirection] [-Authentication {<Default> | <Basic> | <Negotiate> | <NegotiateWithImplicitCredential> | <Credssp> | <Digest> | <Kerberos>}] [-CertificateThumbprint <string>] [-ConfigurationName <string>] [-Credential <PSCredential>] [-Name <string[]>] [-SessionOption <PSSessionOption>] [-ThrottleLimit <int>] [<CommonParameters>]

Descripción

El cmdlet New-PSSession crea una sesión de Windows PowerShell (PSSession) en un equipo local o remoto. Cuando se crea una PSSession, Windows PowerShell establece una conexión persistente con el equipo remoto.

Utilice una PSSession para ejecutar varios comandos que comparten datos, como una función o el valor de una variable. Para ejecutar comandos en una PSSession, utilice el cmdlet Invoke-Command. Para utilizar la PSSession de modo que interactúe directamente con un equipo remoto, utilice el cmdlet Enter-PSSession. Para obtener más información, vea about_PSSessions.

Puede ejecutar comandos en un equipo remoto sin crear una PSSession utilizando los parámetros ComputerName de Enter-PSSession o Invoke-Command. Cuando se utiliza el parámetro ComputerName, Windows PowerShell crea una conexión temporal que se utiliza para la sesión interactiva o para un comando único y, a continuación, se cierra.

Parámetros

-AllowRedirection

Permite la redirección de esta conexión a un identificador uniforme de recursos (URI) alternativo.

Cuando se utiliza el parámetro ConnectionURI, el destino remoto puede devolver una instrucción de redirección a otro URI. De forma predeterminada, Windows PowerShell no redirige conexiones, pero se puede usar el parámetro AllowRedirection para permitir que se redirija la conexión.

Puede limitar igualmente el uso de veces que se redirige la conexión estableciendo la propiedad MaximumConnectionRedirectionCount de la variable de preferencia $PSSessionOption o la propiedad MaximumConnectionRedirectionCount del valor del parámetro SessionOption.

El valor predeterminado es 5. Para obtener más información, vea la descripción del parámetro SessionOption y vea New-PSSessionOption.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-ApplicationName <string>

Especifica el segmento del nombre de aplicación del identificador URI de la conexión. Utilice este parámetro para especificar el nombre de aplicación cuando no está utilizando el parámetro ConnectionURI del comando.

El valor predeterminado es el valor de la variable de preferencia $PSSessionApplicationName en el equipo local. Si no se define esta variable de preferencia, el valor predeterminado es "WSMAN". Este valor resulta apropiado en la mayoría de los casos. Para obtener más información, vea about_Preference_Variables.

El servicio WinRM utiliza el nombre de aplicación para seleccionar un agente de escucha a fin de atender la solicitud de conexión. El valor de este parámetro debe coincidir con el valor de la propiedad URLPrefix de un agente de escucha en el equipo remoto.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

WSMAN

¿Aceptar canalización?

true (ByPropertyName)

¿Aceptar caracteres comodín?

false

-Authentication <AuthenticationMechanism>

Especifica el mecanismo que se utiliza para autenticar las credenciales del usuario. Los valores válidos son "Default", "Basic", "Credssp", "Digest", "Kerberos", "Negotiate" y "NegotiateWithImplicitCredential". El valor predeterminado es "Default".

La autenticación CredSSP está disponible solo en Windows Vista, Windows Server 2008 y versiones posteriores de Windows.

Para obtener más información sobre los valores de este parámetro, vea la descripción de la enumeración System.Management.Automation.Runspaces.AuthenticationMechanism en MSDN (Microsoft Developer Network) Library, en https://go.microsoft.com/fwlink/?LinkID=144382.

Precaución: la autenticación Credential Security Service Provider (CredSSP), en la que las credenciales del usuario pasan a un equipo remoto para su autenticación, está diseñada para los comandos que requieren autenticación en más de un recurso, como acceso a un recurso compartido de red remota. Este mecanismo aumenta el riesgo que supone la operación remota para la seguridad. Si el equipo remoto está en peligro, las credenciales que se le pasen podrán usarse para controlar la sesión de red.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

Default

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-CertificateThumbprint <string>

Especifica el certificado de clave pública digital (X509) de una cuenta de usuario que tiene permiso para realizar esta acción. Escriba la huella digital del certificado.

Los certificados se usan en una autenticación basada en certificados del cliente. Pueden asignarse únicamente a cuentas de usuario locales; no funcionan con cuentas de dominio.

Para obtener la huella digital de un certificado, se usa el comando Get-Item o Get-ChildItem en la unidad Cert: de Windows PowerShell.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-ComputerName <string[]>

Crea una conexión persistente (PSSession) con el equipo especificado. Si escribe varios nombres de equipo, New-PSSession creará varias PSSessions, una para cada equipo. El valor predeterminado es el equipo local.

Se debe escribir el nombre NetBIOS, la dirección IP o el nombre de dominio completo de uno o varios equipos remotos. Para especificar el equipo local, escriba el nombre del equipo, "localhost", o bien, un punto (.). Cuando el equipo está en un dominio que no es el del usuario, se requiere el nombre de dominio completo. También se puede canalizar un nombre de equipo (entre comillas) a New-PSSession.

Para usar una dirección IP en el valor del parámetro ComputerName, el comando debe incluir el parámetro Credential. Se debe configurar igualmente el equipo para el transporte HTTPS o la dirección IP del equipo remoto debe estar incluida en la lista TrustedHosts de WinRM del equipo local. Para obtener instrucciones a fin de agregar un nombre de equipo a la lista TrustedHosts, vea el tema sobre cómo agregar un equipo a la lista de hosts de confianza en about_Remote_Troubleshooting.

Nota: en Windows Vista y versiones posteriores de Windows, para incluir el equipo local en el valor del parámetro ComputerName, se debe iniciar Windows PowerShell con la opción "Ejecutar como administrador".

¿Requerido?

false

¿Posición?

1

Valor predeterminado

¿Aceptar canalización?

true (ByValue, ByPropertyName)

¿Aceptar caracteres comodín?

false

-ConfigurationName <string>

Especifica la configuración de sesión que se usa para la nueva sesión de PowerShell.

Escriba un nombre de configuración o el identificador uniforme de recursos (URI) de recurso completo para una configuración de sesión. Si se especifica únicamente el nombre de configuración, se antepone el siguiente identificador URI de esquema: https://schemas.microsoft.com/powershell.

La configuración de una sesión se encuentra en el equipo remoto. Si la configuración de sesión especificada no existe en el equipo remoto, el comando generará un error.

El valor predeterminado es el valor de la variable de preferencia $PSSessionConfigurationName en el equipo local. Si esta variable de preferencia no está establecida, el valor predeterminado es Microsoft.PowerShell. Para obtener más información, vea about_Preference_Variables.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

¿Aceptar canalización?

true (ByPropertyName)

¿Aceptar caracteres comodín?

false

-ConnectionURI <Uri[]>

Especifica un identificador uniforme de recursos (URI) que define el extremo de la conexión. El identificador URI debe ser completo.

El formato de esta cadena es:

<Transporte>://<nombreDeEquipo>:<Puerto>/<nombreDeAplicación>

El valor predeterminado es.

https://localhost:80/WSMAN

Los valores válidos para el segmento Transport del URI son HTTP y HTTPS. Si no se especifica un ConnectionURI, se pueden utilizar los parámetros UseSSL, ComputerName, Port y ApplicationName para especificar los valores URI.

Si el equipo de destino redirige la conexión a un identificador URI diferente, Windows PowerShell impide la redirección, a menos que se use el parámetro AllowRedirection en el comando.

¿Requerido?

true

¿Posición?

1

Valor predeterminado

¿Aceptar canalización?

true (ByPropertyName)

¿Aceptar caracteres comodín?

false

-Credential <PSCredential>

Especifica una cuenta de usuario con permiso para realizar esta acción. El valor predeterminado es el usuario actual.

Escriba un nombre de usuario, como "Usuario01", "Dominio01\Usuario01" o "Usuario@Dominio.com", o bien, escriba un objeto PSCredential, como uno devuelto por el cmdlet Get-Credential.

Cuando escriba un nombre de usuario, se le solicitará una contraseña.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

¿Aceptar canalización?

true (ByPropertyName)

¿Aceptar caracteres comodín?

false

-Name <string[]>

Especifica un nombre simple para la PSSession.

Se puede utilizar el nombre para hacer referencia a la PSSession cuando se utilicen otros cmdlets, como Get-PSSession y Enter-PSSession. No se requiere que el nombre sea único en el equipo o la sesión actual.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-Port <int>

Especifica el puerto de red del equipo remoto que se utiliza para este comando. El valor predeterminado es el puerto 80 (puerto HTTP).

Antes de usar un puerto alternativo, debe configurar la escucha de WinRM en el equipo remoto para escuchar en ese puerto. Use los comandos siguientes para configurar la escucha:

1. winrm delete winrm/config/listener?Address=*+Transport=HTTP

2. winrm create winrm/config/listener?Address=*+Transport=HTTP @{Port=&quot;&lt;númeroDePuerto&gt;&quot;}

El parámetro Port no se debe usar a menos que sea imprescindible. La configuración del puerto del comando se aplica a todos los equipos y sesiones en que el comando se ejecuta. La configuración de un puerto alternativo puede impedir la ejecución del comando en todos los equipos.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

80

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-Session <PSSession[]>

Utiliza la PSSession especificada como modelo para la nueva PSSession. Este parámetro crea nuevas PSSessions con las mismas propiedades que las PSSessions especificadas.

Escriba una variable que contenga las PSSessions o un comando que las cree u obtenga, como un comando New-PSSession o Get-PSSession.

Las PSSessions resultantes tienen los mismos nombre de equipo, nombre de aplicación, URI de conexión, puerto, nombre de configuración, límite y valor de Capa de sockets seguros (SSL) que las originales, pero diferentes nombre simple, identificador e identificador de instancia (GUID).

¿Requerido?

false

¿Posición?

1

Valor predeterminado

¿Aceptar canalización?

true (ByValue, ByPropertyName)

¿Aceptar caracteres comodín?

false

-SessionOption <PSSessionOption>

Establece opciones avanzadas para la sesión. Se debe especificar un objeto SessionOption creado mediante el cmdlet New-PSSessionOption.

Los valores predeterminados para las opciones los determina el valor de la variable de preferencia $PSSessionOption, si se ha definido. De lo contrario, la sesión utiliza los valores predeterminados del sistema.

Para obtener una descripción de las opciones de sesión, incluidos los valores predeterminados, vea New-PSSessionOption. Para obtener información acerca de la variable de preferencia $PSSessionOption, vea about_Preference_Variables.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-ThrottleLimit <int>

Especifica el número máximo de conexiones simultáneas que se pueden establecer para ejecutar este comando. Si se omite este parámetro o se escribe el valor 0 (cero), se utilizará el valor predeterminado, 32.

Este límite se aplica únicamente al comando actual; no se aplica a la sesión ni al equipo.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

32

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

-UseSSL

Use el protocolo Capa de sockets seguros (SSL) para establecer una conexión con el equipo remoto. De forma predeterminada, no se usa SSL.

WS-Management cifra todo el contenido de Windows PowerShell que se transmite a través de la red. UseSSL es una protección adicional que envía los datos a través de una conexión HTTPS, en lugar de una conexión HTTP.

Si se usa este parámetro pero SSL no está disponible en el puerto utilizado para el comando, se producirá un error en el comando.

¿Requerido?

false

¿Posición?

named

Valor predeterminado

¿Aceptar canalización?

false

¿Aceptar caracteres comodín?

false

<CommonParameters>

Este cmdlet admite los parámetros comunes: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer y -OutVariable. Para obtener más información, vea about_Commonparameters.

Entradas y salidas

El tipo de entrada es el tipo de los objetos que se pueden canalizar al cmdlet. El tipo devuelto es el tipo de los objetos que el cmdlet devuelve.

Entradas

System.String, System.URI, System.Management.Automation.Runspaces.PSSession

Se puede canalizar un objeto ComputerName (cadena), ConnectionURI (URI) o Session (PSSession) a New-PSSession.

Salidas

System.Management.Automation.Runspaces.PSSession

Notas

Este cmdlet utiliza la infraestructura de comunicación remota de Windows PowerShell. Para usar este cmdlet, el equipo local y los equipos remotos deben estar configurados para la comunicación remota de Windows PowerShell. Para obtener más información, vea about_Remote_Requirements.

En Windows Vista y versiones posteriores de Windows, para crear una PSSession en el equipo local, debe iniciar Windows PowerShell con la opción "Ejecutar como administrador".

Cuando finalice la PSSession, debe utilizar el cmdlet Remove-PSSession para eliminarla y liberar sus recursos.

Ejemplo 1

C:\PS>$s = new-pssession

Descripción
-----------
Este comando crea una nueva PSSession en el equipo local y la guarda en la variable $s.

Puede utilizar esta PSSession para ejecutar comandos en el equipo local.

Ejemplo 2

C:\PS>$Server01 = new-pssession -ComputerName Server01

Descripción
-----------
Este comando crea una nueva PSSession en el equipo Server01 y la guarda en la variable $Server01. 

Si crea varias PSSessions, debe asignarlas a variables con nombres útiles. Esto le ayudará a administrar las PSSessions en comandos subsiguientes.

Ejemplo 3

C:\PS>$s1, $s2, $s3 = new-session -computername server1,server2,server3

Descripción
-----------
Este comando crea tres nuevas PSSessions, una en cada uno de los equipos especificados por el parámetro ComputerName. 

El comando utiliza el operador de asignación (=) para asignar las nuevas PSSessions a una matriz de variables: $s1, $s2, $s3. Asigna la PSSession de Server01 a $1, la PSSession de Server02 a $s2 y la PSSession de Server03 a $s3.

Cuando se asignan varios objetos a una matriz de variables, Windows PowerShell asigna cada objeto a una variable en la matriz, respectivamente. Si hay más objetos que variables, todos los objetos restantes se asignan a la última variable. Si hay más variables que objetos, las variables restantes quedan vacías (NULL).

Ejemplo 4

C:\PS>new-pssession -computername Server01 -port 8081 -useSSL -ConfigurationName E12

Descripción
-----------
Este comando crea una nueva PSSession en el equipo Server01 que se conecta al puerto de servidor 8081 y utiliza el protocolo SSL. La nueva PSSession utiliza una configuración de sesión alternativa denominada "E12".

Antes de configurar el puerto, debe configurar la escucha de WinRM en el equipo remoto para escuchar en el puerto 8081. Para obtener más información detallada, vea la descripción del parámetro Port.

Ejemplo 5

C:\PS>new-pssession -session $s -credential domain01\user01

Descripción
-----------
Este comando crea una nueva PSSession con las mismas propiedades que una PSSession existente. Puede utilizar este formato de comando cuando los recursos de una PSSession existente se agotan y se necesita una nueva PSSession para compartir una parte de la demanda.

El comando utiliza el parámetro Session de New-PSSession para especificar la PSSession guardada en la variable $s. Utiliza las credenciales del usuario Domain1\Admin01 para completar el comando.

Ejemplo 6

C:\PS>$global:s = new-pssession -computername server1.domain44.corpnet.fabrikam.com -credential domain01\admin01

Descripción
-----------
En este ejemplo se muestra la forma de crear una PSSession con un ámbito global en un equipo de un dominio diferente.

De forma predeterminada, las PSSessions creadas en la línea de comandos se crean con ámbito local y las creadas en un script tienen ámbito de script. 

Para crear una PSSession con ámbito global, cree una nueva PSSession y, a continuación, almacénela en una variable que se convierte a un ámbito global. En este caso, la variable $s se convierte a un ámbito global.

El comando utiliza el parámetro ComputerName para especificar el equipo remoto. Dado que el equipo está en un dominio que no es el de la cuenta de usuario, el nombre completo del equipo se especifica junto con las credenciales del usuario.

Ejemplo 7

C:\PS>$rs = get-content c:\test\servers.txt | new-PSsession -throttleLimit 50

Descripción
-----------
Este comando crea una PSSession en cada uno de los 200 equipos enumerados en el archivo Servers.txt y almacena la PSSession resultante en la variable $rs. El límite establecido para PSSessions es de 50.

Este formato de comando se puede utilizar cuando los nombres de los equipos se almacenan en una base de datos, una hoja de cálculo, un archivo de texto u otro formato de texto convertible.

Ejemplo 8

C:\PS>$s = new-PSSession -URI http://Server01:91/NewSession -credential domain01\user01

Descripción
-----------
Este comando crea una PSSession en el equipo Server01 y la almacena en la variable $s. Utiliza el parámetro URI para especificar el protocolo de transporte, el equipo remoto, el puerto y una configuración de sesión alternativa. También utiliza el parámetro Credential para especificar una cuenta de usuario con permiso para crear una sesión en el equipo remoto.

Ejemplo 9

C:\PS>$s = new-PSSession -computername (import-csv servers.csv) -credential domain01\admin01 -throttlelimit 16

C:\PS> invoke-command -session $s -scriptblock {get-process powershell} -AsJob

Descripción
-----------
Estos comandos crean un conjunto de PSSessions y, a continuación, ejecutan un trabajo en segundo plano en cada una de las PSSessions. 

El primer comando crea una nueva PSSession en cada uno de los equipos enumerados en el archivo Servers.csv. Utiliza el cmdlet New-PSSession para crear la PSSession. El valor del parámetro ComputerName es un comando que utiliza el cmdlet Import-Csv para importar el archivo Servers.csv y leer su contenido. 

El comando utiliza el parámetro Credential para crear las PSSessions con permiso de administrador de dominio y el parámetro ThrottleLimit para limitar el comando a 16 conexiones simultáneas. El comando guarda las PSSessions en la variable $s.
   
El segundo comando usa el parámetro AsJob de Invoke-Command para iniciar un trabajo en segundo plano que ejecuta un comando "Get-Process PowerShell" en cada una de las PSSessions contenidas en $s. 

Para obtener más información sobre los trabajos en segundo plano, vea about_Jobs y about_Remote_Jobs.

Ejemplo 10

C:\PS>new-PSSession -ConnectionURI https://management.exchangelabs.com/Management

Descripción
-----------
Este comando crea una nueva PSSession que se conecta a un equipo especificado por un identificador URI, en lugar de un nombre de equipo.

Ejemplo 11

C:\PS>$so = New-WSManSessionOption -SkipCACheck

PS C:\> new-pssession -ConnectionUri https://management.exchangelabs.com/Management -SessionOption $so -credential server01\admin01

Descripción
-----------
En este ejemplo se muestra la forma de crear y utilizar un parámetro SessionOption. 

El primer comando utiliza el cmdlet New-WSManSessionOption para crear una opción de sesión. Guarda el objeto SessionOption resultante en el parámetro $so.

El segundo comando usa la opción en una nueva sesión. El comando usa el cmdlet New-PSSession para crear una nueva sesión. El valor del parámetro SessionOption es el objeto SessionOption en la variable $so.

Vea también

Conceptos

about_PSSessions
about_Remote
Get-PSSession
Remove-PSSession
Enter-PSSession
Exit-PSSession
Invoke-Command