Начало работы с добавочными ASP.NET для миграции ASP.NET Core

Important

Перед началом работы: в этой статье предполагается, что вы ознакомились с обзором миграции ASP.NET Core. Если вы еще не прочитали его, начните с понимания концепций, подхода и преимуществ добавочной миграции.

Для крупной миграции мы рекомендуем настроить приложение ASP.NET Core, которое будет переносить запросы в исходное приложение .NET Framework. Новое приложение с поддержкой прокси-сервера отображается на следующем рисунке:

запуск миграции маршрутов

В этой статье приведены практические шаги по продолжению добавочной миграции после понимания подхода.

Prerequisites

Перед началом добавочной миграции убедитесь, что у вас есть следующее:

  1. Ознакомьтесь с обзором: постепенная миграция от ASP.NET к ASP.NET Core
  2. Рабочее приложение ASP.NET Framework , которое требуется перенести
  3. Visual Studio 2022 с последними обновлениями
  4. Установленный пакет SDK для .NET 8 или более поздней версии
  5. Понимание зависимостей приложения и сторонних библиотек

Общие сведения о шагах миграции

Процесс добавочной миграции выполняет следующие ключевые действия.

  1. Настройка основного проекта ASP.NET
  2. Исправление технического долга
  3. Определение и устранение перекрестных проблем
  4. Обновление вспомогательных библиотек

Настройка основного проекта ASP.NET

Первым шагом является создание нового приложения ASP.NET Core, которое будет служить прокси-сервером.

Что вы сделаете:

  • Создание нового проекта ASP.NET Core вместе с существующим приложением ASP.NET Framework
  • Настройте его для прокси-запросов к исходному приложению с помощью YARP (еще один обратный прокси-сервер)
  • Настройка базовой инфраструктуры для добавочной миграции

Подробные инструкции:

Устранение технического долга

Когда выполнять этот шаг: Перед обновлением какой-либо вспомогательной библиотеки устраните технический долг, который может осложнить процесс миграции.

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

Обновление зависимостей пакетов

Просмотрите и обновите пакеты NuGet до последних совместимых версий:

  1. Аудит существующих пакетов: используйте диспетчер пакетов NuGet Visual Studio, так как dotnet интерфейс командной строки не работает для приложений ASP.NET Framework
  2. Постепенное обновление пакетов: обновление пакетов одновременно, чтобы избежать проблем совместимости
  3. Проверка после каждого обновления. Убедитесь, что приложение по-прежнему работает правильно после каждого обновления пакета.
  4. Устранение нарушающих совместимость изменений: Некоторые обновления пакетов могут привести к изменениям, нарушающим совместимость, которые необходимо устранить

Модернизация средств сборки

Обновите средства сборки и конфигурацию проекта:

  1. Средства обновления. Убедитесь, что вы используете последнюю версию MSBuild/Visual Studio
  2. Мигрируйте на PackageReference для управления зависимостями: рассмотрите возможность перехода с формата packages.config на PackageReference, если вы еще этого не сделали в проекте веб-приложения.
  3. Очистка неиспользуемых ссылок: удаление всех неиспользуемых ссылок на сборки или пакетов NuGet
  4. Перейдите на файлы проектов с управлением SDK: преобразуйте существующие файлы проектов в современный стиль формата SDK. Это важно для совместимости с современными проектами .NET и обеспечивает лучшую поддержку инструментов.
  5. Обновление скриптов сборки: проверка и обновление любых пользовательских скриптов сборки или конфигураций CI/CD

Устранение проблем с качеством кода

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

  1. Исправление предупреждений компилятора: устраните любые предупреждения компилятора, особенно те, которые связаны с API, объявленными устаревшими
  2. Удаление мертвого кода: очистка неиспользуемых классов, методов и других элементов кода
  3. Обновление устаревшего использования API: замените использование устаревших API современными эквивалентами по возможности

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

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

Когда выполнять этот шаг: При исправлении технического долга, но перед обновлением вспомогательных библиотек, определите и настройте сквозные аспекты, влияющие на все приложение.

Перекрестные проблемы — это аспекты приложения, охватывающие несколько уровней или компонентов, таких как проверка подлинности, управление сеансами, ведение журнала и кэширование. Эти аспекты необходимо учитывать на ранних этапах процесса миграции, так как они влияют на то, как приложения ASP.NET Framework и ASP.NET Core взаимодействуют и совместно используют состояние во время добавочной миграции.

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

Конфигурация поддержки сеансов

Настройте это, если: Приложение ASP.NET Framework использует состояние сеанса.

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

Сеанс — это часто используемая функция ASP.NET, которая использует имя с функцией в ASP.NET Core, но API-интерфейсы отличаются. При обновлении библиотек, использующих состояние сеанса, необходимо настроить поддержку сеансов. Дополнительные сведения о том, как включить общий доступ к состоянию сеанса между приложениями, см. в документации по поддержке удаленных сеансов .

Настройка проверки подлинности

Настройте это, если: Приложение ASP.NET Framework использует проверку подлинности и хотите предоставить общий доступ к состоянию проверки подлинности между старыми и новыми приложениями.

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

Можно разделить проверку подлинности между исходным приложением ASP.NET и новым приложением ASP.NET Core с помощью функции удаленной проверки подлинности адаптеров System.Web. Эта функция позволяет приложению ASP.NET Core делегировать проверку подлинности исходному ASP.NET приложению. Дополнительные сведения см. в документации по удаленной проверке подлинности .

Другие перекрестные проблемы, которые следует рассмотреть

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

  • Ведение журнала. Обеспечение согласованного ведения журнала в обоих приложениях. Рекомендуется использовать общий поставщик ведения журнала или обеспечить правильное агрегирование журналов.
  • Кэширование. Если приложение использует кэширование (в памяти, распределенное или выходное кэширование), спланируйте, как поддерживать согласованность кэша между приложениями.
  • Обработка ошибок. Создание согласованной обработки ошибок и отчетов как в ASP.NET Framework, так и в ASP.NET основных приложениях.
  • Управление конфигурацией: Спланируйте, как настройки конфигурации будут распределяться или управляться между двумя приложениями.
  • Мониторинг работоспособности: настройка проверок мониторинга и работоспособности обоих приложений во время процесса миграции.
  • Внедрение зависимостей. При использовании контейнера DI в приложении ASP.NET Framework запланируйте миграцию в встроенный контейнер DI Core ASP.NET.

Обновление вспомогательных библиотек

Когда выполнить этот шаг: Только когда необходимо перенести определенные маршруты, зависящие от библиотек классов, содержащих бизнес-логику, которую нужно будет разделить между старыми и новыми приложениями.

Note

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

Процесс обновления библиотеки

Important

Вспомогательные библиотеки должны быть обновлены в постфиксном порядке поискового обхода. Это означает:

  1. Начните с конечных зависимостей: начните с библиотек, которые не имеют зависимостей от других библиотек в решении
  2. Работа вверх по дереву зависимостей: обновление библиотеки только после успешного обновления всех зависимостей
  3. Заканчивается основным приложением: основное приложение ASP.NET Framework должно быть последним элементом, который необходимо изменить.

Данное упорядочивание важно, так как:

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

ПРИМЕЧАНИЕ: Следовать этому упорядочению необходимо только для подмножества библиотек, требуемых для маршрутов, которые вы сейчас переносите, а не для всего решения.

Процесс обновления для каждой библиотеки:

Если у вас есть вспомогательные библиотеки в решении, которые необходимо использовать для маршрутов, которые вы переносите, они должны быть обновлены до .NET Standard 2.0, если это возможно. Модернизация приложений GitHub Copilot поможет вам в этом. Если библиотеки не могут использовать .NET Standard, вы можете использовать .NET 8 или более поздней версии вместе с целевым объектом .NET Framework в исходном проекте или в новом проекте вместе с исходным.

Адаптеры System.Web можно использовать в этих библиотеках, HttpContext чтобы обеспечить поддержку использования в библиотеках классов. Чтобы включить HttpContext использование в библиотеке, выполните приведенные действия.

  1. Удаление ссылки на System.Web файл проекта
  2. Microsoft.AspNetCore.SystemWebAdapters Добавление пакета
  3. Включите многоплатформенную поддержку и добавьте целевой фреймворк .NET 8 или более поздней версии, или переведите проект на .NET Standard 2.0.

На этом шаге может потребоваться изменить ряд проектов в зависимости от структуры решения и маршрутов, которые вы переносите. Модернизация приложений GitHub Copilot поможет определить, какие из них необходимо изменить и автоматизировать ряд шагов в процессе.

Дальнейшие шаги

Выполнив описанные выше действия по настройке и обновлению библиотеки, выполните следующие действия.

  1. Начните с малого: Сначала необходимо перенести простые конечные точки без состояния.
  2. Тщательное тестирование. Убедитесь, что каждый перенесенный компонент работает правильно в обеих средах.
  3. Мониторинг производительности. Следите за любыми последствиями производительности при настройке прокси-сервера.
  4. Итерации. Продолжайте перенос компонентов постепенно, пока миграция не завершится
  • Last updated on