Acerca de 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 prefijo PS, 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 los trabajos remotos y en segundo plano 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 <(Cadena)>

Especifica un nombre descriptivo para el trabajo de flujo de trabajo. De forma predeterminada, los trabajos se denominan "Trabajo<n>", donde <n> es un número ordinal.

Si utiliza 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, incluso si no incluye el AsJob parámetro 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 utiliza el PSConnectionURI parámetro, el destino remoto puede devolver una instrucción para redirigir a un URI diferente. De forma predeterminada, Windows PowerShell no redirige las conexiones, pero puede usar el PSAllowRedirection parámetro 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 MaximumConnectionRedirectionCount propiedad de la $PSSessionOption variable de preferencia o la MaximumConnectionRedirectionCount propiedad del valor de .PSSessionOption parameter El valor predeterminado es 5. Para obtener más información, consulte la descripción del PSSessionOption parámetro y New-PSSessionOption.

-PSApplicationName <(Cadena)>

Especifica el segmento de nombre de aplicación del URI de conexión que se usa para conectarse a los equipos de destino. Utilice este parámetro para especificar el nombre de la aplicación cuando no utilice el ConnectionURI parámetro en el 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 es adecuado para la mayoría de los usos. Para obtener más información, consulte about_Preference_Variables.

El servicio WinRM usa el nombre de la aplicación para seleccionar un agente de escucha para atender la solicitud de conexión. El valor de este parámetro debe coincidir con el valor de la URLPrefix propiedad 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:

• Predeterminado
• Básico
• Credssp
• Resumen
• Kerberos
• Negociar
• NegotiateWithImplicitCredential

El valor predeterminado es Default.

Para obtener información acerca de los valores de este parámetro, vea la descripción de la System.Management.Automation.Runspaces.AuthenticationMechanism enumeración en MSDN.

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

-PSCertificateCadena de huella <digital>

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

Los certificados se usan en 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] (xref:Microsoft.PowerShell.Management.Get-Childitem) en la unidad Cert: de Windows PowerShell.

-PSComputerName <Cadena[]>

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. El valor predeterminado 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, "localhost" o un punto (.).

Para incluir el equipo local en el valor del PSComputerName parámetro, 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 utilizar una dirección IP en el valor del ComputerName parámetro, el comando debe incluir el PSCredential parámetro. Además, el equipo debe configurarse para el transporte HTTPS o la dirección IP del equipo remoto debe incluirse en la lista WinRM TrustedHosts del equipo local. Para obtener instrucciones sobre cómo agregar un nombre de equipo a la lista TrustedHosts, consulte "Cómo agregar un equipo a la lista de hosts de confianza" en about_Remote_Troubleshooting.

-PSConfigurationName <(Cadena)>

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), representa que no hay reintentos.

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

<Transport>://<ComputerName>:<Port>/<ApplicationName>

El valor predeterminado es https://localhost:5985/WSMAN.

Si no especifica un PSConnectionURI, puede utilizar los PSUseSSLparámetros , PSComputerName, PSPorty PSApplicationName para especificar los PSConnectionURI valores.

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 para 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 está incluido en el comando.

Escriba un nombre de usuario, como "Usuario01" o "Dominio01\Usuario01", o escriba una variable que contenga un PSCredential objeto, como uno que devuelva 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 un valor predeterminado de PSElapsedTimeoutSec de 20 segundos, excepto Server01, que invalida el valor predeterminado especificando su propio tiempo de espera de 10 segundos.

-PSPersist <booleano>

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 activity PSPersist , la Checkpoint-Workflow activity 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.

Valores válidos:

• (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 utilice el parámetro PSPort a menos que sea necesario. 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 alternativa podría impedir que el comando se ejecute en todos los equipos. Antes de usar un puerto alternativo, debe configurar el agente de escucha winRM en el equipo remoto para que escuche 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 PSSessionOption objeto, 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 el tema de ayuda del New-PSSessionOption cmdlet (xref:Microsoft.PowerShell.Core.New-PSSessionOption). Para obtener información sobre la variable de preferencia de $PSSessionOption, vea 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 transmitido a través de la red. UseSSL es una protección adicional que envía los datos a través de un HTTPS, en lugar de HTTP. Si usa este parámetro, pero SSL no está disponible en el puerto usado para el comando, se produce un error en el comando.

VÉASE TAMBIÉN

• about_ActivityCommonParameters
• about_Workflows
• Invoke-AsWorkflow
• New-PSWorkflowExecutionOption
• New-PSWorkflowSession