Обновление приложения Windows Forms до .NET 6 с помощью помощника по обновлению .NET

помощник по обновлению .net — это программа командной строки, которая может помочь при обновлении платформа .NET Framework Windows Forms приложений до .net 6. В этой статье приводится следующее:

  • Демонстрация запуска средства для приложения .NET Framework Windows Forms
  • Советы по устранению неполадок

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

Демонстрационное приложение

для тестирования обновления с помощью помощника по обновлению можно использовать образец проекта " базовый Windows Forms ".

Анализ приложения

Средство "помощник по обновлению .NET" включает режим анализа, который выполняет упрощенный прогон обновления приложения. Он может предоставить подробные сведения о том, какие изменения могут потребоваться перед началом обновления. Откройте терминал и перейдите в папку, в которой находится целевой проект или решение. upgrade-assistant analyzeВыполните команду, передав имя проекта или решения, которое вы обновляете.

например, выполнение режима анализа с примером приложения " базовый Windows Forms " создает следующие выходные данные, указывающие, что перед обновлением не нужно вносить изменения:

> upgrade-assistant analyze .\MatchingGame.sln

16:18:52 INF] Loaded 5 extensions
[16:18:53 INF] Using MSBuild from C:\Program Files\dotnet\sdk\6.0.200-preview.22055.15\
[16:18:53 INF] Using Visual Studio install from C:\Program Files\Microsoft Visual Studio\2022\Preview [v17]
[16:18:55 INF] Recommending Windows TFM net6.0-windows because the project either has Windows-specific dependencies or builds to a WinExe
[16:18:56 INF] Reference to .NET Upgrade Assistant analyzer package (Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers, version 0.3.261602) needs to be added
[16:18:57 INF] Adding Microsoft.Windows.Compatibility 6.0.0
[16:18:57 INF] Reference to .NET Upgrade Assistant analyzer package (Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers, version 0.3.261602) needs to be added
[16:18:57 INF] Running analyzers on MatchingGame
[16:18:59 INF] Identified 0 diagnostics in project MatchingGame
[16:18:59 INF] Running analyzers on MatchingGame.Logic
[16:18:59 INF] Identified 0 diagnostics in project MatchingGame.Logic
[16:18:59 WRN] HighDpiMode needs to set in Main() instead of app.config or app.manifest - Application.SetHighDpiMode(HighDpiMode.<setting>). It is recommended to use SystemAware as the HighDpiMode option for better results.

В выходных данных содержится довольно много внутренних диагностических данных, но некоторые сведения полезны. Обратите внимание, что режим анализа указывает, что при обновлении будет рекомендовано назначение моникера целевой платформы (net6.0-windows) для проекта net6.0-windows . это связано с тем, что проекты, на которые ссылается решение, являются Windows Forms проектами, технологией, предназначенной только для Windows. консольное приложение, вероятно, получит рекомендацию выполнить обновление до TFM net6.0 напрямую, если только не использовали определенные библиотеки Windows.

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

Запуск upgrade-assistant

Откройте терминал и перейдите в папку, в которой находится целевой проект или решение. upgrade-assistant upgradeВыполните команду, передав имя проекта или решения, которое вы обновляете.

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

upgrade-assistant upgrade .\MatchingGame.sln

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

  • Получите дополнительные сведения о шаге.
  • Изменение проектов.
  • Настройте параметры ведения журнала.
  • Завершите обновление и завершите работу.

Нажатие клавиши Ввод без выбора номера выбирает первый элемент в списке.

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

Выбор точки входа

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

Upgrade Steps

1. [Next step] Select an entrypoint
2. Select project to upgrade

Choose a command:
   1. Apply next step (Select an entrypoint)
   2. Skip next step (Select an entrypoint)
   3. See more step details
   4. Configure logging
   5. Exit

Выберите команду 1 , чтобы запустить этот шаг. Отобразятся результаты:

[16:32:05 INF] Applying upgrade step Select an entrypoint
Please select the project you run. We will then analyze the dependencies and identify the recommended order to upgrade projects.
   1. MatchingGame
   2. MatchingGame.Logic

в списке есть два проекта: основное Windows Forms приложение (матчинггаме) и проект библиотеки (матчинггаме. Logic). Выберите проект Матчинггаме для точки входа, которая является элементом 1.

Выберите проект для обновления

После определения точки входа следует выбрать проект, который необходимо сначала обновить. в этом примере средство определило, что проект библиотеки (матчинггаме. Logic) следует сначала обновить, так как от него зависит главный проект Windows Forms приложения.

[16:36:20 INF] Applying upgrade step Select project to upgrade
Here is the recommended order to upgrade. Select enter to follow this list, or input the project you want to start with.
   1. MatchingGame.Logic
   2. MatchingGame

Рекомендуемый путь заключается в том, чтобы сначала обновить проект матчинггаме. Logic , так как от него зависит проект матчинггаме . Рекомендуется следовать рекомендациям по обновлению.

Обновление матчинггаме. Logic является простым проектом и не предоставляет каких-либо проблем, возникающих после обновления. Поэтому эта статья продолжится, как если бы этот проект уже был обновлен, а следующий проект для обновления — матчинггаме.

Обновление проекта

После выбора проекта появится список шагов обновления, которые будут выполнены в списке.

Важно!

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

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

Следующие выходные данные описывают шаги, связанные с обновлением проекта.

[16:38:44 INF] Initializing upgrade step Back up project

Upgrade Steps

Entrypoint: C:\code\Work\temp\Migration\winforms\net45cs\MatchingGame\MatchingGame.csproj
Current Project: C:\code\Work\temp\Migration\winforms\net45cs\MatchingGame\MatchingGame.csproj

1. [Next step] Back up project
2. Convert project file to SDK style
3. Clean up NuGet package references
4. Update TFM
5. Update NuGet Packages
6. Add template files
7. Update Winforms Project
    a. Default Font API Alert
    b. Winforms Source Updater
8. Upgrade app config files
    a. Convert Application Settings
    b. Convert Connection Strings
    c. Disable unsupported configuration sections
9. Update source code
    a. Apply fix for UA0002: Types should be upgraded
    b. Apply fix for UA0012: 'UnsafeDeserialize()' does not exist
10. Move to next project

Choose a command:
   1. Apply next step (Back up project)
   2. Skip next step (Back up project)
   3. See more step details
   4. Select different project
   5. Configure logging
   6. Exit

Примечание

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

Создание резервной копии

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

[16:43:22 INF] Applying upgrade step Back up project
Please choose a backup path
   1. Use default path [C:\code\Work\temp\Migration\winforms\net45cs.backup]
   2. Enter custom path

Средство выбирает путь резервного копирования по умолчанию под текущей папкой, но с .backup добавлением к нему. Можно выбрать пользовательский путь в качестве альтернативы пути по умолчанию. Для каждого обновленного проекта папка проекта копируется в папку Backup. В этом примере MatchingGame Папка копируется из MatchingGame в net45cs. баккуп\матчинггаме на этапе резервного копирования:

[16:43:37 INF] Backing up C:\code\Work\temp\Migration\winforms\net45cs\MatchingGame to C:\code\Work\temp\Migration\winforms\net45cs.backup\MatchingGame
[16:43:37 INF] Project backed up to C:\code\Work\temp\Migration\winforms\net45cs.backup\MatchingGame
[16:43:37 INF] Upgrade step Back up project applied successfully
Please press enter to continue...

Обновление файла проекта

проект обновляется из платформа .NET Framework формата проекта в формат проекта пакета SDK для .net.

[16:44:31 INF] Applying upgrade step Convert project file to SDK style
[16:44:31 INF] Converting project file format with try-convert, version 0.3.261602+8aa571efd8bac422c95c35df9c7b9567ad534ad0
[16:44:31 INF] Recommending Windows TFM net6.0-windows because the project either has Windows-specific dependencies or builds to a WinExe
C:\code\Work\temp\Migration\winforms\net45cs\MatchingGame\MatchingGame.csproj contains an App.config file. App.config is replaced by appsettings.json in .NET Core. You will need to delete App.config and migrate to appsettings.json if it's applicable to your project.
[16:44:32 INF] Converting project C:\code\Work\temp\Migration\winforms\net45cs\MatchingGame\MatchingGame.csproj to SDK style
[16:44:32 INF] Project file converted successfully! The project may require additional changes to build successfully against the new .NET target.
[16:44:33 INF] Upgrade step Convert project file to SDK style applied successfully
Please press enter to continue...

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

App.config заменяется appSettings. JSON в .NET Core. Необходимо удалить App.config и выполнить миграцию в appSettings. JSON, если он применим к проекту.

в рамках этого шага обновления NuGet пакеты, на которые ссылается packages.config , переносятся в файл проекта.

очистка NuGet ссылок

после обновления формата проекта следующим шагом является очистка ссылок на NuGet пакетов.

В дополнение к пакетам, на которые ссылается ваше приложение, файл packages.config содержит ссылки на зависимости этих пакетов. Например, если вы добавили ссылку на пакет а , который зависит от пакета B, в файле packages.config будет ссылаться на оба пакета. В новой системе проектов требуется только ссылка на пакет A . На этом шаге анализируются ссылки на пакет и удаляются те, которые не требуются.

[16:46:06 INF] Applying upgrade step Clean up NuGet package references
[16:46:06 INF] Removing outdated package reference: MetroFramework.Design, Version=1.2.0.3
[16:46:06 INF] Removing outdated package reference: MetroFramework.Fonts, Version=1.2.0.3
[16:46:06 INF] Removing outdated package reference: MetroFramework.RunTime, Version=1.2.0.3
[16:46:06 INF] Adding package reference: Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers, Version=0.3.261602
[16:46:08 INF] Upgrade step Clean up NuGet package references applied successfully
Please press enter to continue...

приложение по-прежнему ссылается на платформа .NET Framework сборки. некоторые из этих сборок могут быть доступны в виде пакетов NuGet. этот шаг анализирует эти сборки и ссылается на соответствующий пакет NuGet.

Работа с TFM

далее средство изменяет TFM с платформа .NET Framework на предлагаемый пакет SDK. В нашем примере он выглядит следующим образом: net6.0-windows.

[16:47:16 INF] Applying upgrade step Update TFM
[16:47:16 INF] Recommending Windows TFM net6.0-windows because the project either has Windows-specific dependencies or builds to a WinExe
[16:47:18 INF] Updated TFM to net6.0-windows
[16:47:18 INF] Upgrade step Update TFM applied successfully
Please press enter to continue...

Обновление пакетов NuGet

затем средство обновляет пакеты NuGet проекта до версий, поддерживающих обновленную TFM, net6.0-windows .

[16:47:47 INF] Applying upgrade step Update NuGet Packages
[16:47:47 INF] Removing outdated package reference: Microsoft.CSharp, Version=4.7.0
[16:47:47 INF] Removing outdated package reference: System.Data.DataSetExtensions, Version=4.5.0
[16:47:47 INF] Adding package reference: Microsoft.Windows.Compatibility, Version=6.0.0
[16:47:49 INF] Upgrade step Update NuGet Packages applied successfully
Please press enter to continue...

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

Windows Forms обновлений для конкретных проектов

первое Windows Forms конкретное обновление — фактически уведомлять о том, что шрифт по умолчанию в Windows Forms изменился. шрифт по умолчанию изменен с Microsoft Sans Serif, 8.25 pt (платформа .NET Framework) на Segoe UI, 9pt (.net 6 или более поздней версии). дополнительные сведения см. в разделе новые возможности в Windows Forms: шрифт по умолчанию. Из-за этого изменения необходимо изучить все формы и пользовательские элементы управления. Изменение шрифта по умолчанию может повлиять на макет элементов управления в формах.

[16:48:45 INF] Applying upgrade step Default Font API Alert
[16:48:45 WRN] Default font in Windows Forms has been changed from Microsoft Sans Serif to Seg Segoe UI, in order to change the default font use the API - Application.SetDefaultFont(Font font). For more details see here - https://devblogs.microsoft.com/dotnet/whats-new-in-windows-forms-in-net-6-0-preview-5/#application-wide-default-font.
[16:48:45 INF] Upgrade step Default Font API Alert applied successfully
Please press enter to continue...

следующим изменением для Windows Forms является обновление логики запуска приложения для вызова SetHighDpiMode метода, который устанавливает режим DPI приложения Windows Forms. Ранее это было задано в файле app.config или app. manifest . Это также может повлиять на макет элементов управления в формах.

[16:49:05 INF] Applying upgrade step Winforms Source Updater
[16:49:05 WRN] HighDpiMode needs to set in Main() instead of app.config or app.manifest - Application.SetHighDpiMode(HighDpiMode.<setting>). It is recommended to use SystemAware as the HighDpiMode option for better results.
[16:49:05 INF] Updated Program.cs file at C:\code\Work\temp\Migration\winforms\net45cs\MatchingGame\Program.cs with HighDPISetting set to SystemAware
[16:49:05 INF] Upgrade step Winforms Source Updater applied successfully
[16:49:05 INF] Applying upgrade step Update Winforms Project
[16:49:05 INF] Upgrade step Update Winforms Project applied successfully
Please press enter to continue...

Файлы конфигурации и кода

Затем необходимо перенести файл app.config . Нет ни одной строки подключения или параметров для миграции в новый файл appSettings. JSON . Если вы просматриваете выходные данные в примере проекта, обратите внимание, что запись инициализации отображалась три раза, каждая с другим шагом. Если шаг не имеет ничего, он пропускается, как в случае с шагами «обновление файлов конфигурации приложения» и «обновление исходного кода».

[07:35:56 INF] Initializing upgrade step Upgrade app config files
[07:35:56 INF] Found 0 app settings for upgrade:
[07:35:56 INF] Found 0 connection strings for upgrade:
[07:35:56 INF] Initializing upgrade step Update source code
[07:35:56 INF] Running analyzers on MatchingGame
[07:35:57 INF] Identified 0 diagnostics in project MatchingGame
[07:35:57 INF] Initializing upgrade step Move to next project

Завершение обновления

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

1. [Next step] Finalize upgrade

Choose a command:
   1. Apply next step (Finalize upgrade)
   2. Skip next step (Finalize upgrade)
   3. See more step details
   4. Configure logging
   5. Exit

после завершения обновления перенесенный Windows Forms проект выглядит как следующий код XML:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net6.0-windows</TargetFramework>
    <OutputType>WinExe</OutputType>
    <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
    <UseWindowsForms>true</UseWindowsForms>
    <ImportWindowsDesktopTargets>true</ImportWindowsDesktopTargets>
  </PropertyGroup>
  <ItemGroup>
    <ProjectReference Include="..\MatchingGame.Logic\MatchingGame.Logic.csproj" />
  </ItemGroup>
  <ItemGroup>
    <PackageReference Include="MetroFramework" Version="1.2.0.3" />
    <PackageReference Include="Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers" Version="0.3.261602">
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
    <PackageReference Include="Microsoft.Windows.Compatibility" Version="6.0.0" />
  </ItemGroup>
</Project>

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

проекты Visual Basic

если вы используете Visual Basic для кодирования проекта, помощник по обновлению .net может содержать дополнительные действия, такие как перенос My пространства имен. Вы должны увидеть только те шаги, которые были добавлены, если проект использует эти функции. В примере приложения код в матчинггаме. Logic использует пространство имен для доступа к реестру. Этот проект будет иметь шаг, связанный My с:

7. Update Visual Basic project
    a. Update vbproj to support "My." namespace

После обновления

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

На момент публикации этой статьи не удается скомпилировать проект матчинггаме. Logic . этот проект использует реестр Windows, который не предоставляется непосредственно в .net 6, как это было в платформа .NET Framework. чтобы получить доступ к реестру Windows, добавьте NuGet пакет Microsoft. Win32. Registry в проект.

<PackageReference Include="Microsoft.Win32.Registry" Version="5.0.0" />

После того как этот элемент будет зафиксирован, пример приложения компилируется и выполняется.

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

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

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

См. также раздел