Acerca de ActivityCommonParameters

DESCRIPCIÓN BREVE

Describe los parámetros que el flujo de trabajo de Windows PowerShell agrega a las actividades.

DESCRIPCIÓN LARGA

El flujo de trabajo de Windows PowerShell agrega los parámetros comunes de la actividad a las actividades que se derivan de la clase base PSActivity. Esta categoría incluye la actividad InlineScript y los cmdlets de Windows PowerShell que se implementan como actividades, como Get-Process y Get-WinEvent.

Los parámetros comunes de la actividad no son válidos en las actividades Suspend-Workflow y Checkpoint-Workflow y no se agregan a cmdlets o expresiones que el flujo de trabajo de Windows PowerShell ejecuta automáticamente en un bloque de script InlineScript o una actividad similar. Los parámetros comunes de la actividad están disponibles en la actividad InlineScript, pero no en los comandos del bloque de script InlineScript.

Varios de los parámetros comunes de actividad también son parámetros comunes de flujo de trabajo o parámetros comunes de Windows PowerShell. Otros parámetros comunes de actividad son únicos para las actividades.

Para obtener información sobre los parámetros comunes del flujo de trabajo, consulte about_WorkflowCommonParameters. Para obtener información sobre los parámetros comunes de Windows PowerShell, consulte about_CommonParameters.

LISTA DE PARÁMETROS COMUNES DE ACTIVIDAD

AppendOutput                      PSDebug
Debug                             PSDisableSerialization
DisplayName                       PSDisableSerializationPreference
ErrorAction                       PSError
Input                             PSPersist
MergeErrorToOutput                PSPort
PSActionRetryCount                PSProgress
PSActionRetryIntervalSec          PSProgressMessage
PSActionRunningTimeoutSec         PSRemotingBehavior
PSApplicationName                 PSRequiredModules
PSAuthentication                  PSSessionOption
PSCertificateThumbprint           PSUseSSL
PSComputerName                    PSVerbose
PSConfigurationName               PSWarning
PSConnectionRetryCount            Result
PSConnectionRetryIntervalSec      UseDefaultInput
PSConnectionURI                   Verbose
PSCredential                      WarningAction

DESCRIPCIONES DE PARÁMETROS

En esta sección se describen los parámetros comunes de la actividad.

AppendOutput <(valor booleano)>

Un valor de $True agrega la salida de la actividad al valor de la variable. Un valor de $False no tiene ningún efecto. De forma predeterminada, asignar un valor a una variable reemplaza el valor de la variable.

Por ejemplo, los siguientes comandos agregan un objeto de proceso al objeto de servicio en la $x variable .

Workflow Test-Workflow
{
    $x = Get-Service
    $x = Get-Process -AppendOutput $true
}

Este parámetro está diseñado para flujos de trabajo basados en XAML. En los flujos de trabajo de scripts, también puede utilizar el operador de asignación += para agregar salida al valor de una variable, como se muestra en el ejemplo siguiente.

Workflow Test-Workflow
{
    $x = Get-Service
    $x += Get-Process
}

Depurar <SwitchParameter>

Muestra detalles de nivel de programador sobre la operación realizada por el comando. El parámetro Debug reemplaza el valor de la variable $DebugPreference para el comando actual. Este parámetro solo funciona cuando el comando genera mensajes de depuración. Este parámetro también es un parámetro común de Windows PowerShell.

Cadena DisplayName <>

Especifica un nombre descriptivo para la actividad. El valor DisplayName aparece en la barra de progreso mientras se ejecuta el flujo de trabajo y en el valor de la propiedad Progress del trabajo de flujo de trabajo. Cuando el parámetro PSProgressMessage también se incluye en el comando, el contenido de la barra de progreso aparece en <formato DisplayName>:<PSProgressMessage> .

Acción ErrorActionPreference <>

Determina cómo responde la actividad a un error de no terminación del comando . No tiene ningún efecto en los errores de terminación. Este parámetro solo funciona cuando el comando genera un error que no termina, como los del cmdlet Write-Error. El parámetro ErrorAction invalida el valor de la variable $ErrorActionPreference para el comando actual. Este parámetro también es un parámetro común de Windows PowerShell.

Valores válidos:

• Continuar. Muestra el mensaje de error y continúa ejecutando el comando. "Continuar" es el valor predeterminado.

• Ignorar. Suprime el mensaje de error y continúa ejecutando el comando. A diferencia de SilentlyContinue, Ignore no agrega el mensaje de error a la variable automática $Error. El valor Ignore se introduce en Windows PowerShell 3.0.

• Preguntar. Muestra el mensaje de error y le pide confirmación antes de continuar la ejecución. Este valor rara vez se usa.

• Suspender. Suspende automáticamente un trabajo de flujo de trabajo para permitir una investigación más detallada. Después de la investigación, se puede reanudar el flujo de trabajo.

• Continuar en silencio. Suprime el mensaje de error y continúa ejecutando el comando.

• Detener. Muestra el mensaje de error y deja de ejecutar el comando.

Objeto Input <[]>

Envía una colección de objetos a una actividad. Esta es una alternativa a canalizar los objetos a la actividad de uno en uno.

MergeErrorToOutput <(valor booleano)>

Valor de $True agrega errores al flujo de salida. Un valor de $False no tiene efecto. Utilice este parámetro con las palabras clave Parallel y ForEach -Parallel para recopilar errores y resultados de varios comandos paralelos en una sola colección.

PSActionRetryCount <Int32>

Intenta ejecutar repetidamente la actividad si se produce un error en el primer intento. El valor predeterminado, 0, no se vuelve a intentar.

PSActionRetryIntervalSec <Int32>

Determina el intervalo entre reintentos de acción en segundos. El valor predeterminado, 0, vuelve a intentar la acción inmediatamente. Este parámetro solo es válido cuando el parámetro PSActionRetryCount también se usa en el comando.

PSActionRunningTimeoutSec <Int32>

Determina cuánto tiempo se puede ejecutar la actividad en cada equipo de destino. Si la actividad no se completa antes de que expire el tiempo de espera, el flujo de trabajo de Windows PowerShell genera un error de terminación y deja de procesar el flujo de trabajo en el equipo de destino afectado.

PSAllowRedirection <- valor booleano>

Un valor de $True permite la redirección de la conexión a los equipos de destino. Un valor de $False no tiene ningún efecto. Este parámetro común de actividad también es un parámetro común de flujo de trabajo.

Cuando se usa el parámetro PSConnectionURI, 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 parámetro PSAllowRedirection con un valor de $True 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 SSessionOption de los cmdlets que crean una sesión. El valor predeterminado es 5.

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. Use este parámetro para especificar el nombre de la aplicación cuando no use el parámetro ConnectionURI en el comando . Este parámetro común de actividad también es un parámetro común de flujo de trabajo.

El valor predeterminado es el valor de la $PSSessionApplicationName variable de preferencia en el equipo de destino. 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 propiedad URLPrefix de un agente de escucha en el equipo remoto.

Autenticación de PSAuthenticationMechanism <>

Especifica el mecanismo que se usa para autenticar las credenciales del usuario al conectarse a los equipos de destino. Los valores válidos son Default, Basic, Credssp, Digest, Kerberos, Negotiate y NegotiateWithImplicitCredential. El valor predeterminado es Default. Este parámetro común de actividad también es un parámetro común de flujo de trabajo.

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

Cadena PSCertificateThumbprint <>

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. Este parámetro común de actividad también es un parámetro común de flujo de trabajo.

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 en la unidad Cert: de Windows PowerShell.

PSComputerName <Cadena[]>

Especifica los equipos de destino en los que se ejecuta la actividad. El valor predeterminado es el equipo local. Este parámetro común de actividad también es un parámetro común de flujo de trabajo.

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 parámetro PSComputerName, abra Windows PowerShell con la opción "Ejecutar como administrador".

Si este parámetro se omite en el comando, o su valor es $null 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 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 para agregar un nombre de equipo a la lista TrustedHosts, vea "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 crear sesiones en los equipos de destino. Escriba el nombre de una configuración de sesión en los equipos de destino (no en el equipo que ejecuta el flujo de trabajo. El valor predeterminado es Microsoft.PowerShell. Este parámetro común de actividad también es un parámetro común de flujo de trabajo.

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. Este parámetro común de actividad también es un parámetro común de flujo de trabajo.

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. Este parámetro común de actividad también es un parámetro común de flujo de trabajo.

PSConnectionURI <System.Uri>

Especifica un identificador uniforme de recursos (URI) que define el punto de conexión para la actividad en el equipo de destino. El identificador URI debe ser completo. Este parámetro común de actividad también es un parámetro común de flujo de trabajo.

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 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 para HTTPS.

PSCredential <PSCredential>

Especifica una cuenta de usuario que tiene permiso para ejecutar la actividad 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. Este parámetro común de actividad también es un parámetro común de flujo de trabajo.

Escriba un nombre de usuario, como "User01" o "Domain01\User01", o escriba una variable que contenga un objeto PSCredential, como uno que devuelva el cmdlet Get-Credential. Si escribe solo un nombre de usuario, se le pedirá una contraseña.

PSDebug <PSDataCollection[DebugRecord]>

Agrega mensajes de depuración de la actividad a la colección de registros de depuración especificada, en lugar de escribir los mensajes de depuración en la consola o en el valor de la propiedad Debug del trabajo de flujo de trabajo. Puede agregar mensajes de depuración de varias actividades al mismo objeto de colección de registros de depuración.

Para usar este parámetro común de actividad, use el cmdlet New-Object para crear un objeto PSDataCollection con un tipo DebugRecord y guarde el objeto en una variable. A continuación, use la variable como el valor del parámetro PSDebug de una o varias actividades, como se muestra en el ejemplo siguiente.

Workflow Test-Workflow
{
    $debugCollection = New-Object -Type `
    System.Management.Automation.PSDataCollection[System.Management.Automation.DebugRecord]
    InlineScript {\Server01\Share01\Get-AssetData.ps1} -PSDebug $debugCollection -Debug $True
    InlineScript {\Server01\Share01\Set-AssetData.ps1} -PSDebug $debugCollection -Debug $True
    if ($debugCollection -like "Missing") { ...}
}

PSDisableSerialization <booleano>

Dirige la actividad para devolver objetos "dinámicos" (no serializados) al flujo de trabajo. Los objetos resultantes tienen métodos, así como propiedades, pero no se pueden guardar cuando se toma un punto de control.

PSDisableSerializationPreference <- valor booleano>

Aplica el equivalente del parámetro PSDisableSerialization a todo el flujo de trabajo, no solo a la actividad. Por lo general, no se recomienda agregar este parámetro, ya que no se puede reanudar ni conservar un flujo de trabajo que no serialice sus objetos.

Valores válidos:

• (Predeterminado) Si se omite, y tampoco se ha agregado el parámetro PSDisableSerialization a una actividad, los objetos se serializan.

• $True. dirige todas las actividades de un flujo de trabajo para devolver los objetos "activos" (no serializados). Los objetos resultantes tienen métodos, así como propiedades, pero no se pueden guardar cuando se toma un punto de control.

• $False. los objetos de flujo de trabajo se serializan.

PSError <PSDataCollection[ErrorRecord]>

Agrega mensajes de error de la actividad a la colección de registros de errores especificada, en lugar de escribir los mensajes de error en la consola o en el valor de la propiedad Error del trabajo de flujo de trabajo. Puede agregar mensajes de error de varias actividades al mismo objeto de colección de registros de depuración.

Para usar este parámetro común de actividad, use el New-Object cmdlet para crear un objeto PSDataCollection con un tipo de ErrorRecord y guarde el objeto en una variable. A continuación, use la variable como el valor del parámetro PSError de una o varias actividades, como se muestra en el ejemplo siguiente.

Workflow Test-Workflow
{
   $typeName = "System.Management.Automation.PSDataCollection"
   $typeName += '[System.Management.Automation.ErrorRecord]'
   $ec = New-Object $typeName
   InlineScript {\Server01\Share01\Get-AssetData.ps1} -PSError $ec
   InlineScript {\Server01\Share01\Set-AssetData.ps1} -PSError $ec
   if ($ec.Count -gt 2)
   {
      # Do Some Work.
   }
}

PSPersist <booleano>

Toma un punto de control después de la actividad. Este punto de control se suma a los puntos de control especificados en el flujo de trabajo. Este parámetro común de actividad también es un parámetro común de flujo de trabajo.

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

• (Valor predeterminado) Si omite este parámetro, no se agregan puntos de control. Los puntos de control se toman en función de la configuración del flujo de trabajo.

• $True. Toma un punto de control una vez completada la actividad. Este punto de control se suma a 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). Este parámetro común de actividad también es un parámetro común de flujo de trabajo.

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.

PSProgress <PSDataCollection[ProgressRecord]>

Agrega mensajes de progreso de la actividad a la colección de registros de progreso especificada, en lugar de escribir los mensajes de progreso en la consola o en el valor de la propiedad Progress del trabajo de flujo de trabajo. Puede agregar mensajes de progreso de varias actividades al mismo objeto de colección de registros de progreso.

Cadena PSProgressMessage <>

Especifica una descripción fácil de la actividad. El valor de PSProgressMessage aparece en la barra de progreso mientras se ejecuta el flujo de trabajo. Cuando DisplayName también se incluye en el comando, el contenido de la barra de progreso aparece en <formato DisplayName>:<PSProgressMessage> .

Este parámetro es especialmente útil para identificar actividades en un bloque de script de -Parallel ForEach. Sin este mensaje, las actividades de todas las ramas paralelas se identifican con el mismo nombre.

PSRemotingBehavior <RemotingBehavior>

Especifica cómo se administra la comunicación remota cuando se ejecuta la actividad en los equipos de destino. PowerShell es el valor predeterminado.

Los valores válidos son:

• Ninguno: la actividad no se ejecuta en equipos remotos.

• PowerShell: la comunicación remota de Windows PowerShell se usa para ejecutar la actividad en los equipos de destino.

• Personalizado: la actividad admite su propio tipo de comunicación remota. Este valor es válido cuando el cmdlet que se implementa como actividad establece el valor del atributo RemotingCapability en SupportedByCommand y el comando incluye el parámetro ComputerName.

PSRequiredModules <String[]>

Importa los módulos especificados antes de ejecutar el comando. Escriba los nombres del módulo. Los módulos deben instalarse en el equipo de destino.

Los módulos que se instalan en una ruta especificada en la variable de entorno PSModulePath se importan automáticamente en el primer uso de cualquier comando en el módulo. Use este parámetro para importar módulos que no estén en una ubicación de PSModulePath.

Dado que cada actividad de un flujo de trabajo se ejecuta en su propia sesión, un comando Import-Module importa un módulo solo en la sesión en la que se ejecuta. No importa el módulo en las sesiones en las que se ejecutan otras actividades.

PSSessionOption <PSSessionOption>

Establece opciones avanzadas para las sesiones en los equipos de destino. Escriba un objeto PSSessionOption, como uno que cree mediante el cmdlet New-PSSessionOption. Este parámetro común de actividad también es un parámetro común de flujo de trabajo.

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 cmdlet New-PSSessionOption de New-PSSessionOption.

Para obtener más información sobre la variable de preferencia $PSSessionOption, consulte about_Preference_Variables.

PSUseSSL <booleano>

Un valor de $True utiliza el protocolo Secure Sockets Layer (SSL) para establecer una conexión con el equipo de destino. De forma predeterminada, no se usa SSL. Un valor de $False no tiene ningún efecto. Este parámetro común de actividad también es un parámetro común de flujo de trabajo.

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.

PSVerbose <PSDataCollection[VerboseRecord]>

Agrega mensajes detallados de la actividad a la colección de registros detallados especificada, en lugar de escribir los mensajes detallados en la consola o en el valor de la propiedad Verbose del trabajo de flujo de trabajo. Puede agregar mensajes detallados de varias actividades al mismo objeto de colección de registros detallados.

PSWarning <PSDataCollection[WarningRecord]>

Agrega mensajes de advertencia de la actividad a la colección de registros de advertencia especificada, en lugar de escribir los mensajes de advertencia en la consola o en el valor de la propiedad Warning del trabajo de flujo de trabajo. Puede agregar mensajes de advertencia de varias actividades al mismo objeto de colección de registros de advertencia.

Resultado

Este parámetro solo es válido en flujos de trabajo XAML.

UseDefaultInput <(valor booleano)>

Acepta todas las entradas de flujo de trabajo como entrada para la actividad por valor.

Por ejemplo, la actividad Get-Process del siguiente flujo de trabajo de ejemplo usa el parámetro común de la actividad UseDefaultInput para obtener la entrada que se pasa al flujo de trabajo. Cuando se ejecuta el flujo de trabajo con la entrada, la actividad usa esa entrada.

workflow Test-Workflow
{
    Get-Service -UseDefaultInput $True
}

PS C:> Test-Workflow -InputObject WinRm

Status   Name        DisplayName                            PSComputerName
------   ----        -----------                            --------------
Running  winrm       Windows Remote Management (WS-Manag... localhost

<SwitchParameter detallado>

Muestra información detallada sobre la operación realizada por el comando . Esta información es similar a la información de un seguimiento o de un registro de transacciones. El parámetro Verbose invalida el valor de la variable $VerbosePreference para el comando actual. Este parámetro solo funciona cuando el comando genera un mensaje extenso. Este parámetro también es un parámetro común de Windows PowerShell.

WarningAction <ActionPreference>

Determina cómo responde la actividad a una advertencia. "Continuar" es el valor predeterminado. El parámetro WarningAction invalida el valor de la variable $WarningPreference para el comando actual. Este parámetro solo funciona cuando el comando genera un mensaje de advertencia. Este parámetro también es un parámetro común de Windows PowerShell.

Valores válidos:

• Continuar en silencio. Suprime el mensaje de advertencia y continúa ejecutando el comando.

• Continuar. Muestra el mensaje de advertencia y continúa ejecutando el comando. "Continuar" es el valor predeterminado.

• Preguntar. Muestra el mensaje de advertencia y le pide confirmación antes de continuar la ejecución. Este valor rara vez se usa.

• Detener. Muestra el mensaje de advertencia y deja de ejecutar el comando.

EJEMPLOS

Los parámetros comunes de actividades son extremadamente útiles. Por ejemplo, puede usar el parámetro PSComputerName para ejecutar actividades concretas solo en un subconjunto de los equipos de destino.

O bien, puede usar los parámetros PSConnectionRetryCount y PSConnectionRetryIntervalSec para ajustar los valores de reintento de actividades concretas.

En el ejemplo siguiente se muestra cómo usar los parámetros comunes de la actividad PSComputerName para ejecutar una actividad Get-EventLog solo en equipos de un dominio determinado.

Workflow Test-Workflow
{
    $UserDomain = Get-Content -Path '.\UserComputers.txt'
    $Log = (Get-EventLog -LogName "Windows PowerShell" `
      -PSComputerName $UserDomain)

    if ($Log)
    {
        # Do Work Here.
    }
}

VÉASE TAMBIÉN

about_Workflowsabout_WorkflowCommonParameters