Installing .NET MAUI Preview

Author

Vlad Antohi

Category

.NET MAUI

Date

09 / 11 / 2021

Installing .NET MAUI on Windows

On Windows you can install MAUI via the the Visual Studio Installer for Visual Studio 2022, and the instructions can be found here.

Once installed, you can create a new .NET MAUI app through the built-in Visual Studio templates for MAUI:

Installing .NET MAUI on macOS

Installing MAUI on macOS is a manual process at the moment, and the steps, based on James Montemagno’s video .NET MAUI Preview 7 – Full Windows & Mac Setup with CLI, VS Code, & Visual Studio 2022, are outlined below.

Install XCode 13

Install XCode 13 from the Apple App Store if you don’t have it installed already.

Install the .NET 6 SDK and Runtime

There are two options for installing the .NET 6 SDK, either through the Visual Studio for Mac 2022 Preview setup, or by manually installing it from here.

If you are choosing the manual option, install the x64 .NET SDK via the macOS x64 .pkg installer, which also includes the .NET 6 Runtime.

Note: On an M1 Mac it is currently necessary to install the x64 version of the .NET SDK and Runtime because there is some outstanding work left for the ARM64 versions, as discussed here.

Uninstall

If at some point in the future you want to uninstall a .NET SDK or Runtime, especially a preview version, you can do so via the .NET Uninstall Tool.

Here are some usage examples:

  • Remove a specific SDK version:
sudo ./dotnet-core-uninstall remove --sdk 6.0.100-rc.1.21463.6
  • Remove all preview runtimes:
sudo ./dotnet-core-uninstall remove --runtime --all-previews

To see which SDKs and runtimes you have installed on your computer, run the following commands in the Terminal app:

dotnet --list-sdks
dotnet --list-runtimes

Install and Run the Maui-Check Tool

To install the Maui-Check tool, run the following command in the Terminal app:

dotnet tool install -g redth.net.maui.check

Then navigate to the .NET tools folder

cd $HOME/.dotnet/tools

and run the MAUI-Check tool

./maui-check

which will give you the following output and guide you through setting up the MAUI prerequisites:

The MAUI-Check tool will verify that the iOS and Android requirements are met and that all the .NET components are in place.

Troubleshooting

  • If you see an error message saying that “Xcode.app (13 Beta 5) not installed”  you can ignore it because you would have already installed the official XCode 13 release in the first step, and the installation process will still work regardless.

  • If you are prompted to download the .NET SDK, type “n” because you would have already installed the correct SDK beforehand, and the tool might not download the version that works correctly for your setup.

  • If you see the error messages below regarding the workloads

you can resolve these by installing the MAUI workload manually:

sudo dotnet workload install maui
  • If you get the error message “command not found: dotnet” or “It was not possible to find any compatible framework version” then reinstall just the .NET 6 Runtime from here.

  • If you get an error message that says “killed ./maui-check” then uninstall and reinstall the MAUI-Check tool by running
dotnet tool uninstall -g redth.net.maui.check
dotnet tool install -g redth.net.maui.check
  • If you get an error message saying “Unhandled exception. System.BadImageFormatException: Could not load file or assembly '/usr/local/share/dotnet/sdk/6.0.100-rc.2.21505.57/dotnet.dll'. An attempt was made to load a program with an incorrect format” then that most likely means that you have installed the Arm64 version instead of the x64 version of the SDK and Runtime on your M1 Mac. Use the .NET Uninstall Tool to remove the ARM64 versions and then install the x64 versions.

Create a MAUI App

Once you have completed all the installation steps, you can now create a MAUI app via the dotnet command line tool:

dotnet new maui -n HelloMauiPreview

Then change the directory to the newly created folder:

cd HelloMauiPreview

and restore the NuGet packages:

dotnet restore

Open and Run the MAUI App

To view and run the code of a MAUI app there are two main options:

Running the App from Visual Studio Code

Open the solution folder in Visual Studio Code and in the command line panel execute the following commands to run the app on the different platforms:

dotnet build -t:Run -f net6.0-ios
dotnet build -t:Run -f net6.0-maccatalyst
dotnet build -t:Run -f net6.0-android

Running the App from Visual Studio 2022 for Mac Preview

You can open the solution in Visual Studio 2022 for Mac Preview and run the app on iOS, MacCatalyst, and Android, but there are currently a number of limitations and restrictions, for example, hot-reload is not yet supported, debugging only works partially, and you might get some errors and unexpected behaviors, but hopefully these will be resolved soon in the next preview versions.

Note: To run the app on an Android emulator on an M1 Mac, you need to install Android Studio from here and let the installation process create an ARM64-based emulator, which you can then use in Visual Studio.

Troubleshooting

To resolve the error message “'...project.assets.json' doesn't have a target for ...” you can add the following to your .csproj file:

<PropertyGroup Condition="$(TargetFramework.Contains('-maccatalyst'))">
    <RuntimeIdentifier>maccatalyst-x64</RuntimeIdentifier>
    <MtouchLink>SdkOnly</MtouchLink>
</PropertyGroup>

<PropertyGroup Condition="$(TargetFramework.Contains('-android'))">
    <RuntimeIdentifier>android-arm64</RuntimeIdentifier>
</PropertyGroup>

<PropertyGroup Condition="$(TargetFramework.Contains('-ios'))">
    <RuntimeIdentifier>iossimulator-x64</RuntimeIdentifier>
    <MtouchLink>SdkOnly</MtouchLink>
</PropertyGroup>

If the error message still occurs after applying the change above when switching deployment targets, the solution is to restart Visual Studio every time the error appears.

Leave a Reply