diff --git a/dotnet-desktop-guide/net/winforms/migration/index.md b/dotnet-desktop-guide/net/winforms/migration/index.md index 4a2272e..a6b5b71 100644 --- a/dotnet-desktop-guide/net/winforms/migration/index.md +++ b/dotnet-desktop-guide/net/winforms/migration/index.md @@ -49,13 +49,13 @@ When migrating a .NET Framework Windows Forms application, there are a few thing ## 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. Don't rely on tools such as the .NET Portability Analyzer to back up your project, even if they seem to. It's better to have a copy of the original project safely stored in the cloud or elsewhere on your computer. +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. 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 packages If your project is referencing NuGet packages, you probably have a **packages.config** file in your project folder. With SDK-style projects, NuGet package references are configured in the project file. Visual Studio project files can optionally define NuGet packages in the project file too. .NET 5 doesn't use **packages.config** for NuGet packages. NuGet package references must be migrated into the project file before migration. -To migrate the **packages.config** file, do the following: +To migrate the **packages.config** file, do the following steps: 01. In **Solution explorer**, find the project you're migrating. 02. Right-click on **packages.config** > **Migrate packages.config to PackageReference**. @@ -67,13 +67,15 @@ A build report is generated to let you know of any issues migrating the NuGet pa The next step in migrating your app is converting the project file. As previously stated, .NET 5 uses SDK-style project files and won't load the Visual Studio project files that .NET Framework uses. However, there's the possibility that you're already using SDK-style projects. 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. If this menu item is missing, you're using the old Visual Studio project format and need to upgrade. -To upgrade, do the following: +Convert each project in your solution. 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: 01. In **Solution explorer**, find the project you're migrating. 01. Right-click on the project and select **Unload Project**. 01. Right-click on the project and select **Edit Project File**. 01. 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. -01. Erase the content of the file and paste in the following content: +01. Erase the content of the file and paste the following XML: ```xml @@ -91,14 +93,14 @@ To upgrade, do the following: > [!IMPORTANT] > Libraries don't need to define an `` setting. Remove that entry if you're upgrading a library project. -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: +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: 01. Copy the following elements from the old project file into the `` element in the new project file: - `` - `` - Your project file should look similar to the following: + Your project file should look similar to the following XML: ```xml @@ -118,7 +120,7 @@ This XML gives you the basic structure of the project. However, it doesn't conta 01. Copy the `` elements from the old project file that contain `` or `` into the new file after the `` closing tag. - Your project file should look similar to the following: + Your project file should look similar to the following XML: ```xml @@ -142,7 +144,7 @@ This XML gives you the basic structure of the project. However, it doesn't conta ``` - The `` elements don't need the `` and `` children, so you can remove those: + The `` elements don't need the `` and `` children, so you can remove those settings: ```xml @@ -156,7 +158,7 @@ Windows Forms projects for .NET Framework typically include other files such as Copy those entries from the old project file into an `` element in the new project. After you copy the entries, change any `` or `` elements to instead use `Update` instead of `Include`. -- Import the configuration for the *Settings.settings* file. Note that `Include` was changed to `Update` on the `` element: +- Import the configuration for the *Settings.settings* file. Notice that the `Include` was changed to `Update` on the `` element: ```xml @@ -172,7 +174,10 @@ Copy those entries from the old project file into an `` element in th ``` -- Import the configuration for any *resx* file, such as the *properties/Resources.resx* file. Note that `Include` was changed to `Update` on both the `` and `` elements, and `` was removed from ``: + > [!IMPORTANT] + > **Visual Basic** projects typically use the folder *My Project* while C# projects typically use the folder *Properties* for the default project settings file. + +- Import the configuration for any *resx* file, such as the *properties/Resources.resx* file. Notice that the `Include` was changed to `Update` on both the `` and `` elements, and `` was removed from ``: ```xml @@ -188,11 +193,97 @@ Copy those entries from the old project file into an `` element in th ``` -Convert each project in your solution. If you're using the sample app previously referenced, the **MatchingGame.Logic** project would be converted. + > [!IMPORTANT] + > **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 language projects require extra configuration. + +01. Import the configuration file *My Project\Application.myapp* setting. Notice that the `` and `` elements use the `Update` attribute instead of the `Include` attribute. + + ```xml + + + MyApplicationCodeGenerator + Application.Designer.vb + + + True + Application.myapp + True + + + ``` + +01. Add the `WindowsForms` setting to the `` element: + + ```xml + + (contains settings previously described) + + WindowsForms + + ``` + + This setting imports the `My` namespace members Visual Basic programmers are familiar with. + +01. Import the namespaces defined by your project. + + 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 `` closing tag. + + ```xml + + + + + + + + + + + + + + ``` + + 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: + + ```xml + + + + + + ``` + +01. From the original project, copy the `` and `` settings to the `` element: + + ```xml + + (contains settings previously described) + + On + Binary + Off + On + MatchingGame.My.MyApplication + + ``` + +### Reload the project + +After you convert a project to the new SDK-style format, reload the project in Visual Studio: + +01. In **Solution Explorer**, find the project you converted. +01. Right-click on the project and select **Reload Project**. + + 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. ## Edit App.config -If your app has an *App.config* file, remove the `` element. +If your app has an *App.config* file, remove the `` element: ```xml @@ -202,16 +293,18 @@ There are some things you should consider with the *App.config* file. The *App.c ## Add the compatibility package -If compilation fails and you receive errors similar to the following: +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** -You may need to add the [**Microsoft.Windows.Compatibility**](https://www.nuget.org/packages/Microsoft.Windows.Compatibility/) package to your app. 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. +You may need to add the [`Microsoft.Windows.Compatibility`](https://www.nuget.org/packages/Microsoft.Windows.Compatibility/) package to your app. 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. Add the `Microsoft.Windows.Compatibility` package. + +Edit your project file and add the following `` element: ```xml - + ```