Отладка приложений ASP.NET Core

В этой статье описывается отладка приложений, включая отладку BlazorBlazor WebAssembly приложений с помощью средств разработчика браузера или интегрированной среды разработки (IDE).

Blazorвеб-приложения можно отладить в Visual Studio или Visual Studio Code.

Blazor WebAssembly приложения можно отладить:

• В Visual Studio или Visual Studio Code.
• Использование средств разработчика браузера в браузерах на основе Chromium, включая Microsoft Edge, Google Chrome и Firefox.

Доступные сценарии отладки Blazor WebAssembly :

• Установка и удаление точек останова.
• Запуск приложения с поддержкой отладки в IDE.
• Пошаговое прохождение кода.
• Возобновление выполнения кода с помощью сочетания клавиш в IDE.
• Просмотр значений локальных переменных в окне Локальные переменные.
• Просмотр стека вызовов, включая цепочки вызовов между JavaScript и .NET.
• Используйте сервер символов для отладки, настроенный предпочтениями Visual Studio.

Неподдерживаемые сценарии включают:

• Отладка в нелокальных сценариях (например, в подсистеме Windows для Linux (WSL) или Visual Studio Codespaces).
• Отладка в Firefox из Visual Studio или Visual Studio Code.

Необходимые компоненты

В этом разделе описываются предварительные требования для отладки.

Предварительные требования для браузера

Последняя версия следующих браузеров:

• Google Chrome
• Microsoft Edge
• Firefox (только средства разработчика браузера)

Убедитесь, что брандмауэры или прокси-серверы не блокируют обмен данными с прокси-сервером отладки (процесс NodeJS). Дополнительные сведения см. в разделе Настройка брандмауэра.

Примечание.

В настоящее время Apple Safari в macOS не поддерживается.

Предварительные требования к интегрированной среде разработки

Требуется последняя версия Visual Studio или Visual Studio Code.

Предварительные требования Visual Studio Code

Для Visual Studio Code требуется пакет средств разработки C# для Visual Studio Code (начало работы с C# в VS Code). В Visual Studio Code Extensions Marketplace отфильтруйте список расширений с помощью "c# dev kit", чтобы найти расширение:

Установка комплекта разработки C# автоматически устанавливает следующие дополнительные расширения:

• Средство установки .NET
• C#
• Набор средств разработки IntelliCode для C#

При возникновении предупреждений или ошибок можно открыть проблему (microsoft/vscode-dotnettools репозиторий GitHub), описывающую проблему.

Предварительные требования к конфигурации приложений

Руководство в этом подразделе относится к отладке на стороне клиента.

Properties/launchSettings.json Откройте файл запускаемого проекта. Подтвердите наличие следующего inspectUri свойства в каждом профиле запуска узла файла profiles . Если следующее свойство отсутствует, добавьте его в каждый профиль:

"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}"

Свойство inspectUri:

• Позволяет интегрированной среде разработки обнаруживать, что приложение является приложением Blazor.
• Предписывает инфраструктуре отладки сценариев подключаться к браузеру через прокси-сервер отладки Blazor.

Прототипы значений для протокола WebSocket (wsProtocol), узла (url.hostname), порта (url.port) и URI инспектора в запущенном браузере (browserInspectUri) предоставляются платформой.

Пакеты

Blazorвеб-приложения. Microsoft.AspNetCore.Components.WebAssembly.ServerСсылки на внутренний пакет (Microsoft.NETCore.BrowserDebugHost.Transport) для сборок, использующих узел отладки браузера.

Автономный Blazor WebAssembly: Microsoft.AspNetCore.Components.WebAssembly.DevServer: сервер разработки для использования при создании Blazor приложений. Вызывает WebAssemblyNetDebugProxyAppBuilderExtensions.UseWebAssemblyDebugging на внутреннем уровне, чтобы добавить ПО промежуточного слоя для отладки приложений Blazor WebAssembly в средствах для разработчика Chromium.

Примечание.

Рекомендации по добавлению пакетов в приложения .NET см. в разделе Способы установки пакетов NuGet в статье Рабочий процесс использования пакета (документация по NuGet). Проверьте правильность версий пакета на сайте NuGet.org.

Отладка Blazor веб-приложения в интегрированной среде разработки

Visual Studio

В примере в этом разделе предполагается, что вы создали Blazor веб-приложение с интерактивным режимом отрисовки авто (сервер и webAssembly) и расположением взаимодействия между компонентами.

1. Запустите приложение.
2. Задайте точку останова в currentCount++; строке компонента Counter (Pages/Counter.razor) клиентского проекта (.Client).
3. Нажмите клавишу F5, чтобы запустить приложение в отладчике.
4. В браузере перейдите на страницу Counter по адресу /counter. Подождите несколько секунд, пока отладочный прокси-сервер будет загружен и запущен. Нажмите кнопку "Щелкнуть меня", чтобы выбрать точку останова.
5. В Visual Studio просмотрите значение поля currentCount в окне Локальные переменные.
6. Нажмите клавишу F5, чтобы продолжить выполнение.

Точки останова также можно попасть в проект сервера в статически отрисованных и интерактивных серверных компонентах.

1. Остановите отладчик.

2. Добавьте следующий компонент в серверные приложения. Компонент применяет режим отрисовки интерактивного сервера (InteractiveServer).

   Components/Pages/Counter2.razor:

   @page "/counter-2"
   @rendermode InteractiveServer
   
   <PageTitle>Counter 2</PageTitle>
   
   <h1>Counter 2</h1>
   
   <p role="status">Current count: @currentCount</p>
   
   <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
   
   @code {
       private int currentCount = 0;
   
       private void IncrementCount()
       {
           currentCount++;
       }
   }
   

3. Задайте точку останова в строке currentCount++;Counter2 компонента.

4. Нажмите клавишу F5, чтобы запустить приложение в отладчике.

5. В браузере перейдите на страницу Counter2 по адресу /counter-2. Подождите несколько секунд, пока отладочный прокси-сервер будет загружен и запущен. Нажмите кнопку "Щелкнуть меня", чтобы выбрать точку останова.

6. Нажмите клавишу F5, чтобы продолжить выполнение.

Попадание в точки останова не происходит во время запуска приложения перед запуском прокси-сервера отладки. Сюда входят точки останова в файле и точках останова в ProgramOnInitialized{Async} методах жизненного цикла компонентов, загруженных первой страницей, запрошенной приложением.

Visual Studio Code

В этом разделе предполагается, что вы создали Blazor веб-приложение с интерактивным режимом отрисовки (сервер и webAssembly) и расположением интерактивного взаимодействия для каждого компонента.

1. Откройте приложение в Visual Studio Code, открыв папку решения, которая является папкой, содержащей папки сервера и .Client проекта.
2. Задайте точку останова в currentCount++; строке компонента Counter (Pages/Counter.razor) клиентского проекта (.Client).
3. Откройте панель "Запуск и отладка" и нажмите кнопку "Запуск и отладка". Кроме того, нажмите клавишу F5 (начать отладку). C# Выберите отладчик в палитре команд в верхней части пользовательского интерфейса. Выберите профиль по умолчанию для проекта сервера (например, C#:BlazorSample [Default Configuration]).
4. В браузере перейдите на страницу Counter по адресу /counter. Подождите несколько секунд, пока отладочный прокси-сервер будет загружен и запущен. Нажмите кнопку "Щелкнуть меня", чтобы выбрать точку останова.
5. Нажмите кнопку "Продолжить " в пользовательском интерфейсе или нажмите клавишу F5 (Продолжить), чтобы продолжить выполнение.

Точки останова также могут быть поражены в серверном проекте.

1. Остановите отладку, нажав кнопку "Остановить" или нажмите клавиши SHIFT+F5 на клавиатуре.

2. Добавьте следующий компонент в серверные приложения. Компонент принимает режим отрисовки интерактивного сервера (InteractiveServer).

   Components/Pages/Counter2.razor:

   @page "/counter-2"
   @rendermode InteractiveServer
   
   <PageTitle>Counter 2</PageTitle>
   
   <h1>Counter 2</h1>
   
   <p role="status">Current count: @currentCount</p>
   
   <button class="btn btn-primary" @onclick="IncrementCount">Click me</button>
   
   @code {
       private int currentCount = 0;
   
       private void IncrementCount()
       {
           currentCount++;
       }
   }
   

3. Задайте точку останова в строке currentCount++;Counter2 компонента.

4. Нажмите кнопку "Начать отладку" в пользовательском интерфейсе или нажмите клавишу F5 (Начать отладку), чтобы запустить приложение в отладчике.

5. В браузере перейдите на страницу Counter2 по адресу /counter-2. Подождите несколько секунд, пока отладочный прокси-сервер будет загружен и запущен. Нажмите кнопку "Щелкнуть меня", чтобы выбрать точку останова.

6. Нажмите кнопку "Продолжить " в пользовательском интерфейсе или нажмите клавишу F5 (Продолжить), чтобы продолжить выполнение.

Попадание в точки останова не происходит во время запуска приложения перед запуском прокси-сервера отладки. Сюда входят точки останова в файле и точках останова в ProgramOnInitialized{Async} методах жизненного цикла компонентов, загруженных первой страницей, запрошенной приложением.

Запуск без отладки [CTRL+F5 (Windows) или ⌘+F5 (macOS)] не поддерживается. При запуске приложения в конфигурации отладки затраты на отладку всегда приводят к небольшому снижению производительности.

Отладка приложения в интегрированной Blazor WebAssembly среде разработки

Visual Studio

1. Запустите приложение.
2. Задайте точку останова в строке currentCount++;Counter компонента (Pages/Counter.razor).
3. Нажмите клавишу F5, чтобы запустить приложение в отладчике.
4. В браузере перейдите на страницу Counter по адресу /counter. Подождите несколько секунд, пока отладочный прокси-сервер будет загружен и запущен. Нажмите кнопку "Щелкнуть меня", чтобы выбрать точку останова.
5. В Visual Studio просмотрите значение поля currentCount в окне Локальные переменные.
6. Нажмите клавишу F5, чтобы продолжить выполнение.

Попадание в точки останова не происходит во время запуска приложения перед запуском прокси-сервера отладки. Сюда входят точки останова в файле и точках останова в ProgramOnInitialized{Async} методах жизненного цикла компонентов, загруженных первой страницей, запрошенной приложением.

Visual Studio Code

1. Откройте папку приложения в Visual Studio Code.
2. Задайте точку останова в строке currentCount++;Counter компонента (Pages/Counter.razor).
3. Откройте панель "Запуск и отладка" и нажмите кнопку "Запуск и отладка". Кроме того, нажмите клавишу F5 (начать отладку). C# Выберите отладчик в палитре команд в верхней части пользовательского интерфейса. Выберите профиль по умолчанию (например, C#:BlazorSample [Default Configuration]).
4. Нажмите клавишу F5, чтобы запустить приложение в отладчике.
5. Автономное приложение запустится и откроется браузер отладки.
6. В браузере перейдите на страницу Counter по адресу /counter. Подождите несколько секунд, пока отладочный прокси-сервер будет загружен и запущен. Нажмите кнопку "Щелкнуть меня", чтобы выбрать точку останова.
7. Нажмите клавишу F5, чтобы продолжить выполнение.

Попадание в точки останова не происходит во время запуска приложения перед запуском прокси-сервера отладки. Сюда входят точки останова в файле и точках останова в ProgramOnInitialized{Async} методах жизненного цикла компонентов, загруженных первой страницей, запрошенной приложением.

Запуск без отладки [CTRL+F5 (Windows) или ⌘+F5 (macOS)] не поддерживается. При запуске приложения в конфигурации отладки затраты на отладку всегда приводят к небольшому снижению производительности.

Debugger support

Отладка включена для среды выполнения, если включена <DebuggerSupport>{VALUE}</DebuggerSupport>поддержка отладчика, в которой {VALUE} находится владелец true места либо false.

По умолчанию Blazor платформа отключает поддержку отладчика для всех конфигураций, отличных от отладки. Чтобы включить поддержку отладчика для конфигурации, отличной от отладки, добавьте <DebuggerSupport> свойство в файл проекта приложения.

В следующем примере поддержка отладчика включена для настраиваемой конфигурации "DebugCustom:

<DebuggerSupport Condition="'$(Configuration)' == 'DebugCustom'">true</DebuggerSupport>

Дополнительные сведения см Blazor WebAssembly . в разделе настраиваемой конфигурации отладчика (dotnet/runtime #96239).

Присоединение к существующему сеансу отладки Visual Studio Code

Чтобы подключиться к работающему Blazor приложению, откройте .vscode/launch.json файл и замените {URL} заполнитель URL-адресом, в котором выполняется приложение:

{
  "name": "Attach and Debug",
  "type": "blazorwasm",
  "request": "attach",
  "url": "{URL}"
}

Параметры запуска Visual Studio Code

Параметры конфигурации запуска в следующей blazorwasm таблице поддерживаются для типа отладки (.vscode/launch.json).

Вариант	Описание
browser	Браузер для запуска сеанса отладки. Задайте edge или chrome. По умолчанию — edge.
cwd	Рабочий каталог для запуска приложения.
request	Используйте launch, чтобы запустить и подключить сеанс отладки к приложению Blazor WebAssembly, или attach, чтобы подключить сеанс отладки к уже работающему приложению.
timeout	Количество миллисекунд ожидания до подключения сеанса отладки. По умолчанию — 30 000 миллисекунд (30 секунд).
trace	Используется для создания журналов из отладчика JS. Задано значение true, чтобы создавались журналы.
url	URL-адрес для открытия в браузере при отладке.
webRoot	Указывает полный путь к веб-серверу. Если приложение обслуживается с использованием подмаршрута, необходимо указать значение для этого параметра.

Отладка Blazor WebAssembly с помощью Google Chrome или Microsoft Edge

В этом разделе описано, как применить отладку Blazor WebAssembly приложений:

• Google Chrome, работающий в Windows или macOS.
• Microsoft Edge, работающий в Windows.

1. Запустите приложение в командной оболочке с dotnet runпомощью .

2. Запустите браузер и перейдите по URL-адресу приложения.

3. Запустите удаленную отладку, нажав клавишу:

   • Shift+Alt+d в Windows.
   • Shift'd++ в macOS.

   Браузер должен работать с включенной удаленной отладкой (это не поведение по умолчанию). Если удаленная отладка отключена, отобразится страница с ошибкой Не удается найти вкладку браузера для отладки с инструкциями по запуску браузера с открытым портом отладки. Следуйте инструкциям в браузере.

   После выполнения инструкций по включению удаленной отладки приложение открывается в новом окне браузера. Запустите удаленную отладку, нажав сочетание HotKey в новом окне браузера:

   • Shift+Alt+d в Windows.
   • Shift'd++ в macOS.

   Откроется вкладка браузера инструментов разработчика окна с изображением фантомного изображения приложения.

   Примечание.

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

4. Через некоторое время на вкладке "Источники" отображается список сборок и страниц приложения .NET.

5. Откройте узел file://. В коде компонента (.razor файлах) и файлах кода C# (.cs), точек останова, заданных при выполнении кода на вкладке браузера приложения (начальная вкладка, открытая после запуска удаленной отладки). После нажатия точки останова одношаговый (F10) через код или выполнение кода возобновления (F8) обычно на вкладке отладки.

Для отладки браузера на основе Chromium предоставляется прокси-сервер отладки, Blazor реализующий протокол Chrome DevTools и расширяющий протокол с помощью . Сведения, относящиеся к NET. При нажатии сочетания клавиш для отладки Blazor указывает Chrome DevTools на прокси-сервер. Прокси-сервер подключается к окну браузера, для которого выполняется отладка (поэтому и надо было включить удаленную отладку).

Отладка Blazor WebAssembly приложения с помощью Firefox

В этом разделе описано, как применить отладку Blazor WebAssembly приложений в Firefox, работающих в Windows.

Blazor WebAssembly Отладка приложения с помощью Firefox требует настройки браузера для удаленной отладки и подключения к браузеру с помощью средств разработчика браузера с помощью прокси-сервера отладки .NET WebAssembly.

Примечание.

Отладка в Firefox из Visual Studio в настоящее время не поддерживается.

Отладка Blazor WebAssembly приложения в Firefox во время разработки:

1. Настройка Firefox:
   • Откройте about:config на новой вкладке браузера. Прочтите и закройте предупреждение, которое появится.
   • Включите devtools.debugger.remote-enabled , задав для нее значение True.
   • Включите devtools.chrome.enabled , задав для нее значение True.
   • Отключите devtools.debugger.prompt-connection , задав для нее значение False.
2. Закройте все экземпляры Firefox.
3. Запустите приложение в командной оболочке с dotnet runпомощью .
4. Повторно запустите браузер Firefox и перейдите к приложению.
5. Откройте about:debugging новую вкладку браузера. Оставьте эту вкладку открытой.
6. Вернитесь на вкладку, на которой запущено приложение. Запустите удаленную отладку, нажав клавиши SHIFT+ALT+D.
7. На вкладке Debugger откройте исходный файл приложения, который вы хотите отладить под file:// узлом, и установите точку останова. Например, задайте точку останова в currentCount++; строке в IncrementCount методе Counter компонента (Pages/Counter.razor).
8. Перейдите Counter на страницу компонента (/counter) на вкладке браузера приложения и нажмите кнопку счетчика, чтобы попасть в точку останова.
9. Нажмите клавишу F5 , чтобы продолжить выполнение на вкладке отладки.

Разрыв с необработанными исключениями

Отладчик по умолчанию не прерывает необработанные исключения, так как Blazor перехватывает исключения, необработанные кодом разработчика.

Чтобы разорвать необработанные исключения, выполните приведенные действия.

• Откройте параметры исключений отладчика (отладка>Параметры исключений Windows>) в Visual Studio.
• Задайте следующие параметры исключений JavaScript:
  • Все исключения
  • Неуловимые исключения

Сопоставители с исходным кодом в браузере

Сопоставители с исходным кодом в браузере позволяют браузеру сопоставлять скомпилированные файлы с исходными файлами и обычно используются для отладки на стороне клиента. Однако Blazor в настоящее время не сопоставляет C# напрямую с JavaScript/WASM. Вместо этого Blazor выполняет интерпретацию IL в браузере, поэтому сопоставление с исходным кодом не актуально.

Настройка брандмауэра

Если брандмауэр блокирует обмен данными с прокси-сервером отладки, создайте правило исключения брандмауэра, которое разрешает обмен данными между браузером и процессом NodeJS.

Предупреждение

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

Разрешение начала обмена данными с NodeJS процессом:

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

Если возможно, разрешайте открытый обмен данными с NodeJS процессом только в доверенных или частных сетях.

Инструкции по настройке брандмауэра Windows см. в статье Создание правила для входящего трафика для программы или службы. Дополнительные сведения см. в статье Брандмауэр Защитника Windows с расширенными функциями безопасности и в связанных статьях в наборе документации по брандмауэру Windows.

Устранение неполадок

При возникновении ошибок воспользуйтесь следующими советами:

• Удалите точки останова:
  • Google Chrome: на вкладке "Отладчик " откройте средства разработчика в браузере. В консоли выполните localStorage.clear(), чтобы удалить все точки останова.
  • Microsoft Edge: на вкладке "Приложение " откройте локальное хранилище. Щелкните правой кнопкой мыши сайт и нажмите кнопку "Очистить".
• Убедитесь, что вы установили и сделали доверенным сертификат разработки HTTPS ASP.NET Core. Дополнительные сведения см. в статье Принудительное использование HTTPS.
• Visual Studio требует включения отладки JavaScript для ASP.NET (Chrome и Edge) в разделе "Параметры>отладки>инструментов".> Этот параметр включен в Visual Studio по умолчанию. Если отладка не работает, проверьте, выбран ли этот параметр.
• Если в среде используется прокси-сервер HTTP, необходимо включить localhost в параметры обхода прокси-сервера. Это можно сделать, задав NO_PROXY переменную среды в следующих параметрах:
  • файл launchSettings.json проекта;
  • на уровне пользовательских или системных переменных среды для применения ко всем приложениям. Перезапустите Visual Studio, чтобы изменение переменной среды вступило в силу.
• Убедитесь, что брандмауэры или прокси-серверы не блокируют обмен данными с прокси-сервером отладки (процесс NodeJS). Дополнительные сведения см. в разделе Настройка брандмауэра.

Точки останова в OnInitialized{Async} не срабатывают

Blazor Прокси-сервер отладки платформы не запускается мгновенно при запуске приложения, поэтому точки останова в OnInitialized{Async} методах жизненного цикла могут не попасть. Мы рекомендуем добавить задержку в начале тела метода, чтобы прокси-сервер отладки успел запуститься до срабатывания точки останова. Вы можете включить задержку на основе директивы компилятора if, чтобы обеспечить отсутствие задержки для конечной сборки приложения.

OnInitialized:

protected override void OnInitialized()
{
#if DEBUG
    Thread.Sleep(10000);
#endif

    ...
}

OnInitializedAsync:

protected override async Task OnInitializedAsync()
{
#if DEBUG
    await Task.Delay(10000);
#endif

    ...
}

истекло время ожидания Visual Studio (Windows)

Если Visual Studio вызывает исключение о том, что не удалось запустить адаптер отладки, указав, что истекло время ожидания, то можно настроить время ожидания с помощью параметра реестра.

VsRegEdit.exe set "<VSInstallFolder>" HKCU JSDebugger\Options\Debugging "BlazorTimeoutInMilliseconds" dword {TIMEOUT}

Заполнитель {TIMEOUT} в предыдущей команде указывается в миллисекундах. Например, одной минуте соответствует значение 60000.