GRIP

MAUI Developer

How to contribute

WORKING DOCUMENT!!

This project is currently ongoing, and this document will be regularly updated. Last update: 15-10-2023

Building and Integrating .NET MAUI from Source (On windows)

This guide outlines the steps to build and run the .NET MAUI repository from source and integrate it into your own application on Windows. Please note that this document is a work in progress and may undergo further revisions.

Platform Compatibility: The steps have been tested on Windows 11.

PREREQUISITES

Before you begin, ensure you have the following prerequisites in place:

  • Windows 11 on a PC
  • Latest version of Visual Studio 22 Preview
  • GIT
  • Android SKD's

TODO: Determine the optimal Mac setup. I have one Mac running MacOS Ventura and another with Sonoma (the latest version, though not yet officially supported by Visual Studio).

Preperation

Source Code

Before integrating MAUI into your application, you need to have the source code at hand. Follow these steps:

  1. Go to https://github.com/dotnet/maui and fork the project to your GitHub account by clicking the "Fork" button.
  2. Clone the project to your local workstation.
  3. Set up the upstream repository.
  4. Validate the upstream setup.
Example of cloning the project to your workstation:
cd  c:
cd mkdir src
cd src
git clone git@github.com:USERNAME/maui.git

Result: c:\src\maui

Note: I recommend maintaining a short folder structure on the C: drive due to Windows 11's path length limitations. Windows 10 allows disabling short path lengths, but this feature is buggy in Windows 11. This can lead to complications, particularly when working with certain packages like Plugin.Firebase, which may generate numerous compilation errors on Windows 11.

Example of setting up the upstream repository:
git remote add upstream https://github.com/dotnet/maui.git
Example of validating the upstream setup:
git remote -v

Update Your Source with Latest Code from Upstream

Make it a regular practice to keep your source code up to date with the latest changes from the upstream repository.

Example:
git checkout main
git fetch upstream
git merge upstream/main

Environment Variables

To inform the tooling and scripts about the location of the Android SDK on a Windows system, create an environment variable following these steps:

  1. Go to environment variables
  2. Add a user variable for your user
    • Variable: ANDROID_HOME
    • Value: LOCATION_OF_YOUR_SDK (e.g., C:\Android\Sdk)
  3. Reboot windows

Visual studio

Ensure that you have the necessary SDK installed in Visual Studio:

  1. Open Visual Studio Installer
  2. Select the Modify option for Visual Studio 2022 Preview.
  3. Navigate to the Individual Components tab and search for 20348.
  4. Select Windows 10 SDK 10.0.20348.0
  5. Click modify

Building

Next step is building the build tasks so the command like cake become available in dotnet.

  1. Open a terminal (PowerShell, CMD, or GitBash).
  2. Run the following dotnet commands in the git checkout directory.
Example:
cd c:
cd src/maui
dotnet tool restore
dotnet cake --target=VS --workloads=global

Troubleshooting

If you encounter an error while running the dotnet cake --target=VS --workloads=global command, such as:

FAILURE: Build failed with an exception.

  * What went wrong:
  Could not determine the dependencies of task ':maui:verifyReleaseResources'.  
  
  > SDK location not found. Define location with an ANDROID_SDK_ROOT environment variable or by setting the sdk.dir   path in your project's local properties file at 'C:\src\maui\src\Core\AndroidNative\local.properties'.
To fix this issue:

Open C:\src\maui\Microsoft.Maui-dev.sln This solution is automatically opened when dotnet cake --target=VS --workloads=global is finished. Ensure that the ANDROID_HOME environment variable (in Windows) points to the correct directory, such as C:\Android\Sdk. This directory is the root folder for all Android SDK-related components. After making this change, reboot your system.

Additional information: https://developer.android.com/tools/variables

Validation

Now, let's perform an initial validation to check if everything is functioning correctly. If Visual Studio is not open, launch it and open C:\src\maui\Microsoft.Maui-dev.sln

  1. Go to the menu build
  2. Click on build solution

Please note that on the first run, you may encounter output like "Build: 57 succeeded, 12 failed, 0 up-to-date, 0 skipped." The failed projects are likely sample or test projects, which may have the following error:

Error NETSDK1047 Assets file '<PROJECT_PATH>\obj\project.assets.json' doesn't have a target for 'net7.0-ios/ios-arm64'. Ensure that restore has run and that you have included 'net7.0-ios' in the TargetFrameworks for your project. You may also need to include 'ios-arm64' in your project's RuntimeIdentifiers.

Thanks to @vhugo for the solution, to resolve this issue, add the following snippet to the .csproj files of the affected projects:

<PropertyGroup Condition="'$(Configuration)|$(TargetFramework)|$(Platform)'=='Debug|net7.0-ios|AnyCPU'">
    <RuntimeIdentifier>ios-arm64</RuntimeIdentifier>
</PropertyGroup>

Please be aware that this modification may prevent running on simulators, requiring the use of a physical device.

Packaging

After verifying that everything is compilable, you can make changes to the source code. To create a new workload for use within your own application, use dotnet cake. Close visual studio and execute the following commands in a terminal

Example:
cd "c:\src\maui"
dotnet tool restore
dotnet cake --target=VS --pack --sln="c:\src\MyApp\MyApp.sln" --verbose

Replace c:\src\MyApp\MyApp.sln with the path to the solution of your application.

Result: Visual Studio will now open your application using the MAUI workloads you just build.

Build your application

From here on, you can develop your application and build it with the locally packaged MAUI workloads. The first time I wanted to build my application, I encountered a few errors. Refer to the Troubleshooting section below for solutions to potential issues.

Example:

cd "c:\src\maui"
dotnet tool restore
dotnet cake --target=VS --pack --sln="c:\src\MyApp\MyApp.sln" --verbose

Troubleshooting

Here are fixes for possible issues you may encounter while building your own application with your custom MAUI version:

Error messages

It is possible that you get the following message:

Error	XA1018	Specified AndroidManifest file does not exist: C:\src\MyApp\MyApp\AndroidManifest.xml.	C:\src\maui\bin\dotnet\packs\Microsoft.Android.Sdk.Windows\33.0.68\tools\Xamarin.Android.Common.targets	574

There appears to be an issue with locating the AndroidManifest.xml file in its expected location at Platforms\Android\AndroidManifest.xml for some unknown reason. Currently, I don't have a solution to address this problem (yet). However, a workaround to resolve these errors is to manually copy the Platforms\Android\AndroidManifest.xml to the suggested folder.

Missing android emulators

Upon launching Visual Studio using the dotnet cake command, I encountered a situation where some Android emulators were missing. However, after performing the file copy operation, the emulators reappeared in the list.

Dependencies (Exclamation mark)

Upon initiating Visual Studio with the dotnet cake command, you might notice an exclamation mark on the dependencies icon for net7.0-android33.0 and net7.0-ios. It's currently uncertain whether this is a normal occurrence, given that we started Visual Studio using a command and a custom MAUI workload package.

Specifically, the packages microsoft.Maui.Controls (7.0.100-dev) and microsoft.Maui.Controls.Compatibility (7.0.100-dev)

After copying the AndroidManifest.xml file and beginning the build process, you may encounter reference errors like:

Error	CS0246	The type or namespace name 'ContentPage' could not be found (are you missing a using directive or an assembly reference?)	MyApp (net7.0-android33.0), MyApp (net7.0-ios)	C:\src\MyApp\MyApp\MainPage.xaml.cs

These errors likely stem from the dependency issues indicated by the exclamation mark.

Additionally, you might encounter an error like this:

Build started...
NuGet package restore failed. Please see Error List window for detailed warnings and errors.
Error occurred while restoring NuGet packages: Object reference not set to an instance of an object.

To resolve these issues, start by clearing the NuGet package cache in Visual Studio:

  1. Navigate to the Tools menu
  2. Go to the NuGet Package Manager submenu
  3. Select Package Manager Settings
  4. In the options menu, click Clear All NuGET storage

Next, close Visual Studio and open Windows PowerShell to run the following command:

dotnet cake --target=VS --pack --sln="c:\src\MyApp\MyApp.sln" --verbose

Visual Studio reopens. Go to the PowerShell within visual studio and execute the following commands:

dotnet workload restore

Check if something like this is visible in the output 'Pack Microsoft.Maui.Sdk version 7.0.100-dev is already installed.' Then:

msbuild -t:restore
msbuild -t:build -restore
msbuild

TODO: Research why this is not working in wone command like msbuild -t:build -restore shoud have been enough. But for some reason it needs some extra persuation :'-)

.NET8.0

If you want to use .NET 8.0 for MAUI, just fetch the latest upstream/main branch! The main branch is now running on .NET 8. How can you confirm this? Simply navigate to the root folder and locate the file Directory.Build.props. In this file, search for the entry 'MauiDotNetVersionMajor,' and the value should be 8 as of the current version.

prerequisites

Make sure you have the latest version of Visual Studio 2022 Preview (I've tested it with Version 17.8.0 Preview 2.0).

Example:
cd "c:\src\maui"
git checkout main
git fetch upstream
git checkout -b MyFirstNet8MauiManualBuild upstream/main
git push -u origin

Switching from an older .NET7 bracnh

When managing multiple branches with varying .NET versions, switching between them can result in various issues. To ensure a smooth transition, it's essential to clean the bin/Obj folders and restore your tools.

Example:
cd "c:\src\maui"
git checkout MyBranchOnAnotherVersion
dotnet cake --clean
dotnet tool restore

Building

Building and using this branch follows the same process as described in the Build your application section above. You may need to perform an additional step: dotnet restore.

In PowerShell (outside of Visual Studio):

Example:
dotnet tool restore
dotnet cake --target=VS --workloads=global

Result: Visual Studio will open with Microsoft.Maui-windows.slnf loaded.

Then, in Visual Studio's PowerShell window:

Example:
dotnet workload restore
dotnet restore

Now you should be able to build the source. You might encounter two projects that don't build, but, for now, this doesn't seem to be a problem. If you want to use MAUI manually, close Visual Studio and run the following command in Windows PowerShell:

dotnet cake --target=VS --pack --sln="c:\src\MyApp\MyApp.sln" --verbose

Troubleshooting

I've encountered the error Unhandled exception: Microsoft.Build.Exceptions.InvalidProjectFileException: The imported project when running dotnet restore at the end. Fortunately, this error didn't cause any significant issues for me.

@TODO: I will investigate what this error is, determine whether it needs fixing, and explore potential solutions.

Read

dotnet restore

A .NET project typically references external libraries in NuGet packages that provide additional functionality. These external dependencies are referenced in the project file (.csproj or .vbproj). When you run the dotnet restore command, the .NET CLI uses NuGet to look for these dependencies and download them if necessary.

Extra information: https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-restore

dotnet tool restore

The dotnet tool restore command finds the tool manifest file that is in scope for the current directory and installs the tools that are listed in it.

Extra information: https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-tool-restore

Cake

Cake (C# Make) is a free and open source cross-platform build automation system with a C# DSL for tasks such as compiling code, copying files and folders, running unit tests, compressing files and building NuGet packages.

Extra information: https://cakebuild.net/

dotnet cake

Cake .NET Tool is a runner which allows to run Cake scripts.

Extra information https://cakebuild.net/docs/running-builds/runners/dotnet-tool

Handy commands

Show workloads: dotnet workload list Show installed dotnet SKD's: dotnet --list-sdks