Share via

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

  • Статья

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

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

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

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

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

Итоги

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

  • При необходимости копирует проект и переносит копию; оставляя исходный проект неизменным.
  • При необходимости переносит проект на месте (в одних и том же папках и файлах без переименования папок); и не делает копию.
  • Обновляет проект с платформа .NET Framework формата проекта до последнего формата проекта пакета SDK для .NET.
  • Очищает ссылки на пакеты 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 и пакета SDK для приложений Windows, и использует toDOs списка задач для маркировки API, которые больше не поддерживаются.

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

Совет

Чтобы просмотреть все созданные средства toDOs, просмотрите список задач в Visual Studio.

Примечание.

После завершения работы средства можно выполнить некоторые дальнейшие действия, которые можно выполнить при необходимости. Код можно переместить в App.xaml.old.csApp.xaml.cs; и восстановить AssemblyInfo.cs из резервной копии, которую создает средство.

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

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

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

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

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

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

  • Пользовательские представления не поддерживаются. Например, вы не получите предупреждение или исправление для пользовательского диалогового окна, расширяющего MessageDialog, и неправильно вызывает API.
  • среда выполнения Windows компоненты не поддерживаются.
  • Приложения с несколькими окнами могут быть перенесены неправильно.
  • Проект, который следует нестандартной структуре файлов (например App.xaml , не App.xaml.cs находясь в корневой папке), может быть неправильно перенесен.

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

Примечание.

Инструкции по процессу миграции и различия между функциями пакета SDK для приложений UWP и Windows см. в статье "Миграция с UWP в пакет SDK для приложений Windows".

Совет

Вы можете увидеть, какую версию средства у вас есть, выполнив команду upgrade-assistant --version.

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

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

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

Примечание.

Вы увидите пример примера PhotoLab, который полностью переносится вручную в пакете SDK для приложений Windows для примера приложения UWP PhotoLab.

  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>net6.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>win10-x86;win10-x64;win10-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 (просмотр>списка задач) для toDOs, которые необходимо выполнить вручную для завершения миграции.

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

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

  1. Добавьте это пространство имен в корневой <элемент Package> :
xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"

  1. <Изменение элемента Application> из EntryPoint="appnamehere.App"EntryPoint="$targetentrypoint$"

  2. Замените все указанные ниже значения 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.