Trace-Command

  • Referencia
Módulo:
Microsoft.PowerShell.Utility

Configura e inicia un seguimiento de la expresión o el 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 Trace-Command cmdlet configura e inicia un seguimiento de la expresión o comando especificados. Funciona igual que Set-TraceSource, salvo que se aplica solo 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 Get-Process Notepad expresión.

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 las operaciones ParameterBinding de PowerShell mientras procesa una Get-Alias expresión 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 $A variable . El segundo comando usa el Trace-Command cmdlet con el origen de seguimiento ParameterBinding. El parámetro PSHost envía la salida a la consola.

La expresión que se está procesando es Get-Alias $Input, donde la $Input variable 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 TestExenativo .

$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 del comando objeto de 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. El resultado se puede ver en cualquier depurador de modo kernel o modo de usuario 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 del archivo.

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 al comando a ejecutarse sin solicitar la 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 especificar una variable que representa la entrada aceptada por 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 permitidos para este parámetro son los siguientes:

  • 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 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 los 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 de los que se realiza un seguimiento. Los valores permitidos para este parámetro son los siguientes:

  • 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, , , EventsScope
  • 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 ajustar los programas. Al realizar el seguimiento, el programa genera los mensajes detallados sobre cada paso en el 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. Estos cmdlets le permiten supervisar casi cualquier aspecto 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 el seguimiento de un componente, se identifica el origen de seguimiento.

Use Get-TraceSource para ver una lista de componentes de PowerShell que están 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 a una consola, a un archivo o a un agente de escucha personalizado derivado de la clase System.Diagnostics.TraceListener .