about_ActivityCommonParameters
DESCRIPCIÓN BREVE
Describe los parámetros que el flujo de trabajo de Windows PowerShell agrega a las actividades.
DESCRIPCIÓN LARGA
Flujo de trabajo de Windows PowerShell agrega los parámetros comunes de actividad a las actividades derivadas 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 Suspend-Workflow actividades y Checkpoint-Workflow y no se agregan a cmdlets o expresiones que el flujo de trabajo de Windows PowerShell se ejecuta automáticamente en un bloque de script InlineScript o una actividad similar. Los parámetros comunes de actividades están disponibles en la actividad InlineScript , pero no en comandos en el bloque de script de 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 <Boolean>
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 script, también puede usar el += operador de asignación para agregar la 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 invalida el valor de la $DebugPreference variable 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.
DisplayName <String>
Especifica un nombre descriptivo para la actividad. El valor DisplayName aparece en la barra de progreso mientras el flujo de trabajo se ejecuta 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 <DisplayName>:<PSProgressMessage> formato.
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 de no terminación, como los del Write-Error cmdlet . El parámetro ErrorAction invalida el valor de la $ErrorActionPreference variable para el comando actual. Este parámetro también es un parámetro común de Windows PowerShell.
Los valores válidos son:
Continue. Muestra el mensaje de error y continúa ejecutando el comando. El valor predeterminado esContinue.Ignore. Suprime el mensaje de error y continúa ejecutando el comando. A diferencia deSilentlyContinue,Ignoreno agrega el mensaje de error a la$Errorvariable automática. ElIgnorevalor se introduce en Windows PowerShell 3.0.Inquire. Muestra el mensaje de error y le pide confirmación antes de continuar la ejecución. Este valor rara vez se usa.Suspend. 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.SilentlyContinue. Suprime el mensaje de error y continúa ejecutando el comando.Stop. 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 <Boolean>
Valor de $True agrega errores al flujo de salida. Un valor de $False no tiene ningún efecto. Use 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 vuelve a intentarlo.
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 <Boolean>
Un valor de $True permite el redireccionamiento 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 otro URI. 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 SessionOption de cmdlets que crean una sesión. El valor predeterminado es 5.
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 . 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 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.
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 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.
Cadena PSCertificateThumbprint <>
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. Este parámetro común de actividad también es un parámetro común de flujo de trabajo.
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 los equipos de destino en los que se ejecuta la actividad. La opción predeterminada 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, 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 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.Workflow. 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), no representa ningún reintento. 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:
<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 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 se incluye 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 el que devuelve el Get-Credential cmdlet. 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 Depurar 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 New-Object cmdlet para crear un objeto PSDataCollection con un tipo de DepurarRecord y guardar el objeto en una variable. A continuación, use la variable como 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 <Boolean>
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 <Boolean>
Aplica el equivalente del parámetro PSDisableSerialization a todo el flujo de trabajo, no solo 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.
Los valores válidos son:
(Valor 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 guardar el objeto en una variable. A continuación, use la variable como 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 <Boolean>
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.
Los valores válidos son:
(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 59'86 (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 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.
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 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 <DisplayName>:<PSProgressMessage> formato.
Este parámetro es especialmente útil para identificar actividades en un ForEach -Parallel bloque de script. 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:
None: 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.Custom: la actividad admite su propio tipo de comunicación remota. Este valor es válido cuando el cmdlet que se implementa como una 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 instalados en una ruta de acceso especificada en la variable de entorno PSModulePath se importan automáticamente al primer uso de cualquier comando del módulo. Use este parámetro para importar módulos que no están en una ubicación PSModulePath .
Dado que cada actividad de un flujo de trabajo se ejecuta en su propia sesión, un Import-Module comando importa un módulo solo a 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 New-PSSessionOption cmdlet . 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 $PSSessionOption variable de preferencia, consulte about_Preference_Variables.
PSUseSSL <Boolean>
Un valor de $True 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. 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 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.
PSVerbose <PSDataCollection[VerboseRecord]>
Agrega mensajes detallados de la actividad a la colección de registros detallada 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 <Boolean>
Acepta todas las entradas de flujo de trabajo como entrada para la actividad por valor.
Por ejemplo, la Get-Process actividad del flujo de trabajo de ejemplo siguiente usa el parámetro común de 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 $VerbosePreference variable para el comando actual. Este parámetro solo funciona cuando el comando genera un mensaje detallado. 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. El valor predeterminado es Continue. El parámetro WarningAction invalida el valor de la $WarningPreference variable 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:
SilentlyContinue. Suprime el mensaje de advertencia y continúa ejecutando el comando.Continue. Muestra el mensaje de advertencia y continúa ejecutando el comando. El valor predeterminado esContinue.Inquire. Muestra el mensaje de advertencia y le pide confirmación antes de continuar la ejecución. Este valor rara vez se usa.Stop. Muestra el mensaje de advertencia y deja de ejecutar el comando.
Nota:
El parámetro WarningAction no invalida el valor de la $WarningAction variable de preferencia cuando el parámetro se usa en un comando para ejecutar un script o una función.
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 para determinadas actividades.
En el ejemplo siguiente se muestra cómo usar los parámetros comunes de la actividad PSComputerName para ejecutar una Get-EventLog actividad solo en equipos en los que es 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.
}
}
