Installing .NET MAUI on Windows
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
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.
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
and run the MAUI-Check tool
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.
- 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:
and restore the NuGet packages:
Open and Run the MAUI App
To view and run the code of a MAUI app there are two main options:
- Open the code in Visual Studio Code and run it using Terminal commands
- Open and run the code in Visual Studio 2022 for Mac Preview
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.
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.