about_WorkflowCommonParameters
DESCRIPCIÓN BREVE
En este tema se describen los parámetros que son válidos en todos los comandos de flujo de trabajo de Windows PowerShell. Dado que el motor de Windows PowerShell los agrega a los flujos de trabajo, puede usar estos parámetros en cualquier flujo de trabajo y se habilitan automáticamente en los flujos de trabajo que crea.
DESCRIPCIÓN LARGA
Los parámetros comunes de flujo de trabajo de Windows PowerShell son un conjunto de parámetros de cmdlet que puede usar con todos los flujos de trabajo y actividades de Windows PowerShell. El motor de flujo de trabajo de Windows PowerShell los agrega, no el autor del flujo de trabajo, y están disponibles automáticamente en flujos de trabajo y actividades. Sin embargo, los flujos de trabajo anidados de tres niveles profundos no admiten ningún parámetro común, incluidos los parámetros comunes del flujo de trabajo.
Todos los parámetros de flujo de trabajo son opcionales y denominados (no posicionales). No toman la entrada de la canalización.
La mayoría de los parámetros comunes del flujo de trabajo tienen un PS prefijo, como PSComputerName y PSCredential. Los parámetros con prefijo PS configuran la conexión y el entorno de ejecución de los equipos de destino, también conocidos como "nodos remotos".
Muchos de los parámetros comunes del flujo de trabajo, como PSAllowRedirection y AsJob, tienen nombres similares a los parámetros usados en trabajos en segundo plano y comunicación remota de Windows PowerShell. Estos parámetros funcionan de la misma manera que los parámetros de trabajo y comunicación remota con nombre similar, por lo que puede usar el conocimiento que desarrolló en la comunicación remota y los trabajos para administrar flujos de trabajo.
Los flujos de trabajo se presentan en Windows PowerShell 3.0.
DESCRIPCIONES DE PARÁMETROS
En esta sección se describen los parámetros comunes del flujo de trabajo.
-AsJob <SwitchParameter>
Ejecuta el flujo de trabajo como un trabajo de flujo de trabajo. El comando de flujo de trabajo devuelve inmediatamente un objeto que representa un trabajo primario. El trabajo primario contiene los trabajos secundarios que se ejecutan en cada uno de los equipos de destino. Para administrar el trabajo, use los cmdlets Job. Para obtener los resultados del trabajo, use Receive-Job.
-JobName <String>
Especifica un nombre descriptivo para el trabajo de flujo de trabajo. De forma predeterminada, los trabajos se denominan Job<n>, donde <n> es un número ordinal.
Si usa el parámetro JobName en un comando de flujo de trabajo, el flujo de trabajo se ejecuta como un trabajo y el comando de flujo de trabajo devuelve un objeto de trabajo, aunque no incluya el parámetro AsJob en el comando.
Para obtener más información sobre los trabajos en segundo plano de Windows PowerShell, consulte about_Jobs.
-PSAllowRedirection <SwitchParameter>
Permite el redireccionamiento de la conexión a los equipos de destino.
Cuando se usa el parámetro PSConnectionURI , el destino remoto puede devolver una instrucción para redirigir a otro URI. De forma predeterminada, Windows PowerShell no redirige las conexiones, pero puede usar el parámetro PSAllowRedirection para permitir el redireccionamiento de la conexión al equipo de destino.
También puede limitar el número de veces que se redirige la conexión estableciendo la propiedad MaximumConnectionRedirectionCount de la $PSSessionOption variable de preferencia o la propiedad MaximumConnectionRedirectionCount del valor del parámetro PSSessionOption. El valor predeterminado es 5. Para obtener más información, consulte la descripción del parámetro PSSessionOption y New-PSSessionOption.
-PSApplicationName <String>
Especifica el segmento de nombre de aplicación del URI de conexión que se usa para conectarse a los equipos de destino. Use este parámetro para especificar el nombre de la aplicación cuando no use el parámetro ConnectionURI en el comando .
El valor predeterminado es el valor de la $PSSessionApplicationName variable de preferencia 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, consulte about_Preference_Variables.
El servicio WinRM usa el nombre de aplicación para seleccionar un agente de escucha que atienda 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.
-PSAuthentication <AuthenticationMechanism>
Especifica el mecanismo que se usa para autenticar las credenciales del usuario al conectarse a los equipos de destino.
Los valores válidos son:
DefaultBasicCredsspDigestKerberosNegotiateNegotiateWithImplicitCredential
El valor predeterminado es Default.
Para obtener información sobre los valores de este parámetro, consulte la descripción de la enumeración System.Management.Automation.Runspaces.AuthenticationMechanism en el SDK de PowerShell.
Advertencia
La autenticación del proveedor de servicios de seguridad de credenciales (CredSSP), en la que las credenciales del usuario se pasan a un equipo remoto para autenticarse, está diseñada para comandos que requieren autenticación en más de un recurso, como el acceso a un recurso compartido de red remoto. Este mecanismo el riesgo de seguridad de la operación remota. Si el equipo remoto se ve comprometido, las credenciales que se pasen a él se pueden utilizar para controlar la sesión de red.
-PSAuthenticationLevel AuthenticationLevel <>
Especifica el nivel de autenticación de las conexiones a los equipos de destino.
El valor predeterminado es Default.
Los valores válidos son:
| Nombre | Descripción |
|---|---|
Unchanged |
El nivel de autenticación es el mismo que el comando anterior. |
Default |
Autenticación de Windows. |
None |
Sin autenticación COM. |
Connect |
Autenticación COM de nivel de conexión. |
Call |
Autenticación COM de nivel de llamada. |
Packet |
Autenticación COM de nivel de paquete. |
PacketIntegrity |
Autenticación COM de nivel de integridad de paquetes. |
PacketPrivacy |
Autenticación COM de nivel de privacidad de paquetes. |
-PSCertificateThumbprint <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 para la autenticación basada en certificados de cliente. Solo se pueden asignar a cuentas de usuario locales, no funcionan con cuentas de dominio.
Para obtener un certificado, use los cmdlets Get-Item o Get-ChildItem en la unidad de Windows PowerShell Cert: .
-PSComputerName <String[]>
Especifica la lista de equipos que son los nodos de destino del flujo de trabajo. Los comandos o actividades de un flujo de trabajo se ejecutan en los equipos especificados mediante este parámetro. La opción predeterminada es el equipo local.
Escriba el nombre NETBIOS, la dirección IP o el nombre de dominio completo de uno o más equipos en una lista separada por comas. Para especificar el equipo local, escriba el nombre del equipo, localhosto un punto (.).
Para incluir el equipo local en el valor del parámetro PSComputerName , abra Windows PowerShell con la opción Ejecutar como administrador .
Si se omite este parámetro del comando, o bien es $null un valor o una cadena vacía, el destino del flujo de trabajo es el equipo local y la comunicación remota de Windows PowerShell no se usa para ejecutar el comando.
Para usar una dirección IP en el valor del parámetro ComputerName , el comando debe incluir el parámetro PSCredential . Además, el equipo debe estar configurado para el transporte HTTPS, o la dirección IP del equipo remoto debe incluirse en la lista WinRM TrustedHosts en el equipo local. Para obtener instrucciones para agregar un nombre de equipo a la lista TrustedHosts, consulte "Cómo agregar un equipo a la lista de hosts de confianza" about_Remote_Troubleshooting.
-PSConfigurationName <String>
Especifica las configuraciones de sesión que se usan para configurar sesiones en los equipos de destino. Escriba una configuración de sesión en los equipos de destino (no en el equipo del servidor de flujo de trabajo). El valor predeterminado es Microsoft.PowerShell.Workflow.
-PSConnectionRetryCount <UInt>
Especifica el número máximo de intentos para conectarse a cada equipo de destino si se produce un error en el primer intento de conexión. Escriba un número entre 1 y 4.294.967.295 (UInt.MaxValue). El valor predeterminado, cero (0), no representa ningún reintento.
-PSConnectionRetryIntervalSec <UInt>
Especifica el retraso entre los reintentos de conexión en segundos. El valor predeterminado es cero (0). Este parámetro solo es válido cuando el valor de PSConnectionRetryCount es al menos 1.
-PSConnectionURI <System.Uri>
Especifica un identificador uniforme de recursos (URI) que define el punto de conexión para el flujo de trabajo en el equipo de destino. El identificador URI debe ser completo.
El formato de esta cadena es:
<Transport>://<ComputerName>:<Port>/<ApplicationName>
El valor predeterminado es http://localhost:5985/WSMAN.
Si no especifica un PSConnectionURI, puede usar los parámetros PSUseSSL, PSComputerName, PSPort y PSApplicationName para especificar los valores de PSConnectionURI.
Los valores válidos para el segmento Transporte del URI son HTTP y HTTPS. Si especifica un URI de conexión con un segmento de transporte, pero no especifica un puerto, la sesión se crea con puertos estándar: 80 para HTTP y 443 PARA HTTPS. Para usar los puertos predeterminados para la comunicación remota de Windows PowerShell, especifique el puerto 5985 para HTTP o 5986 HTTPS.
-PSCredential PSCredential <>
Especifica una cuenta de usuario que tiene permiso para ejecutar un flujo de trabajo en el equipo de destino. El valor predeterminado es el usuario actual. Este parámetro solo es válido cuando el parámetro PSComputerName se incluye en el comando .
Escriba un nombre de usuario, como User01 o Domain01\User01, o escriba una variable que contenga un objeto PSCredential , como el que devuelve el Get-Credential cmdlet. Si escribe solo un nombre de usuario, se le pedirá una contraseña.
-PSElapsedTimeoutSec <UInt32>
Determina cuánto tiempo se mantiene el flujo de trabajo y todos los recursos relacionados en el sistema. Cuando expira el tiempo de espera, se elimina el flujo de trabajo, incluso si sigue procesando. Escriba un valor entre 10 y 4.294.967.295. El valor predeterminado, 0 (cero), significa que no hay tiempo de espera transcurrido.
-PSParameterCollection <Hashtable[]>
Especifica valores de parámetro comunes de flujo de trabajo diferentes para distintos equipos de destino.
Escriba una lista separada por comas de tablas hash con una tabla hash para cada equipo de destino. En cada tabla hash, la primera clave es PSComputerName y su valor es el nombre del equipo de destino. Se permiten caracteres comodín en el nombre del equipo. Para las claves restantes de la tabla hash, la clave es el nombre del parámetro y el valor es el valor del parámetro.
Por ejemplo:
-PSParameterCollection @{PSComputerName="*"; PSElapsedTimeoutSec=20},
@{PSComputerName="Server02"},
@{PSComputerName="Server03"},
@{PSComputerName="Server01"; PSElapsedTimeoutSec=10}
En el ejemplo anterior, todas las conexiones tendrán una PSElapsedTimeoutSec predeterminada de 20 segundos, excepto server01, que invalida el valor predeterminado especificando su propio tiempo de espera de 10 segundos.
-PSPersist <Boolean>
Agrega puntos de control al flujo de trabajo, además de los puntos de control especificados en el flujo de trabajo.
Este parámetro no puede suprimir los puntos de control de un flujo de trabajo, como los especificados mediante el parámetro común de actividad PSPersist , la Checkpoint-Workflow actividad o la $PSPersistPreference variable.
Un "punto de control" o "punto de persistencia" es una instantánea del estado del flujo de trabajo y los datos que se capturan mientras el flujo de trabajo se ejecuta y se guarda en un almacén de persistencia en el disco o en una base de datos SQL. Flujo de trabajo de Windows PowerShell usa los datos guardados para reanudar un flujo de trabajo suspendido o interrumpido desde el último punto de persistencia, en lugar de reiniciar el flujo de trabajo.
Los valores válidos son:
(Valor predeterminado) Si omite este parámetro, se agrega un punto de control al principio y al final del flujo de trabajo, además de los puntos de control especificados en el flujo de trabajo.
$True. Agrega un punto de control al principio y al final del flujo de trabajo y un punto de control después de cada actividad, además de los puntos de control especificados en el flujo de trabajo.$False. No se agregan puntos de control. Los puntos de control solo se toman cuando se especifican en el flujo de trabajo.
-PSPort <Int32>
Especifica el puerto de red en los equipos de destino. Los puertos predeterminados son 5985 (el puerto winRM para HTTP) y 5986 (el puerto winRM para HTTPS).
No use el parámetro PSPort a menos que deba. El puerto establecido en el comando se aplica a todos los equipos o sesiones en los que se ejecuta el comando. Una configuración de puerto alternativo podría impedir que el comando se ejecutara en todos los equipos. Antes de usar un puerto alternativo, debe configurar el agente de escucha de WinRM en el equipo remoto para poder escuchar en ese puerto.
-PSPrivateMetadata <Hashtable>
Proporciona información personalizada para los trabajos de flujo de trabajo. Escriba una tabla hash. Las claves y los valores se personalizan para cada flujo de trabajo. Para obtener información sobre los metadatos privados de un flujo de trabajo, consulte el tema de ayuda del flujo de trabajo.
El motor de flujo de trabajo de Windows PowerShell no procesa este parámetro. En su lugar, el motor pasa la tabla hash directamente al flujo de trabajo.
-PSRunningTimeoutSec <UInt32>
Especifica el tiempo de ejecución del flujo de trabajo en segundos, excepto en cualquier momento en que se suspenda el flujo de trabajo. Si la ejecución del flujo de trabajo no se completa cuando expira el tiempo, el motor de flujo de trabajo de Windows PowerShell detiene forzosamente la ejecución del flujo de trabajo.
-PSSessionOption <PSSessionOption>
Establece opciones avanzadas para las sesiones en los equipos de destino. Escriba un objeto PSSessionOption , como uno que cree mediante el New-PSSessionOption cmdlet .
Los valores predeterminados de las opciones de sesión se determinan mediante el valor de la $PSSessionOption variable de preferencia, si se establece. De lo contrario, la sesión usa los valores especificados en la configuración de la sesión.
Para obtener una descripción de las opciones de sesión, incluidos los valores predeterminados, consulte New-PSSessionOption.
Para obtener información sobre la $PSSessionOption variable de preferencia, consulte about_Preference_Variables.
-PSUseSSL <SwitchParameter>
Usa el protocolo Capa de sockets seguros (SSL) para establecer una conexión con el equipo de destino. De forma predeterminada, no se usa SSL.
WS-Management cifra todo el contenido de Windows PowerShell que se transmite por la red. UseSSL es una protección adicional que envía los datos a través de HTTPS, en lugar de HTTP. Si se usa este parámetro, pero SSL no está disponible en el puerto utilizado para el comando, el comando producirá un error.
