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

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 для указания источников трассировки, параметра выражения для указания команды и параметра 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. Операции Trace 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

Задает параметры и значения параметров для трассировки команды. Псевдоним для ArgumentListArgs. Эта функция полезна для отладки динамических параметров.

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

Тип:Object[]
Aliases:Args
Position:Named
Default value:None
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-Command

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

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

Тип:String
Position:1
Default value:None
Обязательно:True
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-Debugger

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

Тип:SwitchParameter
Position:Named
Default value:None
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-Expression

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

Тип:ScriptBlock
Position:1
Default value:None
Обязательно:True
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-FilePath

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

Тип:String
Aliases:PSPath, Path
Position:Named
Default value:None
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-Force

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

Тип:SwitchParameter
Position:Named
Default value:None
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-InputObject

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

Тип:PSObject
Position:Named
Default value:None
Обязательно:False
Принять входные данные конвейера:True
Принять подстановочные знаки:False

-ListenerOption

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

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

None — это значение по умолчанию.

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

Тип:TraceOptions
Допустимые значения:None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, Callstack
Position:Named
Default value:None
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-Name

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

Тип:String[]
Position:0
Default value:None
Обязательно:True
Принять входные данные конвейера:False
Принять подстановочные знаки: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. Передача значений в виде массива является самым простым параметром, а также позволяет использовать завершение табуляции для значений.

Тип:PSTraceSourceOptions
Допустимые значения: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
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:False

-PSHost

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

Тип:SwitchParameter
Position:Named
Default value:None
Обязательно:False
Принять входные данные конвейера:False
Принять подстановочные знаки:False

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

PSObject

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

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

PSObject

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

Примечания

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

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

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

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