Поделиться через

Trace-Command

  • Ссылка
Модуль:
Microsoft.PowerShell.Utility

Настраивает и запускает трассировку указанного выражения или команды.

Синтаксис

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

Описание

Командлет Trace-Command настраивает и запускает трассировку указанного выражения или команды. Он аналогичен командлету Set-TraceSource за тем исключением, что его действие распространяется только на указанную команду.

Примеры

Пример 1. Обработка метаданных трассировки, привязка параметров и выражение

В этом примере запускается трассировка обработки метаданных, привязки параметров, а также создание и уничтожение выражения командлета Get-Process Notepad .

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

Он использует параметр Name для указания источников трассировки, параметр Expression для указания команды и параметр PSHost для отправки выходных данных в консоль. Так как в ней не указаны параметры трассировки или прослушивателя, команда использует значения по умолчанию:

  • Все для параметров трассировки
  • Нет для параметров прослушивателя

Пример 2. Трассировка действий операций ParameterBinding

В этом примере выполняется трассировка действий операций ParameterBinding PowerShell при обработке Get-Alias выражения, принимающего входные данные из конвейера.

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

В Trace-Commandпараметр InputObject передает объект выражению, которое обрабатывается во время трассировки.

Первая команда сохраняет строку i* в переменной $A . Вторая команда использует Trace-Command командлет с источником трассировки ParameterBinding. Параметр PSHost отправляет выходные данные в консоль.

Обрабатываемого выражения является Get-Alias $Input, где $Input переменная связана с параметром InputObject . Параметр InputObject передает переменную $A выражению. По сути, команда, обрабатываемая во время трассировки, имеет значение Get-Alias -InputObject $A" or "$A | Get-Alias.

Пример 3. Операции трассировки ParameterBinding для собственных команд

В PowerShell 7.3 добавлена возможность трассировки привязки параметров для собственных команд. В следующем примере показано, как PowerShell анализирует аргументы командной строки для собственной команды 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

Параметры

-ArgumentList

Указывает параметры и значения параметров для трассируемой команды. Псевдоним для ArgumentList — Args. Эта функция полезна для отладки динамических параметров.

Дополнительные сведения о поведении ArgumentList см. в разделе about_Splatting.

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

-Command

Указывает команду, которая обрабатывается во время трассировки.

При использовании этого параметра PowerShell обрабатывает команду так же, как и в конвейере. Например, обнаружение команд не повторяется для каждого входящего объекта.

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

-Debugger

Указывает, что командлет отправляет выходные данные трассировки отладчику. Выходные данные можно просмотреть в любом отладчике, работающем в пользовательском режиме или в режиме ядра, либо в Visual Studio. Данный параметр также определяет прослушиватель трассировки по умолчанию.

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

-Expression

Указывает выражение, которое обрабатывается во время трассировки. Заключите выражение в фигурные скобки ({}).

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

-FilePath

Указывает файл, в который командлет отправляет выходные данные трассировки. Данный параметр также определяет прослушиватель трассировки файла.

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

-Force

Принудительное выполнение команды без запроса на подтверждение пользователем. Используется с параметром FilePath . Даже с помощью параметра Force командлет не может переопределить ограничения безопасности.

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

-InputObject

Указывает входные данные для выражения, обрабатываемого во время трассировки. Можно ввести переменную, которая представляет выходные данные, принимаемые этим выражением, или передать объект по конвейеру.

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

-ListenerOption

Указывает необязательные данные для префикса каждого сообщения трассировки в выходных данных. Допустимые значения для этого параметра:

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

Значение по умолчанию — None.

Эти значения определяются как перечисление на основе флагов. С помощью этого параметра можно объединить несколько значений, чтобы задать несколько флагов. Значения могут передаваться параметру ListenerOption в виде массива значений или строки этих значений, разделенной запятыми. Командлет объединит значения с помощью операции binary-OR. Передача значений в виде массива является самым простым вариантом, а также позволяет использовать для значений заполнение табуляции.

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

Указывает массив отслеживаемых компонентов PowerShell. Введите имя источника трассировки для каждого компонента. Разрешено использовать подстановочные знаки. Чтобы найти источники трассировки на компьютере, введите Get-TraceSource.

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

-Option

Определяет тип трассируемых событий. Допустимые значения для этого параметра:

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

Значение по умолчанию — All.

Следующие значения являются комбинацией других значений:

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

Эти значения определяются как перечисление на основе флагов. С помощью этого параметра можно объединить несколько значений, чтобы задать несколько флагов. Значения могут передаваться в параметр Option в виде массива значений или в виде строки этих значений, разделенной запятыми. Командлет объединит значения с помощью операции binary-OR. Передача значений в виде массива является самым простым вариантом, а также позволяет использовать для значений заполнение табуляции.

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

Указывает, что командлет отправляет выходные данные трассировки на узел PowerShell. Данный параметр также определяет прослушиватель трассировки PSHost.

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

Входные данные

PSObject

В этот командлет можно передать объекты, представляющие входные данные в выражение.

Выходные данные

PSObject

Этот командлет не возвращает собственные выходные данные. Трассировка команды может возвращать выходные данные. Этот командлет записывает трассировку команды в поток отладки.

Примечания

Трассировка — это метод, применяемый разработчиками для отладки и изменения программы. Во время трассировки программа создает подробные сообщения о каждом шаге внутренней обработки. Командлеты трассировки PowerShell предназначены для разработчиков PowerShell, но они доступны всем пользователям. Они позволяют отслеживать практически все аспекты функциональных возможностей оболочки.

Источник трассировки — это часть каждого компонента PowerShell, который управляет трассировкой и создает сообщения трассировки для компонента. Чтобы выполнить трассировку компонента, указать определить его источник трассировки.

Используйте Get-TraceSource для просмотра списка компонентов PowerShell, для которых включена трассировка.

Прослушиватель трассировки получает выходные данные трассировки и отображает их пользователю. Данные трассировки можно отправить в отладчик в пользовательском режиме или в режиме ядра, на узел или консоль, в файл или в пользовательский прослушиватель, производный от класса System.Diagnostics.TraceListener .