Compartir a través de

Trace-Command

  • Referencia
Módulo:
Microsoft.PowerShell.Utility

Configura e inicia un seguimiento de la expresión o comando especificados.

Sintaxis

Trace-Command
     [-InputObject <PSObject>]
     [-Name] <String[]>
     [[-Option] <PSTraceSourceOptions>]
     [-Expression] <ScriptBlock>
     [-ListenerOption <TraceOptions>]
     [-FilePath <String>]
     [-Force]
     [-Debugger]
     [-PSHost]
     [<CommonParameters>]
Trace-Command
     [-InputObject <PSObject>]
     [-Name] <String[]>
     [[-Option] <PSTraceSourceOptions>]
     [-Command] <String>
     [-ArgumentList <Object[]>]
     [-ListenerOption <TraceOptions>]
     [-FilePath <String>]
     [-Force]
     [-Debugger]
     [-PSHost]
     [<CommonParameters>]

Description

El cmdlet Trace-Command configura e inicia un seguimiento de la expresión o comando especificados. Funciona como Set-TraceSource, salvo que solo se aplica al comando especificado.

Ejemplos

Ejemplo 1: Procesamiento de metadatos de seguimiento, enlace de parámetros y una expresión

En este ejemplo se inicia un seguimiento del procesamiento de metadatos, el enlace de parámetros y la creación y destrucción de cmdlets de la expresión de Get-Process Notepad.

Trace-Command -Name metadata,parameterbinding,cmdlet -Expression {Get-Process Notepad} -PSHost

Usa el parámetro Name para especificar los orígenes de seguimiento, el parámetro Expression para especificar el comando y el parámetro PSHost para enviar la salida a la consola. Dado que no especifica ninguna opción de seguimiento ni opciones de agente de escucha, el comando usa los valores predeterminados:

  • Todas para las opciones de seguimiento
  • Ninguna para las opciones del agente de escucha

Ejemplo 2: Seguimiento de las acciones de las operaciones ParameterBinding

En este ejemplo se realiza un seguimiento de las acciones de la ParameterBinding operaciones de PowerShell mientras procesa una expresión Get-Alias que toma la entrada de la canalización.

$A = "i*"
Trace-Command ParameterBinding {Get-Alias $Input} -PSHost -InputObject $A

En Trace-Command, el parámetro InputObject pasa un objeto a la expresión que se está procesando durante el seguimiento.

El primer comando almacena la cadena i* en la variable $A. El segundo comando usa el cmdlet Trace-Command con el origen de seguimiento ParameterBinding. El parámetro PSHost de envía la salida a la consola.

La expresión que se está procesando es Get-Alias $Input, donde la variable $Input está asociada al parámetro InputObject. El parámetro InputObject pasa la variable $A a la expresión. En efecto, el comando que se está procesando durante el seguimiento es Get-Alias -InputObject $A" or "$A | Get-Alias.

Ejemplo 3: operaciones Trace ParameterBinding para comandos nativos

PowerShell 7.3 agregó la capacidad de realizar un seguimiento del enlace de parámetros para comandos nativos. En el ejemplo siguiente se muestra cómo PowerShell analiza los argumentos de la línea de comandos para el comando nativo TestExe.

$a = 'a" "b'
Trace-Command -PSHOST -Name ParameterBinding { TestExe -echoargs $a 'c" "d' e" "f }

DEBUG: 2023-02-27 14:20:45.3975 ParameterBinding Information: 0 : BIND NAMED native application line args [C:\Public\Toolbox\TestExe\testexe.exe]
DEBUG: 2023-02-27 14:20:45.3978 ParameterBinding Information: 0 :     BIND cmd line arg [-echoargs] to position [0]
DEBUG: 2023-02-27 14:20:45.3979 ParameterBinding Information: 0 :     BIND cmd line arg [a" "b] to position [1]
DEBUG: 2023-02-27 14:20:45.3980 ParameterBinding Information: 0 :     BIND cmd line arg [c" "d] to position [2]
DEBUG: 2023-02-27 14:20:45.3982 ParameterBinding Information: 0 :     BIND cmd line arg [e f] to position [3]
DEBUG: 2023-02-27 14:20:47.6092 ParameterBinding Information: 0 : CALLING BeginProcessing

Parámetros

-ArgumentList

Especifica los parámetros y los valores de parámetro para el comando que se realiza el seguimiento. El alias de argumentList es Args. Esta característica es útil para depurar parámetros dinámicos.

Para obtener más información sobre el comportamiento de ArgumentList, vea about_Splatting.

Tipo:Object[]
Alias:Args
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-Command

Especifica un comando que se está procesando durante el seguimiento.

Cuando se usa este parámetro, PowerShell procesa el comando igual que lo haría en una canalización. Por ejemplo, la detección de comandos no se repite para cada objeto entrante.

Tipo:String
Posición:1
Valor predeterminado:None
Requerido:True
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-Debugger

Indica que el cmdlet envía la salida de seguimiento al depurador. Puede ver la salida en cualquier depurador en modo de usuario o en modo kernel o en Visual Studio. Este parámetro también selecciona el agente de escucha de seguimiento predeterminado.

Tipo:SwitchParameter
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-Expression

Especifica la expresión que se está procesando durante el seguimiento. Encierre la expresión entre llaves ({}).

Tipo:ScriptBlock
Posición:1
Valor predeterminado:None
Requerido:True
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-FilePath

Especifica un archivo al que el cmdlet envía la salida de seguimiento. Este parámetro también selecciona el agente de escucha de seguimiento de archivos.

Tipo:String
Alias:PSPath, Path
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-Force

Obliga a que el comando se ejecute sin pedir confirmación del usuario. Se usa con el parámetro FilePath. Incluso con el parámetro Force, el cmdlet no puede invalidar las restricciones de seguridad.

Tipo:SwitchParameter
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-InputObject

Especifica la entrada de la expresión que se está procesando durante el seguimiento. Puede escribir una variable que represente la entrada que acepta la expresión o pasar un objeto a través de la canalización.

Tipo:PSObject
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:True
Aceptar caracteres comodín:False

-ListenerOption

Especifica los datos opcionales para el prefijo de cada mensaje de seguimiento en la salida. Los valores aceptables para este parámetro son:

  • None
  • LogicalOperationStack
  • DateTime
  • Timestamp
  • ProcessId
  • ThreadId
  • Callstack

None es el valor predeterminado.

Estos valores se definen como una enumeración basada en marcas. Puede combinar varios valores para establecer varias marcas mediante este parámetro. Los valores se pueden pasar al parámetro listenerOption de como una matriz de valores o como una cadena separada por comas de esos valores. El cmdlet combinará los valores mediante una operación binary-OR. Pasar valores como una matriz es la opción más sencilla y también permite usar la finalización de tabulación en los valores.

Tipo:TraceOptions
Valores aceptados:None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, Callstack
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-Name

Especifica una matriz de componentes de PowerShell a los que se realiza un seguimiento. Escriba el nombre del origen de seguimiento de cada componente. Se permiten caracteres comodín. Para buscar los orígenes de seguimiento en el equipo, escriba Get-TraceSource.

Tipo:String[]
Posición:0
Valor predeterminado:None
Requerido:True
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-Option

Determina el tipo de eventos que se realizan en el seguimiento. Los valores aceptables para este parámetro son:

  • None
  • Constructor
  • Dispose
  • Finalizer
  • Method
  • Property
  • Delegates
  • Events
  • Exception
  • Lock
  • Error
  • Errors
  • Warning
  • Verbose
  • WriteLine
  • Data
  • Scope
  • ExecutionFlow
  • Assert
  • All

All es el valor predeterminado.

Los valores siguientes son combinaciones de otros valores:

  • ExecutionFlow: Constructor, Dispose, Finalizer, Method, Delegates, Events, Scope
  • Data: Constructor, Dispose, Finalizer, Property, Verbose, WriteLine
  • Errors: Error, Exception

Estos valores se definen como una enumeración basada en marcas. Puede combinar varios valores para establecer varias marcas mediante este parámetro. Los valores se pueden pasar al parámetro Option como una matriz de valores o como una cadena separada por comas de esos valores. El cmdlet combinará los valores mediante una operación binary-OR. Pasar valores como una matriz es la opción más sencilla y también permite usar la finalización de tabulación en los valores.

Tipo:PSTraceSourceOptions
Valores aceptados:None, Constructor, Dispose, Finalizer, Method, Property, Delegates, Events, Exception, Lock, Error, Errors, Warning, Verbose, WriteLine, Data, Scope, ExecutionFlow, Assert, All
Posición:2
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

-PSHost

Indica que el cmdlet envía la salida de seguimiento al host de PowerShell. Este parámetro también selecciona el agente de escucha de seguimiento de PSHost.

Tipo:SwitchParameter
Posición:Named
Valor predeterminado:None
Requerido:False
Aceptar entrada de canalización:False
Aceptar caracteres comodín:False

Entradas

PSObject

Puede canalizar objetos que representan la entrada a la expresión a este cmdlet.

Salidas

PSObject

Este cmdlet no devuelve ninguna salida propia. El comando rastreado puede devolver la salida. Este cmdlet escribe el seguimiento de comandos en la secuencia de depuración.

Notas

El seguimiento es un método que los desarrolladores usan para depurar y refinar programas. Al realizar el seguimiento, el programa genera mensajes detallados sobre cada paso en su procesamiento interno. Los cmdlets de seguimiento de PowerShell están diseñados para ayudar a los desarrolladores de PowerShell, pero están disponibles para todos los usuarios. Permiten supervisar casi todos los aspectos de la funcionalidad del shell.

Un origen de seguimiento es la parte de cada componente de PowerShell que administra el seguimiento y genera mensajes de seguimiento para el componente. Para realizar un seguimiento de un componente, identifique su origen de seguimiento.

Use Get-TraceSource para ver una lista de componentes de PowerShell habilitados para el seguimiento.

Un agente de escucha de seguimiento recibe la salida del seguimiento y lo muestra al usuario. Puede optar por enviar los datos de seguimiento a un depurador en modo de usuario o en modo kernel, al host o la consola, a un archivo o a un agente de escucha personalizado derivado de la clase System.Diagnostics.TraceListener.