Installing and running .NET Upgrade Assistant

As stated previously, .NET Upgrade Assistant will attempt to perform the first four steps of the migration of your Xamarin.Forms app to .NET MAUI outlined in the previous section. The tool is under active development and as the team discovers new improvements, they are added. This is mostly due to feedback they receive from developers like you.

At the time of writing, .NET Upgrade Assistant did not work on all projects and has the following limitations:

• Xamarin.Forms must be version 5.0 and higher
• Only Android and iOS projects are converted
• .NET MAUI must be properly installed with the appropriate workloads

If you have followed the steps from Chapter 1, then the last should should already be satisfied.

If your Xamarin.Forms app meets these criteria, then we can get started by installing the tool.

Installing .NET Upgrade Assistant

.NET Upgrade Assistant is a Visual Studio extension on Windows and a command-line tool on Windows and macOS. You can use the integrated developer PowerShell in Visual Studio or any command-line prompt to install the tool. Follow these steps to install the tool using Visual Studio on Windows:

1. In Visual Studio, select the Extensions menu, then the Manage Extensions item. This will open the Manage Extensions dialog.
2. In the Manage Extensions dialog, use the search box to search for upgrade.
3. Select .NET Upgrade Assistant and click Download:

Figure 3.15 – Visual Studio – the Manage Extensions dialog

4. Once the extension has been downloaded, you will need to close and reopen Visual Studio to install the extension:

Figure 3.16 – Installing the .NET Upgrade Assistant VSIX

5. Click Modify and then follow the instructions to complete the installation.
6. Once the installation is complete, reopen Visual Studio.

Now that the tool has been installed, we can use it to convert a Xamarin.Forms project!

Preparing to run .NET Upgrade Assistant

For the remainder of this chapter, we will be using Visual Studio on Windows to migrate a Xamarin.Forms app to .NET MAUI.

To run .NET Upgrade Assistant, we will need a Xamarin.Forms project to upgrade. For this portion of the chapter, we will use the Xamarin.Forms app that was demoed at the Microsoft Build conference in 2019. The source can be found at https://github.com/mindofai/Build2019Chat, though you can find it in this book’s GitHub repository at https://github.com/PacktPublishing/MAUI-Projects-3rd-Edition under the Chapter03/Build2019Chat folder.

Once you have downloaded the source, open the BuildChat.sln file in Visual Studio. Once the project has finished loading, make sure your configuration is correct by running the app first. You should see a screen that looks like this on Android:

Figure 3.17 – The original app on Android

Now that we have confirmed that the original app runs, we can follow these steps to prepare for running .NET Upgrade Assistant:

1. Right-click the BuildChat solution node in Solution Explorer and select Manage NuGet Packages for Solution…:

Figure 3.18 – Solution context menu

2. In the NuGet – Solution window that opens, select the Updates tab:

Figure 3.19 – The NuGet – Solution window

3. Click the Select all packages checkbox, then click Update.
4. Visual Studio will prompt you with a preview of all the changes that will be made. Click OK once you have reviewed them.
5. Visual Studio will then prompt you to accept the license terms for packages that have them. Once you have reviewed the license terms, click I Accept.
6. After updating, you may still have a gold bar indicator in the Visual Studio window from running the application earlier. You can safely dismiss the message by clicking the X button on the right:
   

Figure 3.20 – Xamarin.Forms version gold bar

7. Once the packages have been updated, let’s make sure the app is still working by running it again. You should get a build error like the following:

Figure 3.21 – Error after upgrading packages

8. To resolve this error, in Solution Explorer, select the BuildChat.Android project, then press Alt and Enter at the same time to open the project properties page.
9. Use the Target Framework dropdown to change the value from Android 8.1 (Oreo) to Android 10.0.

Google Play support

You may get a warning about Google Play requiring new apps and updates to support a specific version of Android. To remove that warning, just set Target Framework to the version indicated in the warning message.

10. Visual Studio will prompt you to confirm the change as it has to close and re-open the project. Select Yes.
11. Visual Studio may also prompt you to install the Android version if you haven’t installed it. Follow the prompts to install the Android version.
12. Attempting to run the project again yields a new set of errors:

Figure 3.22 – Missing packages error

13. To resolve this error, right-click the BuildChat.Android project and select Unload Project. The project file should open in Visual Studio automatically.
14. Locate <ItemGroup> in the file with <PackageReference> items and make the changes highlighted in the following snippet:

    <ItemGroup>
        <PackageReference Include="Microsoft.AspNetCore.SignalR.Client">
        <Version>7.0.9</Version>
        </PackageReference>
        <PackageReference Include="Xamarin.Forms" Version="5.0.0.2578" />
        <PackageReference Include="Xamarin.Android.Support.Design" Version="28.0.0.3" />
        <PackageReference Include="Xamarin.Android.Support.v7.AppCompat" Version="28.0.0.3" />
        <PackageReference Include="Xamarin.Android.Support.v4" Version="28.0.0.3" />
        <PackageReference Include="Xamarin.Android.Support.v7.CardView" Version="28.0.0.3" />
    <PackageReference Include="Xamarin.AndroidX.MediaRouter" Version="1.2.0" />
        <PackageReference Include="Xamarin.AndroidX.Palette" Version="1.0.0.5" />
    </ItemGroup>

    You could also use Visual Studio’s NuGet Package Manager to add these packages.

15. Save and reload the project before trying to run it again. Since the project was unloaded, you will need to set the BuildChat.Android project as the startup project again.

You should be able to run the application at this time since some warnings can be ignored. If not, review the previous steps to make sure you made all the changes correctly. At this point, we are ready to run the upgrade assistant to convert from Xamarin.Forms into .NET MAUI.

Treat warnings as errors

If you have the project option to treat warnings as errors set to anything other than none, then the warnings will prevent you from running the app. Set the option to none to allow the app to run. The option defaults to none.

Running .NET Upgrade Assistant

Running .NET Upgrade Assistant from within Visual Studio is a straightforward process. We will upgrade each project individually; there isn’t any method to upgrade all the projects in one go.

Upgrading the BuildChat project

Let’s start with the shared project, BuildChat, by following these steps:

1. Select the BuildChat project in Solution Explorer.
2. Use the context menu to select the Upgrade menu item:

Figure 3.23 – Upgrading the BuildChat project

This will open the Upgrade assistant in a document window:

Figure 3.24 – Upgrading the BuildChat project

3. Select the In-place project upgrade option.
4. Depending on the versions of .NET you have installed, you will be prompted to choose one. If you followed the setup instructions in Chapter 1, you should have the .NET 7.0 option available. Select .NET 7.0 and select Next:

Figure 3.25 – Choosing the preferred target framework

5. At this point, you are allowed to review the changes that will be made by expanding each node in the list. You can also choose to not upgrade certain items by removing the check in the checkbox next to that item. When you have inspected all the changes, make sure all items are checked again, then click Upgrade selection:

Figure 3.26 – Reviewing the upgrade

6. Visual Studio will start the upgrade process. You can monitor it as it completes each item:

Figure 3.27 – Upgrade in progress

7. When it’s finished, you can inspect each item to see what the result of the upgrade was:

Figure 3.28 – Upgrade complete

A white check in a green circle indicates some transformation was completed and successful, a green check with a white background means the step was skipped since nothing was needed, and a red cross (not shown) means the transformation failed. You can view the complete output from the tool by inspecting the Upgrade Assistant log in the output pane:

Figure 3.29 – Upgrade Assistant log output

Do not be concerned with the errors in the error window at this point. There will be errors until we finish upgrading the remaining projects. Now that the BuildChat project has been upgraded, we can upgrade the BuildChat.Android project.

Upgrading the BuildChat.Android project

The steps for upgrading the remaining projects are largely the same – the only difference will be the steps involved in upgrading each project. The next two sections will skip the screenshots and just provide the steps. To complete the upgrade for the BuildChat.Android project, follow these steps:

1. Select the BuildChat.Android project in Solution Explorer.
2. Use the context menu to select the Upgrade menu item.
3. This will open the Upgrade assistant in a document window.
4. Select the In-place project upgrade option.
5. Select the .NET 7.0 option, then select Next.
6. Review the changes that will be made by expanding each node in the list. Make sure all items are checked, then click Upgrade Selection.
7. Visual Studio will complete the upgrade process.

Now that .NET Upgrade Assistant has completed the BuildChat.Android project, we can upgrade the BuildChat.iOS project.

Upgrading the BuildChat.iOS project

The steps for upgrading the iOS project are largely the same – the only difference will be the steps involved in upgrading each project. To complete the upgrade for the BuildChat.iOS project, follow these steps:

1. Select the BuildChat.iOS project in Solution Explorer.
2. Use the context menu to select the Upgrade menu item.
3. This will open the Upgrade assistant in a document window:
4. Select the In-place project upgrade option.
5. Select the .NET 7.0 option, then select Next.
6. Review the changes that will be made by expanding each node in the list. Make sure all items are checked, then click Upgrade Selection.
7. Visual Studio will complete the upgrade process.

Now that .NET Upgrade Assistant has completed the BuildChat.iOS project, we can see how well it worked.

Completing the upgrade to .NET MAUI

With .NET Upgrade Assistant having done all the work it can to upgrade the projects, we can now see what is left for us to complete the upgrade to .NET MAUI.

The first thing we want to do is make sure that the project is clean of all the previous build artifacts. This will ensure we are referencing all the right dependencies in our build output by forcing a restore and build. The best way to accomplish this is to remove the bin and obj folders from each project folder.

Use File Explorer to remove the bin and obj folders from the BuildChat, BuildChat.Android and BuildChat.iOS folders, then build the solution.

We’ll end up with a few build errors for each project, as shown in the following figure:

Figure 3.30 – Package issues

To resolve these errors, either use Visual Studio’s NuGet Package Manager to add a reference to version 7.0.1 of the Microsoft.Extensions.Logging.Abstractions package to all the projects, or follow these steps to update the project files manually:

1. Select the BuildChat project in Solution Explorer.

   The project file will open in a document window automatically.

2. Locate the ItemGroup element that contains the PackageReference items.
3. Make the changes highlighted in the following snippet:

   <ItemGroup>
       <PackageReference Include="Microsoft.AspNetCore.SignalR.Client" Version="7.0.9" />
       <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="7.0.1" />
   </ItemGroup>

4. Select the BuildChat.Android project in Solution Explorer.

   The project file will open in a document window automatically.

5. Locate the ItemGroup element that contains the PackageReference items.
6. Make the changes highlighted in the following snippet:

   <ItemGroup>
       <PackageReference Include="Xamarin.AndroidX.MediaRouter" Version="1.2.0" />
       <PackageReference Include="Xamarin.AndroidX.Palette" Version="1.0.0.5" />
       <PackageReference Include="Microsoft.AspNetCore.SignalR.Client" Version="7.0.9" />
       <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="7.0.1" />
   </ItemGroup>

7. Select the BuildChat.iOS project in Solution Explorer.

   The project file will open in a document window automatically.

8. Locate the ItemGroup element that contains the PackageReference items.
9. Make the changes highlighted in the following snippet:

   <ItemGroup>
       <PackageReference Include="Microsoft.AspNetCore.SignalR.Client" Version="7.0.9" />
       <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="7.0.1" />
   </ItemGroup>

Now that we have added the required package references, we can try building the app again. After this build, we’ll get two new errors:

Figure 3.31 – Namespace does not exist errors

These two errors show two areas that the upgrade assistant did not upgrade. Luckily, we covered how to upgrade these two files easier in this chapter. Let’s upgrade them again, starting with the BuildChat.Android project.

Open the MainActivity.cs file and make the changes highlighted in the following code:

using Microsoft.Maui;
namespace BuildChat.Droid
{
    [Activity(Label = "BuildChat", Icon = "@mipmap/icon", Theme = "@style/Theme.MaterialComponents", MainLauncher = true, ConfigurationChanges = ConfigChanges.ScreenSize | ConfigChanges.Orientation)]
    public class MainActivity : MauiAppCompatActivity
    {
        protected override void OnCreate(Bundle savedInstanceState)
        {
            base.OnCreate(savedInstanceState);
        }
    }
}

That should complete the changes needed for the Android project. Now, to upgrade the iOS project, open the AppDelegate.cs file in BuildChat.iOS and update it so that it matches the following:

using Foundation;
using Microsoft.Maui;
using Microsoft.Maui.Hosting;
namespace BuildChat.iOS
{
    // The UIApplicationDelegate for the application. This class is responsible for launching the
    // User Interface of the application, as well as listening (and optionally responding) to
    // application events from iOS.
    [Register("AppDelegate")]
    public partial class AppDelegate : MauiUIApplicationDelegate
    {
        protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
    }
}

The final change for the iOS project is to open the Info.plist file and change the MinimumOSVersion property to 15.2. To make this change, use Generic PList Editor. To open the Info.plist file and make this change, follow these steps:

1. Select the Info.plist file in the BuildChat.iOS project.
2. Use the context menu (right-click) and select Open With….
3. In the Open With dialog, select Generic Plist Editor, then select OK:

Figure 3.32 – Opening the Info.plist file

4. Find the entry labeled Minimum system version and change the value from 8.0 to 15.1:

Figure 3.33 – Changing the minimum system version

Great – that should complete the changes needed to get the app running as a .NET MAUI application! The following are the before and after screenshots of the application; before is on the left and after is on the right:

Figure 3.34 – Xamarin.Forms versus .NET MAUI

There are some visual changes between Xamarin.Forms and .NET MAUI, and you can tweak the .NET MAUI settings for the layouts and controls to get a very similar output.