Trace-Command
Configura e inicia um rastreamento da expressão ou comando especificado.
Sintaxe
expressionSet (Predefinição)
Trace-Command
[-Name] <String[]>
[[-Option] <PSTraceSourceOptions>]
[-Expression] <ScriptBlock>
[-InputObject <PSObject>]
[-ListenerOption <TraceOptions>]
[-FilePath <String>]
[-Force]
[-Debugger]
[-PSHost]
[<CommonParameters>]
commandSet
Trace-Command
[-Name] <String[]>
[[-Option] <PSTraceSourceOptions>]
[-Command] <String>
[-InputObject <PSObject>]
[-ArgumentList <Object[]>]
[-ListenerOption <TraceOptions>]
[-FilePath <String>]
[-Force]
[-Debugger]
[-PSHost]
[<CommonParameters>]
Description
O cmdlet Trace-Command configura e inicia um rastreamento da expressão ou comando especificado.
Ele funciona como Set-TraceSource, exceto que se aplica apenas ao comando especificado.
Exemplos
Exemplo 1: Processamento de metadados de rastreamento, associação de parâmetros e uma expressão
Este exemplo inicia um rastreamento de processamento de metadados, associação de parâmetros e criação e destruição de cmdlets da expressão Get-Process Notepad.
Trace-Command -Name Metadata, ParameterBinding, Cmdlet -Expression {Get-Process Notepad} -PSHost
Ele usa o parâmetro Name para especificar as fontes de rastreamento, o parâmetro Expression para especificar o comando e o parâmetro PSHost para enviar a saída para o console. Como ele não especifica nenhuma opção de rastreamento ou opção de ouvinte, o comando usa os padrões:
- Tudo para as opções de rastreamento
- Nenhuma para as opções do ouvinte
Exemplo 2: Rastrear as ações das operações ParameterBinding
Este exemplo rastreia as ações do ParameterBinding operações do PowerShell enquanto processa uma expressão Get-Alias que recebe entrada do pipeline.
$A = "i*"
Trace-Command ParameterBinding {Get-Alias $input} -PSHost -InputObject $A
Em Trace-Command, o parâmetro InputObject passa um objeto para a expressão que está sendo processada durante o rastreamento.
O primeiro comando armazena a cadeia de caracteres i* na variável $A. O segundo comando usa o cmdlet Trace-Command com a fonte de rastreamento ParameterBinding. O parâmetro PSHost envia a saída para o console.
A expressão que está sendo processada é Get-Alias $input, onde a variável $input está associada ao parâmetro InputObject. O parâmetro InputObject passa a variável $A para a expressão. Com efeito, o comando que está sendo processado durante o rastreamento é Get-Alias -InputObject $A" or "$A | Get-Alias.
Exemplo 3: Operações Trace ParameterBinding para comandos nativos
O PowerShell 7.3 adicionou a capacidade de rastrear a vinculação de parâmetros para comandos nativos. O exemplo a seguir mostra como o PowerShell analisa os argumentos de linha de comando para o 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 os parâmetros e valores de parâmetro para o comando que está sendo rastreado. O alias para ArgumentList é Args. Esse recurso é útil para depurar parâmetros dinâmicos.
Para mais informações sobre o comportamento de ArgumentList, consulte about_Splatting.
Propriedades dos parâmetros
| Tipo: | Object[] |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
| Aliases: | Argumentos |
Conjuntos de parâmetros
commandSet
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-Command
Especifica um comando que está sendo processado durante o rastreamento.
Quando você usa esse parâmetro, o PowerShell processa o comando da mesma forma que ele seria processado em um pipeline. Por exemplo, a descoberta de comandos não é repetida para cada objeto de entrada.
Propriedades dos parâmetros
| Tipo: | String |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
commandSet
| Position: | 1 |
| Obrigatório: | True |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-Debugger
Indica que o cmdlet envia a saída de rastreamento para o depurador. Você pode exibir a saída em qualquer depurador de modo de usuário ou modo kernel ou no Visual Studio. Esse parâmetro também seleciona o ouvinte de rastreamento padrão.
Propriedades dos parâmetros
| Tipo: | SwitchParameter |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-Expression
Especifica a expressão que está sendo processada durante o rastreamento. Coloque a expressão entre chaves ({}).
Propriedades dos parâmetros
| Tipo: | ScriptBlock |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
expressionSet
| Position: | 1 |
| Obrigatório: | True |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-FilePath
Especifica um arquivo para o qual o cmdlet envia a saída de rastreamento. Esse parâmetro também seleciona o ouvinte de rastreamento de arquivo.
Propriedades dos parâmetros
| Tipo: | String |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
| Aliases: | PSPath, Caminho |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-Force
Força o comando a ser executado sem pedir a confirmação do usuário. Usado com o parâmetro FilePath. Mesmo usando o parâmetro Force, o cmdlet não consegue ultrapassar restrições de segurança.
Propriedades dos parâmetros
| Tipo: | SwitchParameter |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-InputObject
Especifica a entrada para a expressão que está sendo processada durante o rastreamento. Você pode inserir uma variável que representa a entrada que a expressão aceita ou passar um objeto pelo pipeline.
Propriedades dos parâmetros
| Tipo: | PSObject |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | True |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-ListenerOption
Especifica dados opcionais para o prefixo de cada mensagem de rastreamento na saída. Os valores aceitáveis para este parâmetro são:
NoneLogicalOperationStackDateTimeTimestampProcessIdThreadIdCallstack
None é o padrão.
Esses valores são definidos como uma enumeração baseada em sinalizador. Você pode combinar vários valores juntos para definir vários sinalizadores usando esse parâmetro. Os valores podem ser passados para o parâmetro ListenerOption como uma matriz de valores ou como uma cadeia de caracteres separada por vírgulas desses valores. O cmdlet combinará os valores usando uma operação binary-OR. Passar valores como uma matriz é a opção mais simples e também permite que você use o preenchimento de tabulação nos valores.
Propriedades dos parâmetros
| Tipo: | TraceOptions |
| Default value: | None |
| Valores aceites: | None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, Callstack |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-Name
Especifica uma matriz de componentes do PowerShell que são rastreados. Insira o nome da fonte de rastreamento de cada componente. Curingas são permitidos. Para localizar as fontes de rastreamento no computador, digite Get-TraceSource.
Propriedades dos parâmetros
| Tipo: | String[] |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | 0 |
| Obrigatório: | True |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-Option
Determina o tipo de eventos que são rastreados. Os valores aceitáveis para este parâmetro são:
NoneConstructorDisposeFinalizerMethodPropertyDelegatesEventsExceptionLockErrorErrorsWarningVerboseWriteLineDataScopeExecutionFlowAssertAll
All é o padrão.
Os seguintes valores são combinações de outros valores:
-
ExecutionFlow:Constructor,Dispose,Finalizer,Method, ,EventsDelegates,Scope -
Data:Constructor,Dispose,Finalizer,Property,Verbose,WriteLine -
Errors:Error,Exception
Esses valores são definidos como uma enumeração baseada em sinalizador. Você pode combinar vários valores juntos para definir vários sinalizadores usando esse parâmetro. Os valores podem ser passados para o parâmetro Option como uma matriz de valores ou como uma cadeia de caracteres separada por vírgulas desses valores. O cmdlet combinará os valores usando uma operação binary-OR. Passar valores como uma matriz é a opção mais simples e também permite que você use o preenchimento de tabulação nos valores.
Propriedades dos parâmetros
| Tipo: | PSTraceSourceOptions |
| Default value: | None |
| Valores aceites: | None, Constructor, Dispose, Finalizer, Method, Property, Delegates, Events, Exception, Lock, Error, Errors, Warning, Verbose, WriteLine, Data, Scope, ExecutionFlow, Assert, All |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | 2 |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
-PSHost
Indica que o cmdlet envia a saída de rastreamento para o host do PowerShell. Este parâmetro também seleciona o ouvinte de rastreamento PSHost.
Propriedades dos parâmetros
| Tipo: | SwitchParameter |
| Default value: | None |
| Suporta carateres universais: | False |
| NãoMostrar: | False |
Conjuntos de parâmetros
(All)
| Position: | Named |
| Obrigatório: | False |
| Valor do pipeline: | False |
| Valor do pipeline por nome de propriedade: | False |
| Valor dos restantes argumentos: | False |
CommonParameters
Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.
Entradas
PSObject
Você pode canalizar objetos que representam a entrada para a expressão para este cmdlet.
Saídas
PSObject
Este cmdlet não retorna nenhuma saída própria. O comando traced pode retornar a saída. Este cmdlet grava o rastreamento de comando no fluxo de depuração.
Notas
O rastreamento é um método que os desenvolvedores usam para depurar e refinar programas. Ao rastrear, o programa gera mensagens detalhadas sobre cada etapa de seu processamento interno. Os cmdlets de rastreamento do PowerShell foram projetados para ajudar os desenvolvedores do PowerShell, mas estão disponíveis para todos os usuários. Eles permitem que você monitore quase todos os aspetos da funcionalidade do shell.
Uma fonte de rastreamento é a parte de cada componente do PowerShell que gerencia o rastreamento e gera mensagens de rastreamento para o componente. Para rastrear um componente, identifique sua origem de rastreamento.
Use Get-TraceSource para ver uma lista de componentes do PowerShell habilitados para rastreamento.
Um ouvinte de rastreamento recebe a saída do rastreamento e a exibe para o usuário. Você pode optar por enviar os dados de rastreamento para um depurador de modo de usuário ou kernel, para o host ou console, para um arquivo ou para um ouvinte personalizado derivado da classe System.Diagnostics.TraceListener.
