Полное руководство по логированию ошибок привязки сборок

Узнайте, как включить логирование ошибок привязки сборок (Fusion) в .NET для устранения проблем с загрузкой. Руководство с настройками реестра и скриптами PowerShell.

Авторы: НейроАгент

22.11.2025, 17:58

Как включить логирование ошибок привязки сборок (Fusion) в .NET?

Для включения логирования ошибок привязки сборок (Fusion) в .NET необходимо настроить параметры реестра или воспользоваться утилитой Fusion Log Viewer (fuslogvw.exe). Основной способ – установить DWORD‑значение EnableLog в 1 в ключе реестра HKLM\Software\Microsoft\Fusion, при желании добавить ForceLog, LogFailures и LogResourceBinds для более подробного логирования. После включения логирования воспроизводите проблему привязки, чтобы зафиксировать логи в указанном месте.

Содержание

Включение логирования Fusion через реестр
Использование Fusion Log Viewer (fuslogvw.exe)
Подходы с PowerShell и скриптами
Конфигурация Azure App Service
Отключение логирования Fusion
[Лучшие практики и соображения](#лучшие-практики-и- соображения)

Включение логирования Fusion через реестр

Самый распространённый способ включения логирования ошибок привязки сборок – настройка реестра Windows. Этот подход работает для приложений .NET Framework и обеспечивает всестороннее логирование.

Базовая конфигурация реестра

Для включения базового логирования Fusion необходимо изменить реестр, используя редактор реестра (regedit) или командную строку:

cmd

reg add "HKLM\Software\Microsoft\Fusion" /v EnableLog /t REG_DWORD /d 1 /f

Эта команда создаёт или изменяет значение EnableLog и устанавливает его в 1, что активирует логирование ошибок привязки сборок.

Расширенная конфигурация реестра

Для более подробного логирования можно настроить дополнительные значения реестра:

cmd

reg add "HKLM\Software\Microsoft\Fusion" /v ForceLog /t REG_DWORD /d 1 /f
reg add "HKLM\Software\Microsoft\Fusion" /v LogFailures /t REG_DWORD /d 1 /f
reg add "HKLM\Software\Microsoft\Fusion" /v LogResourceBinds /t REG_DWORD /d 1 /f
reg add "HKLM\Software\Microsoft\Fusion" /v LogPath /t REG_SZ /d "C:\FusionLog\" /f

Если каталог логов не существует, его нужно создать:

cmd

if not exist "C:\FusionLog\" mkdir "C:\FusionLog"

Описание значений реестра

EnableLog – основной переключатель включения/выключения логирования Fusion (1 = включено, 0 = отключено)
ForceLog – принудительное логирование всех попыток привязки, а не только ошибок
LogFailures – логирование только ошибок привязки
LogResourceBinds – логирование дополнительной информации о привязке ресурсов
LogPath – путь к каталогу, где будут храниться файлы логов

Важно: Согласно Stack Overflow, «Если вы когда‑то включите это логирование, НЕ ЗАБУДЬТЕ ОТКЛЮЧИТЬ ИМЕНО, иначе вы пожалеете. Я забыл, и в итоге у меня было несколько гигабайт маленьких файлов с расширением .htm в C:\Windows\System32\config\systemprofile\AppData\Local\Microsoft\Windows\INetCache\IE – это, видимо, логировало все привязки сборок от приложений, работающих под NT AUTHORITY\SYSTEM».

Использование Fusion Log Viewer (fuslogvw.exe)

Fusion Log Viewer (fuslogvw.exe) – графический инструмент от Microsoft, упрощающий включение и просмотр логов привязки сборок.

Запуск инструмента

Вы можете запустить Fusion Log Viewer несколькими способами:

Через командную строку Visual Studio (рекомендуется):
- Откройте командную строку Visual Studio от имени администратора
- Введите fuslogvw и нажмите Enter
Через редактор реестра:
- Перейдите в HKLM\Software\Microsoft\Fusion
- Дважды щёлкните по EnableLog и установите его в 1
- Затем запустите fuslogvw.exe из любой командной строки

Настройка параметров логирования

После открытия Fusion Log Viewer:

Нажмите кнопку «Settings»
Выберите «Log bind failures to disk»
Укажите каталог для логов
Нажмите OK, чтобы сохранить настройки

Просмотр файлов логов

После включения логирования и воспроизведения проблемы привязки:

Нажмите кнопку «Refresh» в Fusion Log Viewer
Ошибки привязки отобразятся в главном окне
Дважды щёлкните любой элемент, чтобы увидеть подробную информацию о привязке

Как объясняет Microsoft Learn, «Чтобы увидеть полную информацию, используйте одну из других настроек. См. важную заметку относительно сборок, загружаемых как domain neutral. Выберите кнопку Log bind failures to disk».

Подходы с PowerShell и скриптами

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

Скрипт PowerShell для включения логирования

powershell

$LogFilePath = 'C:\FusionLog\'
$FusionPath = 'HKLM:\Software\Microsoft\Fusion'

# Убедитесь, что каталог логов существует
if (-not (Test-Path $LogFilePath)) {
    New-Item -ItemType Directory -Path $LogFilePath | Out-Null
}

# Установить значения реестра
$Flags = @( 'ForceLog', 'LogFailures', 'LogResourceBinds' )
$Flags | ForEach-Object {
    Set-ItemProperty -Path $FusionPath -Name $_ -Value 1 -Type DWord
}

Set-ItemProperty -Path $FusionPath -Name LogPath -Value $LogFilePath -Type String
Set-ItemProperty -Path $FusionPath -Name EnableLog -Value 1 -Type DWord

Write-Host "Fusion logging enabled. Log files will be saved to: $LogFilePath"

Скрипт PowerShell для отключения логирования

powershell

$FusionPath = 'HKLM:\Software\Microsoft\Fusion'

# Сброс значений реестра для отключения логирования
Set-ItemProperty -Path $FusionPath -Name EnableLog -Value 0 -Type DWord
Set-ItemProperty -Path $FusionPath -Name ForceLog -Value 0 -Type DWord
Set-ItemProperty -Path $FusionPath -Name LogFailures -Value 0 -Type DWord
Set-ItemProperty -Path $FusionPath -Name LogResourceBinds -Value 0 -Type DWord

Write-Host "Fusion logging disabled."

Скрипты batch

Для сред, где PowerShell недоступен, можно использовать batch‑файлы:

cmd

@echo off
echo Enabling Fusion logging...

reg add "HKLM\Software\Microsoft\Fusion" /v EnableLog /t REG_DWORD /d 1 /f
reg add "HKLM\Software\Microsoft\Fusion" /v ForceLog /t REG_DWORD /d 1 /f
reg add "HKLM\Software\Microsoft\Fusion" /v LogFailures /t REG_DWORD /d 1 /f
reg add "HKLM\Software\Microsoft\Fusion" /v LogResourceBinds /t REG_DWORD /d 1 /f

if not exist "C:\FusionLog\" mkdir "C:\FusionLog\"
reg add "HKLM\Software\Microsoft\Fusion" /v LogPath /t REG_SZ /d "C:\FusionLog\" /f

echo Fusion logging enabled. Please restart your application.

Конфигурация Azure App Service

Для сред Azure App Service вы можете включить логирование Fusion через настройки приложения, а не напрямую редактируя реестр.

Включение в Azure Portal

Перейдите к вашему App Service в Azure Portal
Перейдите в «Configuration» > «Application settings»
Добавьте новое приложение‑настройку:
- Name: APPSETTING_EnableFusionLog
- Value: 1
Сохраните конфигурацию
Перезапустите приложение

Как объясняет документация Azure, «После сохранения этой настройки логирование Fusion будет включено для вашего приложения. Все процессы, запущенные для вашего приложения (w3wp.exe, w3wp.exe для сайта Kudu и любые дочерние процессы этих процессов), будут иметь включённое логирование Fusion. Это означает, что вы можете использовать эту функцию для устранения неполадок привязки сборок даже в WebJobs».

Просмотр логов в Azure

После включения логирования Fusion и воспроизведения проблемы:

Используйте консоль Kudu (https://yourapp.scm.azurewebsites.net/DebugConsole)
Перейдите в каталог логов (обычно D:\home\LogFiles\Application)
Найдите файлы логов Fusion с расширением .htm
Скачайте и просмотрите файлы логов в браузере

Отключение логирования Fusion

Правильное отключение логирования Fusion критически важно для предотвращения проблем с производительностью и чрезмерного использования дискового пространства.

Метод через реестр

cmd

reg add "HKLM\Software\Microsoft\Fusion" /v EnableLog /t REG_DWORD /d 0 /f
reg add "HKLM\Software\Microsoft\Fusion" /v ForceLog /t REG_DWORD /d 0 /f
reg add "HKLM\Software\Microsoft\Fusion" /v LogFailures /t REG_DWORD /d 0 /f
reg add "HKLM\Software\Microsoft\Fusion" /v LogResourceBinds /t REG_DWORD /d 0 /f

Метод PowerShell

powershell

$FusionPath = 'HKLM:\Software\Microsoft\Fusion'

Set-ItemProperty -Path $FusionPath -Name EnableLog -Value 0 -Type DWord
Set-ItemProperty -Path $FusionPath -Name ForceLog -Value 0 -Type DWord
Set-ItemProperty -Path $FusionPath -Name LogFailures -Value 0 -Type DWord
Set-ItemProperty -Path $FusionPath -Name LogResourceBinds -Value 0 -Type DWord

Write-Host "Fusion logging has been disabled."

Перезапуск процессов

После отключения логирования возможно потребуется перезапустить затронутые процессы, чтобы изменения вступили в силу:

Для IIS: iisreset
Для Windows Services: перезапустите службу
Для консольных приложений: перезапустите приложение

Лучшие практики и соображения

Когда включать логирование Fusion

Логирование Fusion следует включать, когда:

Вы сталкиваетесь с ошибками Could not load file or assembly
Перенаправления привязки сборок не работают как ожидается
Необходимо отладить проблемы разрешения зависимостей
Вы устраняете конфликты версий в смешанных средах .NET Framework

Влияние на производительность

Логирование Fusion может значительно снизить производительность приложения:

Дисковая I/O: файлы логов пишутся на диск для каждой попытки привязки
Память: дополнительная нагрузка на инфраструктуру логирования
CPU: затраты на захват и запись информации о привязке

Управление файлами логов

Файлы логов обычно сохраняются с расширением .htm
Они могут быстро накапливаться, занимая значительный объём диска
Рассмотрите возможность реализации ротации логов или политик очистки
Следите за размером каталога логов, особенно в продакшн‑средах

Безопасность

Файлы логов могут содержать конфиденциальную информацию о зависимостях вашего приложения
Обеспечьте надлежащий контроль доступа к каталогам логов
Рассмотрите возможность логирования только в средах разработки и тестирования
Перед распространением в поддержку просмотрите содержимое логов

.NET Core vs .NET Framework

Хотя приведённая информация в основном относится к .NET Framework, стоит отметить, что:

.NET Core использует другие механизмы загрузки сборок
Логирование Fusion в основном предназначено для приложений .NET Framework
Для .NET Core применяются другие подходы к устранению неполадок
Рассмотрите использование dotnet list assemblies или инструментов анализа зависимостей для .NET Core

Заключение

Включение логирования ошибок привязки сборок (Fusion) в .NET необходимо для диагностики сложных проблем загрузки сборок. Подход с реестром, использующий EnableLog, ForceLog и связанные значения, обеспечивает всестороннее логирование, в то время как Fusion Log Viewer предоставляет удобный интерфейс для просмотра и анализа логов. Для автоматизированных сред скрипты PowerShell и batch‑файлы дают программный контроль над конфигурацией логирования.

Ключевые рекомендации:

Включайте логирование только при необходимости и отключайте сразу после устранения проблемы
Используйте Fusion Log Viewer для интерактивного анализа и метод реестра для автоматизированных сценариев
Настраивайте подходящие пути логов и следите за размером файлов логов, чтобы избежать проблем с дисковым пространством
Для сред Azure используйте настройки приложения для включения логирования Fusion
Учитывайте влияние на производительность и внедряйте надлежащие практики управления логами

Следуя этим методам, вы сможете эффективно диагностировать и решать проблемы привязки сборок в ваших .NET‑приложениях, сохраняя при этом производительность и стабильность системы.

Источники

Авторы

НейроАгент

Автор

Проверено модерацией

НейроОтветы

Модерация