Отладка исключений в приложениях .NET с помощью отладчика моментальных снимков
С помощью отладчика моментальных снимков можно автоматически собирать моментальный снимок отладки при возникновении исключения в динамическом приложении .NET. Отладочные моментальные снимки, собранные, показывают состояние исходного кода и переменных в момент возникновения исключения.
Отладчик моментальных снимков в приложении Аналитика:
- отслеживает системные журналы, созданные веб-приложением;
- собирает моментальные снимки для исключений верхнего уровня;
- предоставляет сведения, необходимые для диагностики проблем с рабочей средой.
Поддерживаемые приложения и среды
В этом разделе перечислены поддерживаемые приложения и среды.
Приложения
Коллекция моментальных снимков доступна для:
- платформа .NET Framework версии 4.6.2 и более поздних версий.
- .NET 6.0 или более поздней версии в Windows.
Среды
Поддерживаются следующие среды:
- Служба приложений Azure
- Функции Azure
- Облачные службы Azure под управлением ОС семейства 4 или более поздней версии
- Azure Service Fabric под управлением Windows Server 2012 R2 или более поздней версии
- Azure Виртуальные машины и Azure Масштабируемые наборы виртуальных машин под управлением Windows Server 2012 R2 или более поздней версии
- Локальные виртуальные машины или физические компьютеры под управлением Windows Server 2012 R2 или более поздней версии, а также Windows 8.1 или более поздней версии
Примечание.
Клиентские приложения (например, WPF, Windows Forms или UWP) не поддерживаются.
Предварительные требования для использования отладчика моментальных снимков
Пакеты и конфигурации
- Включите пакет NuGet сборщика моментальных снимков в приложение.
- Настройка параметров коллекции в
ApplicationInsights.config
.
Разрешения
- Убедитесь, что вы добавляете в роль отладчика моментальных снимков приложения Аналитика для целевого приложения Аналитика моментального снимка.
Как работает отладчик моментальных снимков
Отладчик моментальных снимков реализуется как обработчик телеметрии Аналитика приложения. При запуске приложения обработчик телеметрии отладчика моментальных снимков добавляется в конвейер системных журналов приложения.
Важно!
Моментальные снимки могут содержать персональные данные или другую конфиденциальную информацию в значениях переменных и параметров. Данные моментальных снимков хранятся в том же регионе, что и ресурс приложения Аналитика.
Процесс отладчика моментальных снимков
Процесс отладчика моментальных снимков начинается и заканчивается методом TrackException
. Моментальный снимок процесса — это приостановленный клон выполняемого процесса, чтобы пользователи не сталкивались с перерывами.
Приложение создает исключение
TrackException
.Отладчик моментальных снимков отслеживает исключения по мере их создания, подписавшись на
AppDomain.CurrentDomain.FirstChanceException
событие.Счетчик увеличивается для идентификатора проблемы.
- Когда счетчик достигает
ThresholdForSnapshotting
значения, идентификатор проблемы добавляется в план сбора.
Примечание.
Минимальное
ThresholdForSnapshotting
значение по умолчанию — 1. С этим значением приложение должен активировать одно и то же исключение дважды перед созданием моментального снимка.- Когда счетчик достигает
Идентификатор проблемы события исключения вычисляется и сравнивается с идентификаторами проблем в плане сбора.
Если между идентификаторами проблем возникает совпадение, создается моментальный снимок выполняемого процесса.
- Моментальному снимку назначается уникальный идентификатор, и к исключению добавляется метка с этим идентификатором.
Примечание.
Частота создания моментальных снимков ограничивается параметром
SnapshotsPerTenMinutesLimit
. По умолчанию ограничение составляет один моментальный снимок каждые 10 минут.Когда возвращается дескриптор
FirstChanceException
, вызванное исключение обрабатывается в обычном режиме.Исключение снова достигает
TrackException
метода и сообщается приложению Аналитика вместе с идентификатором моментального снимка.
Примечание.
Установите для IsEnabledInDeveloperMode
true
создания моментальных снимков во время отладки в Visual Studio.
Процесс отправки моментальных снимков
Хотя процесс отладчика моментальных снимков продолжает выполняться и обслуживать трафик для пользователей с небольшим прерыванием, моментальный снимок передается процессу отправки моментальных снимков. Средство отправки моментальных снимков:
Создает мини-dump.
Отправляет мини-dump в приложение Аналитика вместе с любыми соответствующими файлами символов (PDB).
Примечание.
Не более 50 моментальных снимков в день можно отправлять.
Если вы включили отладчик моментальных снимков, но не видите моментальные снимки, см . руководство по устранению неполадок.
Ограничения
В этом разделе рассматриваются ограничения для отладчика моментальных снимков.
Хранение данных
Моментальные снимки отладки хранятся в течение 15 дней. Политика хранения по умолчанию задается для каждого приложения отдельно. Если нужно изменить этот параметр, вы можете запросить изменения, открыв окно Службы Поддержки на портале Microsoft Azure. Для каждого экземпляра Application Insights разрешено максимум 50 моментальных снимков в день.
Публикация символов
Отладчик моментальных снимков требует файлов символов на рабочем сервере:
- Декодирование переменных
- Предоставление возможности отладки в Visual Studio
По умолчанию Visual Studio 2017 версии 15.2+ публикует символы для сборок выпуска при публикации в Служба приложений.
В предыдущих версиях необходимо добавить следующую строку в файл профиля
.pubxml
публикации, чтобы символы были опубликованы в режиме выпуска:<ExcludeGeneratedDebugSymbol>False</ExcludeGeneratedDebugSymbol>
Для вычислений Azure и других типов убедитесь, что файлы символов являются следующими:
- В той же папке основного приложения
.dll
(как правило,wwwroot/bin
) или - Доступно по текущему пути.
Дополнительные сведения о различных доступных вариантах символов см. в документации по Visual Studio. Для получения наилучших результатов рекомендуется использовать полный, переносимый или внедренный.
Оптимизированные сборки
В некоторых случаях локальные переменные нельзя просматривать в сборках выпуска из-за оптимизации, примененной компилятором JIT.
Однако в Служба приложений отладчик моментальных снимков может деоптимизировать методы создания, которые являются частью плана сбора.
Совет
Установите расширение сайта application Аналитика в экземпляре Служба приложений, чтобы получить поддержку deoptimization.
Следующие шаги
Включите отладчик моментальных снимков приложения Аналитика для приложения:
- Служба приложений Azure
- Функции Azure
- Oблачныe службы Azure2
- Azure Service Fabric
- Azure Виртуальные машины и Масштабируемые наборы виртуальных машин
- Локальные виртуальные или физические машины
Заметки о выпуске Microsoft.ApplicationInsights.SnapshotCollector
:
В этом разделе содержатся заметки Microsoft.ApplicationInsights.SnapshotCollector
о выпуске пакета NuGet для приложений .NET, который используется отладчиком моментальных снимков приложения Аналитика.
Дополнительные сведения о Snapshot Debugger в Application Insights для приложений .NET.
Для отчетов об ошибках и отзывов откройте проблему на сайте GitHub.
Примечание.
Поддержка приема ключей инструментирования будет завершена 31 марта 31, 2025 г. Прием ключей инструментирования будет и дальше осуществляться, но мы больше не будем предоставлять обновления или поддержку для этой функции. Перейдите на строки подключения, чтобы использовать новые возможности.
1.4.6
Точка выпуска для решения регрессии при использовании приложений .NET 8.
Исправления ошибок
- Исключения, создаваемые динамически созданными методами (например, скомпилированные деревья выражений) в .NET 8 не отслеживаются правильно. Фиксированный.
1.4.5
Точечный выпуск для устранения ошибки, о которой сообщил пользователь.
Исправления ошибок
- Исправлено AccessViolationException при чтении некоторых PDF-файлов.
Изменения
- Добавлен модуль ReadMe в пакет NuGet.
- Обновлены msdia140.dll.
1.4.4
Точечный выпуск для устранения ошибок, о которых сообщают пользователи.
Исправления ошибок
- Исправлено исключение во время извлечения собственных компонентов при использовании одного приложения файлов.
Изменения
- Снизив сообщения о сбоях проверки PDB из ошибки в предупреждение.
- Обновлены msdia140.dll.
- Избегайте подключения к службе, если отладчик отключен с помощью параметров расширения сайта.
1.4.3
Точечный выпуск для устранения ошибок, о которых сообщают пользователи.
Исправления ошибок
- Исправлено скрыть зависимость IMDS от средства отслеживания зависимостей.
- Исправлена функция ArgumentException: telemetryProcessorTypedoes не реализует ITelemetryProcessor..
Сборщик моментальных снимков, используемый через пакет SDK, не поддерживается при включении функции взаимодействия. Дополнительные сведения о сценариях, не поддерживаемых.
1.4.2
Точечный выпуск для устранения ошибки, о которой сообщил пользователь.
Исправления ошибок
Исправлена функция ArgumentException: делегаты должны иметь одинаковый тип.
1.4.1
Точечный выпуск для отмены критического изменения, появившегося в версии 1.4.0.
Исправления ошибок
Исправлен метод, который не найден в веб-заданиях.
1.4.0
Устранено несколько улучшений и добавлена поддержка проверки подлинности Microsoft Entra для приема приложений Аналитика.
Изменения
- Уменьшение размера пакета сборщика моментальных снимков на 60% от 10,34 МБ до 4,11 МБ.
- Целевой netstandard2.0 только в сборщике моментальных снимков.
- Зависимость пакета SDK для приложения Аналитика с 2.15.0.
- Добавлено обратно
MinidumpWithThreadInfo
при написании дампов. - Добавлено
CompatibilityVersion
для улучшения синхронизации между агентом сборщика моментальных снимков и средством отправки моментальных снимков при критических изменениях. - Изменен
SnapshotUploader
алгоритм именования LogFile, чтобы избежать чрезмерного ввода-вывода файлов в Служба приложений. - Добавлен ,
pid
role name
а такжеprocess start time
для отправки метаданных BLOB-объектов. - Используется
System.Diagnostics.Process
в сборщике моментальных снимков и средство отправки моментальных снимков.
Новые возможности
Добавлена проверка подлинности SnapshotCollector
Microsoft Entra в . Дополнительные сведения о проверке подлинности Microsoft Entra в приложении Аналитика см. в статье Microsoft Entra authentication for Application Аналитика.
1.3.7.5
Промежуточный выпуск для исправления ошибок из версии 1.4.0-pre.
Исправления ошибок
Исправлено objectDisposedException при завершении работы.
1.3.7.4
Точка выпуска для решения проблемы, обнаруженной при тестировании сценария подключения без кода Служба приложений.
Изменения
Целевой netcoreapp3.0
объект теперь зависит от Microsoft.ApplicationInsights.AspNetCore
>= 2.1.1 (ранее >= 2.1.2).
1.3.7.3
Промежуточный выпуск для исправления нескольких критических проблем.
Исправления ошибок
- Исправлено обнаружение PDB в папке wwwroot/bin , которая была нарушена при изменении алгоритма поиска символов в версии 1.3.6.
- Исправлен шумный
ExtractWasCalledMultipleTimesException
в телеметрии.
1.3.7
Изменения
Целевой netcoreapp2.0
SnapshotCollector
объект зависит от Microsoft.ApplicationInsights.AspNetCore
>= 2.1.1 (снова). Это изменение отменить изменения поведения до 1.3.5. Мы пытались обновить его в версии 1.3.6, но она сломала некоторые Служба приложений сценарии.
Новые возможности
Сборщик моментальных снимков считывает ConnectionString
и анализирует переменную среды APPLICATIONINSIGHTS_CONNECTION_STRING или из нее TelemetryConfiguration
. В первую очередь он используется для установки конечной точки для подключения к службе моментальных снимков. Дополнительные сведения см. в документации по строкам подключения.
Исправления ошибок
Переключился на использование HttpClient
для всех целевых объектов, за исключением net45
того, что WebRequest
произошел сбой в некоторых средах из-за несовместимости SecurityProtocol
(требуется TLS 1.2).
1.3.6
Изменения
SnapshotCollector
теперь зависит отMicrosoft.ApplicationInsights
>= 2.5.1 для всех целевых платформ. Это требование может быть критическим изменением, если приложение зависит от старой версии пакета SDK Microsoft.Application Аналитика.- Удалена поддержка TLS 1.0 и 1.1 в средство отправки моментальных снимков.
- Период сканирования PDB теперь по умолчанию составляет 24 часа, а не 15 минут. Настраиваемая с помощью
PdbRescanInterval
SnapshotCollectorConfiguration
. - При сканировании PDB выполняется поиск только папок верхнего уровня, а не рекурсивный поиск. Это изменение может быть критическим изменением, если символы находятся в вложенных папках двоичной папки.
Новые возможности
- Смена
SnapshotUploader
журнала, чтобы избежать заполнения папки журналов старыми файлами. - Поддержка деоптимизации (через ReJIT при присоединении) для приложений .NET Core 3.0.
- Добавлены символы в пакет NuGet.
- Задайте дополнительные метаданные при отправке мини-модулей.
- Добавлено
Initialized
свойствоSnapshotCollectorTelemetryProcessor
. Это объектCancellationToken
, который отменяется при инициализации сборщика моментальных снимков и подключении к конечной точке службы. - Теперь моментальные снимки можно записывать для исключений в динамически создаваемых методах. Примером является скомпилированные деревья выражений, созданные запросами Entity Framework.
Исправления ошибок
AmbiguousMatchException
загрузка сборщика моментальных снимков из-за монитора состояния.GetSnapshotCollector
Метод расширения теперь выполняет поиск всехTelemetrySinks
.- Не запускайте отправку моментального снимка на неподдерживаемых платформах.
- Обработка
InvalidOperationException
при удалении динамических методов (например, Entity Framework).
1.3.5
- Добавлена поддержка национальных облаков (старые версии не работают в национальных облаках).
- Упрощение добавления сборщика моментальных снимков с помощью
AddSnapshotCollector()
. Дополнительные сведения см. в разделе "Включить отладчик моментальных снимков" для приложений .NET в службе приложение Azure. - Используйте параметр FISMA MD5 для проверки блоков BLOB-объектов. Этот параметр позволяет избежать алгоритма шифрования .NET MD5 по умолчанию, который недоступен при установке режима, совместимого с FIPS.
- Пропуск кадров .NET Framework при деоптимизации вызовов функций. Управляйте этим поведением
DeoptimizeIgnoredModules
с помощью параметра конфигурации. - Добавлен
DeoptimizeMethodCount
параметр конфигурации, позволяющий деоптимизации нескольких вызовов функции.
1.3.4
- Разрешенные структурированные ключи инструментирования.
- Повышенная надежность средства отправки моментальных снимков. Продолжить запуск, даже если старые журналы отправки не могут быть перемещены.
- Повторное создание отчетов о большей телеметрии при немедленном выходе SnapshotUploader.exe (отключено в версии 1.3.3).
- Упрощенная внутренняя телеметрия.
- Экспериментальная функция: планы сбора Snappoint: добавление
snapshotOnFirstOccurence
. Дополнительные сведения см . в этой статье GitHub.
1.3.3
Исправлена ошибка, из-за которой SnapshotUploader.exe перестать отвечать на запросы и не отправлять моментальные снимки для приложений .NET Core.
1.3.2
- Экспериментальная функция. Планы сбора точек моментальных снимков. Дополнительные сведения см . в этой статье GitHub.
- SnapshotUploader.exe завершает работу при выгрузке
AppDomain
среды выполнения, из которойSnapshotCollector
загружается, вместо ожидания завершения процесса. Это действие повышает надежность сборщика при размещении в СЛУЖБАх IIS. - Добавлена конфигурация, позволяющая нескольким
SnapshotCollector
экземплярам, использующим один и тот же ключ инструментирования, совместно использовать один и тот жеSnapshotUploader
процесс:ShareUploaderProcess
(по умолчаниюtrue
— ). - Сообщается больше телеметрии при немедленном выходе SnapshotUploader.exe .
- Уменьшите количество файлов поддержки, SnapshotUploader.exe необходимо записать на диск.
1.3.1
- Удалена поддержка сбора моментальных снимков с помощью API RtlCloneUserProcess и поддерживается только API PssCaptureSnapshots.
- Увеличено ограничение по умолчанию на количество моментальных снимков в течение 10 минут от одного до трех.
- Разрешить SnapshotUploader.exe согласованию TLS 1.1 и 1.2.
- Сообщается больше телеметрии при
SnapshotUploader
регистрации предупреждения или ошибки. - Остановите создание моментальных снимков при достижении внутренней службы ежедневной квоты (50 моментальных снимков в день).
- Добавлен дополнительный проверка в SnapshotUploader.exe, чтобы два экземпляра не выполнялись одновременно.
1.3.0
Изменения
- Для приложений, предназначенных для платформа .NET Framework, сборщик моментальных снимков теперь зависит от Microsoft.Application Аналитика версии 2.3.0 или более поздней версии. Он использовался для версии 2.2.0 или более поздней версии. Мы считаем, что это изменение не будет проблемой для большинства приложений. Сообщите нам, не будет ли это изменение использовать последний сборщик моментальных снимков.
- Используются экспоненциальные задержки в Snapshot Uploader при повторной попытке загрузки.
- Используйте
ServerTelemetryChannel
(если доступно) для более надежной отчетности телеметрии. - Используйте
SdkInternalOperationsMonitor
начальное подключение к службе отладчика моментальных снимков, чтобы отслеживание зависимостей пропускало его. - Улучшена телеметрия вокруг начального подключения к отладчику моментальных снимков.
- Сообщите больше телеметрии для следующих задач:
- Служба приложений версии.
- Вычислительные экземпляры Azure.
- Контейнеры.
- Функции Azure приложения.
Исправления ошибок
- Если для интервала сброса счетчика проблемы задано значение 24 дня, это интерпретируется как 24 часа.
- Исправлена ошибка, при которой отработка моментального снимка прекращает обработку новых моментальных снимков, если при удалении моментального снимка возникло исключение.
1.2.3
Исправлена подпись строгого имени с двоичными файлами средства отправки моментальных снимков.
1.2.2
Изменения
- Файлы, необходимые для SnapshotUploader(64).exe теперь внедрены в качестве ресурсов в основной библиотеке DLL. Это означает, что
SnapshotCollectorFiles
папка больше не создается, что упрощает сборку и развертывание и снижает нагрузку на Обозреватель решений. Следите за обновлением, чтобы просмотреть изменения в.csproj
файле. ФайлMicrosoft.ApplicationInsights.SnapshotCollector.targets
больше не требуется. - Данные телеметрии регистрируются в ресурсе Application Аналитика, даже если
ProvideAnonymousTelemetry
задано значение false. Это изменение позволяет реализовать функцию проверка работоспособности в портал Azure.ProvideAnonymousTelemetry
влияет только на данные телеметрии, отправляемые корпорации Майкрософт для поддержки и улучшения продуктов. - Когда
TempFolder
илиShadowCopyFolder
перенаправляются в переменные среды, не используйте сборщик бездействия до тех пор, пока эти переменные среды не будут заданы. - Для приложений, которые подключаются к Интернету через прокси-сервер, сборщик моментальных снимков теперь автоматически определяет все параметры прокси-сервера и передает их в SnapshotUploader.exe.
- Ниже приоритет
SnapshotUploader
процесса (по возможности). Этот приоритет можно переопределить с помощьюIsLowPrioirtySnapshotUploader
параметра. - Добавлен
GetSnapshotCollector
методTelemetryConfiguration
расширения для сценариев, в которых необходимо программно настроить сборщик моментальных снимков. - Задана версия пакета SDK Application Insights (вместо версии приложения) в телеметрических данных, доступных для клиентов.
- Первое событие пульса отправляется через две минуты.
Исправления ошибок
- Исправлено
NullReferenceException
, если исключения имеют словари данных null или неизменяемые. - В Uplaoder попытку выполнить повторное выполнение PDB-файла повторяется несколько раз при получении нарушения общего доступа.
- Исправлена ошибка дубликата телеметрии, когда несколько потоков вызывают конвейер телеметрии при запуске.
1.2.1
Изменения
- Файлы комментариев XML Doc теперь включены в пакет NuGet.
- Добавлен
ExcludeFromSnapshotting
методSystem.Exception
расширения для сценариев, в которых вы знаете, что у вас есть шумное исключение и хотите избежать создания моментальных снимков для него. - Добавлено
IsEnabledWhenProfiling
свойство конфигурации, которое по умолчанию имеет значение true. Это изменение по сравнению с предыдущими версиями, где создание моментального снимка было временно отключено, если в Application Insights Profiler собиралась детальная коллекция. Старое поведение можно восстановить, задав для этого свойства значениеfalse
.
Исправления ошибок
- Подписывая SnapshotUploader64.exe правильно.
- Защита от двойной инициализации обработчика данных телеметрии.
- Предотвращен двойной журнал телеметрии в приложениях с несколькими конвейерами.
- Исправлена ошибка с истечением срока действия плана сбора, что может препятствовать моментальным снимкам через 24 часа.
1.2.0
Крупнейшим изменением в этой версии (и, таким образом, переходом на новый дополнительный номер версии) является перезапись конвейера создания и обработки моментального снимка. В предыдущих версиях эта функция реализована в машинном коде (ProductionBreakpoints.dll* и SnapshotHolder.exe*). Новая реализация — это весь управляемый код с P/Invoke.
Для первой версии, использующей новый конвейер, мы не использовали исходное поведение. Новая реализация обеспечивает более эффективное создание отчетов об ошибках и улучшения будущих улучшений.
Другие изменения в этой версии
- MinidumpUploader.exe переименован в SnapshotUploader.exe (или SnapshotUploader64.exe).
- Добавлена телеметрия по времени для деоптимизации или реоптимизации запросов.
- Добавлено сжатие Gzip для отправки минидампа.
- Исправлена проблема, при которой PDB-файлы блокируются, что препятствует обновлению сайта.
- Регистрируйте исходное имя папки (SnapshotCollectorFiles) при теневом копировании.
- Скорректированные ограничения памяти для 64-разрядных процессов, чтобы предотвратить перезапуск сайта из-за OOM.
- Исправлена проблема, из-за которой моментальные снимки по-прежнему были собраны даже после отключения.
- События пульса регистрируются в ресурсе AI клиента.
- Улучшена скорость моментального снимка путем удаления источника из идентификатора проблемы.
1.1.2
Изменения
- Расширенная телеметрия использования.
- Обнаружение и отправка отчетов о версии и ОС .NET.
- Обнаружение и создание отчетов о дополнительных средах Azure (Azure Облачные службы, Azure Service Fabric).
- Метрики исключений записей и отчетов (количество исключений первого шанса
TrackException
и количество вызовов) в телеметрии Heartbeat.
Исправления ошибок
- Правильная обработка, в
SqlException
которой не создается внутреннее исключение (Win32Exception). - Обрезанные конечные пробелы в папках символов, которые привели к
MinidumpUploader
неправильному анализу аргументов командной строки. - Не удалось выполнить бесконечные повторные попытки неудачных подключений к конечной точке агента отладчика моментальных снимков.
1.1.0
Изменения
- Добавлена защита памяти узла. Эта функция снижает потребление памяти главного компьютера.
- Улучшен процесс просмотра моментальных снимков портал Azure.