Перенос классического приложения Windows Forms в .NET 5 How to migrate a Windows Forms desktop app to .NET 5

В этой статье описывается, как перенести классическое приложение Windows Forms из .NET Framework в .NET 5 или более поздней версии. This article describes how to migrate a Windows Forms desktop app from .NET Framework to .NET 5 or later. В пакет SDK для .NET включена поддержка приложений Windows Forms. The .NET SDK includes support for Windows Forms applications. Windows Forms — это платформа, которая по-прежнему поддерживается и функционирует только в ОС Windows. Windows Forms is still a Windows-only framework and only runs on Windows.

Для переноса приложения из .NET Framework в .NET 5, как правило, требуется создать новый файл проекта. Migrating your app from .NET Framework to .NET 5 generally requires a new project file. В .NET 5 используются файлы проектов в стиле пакета SDK, а в .NET Framework обычно используется более старый формат файлов проектов Visual Studio. .NET 5 uses SDK-style project files while .NET Framework typically uses the older Visual Studio project file. Если вы когда-либо открывали файл проекта Visual Studio в текстовом редакторе, вы знаете, насколько он подробный. If you’ve ever opened a Visual Studio project file in a text editor, you know how verbose it is. Проекты в стиле пакета SDK меньше по размеру, и для них не требуется такое количество записей, как в файлах проектов старого формата. SDK-style projects are smaller and don’t require as many entries as the older project file format does.

Дополнительные сведения о .NET 5 см. в статье Введение в .NET. To learn more about .NET 5, see Introduction to .NET.

Предварительные требования Prerequisites

Предварительная версия конструктора WinForms в Visual Studio. Preview WinForms designer in Visual Studio.

Чтобы включить конструктор, последовательно выберите Сервис > Параметры > Среда > Функции предварительной версии, а затем выберите параметр Use the preview Windows Forms designer for .NET Core apps (Использовать конструктор Windows Forms предварительной версии для приложений .NET Core). To enable the designer, go to Tools > Options > Environment > Preview Features and select the Use the preview Windows Forms designer for .NET Core apps option.

В этой статье используется пример приложения Matching game. This article uses the Matching game sample app. Если вы хотите в точности выполнять инструкции данной статьи, скачайте и откройте это приложение в Visual Studio. If you want to follow along, download and open the application in Visual Studio. В противном случае используйте собственное приложение. Otherwise, use your own app.

Consider Consider

При переносе приложения Windows Forms из .NET Framework необходимо учесть ряд аспектов. When migrating a .NET Framework Windows Forms application, there are a few things you must consider.

Удостоверьтесь, что ваше приложение подходит для переноса. Check that your application is a good candidate for migration.

Чтобы выяснить, можно ли перенести проект в .NET 5, используйте анализатор переносимости .NET. Use the .NET Portability Analyzer to determine if your project will migrate to .NET 5. Если у проекта есть проблемы с .NET 5, анализатор поможет их обнаружить. If your project has issues with .NET 5, the analyzer helps you identify those problems. Анализатор переносимости .NET можно установить как расширение Visual Studio или вызвать из командной строки. The .NET Portability Analyzer tool can be installed as a Visual Studio extension or used from the command line. См. дополнительные сведения об анализаторе переносимости .NET. For more information, see .NET Portability Analyzer.

Вы используете другую версию Windows Forms. You’re using a different version of Windows Forms.

После выпуска .NET Core 3.0 открытый код Windows Forms был размещен на GitHub. When .NET Core 3.0 was released, Windows Forms went open source on GitHub. Код Windows Forms для .NET 5 образует вилку с базой кода Windows Forms для .NET Framework. The code for Windows Forms for .NET 5 is a fork of the .NET Framework Windows Forms codebase. Возможно, существуют некоторые различия, и ваше приложение будет затруднительно перенести. It’s possible some differences exist and your app will be difficult to migrate.

Некоторые API, существующие в .NET Framework, недоступны в .NET 5. Some APIs that are available in .NET Framework aren’t available in .NET 5. Пакет обеспечения совместимости Windows добавляет многие из этих API, помогая обеспечить совместимость приложения Windows Forms с .NET 5. The Windows Compatibility Pack adds many of these APIs and may help your Windows Forms app become compatible with .NET 5.

Обновите пакеты NuGet, используемые в проекте. Update the NuGet packages used by your project.

Рекомендуется обновить пакеты NuGet до последней версии перед переносом. It’s always a good practice to use the latest versions of NuGet packages before any migration. Если ваше приложение ссылается на пакеты NuGet, обновите их до последней версии. If your application is referencing any NuGet packages, update them to the latest version. Убедитесь, что сборка приложения выполняется успешно. Ensure your application builds successfully. Если после обновления возникают ошибки пакетов, установите предыдущую версию пакетов, которая не нарушает работу вашего кода. After upgrading, if there are any package errors, downgrade the package to the latest version that doesn’t break your code.

Резервное копирование проектов Back up your projects

При переносе проекта первое, что необходимо сделать, это создать резервную копию проекта. The first step to migrating a project is to back up your project! Если что-то пойдет не так, вы сможете вернуть исходное состояние кода, восстановив резервную копию. If something goes wrong, you can restore your code to its original state by restoring your backup. Не полагайтесь на такие инструменты, как анализатор переносимости .NET, для резервного копирования проекта, даже если все выглядит надежно. Don’t rely on tools such as the .NET Portability Analyzer to back up your project, even if they seem to. Лучше всего лично создать копию исходного проекта. It’s best to personally create a copy of the original project.

Пакеты NuGet NuGet packages

Если проект обращается к пакетам NuGet, возможно, в папке проекта имеется файл packages.config. If your project is referencing NuGet packages, you probably have a packages.config file in your project folder. В проектах в стиле пакета SDK ссылки на пакеты NuGet настраиваются в файле проекта. With SDK-style projects, NuGet package references are configured in the project file. В проектах Visual Studio пакеты NuGet также могут дополнительно определяться в файле проекта. Visual Studio project files can optionally define NuGet packages in the project file too. В .NET 5 файлы packages.config для пакетов NuGet не используются. .NET 5 doesn’t use packages.config for NuGet packages. Перед миграцией необходимо перенести ссылки на пакеты NuGet в файл проекта. NuGet package references must be migrated into the project file before migration.

Чтобы перенести файл packages.config, выполните следующие действия. To migrate the packages.config file, do the following steps:

1. В обозревателе решений найдите проект, который требуется перенести. In Solution explorer, find the project you’re migrating.
2. Щелкните правой кнопкой мыши packages.config >Перенести packages.config в PackageReference. Right-click on packages.config >Migrate packages.config to PackageReference.
3. Выберите все пакеты верхнего уровня. Select all of the top-level packages.

Будет создан отчет о сборке, из которого вы сможете узнать о любых проблемах переноса пакетов NuGet. A build report is generated to let you know of any issues migrating the NuGet packages.

Файл проекта Project file

Следующим шагом при переносе приложения является преобразование файла проекта. The next step in migrating your app is converting the project file. Как было сказано выше, в .NET 5 используются файлы проектов в стиле пакета SDK и не загружаются файлы проектов Visual Studio, которые используются в .NET Framework. As previously stated, .NET 5 uses SDK-style project files and won’t load the Visual Studio project files that .NET Framework uses. Однако вполне возможно, что вы уже используете проекты в стиле пакета SDK. However, there’s the possibility that you’re already using SDK-style projects. Вы можете с легкостью выявить разницу в Visual Studio. You can easily spot the difference in Visual Studio. Щелкните правой кнопкой мыши файл проекта в обозревателе решений и попробуйте найти пункт меню Изменить файл проекта. Right-click on the project file in Solution explorer and look for the Edit Project File menu option. Если этот пункт меню отсутствует, то вы используете старый формат проекта Visual Studio, и его необходимо обновить. If this menu item is missing, you’re using the old Visual Studio project format and need to upgrade.

Преобразуйте каждый проект в вашем решении. Convert each project in your solution. Если вы используете упомянутый выше пример приложения, то необходимо преобразовать проекты MatchingGame и MatchingGame.Logic. If you’re using the sample app previously referenced, both the MatchingGame and MatchingGame.Logic projects would be converted.

Чтобы преобразовать проект, выполните следующие действия. To convert a project, do the following steps:

В обозревателе решений найдите проект, который требуется перенести. In Solution explorer, find the project you’re migrating.

Щелкните проект правой кнопкой мыши и выберите Выгрузить проект. Right-click on the project and select Unload Project.

Щелкните проект правой кнопкой мыши и выберите Изменить файл проекта. Right-click on the project and select Edit Project File.

Скопируйте XML-код проекта и вставьте его в текстовый редактор. Copy-and-paste the project XML into a text editor. Копия нужна, чтобы было проще переместить содержимое в новый проект. You’ll want a copy so that it’s easy to move content into the new project.

Очистите содержимое файла и вставьте следующий XML-код: Erase the content of the file and paste the following XML:

Для библиотек не требуется определять параметр . Libraries don’t need to define an setting. Если вы обновляете проект библиотеки, удалите эту запись. Remove that entry if you’re upgrading a library project.

Этот XML-код представляет базовую структуру проекта. This XML gives you the basic structure of the project. Однако в нем нет никаких параметров из старого файла проекта. However, it doesn’t contain any of the settings from the old project file. Используя старые сведения о проекте, скопированные ранее в текстовый редактор, выполните следующие действия. Using the old project information you previously copied to a text editor, do the following steps:

Скопируйте следующие элементы из старого файла проекта в элемент

в новом файле проекта: Copy the following elements from the old project file into the

element in the new project file:

Теперь XML-код в файле проекта должен выглядеть следующим образом: Your project file should look similar to the following XML:

Скопируйте из старого файла проекта элементы , которые содержат

, и вставьте их в новый файл после закрывающего тега

. Copy the elements from the old project file that contain

into the new file after the

Теперь XML-код в файле проекта должен выглядеть следующим образом: Your project file should look similar to the following XML:

не нужны дочерние элементы

и , поэтому эти параметры можно удалить: The

elements don’t need the

and children, so you can remove those settings:

Ресурсы и параметры Resources and settings

Необходимо отметить, что разница между проектами платформы .NET Framework и проектами в стиле SDK, используемыми в .NET 5, заключается в том, что проекты платформы .NET Framework используют модель согласия для файлов кода. One thing to note about the difference between .NET Framework projects and the SDK-style projects used by .NET 5 is that .NET Framework projects use an opt-in model for code files. Любой файл кода, который нужно скомпилировать, должен быть явным образом определен в файле проекта. Any code file you want to compile needs to be explicitly defined in your project file. В проектах в стиле SDK, напротив, по умолчанию используется поведение отказа: Все файлы кода, начиная с каталога проекта и ниже, автоматически включаются в проект. SDK-style projects are reverse, they default to opt-out behavior: All code files starting from the project’s directory and below are automatically included in your project. Эти записи не нужно переносить, если они являются простыми и не содержат параметров. You don’t need to migrate these entries if they are simple and without settings. То же относится к другим общим файлам, например, к файлам resx. This is the same for other common files such as resx.

Проекты Windows Forms также включают файлы проектов Windows Forms, такие как Properties/Settings.settings и Properties/Resources.resx. Windows Forms projects also include Windows Form project specific files, such as Properties/Settings.settings and Properties/Resources.resx. Может потребоваться перенести эти файлы. Они объявляются в исходном проекте. These files may need to be migrated they are declared in your original project.

Скопируйте эти записи из старого файла проекта в элемент в новом проекте. Copy those entries from the old project file into an element in the new project. После копирования записей измените все элементы , указав Update вместо Include . After you copy the entries, change all elements to instead use the Update attribute instead of Include .

Импортируйте конфигурацию для файла Settings.settings. Import the configuration for the Settings.settings file.

Обратите внимание, что для записи Properties\Settings.settings было сохранено значение Include . Notice that the Properties\Settings.settings entry remained Include . Файлы параметров не включаются в проект автоматически. The project doesn’t automatically include settings files.

В проектах Visual Basic файл параметров проекта обычно по умолчанию находится в папке My Project, а в проектах C# — в папке Properties. Visual Basic projects typically use the folder My Project while C# projects typically use the folder Properties for the default project settings file.

Импортируйте конфигурацию для любого RESX-файла, например для properties/Resources.resx. Import the configuration for any resx file, such as the properties/Resources.resx file. Обратите внимание, что для атрибута Include было задано значение Update в и элементе , а был удален из : Notice that the Include attribute was set to Update on the and element, and was removed from :

В проектах Visual Basic файл ресурсов проекта обычно по умолчанию находится в папке My Project, а в проектах C# — в папке Properties. Visual Basic projects typically use the folder My Project while C# projects typically use the folder Properties for the default project resource file.

Visual Basic Visual Basic

Для проектов на языке Visual Basic требуется дополнительная настройка. Visual Basic language projects require extra configuration.

Импортируйте параметр файла конфигурации My Project\Application.myapp. Import the configuration file My Project\Application.myapp setting. Обратите внимание, что элемент использует атрибут Update вместо атрибута Include . Notice that the element uses the Update attribute instead of the Include attribute.

Добавьте параметр WindowsForms в элемент

: Add the WindowsForms setting to the

Этот параметр импортирует элементы пространства имен My , знакомого программистам Visual Basic. This setting imports the My namespace members Visual Basic programmers are familiar with.

Импортируйте пространства имен, определенные в вашем проекте. Import the namespaces defined by your project.

Проекты Visual Basic могут автоматически импортировать пространства имен в каждый файл кода. Visual Basic projects can automatically import namespaces into every code file. Скопируйте из старого файла проекта элементы , содержащие , и вставьте их в новый файл после закрывающего тега

. Copy the elements from the old project file that contain into the new file after the

Если вы не можете найти никакие инструкции , или не удается скомпилировать проект, проверьте, определены ли в проекте следующие инструкции : If you can’t find any statements, or your project fails to compile, make sure you at least have the following statements defined in your project:

Скопируйте параметры и из исходного проекта в элемент

: From the original project, copy the and settings to the

Перезагрузка проекта Reload the project

После преобразования проекта в новый формат в стиле пакета SDK перезагрузите проект в Visual Studio, выполнив следующие действия. After you convert a project to the new SDK-style format, reload the project in Visual Studio:

В обозревателе решений найдите преобразованный вами проект. In Solution Explorer, find the project you converted.

Щелкните проект правой кнопкой мыши и выберите Перезагрузить проект. Right-click on the project and select Reload Project.

Если проект не загружается, возможно, вы допустили ошибку в XML-коде проекта. If the project fails to load, you may have introduced a mistake in the XML of the project. Откройте файл проекта для редактирования и попробуйте найти и исправить ошибку. Open the project file for editing and try to identify and fix the mistake. Если не удается найти ошибку, попробуйте начать заново. If you can’t find a mistake, try starting over.

Изменение файла App.config Edit App.config

Если в вашем приложении имеется файл App.config, удалите элемент : If your app has an App.config file, remove the element:

При работе с файлом App.config необходимо учитывать некоторые аспекты. There are some things you should consider with the App.config file. Файл App.config в .NET Framework использовался не только для настройки приложения, но и для настройки параметров и режима функционирования среды выполнения, например, для включения ведения журнала. The App.config file in .NET Framework was used not only to configure the app, but to configure runtime settings and behavior, such as logging. В .NET 5+ (и .NET Core) файл App.config больше не используется для конфигурации среды выполнения. The App.config file in .NET 5+ (and .NET Core) is no longer used for runtime configuration. Если ваш файл App.config содержит эти разделы, они не будут учитываться. If your App.config file has these sections, they won’t be respected.

Добавление пакета совместимости Add the compatibility package

Если файл проекта загружается правильно, но его компиляция завершается неудачно, появляется сообщение об ошибке, подобное приведенному ниже. If your project file is loading correctly, but compilation fails for your project and you receive errors similar to the following:

• Не удалось найти тип или пространство именThe type or namespace could not be found
• Имя не существует в текущем контекстеThe name does not exist in the current context

Может потребоваться добавить в ваше приложение пакет Microsoft.Windows.Compatibility . You may need to add the Microsoft.Windows.Compatibility package to your app. Этот пакет добавляет около 21 000 API из .NET Framework, например, класс System.Configuration.ConfigurationManager и интерфейсы API для взаимодействия с реестром Windows. This package adds

21,000 .NET APIs from .NET Framework, such as the System.Configuration.ConfigurationManager class and APIs for interacting with the Windows Registry. Добавьте пакет Microsoft.Windows.Compatibility . Add the Microsoft.Windows.Compatibility package.

Измените файл проекта, добавив в него следующий элемент : Edit your project file and add the following element:

Тестирование приложения Test your app

После завершения переноса приложения протестируйте его! After you’ve finished migrating your app, test it!