Улучшить отслеживание PowerShell и регистрацию для консоли и транскрипций

Фон

Xwrite Первоначально был создан для PowerShell 4 Но это работает безупречно с новейшей и величайшей из PowerShell ( 7.0.0 ). Это 100% модуль сценария, и были предприняты явные усилия, чтобы сохранить его как можно более навязчивым, насколько это возможно, к PowerShell, учитывая чувствительный характер пораженных командлетов.

Модуль был создан, потому что тогда я строил очень сложный трубопровод CI/CD для развертывания SDL Центр знаний на Amazon Web Services Анкет В рамках этих усилий и, когда я созрел в технологии, я осознал некоторые недостатки PowerShell и подумал о некоторых улучшениях, которые я хотел бы для себя.

Отслеживание по умолчанию PowerShell до консоли или файлов транскрипции отсутствует. Чтобы привести пример, я хотел бы увидеть, какой командлет или сценарий написал что -то в качестве отладка, словеса, информации, предупреждения или даже ошибки. Разработчик сценариев должен всегда добавлять эту информацию в корпус вывода, что делает трассировку раздражать для разработчика и кодовой базы грязной.
PowerShell не хватает бесшовного перенаправления прогресса в консоли и транскрипции. Из-за этого разработчик скрипта должен кодировать обе строки для хорошего интерактивного пользовательского опыта, но также и солидный след, когда скрипт выполняется в неинтерактивном режиме. Мне также не нравится рендеринг Write-progress Вывод, который часто мешает консоли и отличается от одного хоста (например, PowerShell, PowerShell ISE, PWSH, VSCODE и т. Д.). Мне нравится концепция, хотя И я хотел бы иметь возможность перенаправить его на консоли.
PowerShell отсутствует простой и быстрый способ обеспечить полное отслеживание консоли. Я не хочу изменять несколько переменных предпочтения, например, $ Debugpreference без автозаполнения. Там должно быть что -то проще и быстрее.

По этим причинам и улучшить свой опыт работы с PowerShell в качестве разработчика и анализа транскрипции, я разработал тогда (2007) The Xwrite модуль. Оказывается, это работает так хорошо, что я начал использовать его с каждым сеансом PowerShell, загружая модуль через мой профиль.

Вот представление о нормальных и расширенных выходах

Xwrite функции

Модуль может:

Включите полное отслеживание для всех переменных предпочтения и отката на исходные настройки.
Увеличить выходной сигнал следующего ядра ( Microsoft. PowerShell. Утилита ) командлеты:
- Писать-хост
- Написать-дебуг
- Написать. Вербоз
- Записать-информацию
- Написать
Добавьте встроенный дополнительный вывод для нативного Write-progress CMDLET с использованием:
- Писать-хост
- Написать-дебуг
- Написать. Вербоз
- Записать-информацию
Бесплатная поддержка с транскрипциями PowerShell.

Вывод каждого из Write-* CMDLETS могут быть улучшены с помощью следующей дополнительной информации:

Источник Это исходный скрипт или имя модуля, которое выполнило Write- Комдлет.
Вызывающий абонент Это имя сценария или модуля, который выполнил Написать- Комдлет.
Дата Это дата, часть текущей даты.
Время Это время часть текущей даты.

Вышеуказанная функциональность включена или отключена с помощью следующих групп командлетов:

Чтобы включить/отключить различные уровни переменных предпочтения:
- SET-XGLOBALTRACE
- Und-xglobaltrace
Чтобы включить/отключить усиленный выход
- Inable-xwrite
- Отключить-xwrite
Чтобы включить/отключить перенаправление вывода прогресса
- Enable-xWriteProgress
- Отключить-xwriteProgress

Настройка для демонстрации

Чтобы продемонстрировать, давайте сначала создать образец функции Test-MyxWrite Это просто пишет значение предпочтения за Отладка , Подробный , Информация и Предупреждение Используя уважаемые командлеты Write-debug , Write-verbose , Write-information и Написать-воротный Анкет То же самое записано для хоста, используя Write-host Комдлет.

# Sample function that uses Write-* commands without any changes
function Test-MyXWrite
{
    param(
    )

    $message=@(
        "DebugPreference=$DebugPreference"
        "VerbosePreference=$VerbosePreference"
        "InformationPreference=$InformationPreference"
        "WarningPreference=$WarningPreference"
    )

    $message|ForEach-Object {
        Write-Host $_
    }

    Write-Debug "DebugPreference=$DebugPreference"
    Write-Verbose "VerbosePreference=$VerbosePreference"
    Write-Information "InformationPreference=$InformationPreference"
    Write-Warning "WarningPreference=$WarningPreference"
}

Затем мы сначала включим все переменные предпочтения, используя SET-XGLOBALTRACE , вызвать Test-MyxWrite и отменить изменения SET-XGLOBALTRACE используя Und-xglobaltrace Анкет

# Enable full trace 
Set-XGlobalTrace -ForAll

# Invoke test function to execute the Write-* commands
Test-MyXWrite

# Disable full trace. Rollback to original settings
Undo-XGlobalTrace

Вот как это выглядит:

Демонстрация xwrite Enhanced Output

Чтобы продемонстрировать расширенный выход, нам просто нужно включить его, используя Enable-xwrite и остальная часть демонстрации такая же, как и раньше.

# Enable XWrite default output enhancement
Enable-XWrite -ForAll

# Enable full trace 
Set-XGlobalTrace -ForAll

# Invoke test function to execute the Write-* commands
Test-MyXWrite

# Disable full trace. Rollback to original settings
Undo-XGlobalTrace

Вот как это выглядит:

Обратите внимание, что имя Invoker, то есть Test-MyxWrite Появляется тоже.

Демонстрация xWrite Advanced Enhanced Output

Увеличенный выход может быть настроен для вывода дополнительной информации с дополнительными токенами, такими как тип Invoker и TimeStamp, используя дополнительные параметры Enable-xwrite Анкет

# Enable XWrite advanced output enhancement
Enable-XWrite -ForAll -Source -Date -Time

# Enable full trace 
Set-XGlobalTrace -ForAll

# Invoke test function to execute the Write-* commands
Test-MyXWrite

# Disable full trace. Rollback to original settings
Undo-XGlobalTrace

Вот как это выглядит:

Обратите внимание, что источник Функция и временная метка добавлена на имя `test-myxwrite.

Форматирование расширенного вывода

Модуль добавит префикс к выводу со следующей логикой:

Имя Invoker Test-MyxWrite всегда присутствует.
Когда -Источник Параметр используется, тогда добавляется источник Invoker. Например
- Функция Когда вызов исходит из функции, объявленной в сфере, как указано выше.
- Модульское имя Когда вызов исходит из функции, которая является частью модуля.
- Имя файла Когда вызов исходит из файла скрипта.
- <Скрипт> Когда вызов исходит из блока сценария.
Когда -Дата или Время используется, тогда их уважаемые значения добавляются.
Когда -Разделитель используется параметр, затем по умолчанию : Сепаратор адаптирован.
Когда -Формат Указан параметр, тогда используется предоставленный пользовательский формат. Действительные токены:
- %источник%
- %Caller%
- %дата%
- % времени% Анкет

Это консолидированная матрица «

Тип инвентаря	-Источник	Функция	%источник%
Имя Invoker	Нет параметра. Всегда активный	Test-MyxWrite	%Caller%
штампа даты, отформатированная как yyyymmdd	-Дата	20170804	%дата%
штампа времени, отформатированная как HH: MM: Ss.fff	-Время	10: 57: 27.858	%время%

Соображения

Модуль работает, проведя глобальную реализацию перезаписи уважаемого командлета над основным от Microsoft. PowerShell. Утилита Пространство имен. Это эффективно перезаписывает поведение по умолчанию каждого Write-* Комдлет. С этим пониманием всегда нужно учитывать следующее:

Когда вызов похож на Microsoft. PowerShell. Утилита/write-host Затем глобальный перезапись обойден.
Двоичные модули, нацеленные на составление имен, сцены Write-* функции и из -за этого Xwrite не будет улучшать их выход.

Влияние на основную функциональность PowerShell

Воздействие минимально, потому что Xwrite Использует приведенные выше соображения и позволяет по умолчанию PowerShell Write-* Функциональность делает тяжелую работу. Это означает, что модуль не мешает PowerShell и просто изменяет полезную нагрузку использованных параметров.

Лучшие практики

Вот несколько лучших практик, которые я приобрел за эти годы:

Используйте Enable-xwrite и Enable-xWriteProgress до SET-XGLOBALTRACE Потому что они пишут Отладка Тело перезаписи и это может загромотить выход.
Если вы хотите подготовиться к реализации каждой из функций перезаписи, используйте SET-XGLOBALTRACE сначала, а затем призвать Enable-xwrite и Enable-xWriteProgress
Вам не нужно ничего делать с выводом транскрипции. Это управляется PowerShell путем перенаправления вывода в файл. С тех пор Xwrite Использовал собственную PowerShell Write-* Функциональность это просто работает.
Попробуйте вызвать Enable-xwrite и Enable-xwriteprogress Как можно раньше в вашем сеансе, с самого начала улучшаются любые стенограммы.
- Для ваших интерактивных сеансов просто добавьте в свой скрипт профиля.
- Для неинтерактивных потоков это может быть частью трубопровода.

Первоначально опубликовано здесь

Оригинал: «https://dev.to/sarafian/enhance-powershell-tracing-and-logging-for-the-console-and-transcriptions-574g»