.NET MAUI on Linux with Visual Studio Code
Published Nov 15 2023 08:00 PM 71.4K Views
Iron Contributor

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. 

elbruno_0-1699984408105.png

 

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]. 

elbruno_1-1699984421362.png

 

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.

03.png

 

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] 

 

elbruno_0-1699984801301.png

 

 

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:

05.png 

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

06.png

 

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:

 

elbruno_1-1699984823407.png

 

The installation should finish without any issues:

 

elbruno_52-1699983570923.png

 

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

 

 

elbruno_53-1699983592241.png

 

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

 

export DOTNET_ROOT=$HOME/.dotnet

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

elbruno_54-1699983616512.png

 

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: 

 

elbruno_55-1699983636376.png

 

.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.

elbruno_56-1699983661852.png

 

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

elbruno_57-1699983677576.png

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:

 

elbruno_58-1699983713516.png

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:

elbruno_59-1699983735820.png

 

elbruno_60-1699983746928.png

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:

elbruno_61-1699983769152.png

 

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

elbruno_62-1699983781684.png

 

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.

 

 

elbruno_63-1699983799845.png

 

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

 

 

elbruno_64-1699983812205.png

 

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

elbruno_65-1699983829910.png

 

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

 

elbruno_66-1699983852399.png

 

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.

elbruno_67-1699983865057.png

 

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

elbruno_68-1699983896466.png

 

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.

 

 

elbruno_69-1699983914694.png

 

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.

elbruno_70-1699983929718.png

 

Step 5 – Install Visual Studio Code

 

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

elbruno_71-1699983953499.png

 

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.

elbruno_72-1699983967053.png

 

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.

elbruno_73-1699983987520.png

 

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

elbruno_74-1699984002322.png

 

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

 

elbruno_75-1699984019309.png

 

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.

elbruno_76-1699984034534.png

 

Step 8 – Create a .NET MAUI app

 

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

elbruno_77-1699984053376.png

 

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

elbruno_78-1699984065052.png

 

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.

elbruno_79-1699984076177.png

 

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

elbruno_80-1699984086212.png

 

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

elbruno_81-1699984097105.png

 

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

elbruno_82-1699984108282.png

 

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.

 

 

elbruno_83-1699984118173.png

 

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

elbruno_84-1699984127211.png

 

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:

elbruno_85-1699984144838.png

 

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

elbruno_86-1699984155548.png

 

Select Set Android SDK path.

elbruno_87-1699984164016.png

 

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

 

elbruno_88-1699984174380.png

 

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! 

 

elbruno_90-1699984220478.png

 

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:

elbruno_91-1699984238920.png

 

 

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.

elbruno_92-1699984254692.png

 

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.

 

 

elbruno_93-1699984266852.png

 

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!

 

 

elbruno_94-1699984275934.png

 

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!

 

Step 12 – Build and test your app on an Android device

 

Click again on Run and Debug.

elbruno_95-1699984293235.png

 

However, this time VS Code will not stop at the building step. It will actually install the app on your device, so you can test it there.

elbruno_96-1699984308761.png

 

You can also add breakpoints and examine your app of course!

elbruno_97-1699984318945.png

 

This setup took some time, but now you are ready to build amazing mobile apps on Linux (or any OS) using .NET MAUI.

 

Best!

Luis Beltran

Bruno Capuano

 

Resources 

10 Comments
Co-Authors
Version history
Last update:
‎Nov 14 2023 10:04 AM
Updated by: