Educator Developer Blog

10 MIN READ

.NET MAUI on Linux with Visual Studio Code

Iron Contributor

Nov 15, 2023

Introduction

.NET MAUI is a framework for developing cross-platform mobile and desktop applications which offers native performance and user experience. Write once, run everywhere: your app can be deployed to Android, Windows, iOS, and macOS without any change in the code! However, for a long time, you could only create .NET MAUI apps using Visual Studio, thus you needed either Windows or macOS to develop this kind of cross-platform application.

In July this year, the first preview of the .NET MAUI extension for Visual Studio Code was announced [1], which opened the door to a long-awaited request from developers for the first time: to be able to create .NET MAUI apps on Linux. You can now develop and debug a .NET MAUI app on devices and emulators anywhere VS Code runs… for instance, Ubuntu! Check it out and install it from here: [2].

This extension relies on the C# Dev Kit extension (also announced earlier this year [3]), which brings other benefits to improve your productivity:

You can browse through files and projects using the Solution Explorer
You can test your apps using Text Explorer
You can improve your productivity thanks to the enhanced IntelliSense code-completion experience.
IntelliCode gives your development experience superpowers as it uses AI to further boost IntelliCode capabilities with whole-line completions and starred suggestions that learns from the code you write.

Back to the .NET MAUI extension for VS Code, it is important to mention the following aspects:

The extension is currently available in Preview mode, so changes, bugs, and fixes are expected.
The following architectures are supported: Linux x64, Alpine Linux ARM64, Linux ARM64, Windows x64, Windows ARM, Alpine Linux 64 bit, Windows ia32, macOS Intel, macOS Apple Silicon
If you are working on Linux, you can build and deploy Android apps only for the moment. You can build (without running) for all target platforms on any OS, though.
You need a valid Visual Studio or IntelliCode subscription to activate the extension. At the moment, a valid free Visual Studio Community license works because the extension uses the same license mode as Visual Studio.
Hot Reload isn’t supported yet.

Feeling adventurous? Let’s install it! First of all, let’s take note of the requirements that are needed to develop a .NET MAUI on Linux using the Visual Studio Code extension!

A supported Linux OS architecture/distribution, as mentioned in the previous section.
The .NET SDK (minimum version supported is .NET 7)
The .NET MAUI workload
OpenJDK
Android Studio, to simplify the setup of Android SDK, SDK Manager, and emulators.
Visual Studio Code
The .NET MAUI extension for VS Code
A valid Visual Studio (or IntelliCode) license

For this demonstration, an Ubuntu virtual machine (VM) was installed on Windows 10 using Hyper-V. Furthermore, the disk size for the VM was increased to 50 GB (default is 12 GB), so it is recommended to consider it while creating it. Here are some tutorials to do it: [4] [5] [6]

It is also important to mention that Gerald Versluis prepared a great Develop .NET MAUI Apps on Linux with VS Code: Complete Guide video walkthrough that goes step by step to install .NET MAUI on Linux. This great resource was used to create the tutorial you are reading right now, and it is available here: [7]

Step 1 – Install .NET 8 on Linux

First of all, you need to visit the Download .NET 8.0 website [8] and click on dotnet-install-scripts:

Now, click on the Copy button for the Bash script.

Then:

You can open a terminal and use the wget command to download the script to your Ubuntu machine.
Make the script executable with the chmod command: chmod +x dotnet-install.sh
And now you can execute the script with the channel argument (we use 8.0, the latest .NET version),

Here is the picture of the above steps:

The installation should finish without any issues:

To make our lives easier, let’s configure an environment variable that includes the .NET path by editing the Bash shell script with the xdg-open tool:

xdg-open .bashrc

At the end of the file, add the following two lines:

export DOTNET_ROOT=$HOME/.dotnet

export PATH=$PATH:$DOTNET_ROOT:$DOTNET_ROOT/tools

Save the file with Ctrl-S and close it.

Next, apply the changes using the source command, and you can immediately test that we can run the dotnet command from any location. For example, let’s see which version is installed with the info argument:

.NET 8 is present in our machine! Let’s proceed with the next step.

Step 2 – Install .NET MAUI Android workload

Use dotnet workload install maui-android to install the latest version of the .NET MAUI Android workload. This will take some time, so you can go for a cup of coffee meanwhile J.

After the setup is completed, you can use the dotnet workload list command to check the version that was installed.

The .NET MAUI Android workload was successfully installed! Let’s proceed with the next step:

Step 3 – Install OpenJDK 11

Visit the Microsoft documentation website [9] to get the instructions for installing OpenJDK on Ubuntu. Currently, you need to run the following three commands first to download a repository to your machine:

ubuntu_release=`lsb_release -rs`

wget https://packages.microsoft.com/config/ubuntu/${ubuntu_release}/packages-microsoft-prod.deb -O packages-microsoft-prod.deb

sudo dpkg -i packages-microsoft-prod.deb

You will be required to enter your password for the last command to proceed. Here is a picture about it:

Next, you can install the OpenJDK Build from Microsoft with the following three commands. However, be careful. The documentation installs the latest version (21). You need to change that to use version 11:

sudo apt-get install apt-transport-https

sudo apt-get update

sudo apt-get install msopenjdk-11

Here is a couple of screenshots for this step:

For the last command, you need to confirm that you want to proceed with the installation. It should finish without any issues after that. Let’s continue!

Step 4 – Install Android Studio

This step is optional but highly recommended because it’s the easiest way to install three fundamental components for developing Android apps: the Android SDK, the SDK Manager, and Android emulators.

You can install Android Studio from the Ubuntu Software Centre:

The process is quite straightforward, just click on the install button that appears once you select Android Studio.

Enter your credentials as authentication is required to proceed, and then wait for a couple of minutes. After the installation is complete, open Android Studio to proceed with the setup, as we have just installed the software but not the components yet.

The Android Studio Setup Wizard launches, and after a few pages of basic confirmations, you can choose Standard setup type to simplify the configuration:

Next, choose a UI Theme and then you will see that important components such as the Android SDK and emulators will be added:

To start the installation process, you are required to accept the License Agreement for each element.

Now you can relax a bit, get another cup of coffee, and wait for the setup to be completed. When all components have been successfully downloaded, click on Finish.

Android Studio automatically launches, and we just need an additional step. Click on More Actions and choose SDK Manager:

Select Android 13 from the SDK Platforms list and click on OK. You will be informed about the disk space that is required for it, just click on OK again.

The SDK Component Installer proceeds to download the requested packages, and it will be completed after some time. Click on Finish once the button is enabled. You have everything you need to develop an Android app now and we can focus our attention now to Visual Studio Code… and .NET MAUI of course.

Step 5 – Install Visual Studio Code

You can come back to the Ubuntu Software Centre in order to install Visual Studio Code.

This step is quite easy. Let’s move on.

Step 6 – Install the .NET MAUI extension for VS Code

Open Visual Studio Code, then click on the Extensions icon (which is located in the Activity Bar on the side) and enter net maui. The top result should be the official .NET MAUI extension from Microsoft. Install it.

Step 7 – Activate C# Dev Kit

In order to be able to use the extension, you need to activate it by connecting your Visual Studio subscription / license. Visit the Welcome page in Visual Studio Code and you should see a Get Started with .NET MAUI assistant in the Walkthroughs section. Click on it.

Next, choose Connect account to C# Dev Kit and click on the Connect button.

You will be prompted to sign in with your credentials. Allow it and enter them.

After a few seconds, you will see a notification pop up in the bottom part of Visual Studio Code, informing you that the extension has successfully been activated.

Step 8 – Create a .NET MAUI app

Back to the Welcome page, click on Create .NET MAUI App and choose .NET: New Project…

Then, select .NET MAUI App Mobile Desktop from the catalog:

You will be prompted to choose a Project Location. Choose any folder you want, or you can also create a new one, and click on Open.

After that, you write a name for your project and press Enter to confirm:

Wait for the project to be created, you will see several files and folders afterwards:

Step 9 – Fix the issues

However, VS Code will also inform you about two errors:

The solution could not be restored
Android SDK not found

Let’s fix them both. First, the solution could not be restored because some workloads are missing (iOS and Windows), so conditional builds are needed.

Open the project file (the one with file extension .csproj😞

The PropertyGroup section includes 2 TargetFrameworks elements:

For the current OS we are building our app, the .NET 8 Android, iOS, and MacCatalyst platforms can be targeted by .NET MAUI.
If the app is being built on Windows, a Windows 10 platform that .NET MAUI can target is included.

Currently, only the .NET 8 bits for Android are available in our machine (they were installed when the .NET MAUI Android workload was added in Step 2), so the first check fails because it can’t find the missing platforms (iOS and Mac Catalyst). To fix this issue, replace the first TargetFrameworks entry only with the following two:

<TargetFrameworks>net8.0-android</TargetFramework>

<TargetFrameworks Condition="!$([MSBuild]::IsOSPlatform('linux'))"> net8.0-android;net8.0-ios;net8.0-maccatalyst</TargetFrameworks>

The first one means that for the current OS, we can build our app for Android only, while the second one adds Android, iOS, and MacCatalyst support only if the app is being built on any non-Linux OS machine.

This is how the.csproj file looks like. Notice that the TargetFrameworks entry that references Windows wasn’t modified:

Regarding the Android SDK path, it can be solved by clicking on the Configure button from the error pop up:

Select Set Android SDK path.

The path should be located at your HOME directory / Android / Sdk path. Click on the Open button afterwards.

After applying both fixes, the pop ups with the errors will not appear anymore.

Step 10 – Edit and build the app

You can start developing your app now! Let’s do a small change, for example replace the Text value of a Label located in the MainPage.xaml file. Next, click on the Run and Debug icon located in the side Activity Bar and finally click on the Run and Debug button. After some time, you should see that the project was successfully built without any errors!

However, if you are using a virtual machine, the application will not run due to the fact that an emulator is another virtual machine, and Hyper-V might have issues running nested virtualization scenarios.

Let’s test the app using a real device instead.

Step 11 – Pair Android device on WiFi

Wireless debugging is a feature from Android 11 (and onwards) that lets you test your applications without needing a USB cable. You can enable it from the Developer options settings menu on your phone:

You will be required to confirm that you want to allow the device for wireless debugging on your current network. Then, the Wireless debugging menu will be presented. Click on the Paired Devices label and you will notice a pairing code along with an IP address and port appearing below. Please notice that the port is different from the one appearing at the IP address and port label that automatically appears when you enter the Wireless debugging menu.

You are about to use this new data. Open a new Terminal from VS Code and browse to the platform-tools folder (HOME à Android à Sdk à platform-tools) using the cd command. Now, enter ./adb pair followed by the IP address and port that you got after clicking on the Paired devices label on your device just a minute ago.

If you enter the data correctly, the device will be successfully paired to your development computer! However, you need an additional command. Use ./adb connect followed by the IP address and port that appear under IP address and port label on the wireless debugging menu. Please note that the ports for connecting and for pairing are different!

You can click on the XAML icon from the bottom bar on VS Code to see that the physical device was correctly identified and is available for debugging our application!