Trace-Command

  • Riferimento
Modulo:
Microsoft.PowerShell.Utility

Configura e avvia una traccia dell'espressione o del comando specificato.

Sintassi

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

Descrizione

Il Trace-Command cmdlet configura e avvia una traccia dell'espressione o del comando specificato. Il funzionamento è analogo a quello di Set-TraceSource, ad eccezione del fatto che quest'ultimo si applica solo al comando specificato.

Esempio

Esempio 1: Elaborazione dei metadati di traccia, associazione di parametri e espressione

In questo esempio viene avviata una traccia dell'elaborazione dei metadati, dell'associazione di parametri e della creazione e della distruzione dei cmdlet dell'espressione Get-Process Notepad .

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

Usa il parametro Name per specificare le origini di traccia, il parametro Expression per specificare il comando e il parametro PSHost per inviare l'output alla console. Poiché non specifica opzioni di traccia o listener, il comando usa le impostazioni predefinite:

  • Tutte per le opzioni di traccia
  • Nessuna per le opzioni del listener

Esempio 2: Tracciare le azioni delle operazioni ParameterBinding

In questo esempio vengono tracciate le azioni delle operazioni ParameterBinding di PowerShell mentre elabora un'espressione Get-Alias che accetta input dalla pipeline.

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

In Trace-Commandil parametro InputObject passa un oggetto all'espressione che viene elaborata durante la traccia.

Il primo comando archivia la stringa i* nella $A variabile. Il secondo comando usa il Trace-Command cmdlet con l'origine di traccia ParameterBinding. Il parametro PSHost invia l'output alla console.

L'espressione elaborata è Get-Alias $Input, dove la $Input variabile è associata al parametro InputObject . Il parametro InputObject passa la variabile $A all'espressione. In effetti, il comando da elaborare durante la traccia è Get-Alias -InputObject $A" or "$A | Get-Alias.

Esempio 3: Operazioni trace ParameterBinding per i comandi nativi

PowerShell 7.3 ha aggiunto la possibilità di tracciare l'associazione dei parametri per i comandi nativi. Nell'esempio seguente viene illustrato come PowerShell analizza gli argomenti della riga di comando per il 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

Parametri

-ArgumentList

Specifica i parametri e i valori dei parametri per il comando da tracciare. L'alias per ArgumentList è Args. Questa funzionalità è utile per il debug di parametri dinamici.

Per altre informazioni sul comportamento di ArgumentList, vedere about_Splatting.

Type:Object[]
Aliases:Args
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Command

Specifica un comando da elaborare durante la traccia.

Quando si usa questo parametro, PowerShell elabora il comando esattamente come viene elaborato in una pipeline. Ad esempio, l'individuazione dei comandi non viene ripetuta per ogni oggetto in ingresso.

Type:String
Position:1
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Debugger

Indica che il cmdlet invia l'output di traccia al debugger. È possibile visualizzare l'output in qualsiasi debugger in modalità utente o kernel oppure in Visual Studio. Questo parametro seleziona anche il listener di traccia predefinito.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Expression

Specifica l'espressione che viene elaborata durante la traccia. Racchiudere l'espressione tra parentesi graffe ({}).

Type:ScriptBlock
Position:1
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-FilePath

Specifica un file a cui il cmdlet invia l'output della traccia. Questo parametro seleziona anche il listener di traccia dei file.

Type:String
Aliases:PSPath, Path
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Force

Forza l'esecuzione del comando senza chiedere conferma all'utente. Utilizzato con il parametro FilePath . Anche usando il parametro Force , il cmdlet non può eseguire l'override delle restrizioni di sicurezza.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-InputObject

Specifica l'input per l'espressione che viene elaborata durante la traccia. È possibile immettere una variabile che rappresenta l'input accettato dall'espressione oppure passare un oggetto tramite la pipeline.

Type:PSObject
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-ListenerOption

Specifica i dati facoltativi per il prefisso di ogni messaggio di traccia nell'output. I valori validi per questo parametro sono:

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

None è l'impostazione predefinita.

Questi valori sono definiti come enumerazione basata su flag. È possibile combinare più valori per impostare più flag usando questo parametro. I valori possono essere passati al parametro ListenerOption come matrice di valori o come stringa delimitata da virgole di tali valori. Il cmdlet combina i valori usando un'operazione binary-OR. Il passaggio di valori come matrice è l'opzione più semplice e consente anche di usare il completamento tramite tabulazione sui valori.

Type:TraceOptions
Accepted values:None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, Callstack
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Name

Specifica una matrice di componenti di PowerShell tracciati. Immettere il nome dell'origine di traccia di ciascun componente. I caratteri jolly sono consentiti. Per trovare le origini di traccia nel computer, digitare Get-TraceSource.

Type:String[]
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Option

Determina il tipo di eventi tracciati. I valori validi per questo parametro sono:

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

All è l'impostazione predefinita.

I valori seguenti sono combinazioni di altri valori:

  • ExecutionFlow: Constructor, Dispose, FinalizerMethod, Delegates, , EventsScope
  • Data: Constructor, Dispose, Finalizer, Property, VerboseWriteLine
  • Errors: Error, Exception

Questi valori sono definiti come enumerazione basata su flag. È possibile combinare più valori per impostare più flag usando questo parametro. I valori possono essere passati al parametro Option come matrice di valori o come stringa delimitata da virgole di tali valori. Il cmdlet combina i valori usando un'operazione binary-OR. Il passaggio di valori come matrice è l'opzione più semplice e consente anche di usare il completamento tramite tabulazione sui valori.

Type:PSTraceSourceOptions
Accepted values:None, Constructor, Dispose, Finalizer, Method, Property, Delegates, Events, Exception, Lock, Error, Errors, Warning, Verbose, WriteLine, Data, Scope, ExecutionFlow, Assert, All
Position:2
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-PSHost

Indica che il cmdlet invia l'output di traccia all'host di PowerShell. Questo parametro seleziona anche il listener di traccia PSHost.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Input

PSObject

È possibile inviare tramite pipe oggetti che rappresentano l'input all'espressione a questo cmdlet.

Output

PSObject

Questo cmdlet non restituisce alcun output autonomo. Il comando tracciato può restituire l'output. Questo cmdlet scrive la traccia del comando nel flusso di debug.

Note

La funzionalità di traccia è un metodo usato dagli sviluppatori per eseguire il debug dei programmi e ottimizzarli. Durante la traccia, il programma genera messaggi dettagliati su ogni passaggio dell'elaborazione interna. I cmdlet di traccia di PowerShell sono progettati per aiutare gli sviluppatori di PowerShell, ma sono disponibili per tutti gli utenti. Consentono di monitorare quasi ogni aspetto della funzionalità della shell.

Un'origine di traccia è la parte di ogni componente di PowerShell che gestisce la traccia e genera messaggi di traccia per il componente. Per tracciare un componente, identificarne l'origine di traccia.

Usare Get-TraceSource per visualizzare un elenco dei componenti di PowerShell abilitati per la traccia.

Un listener di traccia riceve l'output della traccia e lo visualizza all'utente. È possibile scegliere di inviare i dati di traccia a un debugger in modalità utente o in modalità kernel, all'host o alla console, a un file o a un listener personalizzato derivato dalla classe System.Diagnostics.TraceListener .