Ольга Гавриш недавно написала пост о том, как перенести WinForms приложение с .NET Framework на .NET Core. В этом блог посте будут выполняться шаги по переносу WPF-приложения на .NET Core 3. Многие из этих шагов будут знакомы Вам из поста Ольги, но здесь добавлены некоторые дополнительные общие зависимости, с которыми пользователи могут столкнуться, например, использование WCF клиента или сторонних пакетов пользовательского интерфейса.
Чтобы этот пост не был слишком длинным, он разбит на две части. В первой части будет выполнена подготовка к перемещению и созданию нового csproj файла для .NET Core версии приложения. Во втором посте будут добавлены реальные изменения в коде, необходимые для работы приложения на .NET Core.
Эти блог посты не посвящены какой-либо конкретной проблеме переноса. В них описываются шаги, необходимые для переноса WPF приложения. Если есть конкретные темы по миграции на .NET Core, которые Вы хотели бы изучить более детально, сообщите об этом в комментариях.
Видео инструкции
Если предпочитаете видео инструкции по перемещению приложения, Вы можете просмотреть ролики на YouTube, посвященный переносу приложения.
О примере
Для этого примера было написано простое приложение для торговли товарами под названием «Bean Trader». У пользователей приложения есть учетные записи с разным количеством бобов (которые бывают четырех разных цветов). С этим приложением, пользователи могут предлагать и принимать сделки с другими пользователями. Приложение не очень большое (около 2000 строк кода), но, с точки зрения сложности, на шаг впереди «Hello World». Оно создано для того, чтобы Вы могли видеть некоторые проблемы, с которыми пользователи могут столкнуться при переносе реальных приложений.
Интересные зависимости в приложении:
- Соединение WCF с бэкенд-трейдингом через двойной NetTcp канал
- Моделирование пользовательского интерфейса и MahApps.Metro диалогов
- Внедрение зависимостей с помощью Castle.Windsor (хотя, многие DI-решения, включая Microsoft.Extensions.DependencyInjection, могут использоваться в этом сценарии)
- Настройки приложения в app.config и реестре
- Различные ресурсы и resx файлы
Исходный код этого приложения доступен на GitHub. Исходный источник (до переноса) доступен в NetFx\BeanTraderClient каталоге. Последнее перемещенное приложение находится в NetCore\BeanTraderClient директории. Бэкэнд-сервис, с которым должно соединяться приложение, доступен в BeanTraderServer папке.
Отказ
Помните, что этот образец приложения создан для демонстрации проблем перемещения на .NET Core и их решений. Он не предназначен для демонстрации лучших WPF возможностей. На самом деле, некоторые анти-паттерны были намеренно добавлены в приложение для воспроизведения некоторых проблем при перемещении.
Обзор процесса перемещения
Процесс перехода с .NET Framework на .NET Core состоит из четырех основных этапов.
1. Во-первых, полезно подготовиться к перемещению, разобраться в зависимостях проекта и перемещать проект в легко переносимом состоянии.
- Используйте такие инструменты, как .NET Portability Analyzer, для изучения .NET Framework зависимостей.
- Также стоит обновить NuGet ссылки для использования формата и, возможно, придется обновить версии NuGet пакетов.
2. Во-вторых, файл проекта должен быть обновлен. Это можно сделать либо путем создания нового файла проекта, либо путем изменения текущего файла.
3. В-третьих, исходному коду могут потребоваться некоторые обновления, основанные на различных API, как в .NET Core, так и в .NET Core версиях необходимых NuGet пакетов. Это обычно самый продолжительный этап.
4. В-четвертых, не забудьте протестировать перенесенное приложение! Некоторые .NET Core/.NET Framework различия не проявляются до времени выполнения (хотя существуют Roslyn анализаторы кода, помогающие идентифицировать эти случаи).
Шаг 1: Подготовка
Образец клонирован и готов к работе? Супер, теперь можно начать!
Основная проблема при перемещение .NET Framework приложения на .NET Core заключается в том, что его зависимости в .NET Core могут работать по-разному (или вообще не работать!). Сейчас перемещение стало намного проще, чем раньше – многие NuGet пакеты теперь нацелены на .NET Standard, и, начиная с .NET Core 2.0, .NET Framework и .NET Core стали довольно похожими. Тем не менее, некоторые различия остаются (как в поддержке NuGet пакетов, так и в доступных .NET API).
Обновление NuGet ссылок к
Старые .NET Framework проекты обычно перечисляют свои NuGet зависимости в packages.config файле. Однако новый формат файла проекта в SDK стиле по-разному ссылается на NuGet пакеты. Для ссылки на NuGet зависимости он использует элементы в самом csproj файле (а не в отдельном файле конфигурации). К счастью, csproj файлы старого стиля также могут использовать современный синтаксис.
При перемещении есть два преимущества использования ссылок в стиле:
- Это стиль NuGet ссылки, который потребуется для нового файла .NET Core проекта. Если Вы уже используете , эти элементы файла проекта можно скопировать и вставить непосредственно в новый проект.
- В отличие от packages.config файла, элементы ссылаются только на самые важные зависимости, от которых напрямую зависит Ваш проект. Все остальные переходные NuGet пакеты будут определены во время восстановления и записаны в автоматически сгенерированный obj\project.assets.json файл. Это значительно упрощает рассуждение о том, какие зависимости есть у Вашего проекта, что полезно при определении того, будут ли необходимые зависимости работать на .NET Core или нет.
Итак, первый шаг к перемещению Bean Trader образца – это подготовить его к использованию NuGet ссылок. С Visual Studio это очень легко. Просто щелкните правой кнопкой мыши по packages.config файлу проекта в Visual Studio Solution Explorer и выберите «Перенести packages.config в PackageReference».
Появится диалоговое окно, показывающее вычисленные самые важные NuGet зависимости и спрашивающее, какие другие NuGet пакеты должны быть перемещены к этому уровню. Ни один из этих других пакетов не должен быть высокого уровня для Bean Trader образца, поэтому Вы можете снять все эти флажки. Затем нажмите «ОК», и packages.config файл будет удален, а элементы будут добавлены в файл проекта.
Ссылки в стиле не хранят NuGet пакеты локально в папке «пакетов» (вместо этого они хранятся глобально, в качестве оптимизации), поэтому после перемещения Вам нужно будет отредактировать csproj файл и удалить элементы, относящиеся к FxCop анализаторам, которые ранее были из .. \packages директории.
Просмотрите NuGet пакеты
Теперь, когда можно увидеть NuGet пакеты верхнего уровня, от которых зависит проект, есть возможность проверить, будут ли эти пакеты доступны в .NET Core или нет.
Вы можете узнать, поддерживается ли .NET Core пакет, взглянув на его зависимости от nuget.org. Сайт fuget.org, созданный сообществом, также отображает эту информацию в верхней информационной части страницы пакета.
При нацеливании на .NET Core 3 должны работать любые пакеты, нацеленные на .NET Core или .NET Standard (поскольку .NET Core реализует .NET Standard). Вы также можете использовать пакеты, нацеленные на .NET Framework, но это представляет некоторый риск. Разрешены зависимости от .NET Core к .NET Framework, поскольку .NET Core и .NET Framework достаточно похожи, поэтому такие зависимости часто работают без проблем. Однако, если пакет пытается использовать .NET API, которого нет в .NET Core, Вы столкнетесь с трудностями во время работы. По этой причине Вы должны ссылаться на .NET Framework пакеты только тогда, когда другие опции недоступны, и помнить, что это создаст нагрузку на тестирование.
В случае примера Bean Trader есть следующие NuGet зависимости:
- Castle.Windsor, версия 4.1.1. Этот пакет предназначен для .NET Standard 1.6, поэтому он будет работать на .NET Core.
- Microsoft.CodeAnalysis.FxCopAnalyzers, версия 2.6.3. Это метапакет, поэтому неясно, какие платформы он поддерживает, но в документации указано, что его новейшая версия (2.9.2) будет работать как для .NET Framework, так и для .NET Core.
- Nito.AsyncEx, версия 4.0.1. Этот пакет не предназначен для .NET Core, но более новая версия 5.0 сможет это сделать. Это часто происходит при миграции, потому что многие NuGet пакеты за последний год добавили поддержку .NET Standard, но более старые проекты будут использовать более старые версии этих пакетов. Если разница версий незначительна, ее можно легко обновить до более новой версии. Поскольку это серьезное изменение версии, Вы должны быть осторожны при обновлении, поскольку в пакете могут произойти критические изменения.
- MahApps.Metro, версия 1.6.5. Этот пакет также не предназначен для .NET Core, но имеет более новую preview-версию (2.0-alpha).
Все NuGet зависимости из примера Bean Trader предназначены либо для .NET Standard/.NET Core, либо для их более новых версий, поэтому у Вас вряд ли возникнут какие-либо проблемы с блокировкой.
Если бы существовали пакеты, не предназначенные для .NET Core или .NET Standard, пришлось бы подумать о других альтернативах:
- Есть ли другие похожие пакеты, которые можно использовать вместо этих? Иногда NuGet авторы публикуют отдельные .Core версии библиотек, специально предназначенные для .NET Core. Пакеты Enterprise Library – пример того, как сообщество публикует альтернативы с .NetCore расширением.
- Если альтернатив нет, Вы можете продолжить использование пакетов, нацеленных на .NET Framework, имея в виду, что Вам потребуется тщательно их протестировать после запуска на .NET Core.
Обновите NuGet пакеты
Если у Вас есть такая возможность, обновите версии этих пакетов до тех, которые нацелены на .NET Core или .NET Standard на этом этапе, чтобы обнаружить и устранить любые критические изменения.
Если Вы не хотите вносить какие-либо существенные изменения в существующую версию .NET Framework приложения, подождите, пока у Вас не появится новый файл проекта для .NET Core. Тем не менее, предварительное обновление NuGet пакетов до версий, совместимых с .NET Core, упрощает процесс миграции, когда наступает время создания нового файла проекта, и уменьшает количество различий между .NET Framework и .NET Core. версиями приложения.
В случае примера Bean Trader все необходимые обновления могут быть легко выполнены (с помощью диспетчера NuGet пакетов в Visual Studio) с одним исключением: обновление с MahApps.Metro 1.6.5 до 2.0 выявляет серьезные изменения, связанные с API-интерфейсами для управления темами и акцентами.
В идеале приложение должно быть обновлено, чтобы использовать более новую версию пакета (так как оно, скорее всего, будет работать на .NET Core). Однако в некоторых случаях это может быть неосуществимо. В этом случае MahApps.Metro не будет обновляться, потому что этот туториал сосредоточен на переходе на .NET Core 3, а не на MahApps.Metro 2. Кроме того, это .NET Framework зависимость с низким уровнем риска, поскольку приложение Bean Trader выполняет только небольшую часть MahApps.Metro. Конечно, после завершения миграции потребуется тестирование, чтобы убедиться, что все работает.
После обновления NuGet пакетов до последних версий группа элементов в файле проекта Bean Trader должна выглядеть следующим образом:
Анализ переносимости .NET Framework
Теперь рассмотрим зависимости .NET Framework API. Инструмент .NET Portability Analyzer полезен для понимания того, какие из .NET API, которые использует Ваш проект, доступны на других .NET платформах.
Этот инструмент поставляется в виде Visual Studio плагина, инструмента командной строки или в виде простого графического интерфейса пользователя, который упрощает его параметры и всегда сообщает о совместимости с .NET Core 3.
В предыдущем посте Оля Гавриш использовала графический интерфейс, поэтому в этом будет использоваться интерфейс командной строки. Необходимые шаги:
1. Загрузите API Portability Analyzer.
2. Убедитесь, что приложение .NET Framework для переноса собралось успешно.
3. Запустите API-порт с помощью командной строки, например:
- ApiPort.exe analyze -f -r html -r excel -t “.NET Core”
- Аргумент -f указывает путь, содержащий двоичные файлы для анализа. Аргумент -r указывает, какой формат выходного файла Вам нужен. Будут полезны как HTML, так и Excel форматы. Аргумент -t указывает, с какой .NET платформой будет анализироваться использование API. В данном случае нужен .NET Core, поскольку именно эта платформа является целевой. Так как версия не указана, по умолчанию для API Port используется последняя версия платформы (в данном случае – .NET Core 3.0).
Когда Вы откроете HTML-отчет, в первом разделе будут перечислены все проанализированные двоичные файлы и какой процент используемых им .NET API доступен на целевой платформе. Сам по себе этот процент не очень значимый. Что более полезно, так это увидеть конкретные API, которые отсутствуют. Для этого щелкните имя сборки или прокрутите вниз до отчетов по отдельным сборкам.
Вам нужно беспокоиться только о тех сборках, для которых у Вас есть исходный код. В отчете Bean Trader ApiPort перечислено много двоичных файлов, но большинство из них относится к NuGet пакетам. Например, Castle.Windsor показывает, что он зависит от некоторых System.Web API интерфейсов, отсутствующих в .NET Core. Это не проблема, потому что Castle.Windsor поддерживает .NET Core. Обычно NuGet пакеты имеют разные двоичные файлы для использования на разных .NET платформах, поэтому независимо от того, использует ли .NET Framework версия Castle.Windsor System.Web API-интерфейсы или нет, это не имеет значения, если пакет также предназначен для .NET Standard или. NET Core.
В случае примера Bean Trader единственный двоичный файл, который нужно изучить – BeanTraderClient, и в отчете показано, что отсутствуют только два .NET API – System.ServiceModel.ClientBase.Close и System.ServiceModel.ClientBase.Open
Это вряд ли избавит от проблем, потому что WCF Client API (в основном) поддерживаются в .NET Core, поэтому для этих центральных API должны быть альтернативы. Фактически, глядя на System.ServiceModel .NET Core (используя https://apisof.net), можно увидеть, что в .NET Core есть асинхронные альтернативы.
Исходя из этого отчета и предыдущего анализа NuGet зависимостей, похоже, что не должно быть серьезных проблем при переносе образца Bean Trader в .NET Core. Следующий шаг для начала переноса.
Шаг 2: Перемещение файла проекта
Поскольку .NET Core использует новый формат файла проекта в SDK стиле, существующий csproj файл не будет работать. Нам понадобится новый файл проекта для .NET Core версии приложения Bean Trader. Если Вам не нужно было собирать .NET Framework версию приложения в будущем, Вы могли бы просто заменить существующий csproj файл. Но часто разработчики хотят создавать обе версии – особенно тогда, когда .NET Core 3 все еще находится в режиме предварительного просмотра.
Есть три варианта, где должен размещаться новый csproj файл, каждый из которых имеет свои плюсы и минусы:
- Вы можете использовать многоцелевой таргетинг (указав несколько целей), чтобы получить один файл проекта, который создаст .NET Core и .NET Framework версии решения. В будущем это, вероятно, будет лучшим вариантом. Однако, на данный момент, некоторые функции плохо работают с многоцелевым таргетингом. Поэтому сейчас рекомендуется иметь отдельные файлы проекта для версий приложений, ориентированных на .NET Core и .NET Framework.
- Вы можете поместить новый файл проекта в другую директорию. Это облегчит разделение сборки, но означает, что Вы не сможете использовать преимущества новой системы проектов, позволяющей автоматически добавлять C# и XAML файлы. Также необходимо будет добавить элементы для XAML ресурсов, чтобы они были встроены с правильными путями.
- Вы можете поместить новый файл проекта в ту же директорию, что и текущий файл проекта. Это позволяет избежать проблем, связанных с предыдущим параметром, но приведет к конфликту obj и bin папок для двух проектов. Если Вы одновременно открываете только один из проектов, это не будет проблемой. Но если они оба будут открыты одновременно, Вам нужно будет обновить проекты, чтобы использовать разные пути вывода и промежуточные пути вывода.
Лучший вариант – пункт 3 (чтобы файлы проекта работали бок о бок), поэтому этот подход будет использоваться в качестве примера.
Для создания нового файла проекта, обычно используется команда dotnet new wpf во временном каталоге, чтобы сгенерировать файл проекта, а затем скопировать / переименовать его в нужное место. Существует также созданный сообществом инструмент CsprojToVs2017, который может автоматизировать некоторые процессы миграции. Этот инструмент полезен, но все еще нуждается в улучшении, чтобы все детали миграции были верны. Одна конкретная область, которую инструмент не обрабатывает до конца, – это миграция NuGet пакетов из packages.config файлов. Если инструмент запускается в файле проекта, который все еще использует файл packages.config для ссылки на NuGet пакеты, он автоматически мигрирует в элементы, но добавит элементы для всех пакетов, а не только для верхнего уровня. Однако если Вы уже перешли на элементы с помощью Visual Studio, то этот инструмент может помочь с остальной частью конвертирования. Перенос вручную даст лучшие результаты, если у Вас только несколько проектов. Но если Вы портируете десятки или сотни файлов проекта, то такой инструмент, как CsprojToVs2017, может Вам помочь.
Так что, запустите dotnet new wpf во временном каталоге и переместите созданный csproj файл в BeanTraderClient папку и переименуйте его в BeanTraderClient.Core.csproj.
Поскольку новый формат файла проекта автоматически включает C#, resx и XAML файлы, которые он находит в своей директории, файл проекта уже почти готов! Чтобы завершить миграцию, одновременно откройте старые и новые файлы проекта и просмотрите старый, чтобы увидеть, нужно ли переносить какую-либо информацию, содержащуюся в нем. В этом случае следующие элементы должны быть скопированы в новый проект:
- , и свойства должны быть скопированы.
- Также нужно добавить false свойство в новый файл проекта, поскольку образец Bean Trader включает атрибуты уровня сборки в файле AssemblyInfo.cs (например, [AssemblyTitle]). По умолчанию новые проекты в SDK стиле автоматически генерируют эти атрибуты на основе свойств в csproj файле. Поскольку в этом случае это не нужно (автоматически сгенерированные атрибуты будут конфликтовать с теми что из AssemblyInfo.cs), Вам нужно отключить автоматически сгенерированные атрибуты с помощью .
- Хотя resx файлы автоматически добавляются в качестве встроенных ресурсов, другие элементы, например изображения, не добавляются. Итак, скопируйте элементы для того, чтобы вставить изображения и значки файлов. Вы можете упростить png ссылки на одну строку, используя поддержку нового формата файла проекта для сокращения шаблонов: .
- Аналогично, элементы будут включены автоматически, но по умолчанию они не будут скопированы в директорию выхода. Поскольку проект Bean Trader включает в себя элемент, который копируется в директорию выхода (с использованием PreserveNewest), необходимо обновить автоматически заполненный элемент для этого файла, например:
- Образец Bean Trader содержит XAML файл (Default.Accent.xaml) в качестве Содержимого (а не Страницы), поскольку темы и акценты, определенные в этом файле, загружаются из XAML файла во время выполнения, а не встраиваются в само приложение. Новая система проекта автоматически содержит этот файл в виде <Страницы>, разумеется, поскольку это XAML файл. Итак, нужно удалить как XAML файл, так и страницу () и добавить его в качестве содержимого:
- Наконец, добавьте NuGet ссылки, скопировав со всеми элементами. Если бы ранее NuGet пакеты не обновлялись до версий, совместимых с .NET Core, Вы могли бы сделать это сейчас, когда ссылки на пакеты находятся в специфичном для .NET Core проекте.
На этом этапе должна появиться возможность добавить новый проект в решение BeanTrader и открыть его в Visual Studio. Проект должен выглядеть правильно в Solution Explorer и dotnet restore BeanTraderClient.Core.csproj должен успешно восстановить пакеты (с двумя ожидаемыми предупреждениями, связанными с MahApps.Metro версией, которая используется для нацеливания на .NET Framework).
Это, вероятно, хороший переломный момент между первой и второй частями этого блог поста. Во втором посте будет рассказано о том, как приложение собирается и работает на .NET Core.
Источник