Поиск по сайту:

Trace-Command (Microsoft.PowerShell.Utility)

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 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» или «$A | Получить-Псевдоним.

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

В 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.

Тип :

Object[]

Псевдонимы:

Args

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-Command

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

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

Тип :

String

Позиция:

1

Значение по умолчанию:

None

Необходимый:

True

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-Debugger

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

Тип :

SwitchParameter

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-Expression

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

Тип :

ScriptBlock

Позиция:

1

Значение по умолчанию:

None

Необходимый:

True

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-FilePath

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

Тип :

String

Псевдонимы:

PSPath, Path

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-Force

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

Тип :

SwitchParameter

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-InputObject

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

Тип :

PSОбъект

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

True

Принимайте подстановочные знаки:

False

-ListenerOption

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

    None
    LogicalOperationStack
    DateTime
    Timestamp
    ProcessId
    ThreadId
    Callstack

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

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

Тип :

TraceOptions

Принятые значения:

Нет, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, Callstack

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-Name

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

Тип :

String[]

Позиция:

0

Значение по умолчанию:

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

Все — значение по умолчанию.

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

  • ExecutionFlow: Конструктор, Dispose, Финализатор, Метод, Делегаты, События, Область
  • Данные: Конструктор, Dispose, Финализатор, Свойство, Verbose, WriteLine
  • Ошибки: Ошибка, Исключение

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

Тип :

PSTraceSourceOptions

Принятые значения:

Нет, Конструктор, Удаление, Финализатор, Метод, Свойство, Делегаты, События, Исключение, Блокировка, Ошибка, Ошибки, Предупреждение, Подробный, WriteLine, Данные, Область, ExecutionFlow, Утверждать, Все

Позиция:

2

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

-PSHost

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

Тип :

SwitchParameter

Позиция:

Именованный

Значение по умолчанию:

None

Необходимый:

False

Примите ввод конвейера:

False

Принимайте подстановочные знаки:

False

Входы

PSObject

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

Выходы

PSObject

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

Примечания

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

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

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

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