Миграция из UWP в пакет SDK для приложений Windows с помощью помощника по обновлению .NET

Помощник по обновлению .NET (см. обзор помощника по обновлению .NET) — это расширение Visual Studio (рекомендуется) и средство командной строки, которое может помочь при переносе приложения C# универсальная платформа Windows (UWP) в приложение WinUI 3, использующее пакет SDK для приложений Windows.

Наша стратегия поддержки UWP в помощнике по обновлению .NET включает дополнительные улучшения инструментов и добавление поддержки миграции для новых функций. Если вы найдете проблемы, связанные с помощником по обновлению .NET, вы можете отправить их в Visual Studio, выбрав Справка>Отправить отзыв>Сообщить о проблеме.

Также см. репозиторий GitHub помощника по обновлению. Параметры запуска средства в командной строке описаны там.

Установка помощника по обновлению .NET

Помощник по обновлению .NET можно установить как расширение Visual Studio или в качестве средства командной строки .NET. Дополнительные сведения см. в разделе "Установка помощника по обновлению .NET".

Итоги

При использовании помощника по обновлению .NET для переноса приложения UWP приведены высокоуровневые этапы и этапы процесса миграции, который выполняет средство.

• При необходимости копирует проект и переносит копию; оставляя исходный проект неизменным.
• При необходимости переносит проект на месте (в одних и том же папках и файлах без переименования папок); и не делает копию.
• Обновляет проект с формата платформы .NET Framework на последний формат проекта .NET SDK.
• Очищает ссылки на пакеты NuGet. Помимо пакетов, на которые ссылается ваше приложение, packages.config файл содержит ссылки на зависимости этих пакетов. Например, если вы добавили ссылку на пакет A, который зависит от пакета B, оба пакета будут ссылаться в packages.config файле. В новой системе проектов требуется только ссылка на пакет A . Таким образом, этот шаг анализирует ссылки на пакеты и удаляет те, которые не требуются. Ваше приложение по-прежнему ссылается на сборки .NET Framework. Некоторые из этих сборок могут быть доступны в виде пакетов NuGet. Таким образом, этот шаг анализирует эти сборки и ссылается на соответствующий пакет NuGet.
• Предназначено для .NET 6 и пакета SDK для приложений Windows.
• Изменяет идентификатор целевой платформы (TFM) (см. целевые платформы в проектах в стиле SDK) с платформы .NET Framework на рекомендованный SDK. Например, net6.0-windows.
• Переносит исходный код UWP из WinUI 2 в WinUI 3, внося изменения, специфичные для исходного кода.
• Добавляет и обновляет все файлы шаблона, конфигурации и кода. Например, добавление необходимых профилей публикации, App.xaml.cs, MainWindow.xaml.cs, MainWindow.xaml и других.
• Обновите пространства имен и добавьте навигацию MainPage.
• Пытается обнаружить и исправить API, которые различаются между UWP и Windows App SDK, и использует TODO-список задач для обозначения API, которые больше не поддерживаются.

В ходе работы средство также предназначено для предоставления указаний по миграции в виде предупреждающих сообщений в своих выходных данных и списка задач TODO в виде комментариев в исходном коде вашего проекта (например, в случаях, когда полностью автоматизированная миграция исходного кода UWP невозможна). Типичный список задач TODO содержит ссылку на раздел в этой документации по миграции. Как разработчик, вы всегда контролируете процесс миграции.

Что поддерживает средство

Этот выпуск помощника по обновлению .NET в настоящее время находится в предварительной версии и получает частые обновления. В настоящее время средство поддерживает только язык программирования C#; не C++. В большинстве случаев с этим выпуском ваш проект потребует от вас дополнительных усилий для завершения миграции.

Средство предназначено для переноса проекта и кода таким образом, чтобы он компилировался. Но некоторые функции требуют расследовать и устранить их (через список задач TODOs). Дополнительные сведения о том, что следует учитывать перед миграцией, см. в статье "Что поддерживается при миграции с UWP на WinUI 3".

Из-за следующих ограничений текущего выпуска помощника по обновлению .NET вы можете ждать будущий выпуск перед переносом приложения:

• Миграция с API ApplicationView не поддерживается.
• Миграция с API, связанных с AppWindow, не поддерживается.

По возможности средство пытается создать предупреждение; и он намеренно приводит к тому, что код не компилируется, пока не измените его.

• Пользовательские представления не поддерживаются. Например, вы не получите предупреждение или исправление для пользовательского диалогового окна, расширяющего MessageDialog, и неправильно вызывает API.
• Компоненты среды выполнения Windows не поддерживаются.

• Приложения с несколькими окнами могут быть перенесены неправильно.
• Проект, который следует нестандартной структуре файлов (например, App.xaml и App.xaml.cs не находятся в корневой папке), может быть неправильно перенесен.

Репозиторий помощника по обновлению GitHub содержит советы по устранению неполадок и информацию о известных проблемах. Если при использовании средства возникли проблемы, сообщите о них в том же репозитории GitHub, пометьте их тегом UWPобласти. Мы ценим это!

Тестирование средства с помощью примера UWP PhotoLab

Давайте опробуем помощник по обновлению .NET в действии.

В качестве исходного материала мы будем переносить пример приложения UWP PhotoLab. PhotoLab — это пример приложения для просмотра и редактирования файлов изображений. В нем показаны возможности макета XAML, привязки данных и настройки пользовательского интерфейса.

1. Начните с клонирования или скачивания примера исходного кода PhotoLab из приведенной выше ссылки.

1. Откройте решение PhotoLab в Visual Studio.

2. Установив расширение помощника по обновлению .NET (см. раздел "Установка помощника по обновлению .NET" ранее в этом разделе), щелкните проект правой кнопкой мыши в Обозреватель решений и нажмите кнопку "Обновить".

3. Выберите параметр обновление проекта до более новой версии .NET.

4. Выберите вариант обновления проекта на месте.

5. Выберите целевую платформу.

6. Нажмите Обновить выбор.

7. Помощник по обновлению .NET запускается и использует окно Вывод в Visual Studio, чтобы выводить информацию и статус по мере выполнения.

Индикатор выполнения можно отслеживать до завершения операции обновления.

Миграция кода для примера приложения PhotoLab включает:

• Изменения в диалоговых окнах API для выбора содержимого и сохранения файлов.
• Обновление XAML для пакета анимаций.
• Отображение предупреждений и добавление TODOs списка задач в DetailPage.xaml, DetailPage.xaml.cs и MainPage.xaml.cs для настраиваемой кнопки "Назад".
• Реализация функции кнопки "Назад" и добавление списка задач TODO для настройки кнопки XAML.
• Ссылка на документацию предоставляется для получения дополнительных сведений о реализации кнопки "Назад".

Номера версий в результате .csproj будут немного разными, но по сути это будет выглядеть следующим образом (при этом некоторые группы свойств конфигурации сборки удалены для краткости):

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    <Platform Condition=" '$(Platform)' == '' ">x86</Platform>
    <OutputType>WinExe</OutputType>
    <DefaultLanguage>en-US</DefaultLanguage>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>
    <RuntimeIdentifiers>win-x86;win-x64;win-arm64</RuntimeIdentifiers>
    <UseWinUI>true</UseWinUI>
    <ApplicationManifest>app.manifest</ApplicationManifest>
    <EnableMsixTooling>true</EnableMsixTooling>
    <Platforms>x86;x64;arm64</Platforms>
    <PublishProfile>win10-$(Platform).pubxml</PublishProfile>
  </PropertyGroup>
  <ItemGroup>
    <AppxManifest Include="Package.appxmanifest">
      <SubType>Designer</SubType>
    </AppxManifest>
  </ItemGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.1.0" />
    <PackageReference Include="Microsoft.Graphics.Win2D" Version="1.0.0.30" />
    <PackageReference Include="Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers" Version="0.4.346201">
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
    <PackageReference Include="Microsoft.Windows.Compatibility" Version="6.0.0" />
    <PackageReference Include="CommunityToolkit.WinUI.UI.Animations" Version="7.1.2" />
  </ItemGroup>
  <ItemGroup>
    <Compile Remove="App.xaml.old.cs" />
  </ItemGroup>
  <ItemGroup>
    <None Include="App.xaml.old.cs" />
  </ItemGroup>
</Project>

Как видно, проект теперь ссылается на пакет SDK для приложений Windows, WinUI 3 и .NET 6. Теперь, когда PhotoLab перенесен, вы можете воспользоваться всеми новыми функциями, которые должны предложить приложения WinUI 3, и расширить свое приложение с помощью платформы.

Кроме того, помощник по обновлению .NET добавляет анализаторы в проект, который помогает продолжить процесс обновления. Например, пакет NuGet Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers.

Дальнейшие действия по миграции вручную

На этом этапе можно открыть перенесенное решение PhotoLab или проект и просмотреть изменения, внесенные в исходный код. Проект требует немного больше работы, чтобы завершить подключение компонентов до того, как версия WinUI 3 будет собираться, запускаться и работать так же, как версия UWP.

См. список задач в Visual Studio (Просмотр>список задач) для ЗАДАЧ, которые необходимо выполнить вручную для завершения миграции.

Возможно, что версия UWP (платформа .NET Framework) приложения содержит ссылки на библиотеку, которую проект фактически не использует. Необходимо проанализировать каждую ссылку и определить, требуется ли она. Возможно, средство также добавило или обновило ссылку на пакет NuGet до неправильной версии.

Помощник по обновлению не редактирует Package.appxmanifest, что потребует некоторых изменений для запуска приложения:

1. Добавьте это пространство имен к корневому элементу <Package>:

xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"

2. Редактируйте элемент <Application>, изменяя его с EntryPoint="appnamehere.App" на EntryPoint="$targetentrypoint$"

3. Замените указанный Capability на следующее:

<rescap:Capability Name="runFullTrust" />

В вашем файле .csproj может потребоваться изменить файл проекта, чтобы задать <OutputType>WinExe</OutputType> и <UseMaui>False</UseMaui>.

Чтобы использовать многие элементы управления XAML, убедитесь, что файл app.xaml включает в себя <XamlControlsResources>, например, в этом примере:

<Application.Resources>
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>
            <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
            <!-- Other merged dictionaries here -->
        </ResourceDictionary.MergedDictionaries>
        <!-- Other app resources here -->
    </ResourceDictionary>
</Application.Resources>

Советы по устранению неполадок

Существует несколько известных проблем, которые могут возникнуть при использовании помощника по обновлению .NET. В некоторых случаях эти проблемы связаны с средством try-convert, который помощник по обновлению .NET использует внутри системы.

Но дополнительные советы по устранению неполадок и известные проблемы см. в репозитории GitHub Upgrade Assistant.

См. также

• Пакет SDK для приложений Windows и поддерживаемые выпуски Windows