This document explains the different ways to compile the Microsoft.Maui.ManualTests project, which is designed to work with multiple compilation modes depending on your development scenario. It also covers testing procedures, including using nightly builds, bug handling, and reporting.

The project uses conditional compilation based on MSBuild properties to support three different compilation modes:

1. Source Code Mode (Default, UseMaui != 'true') - Compiles against MAUI source code
2. MAUI Workloads Mode - Uses installed MAUI workloads
3. NuGet Packages Mode - Uses specific MAUI NuGet packages

• You're working on the MAUI source code itself
• You need to test changes in MAUI framework components
• You're contributing to the MAUI repository

• Complete MAUI source code repository cloned locally
• .NET SDK that matches the MAUI development requirements
• All MAUI source dependencies available in the solution

This is the default mode when building within the MAUI repository context (no special properties needed, as UseMaui evaluates to != 'true' by default).

dotnet build -p:UseMaui=false

Add this property to your project file temporarily:

<PropertyGroup>
    <UseMaui>false</UseMaui>
</PropertyGroup>

Create a Directory.Build.props file in the solution root:

<Project>
    <PropertyGroup>
        <UseMaui>false</UseMaui>
    </PropertyGroup>
</Project>

When UseMaui != 'true', the project:

• References local project files instead of NuGet packages
• Uses ProjectReference elements for:
  • Core.csproj
  • Controls.Xaml.csproj
  • Controls.Core.csproj
  • Microsoft.AspNetCore.Components.WebView.Maui.csproj
  • Compatibility.csproj (if enabled)
  • Controls.Maps.csproj
  • Graphics.csproj
• Imports Maui.InTree.props for additional build configuration
• Includes Microsoft.Extensions.DependencyInjection as a direct dependency

• Standard app development scenario
• You want to use the officially released MAUI version
• You're building apps that will be distributed to end users

• .NET SDK with MAUI workload installed
• Visual Studio 2022 with MAUI workload, or
• .NET CLI with MAUI workload installed

# Install latest stable MAUI workload
dotnet workload install maui

1. Open Visual Studio Installer
2. Modify your Visual Studio installation
3. Check ".NET Multi-platform App UI development"
4. Install/Update

This mode requires explicitly setting UseMaui=true and specifying MauiVersion to match your installed workload version:

# Standard build (replace <version> with your installed workload version, e.g., 10.0.0)
dotnet build -p:UseMaui=true -p:MauiVersion=<version>

# Restore packages first (recommended)
dotnet restore -p:UseMaui=true -p:MauiVersion=<version>
dotnet build -p:UseMaui=true -p:MauiVersion=<version>

# Build for specific platform
dotnet build -p:UseMaui=true -p:MauiVersion=<version> -f net10.0-android
dotnet build -p:UseMaui=true -p:MauiVersion=<version> -f net10.0-ios

dotnet workload search maui

# Example: Install .NET 9 preview workload  
dotnet workload install maui --version 9.0.100-preview.1

dotnet workload update

• You want to use a specific version of MAUI different from your workload
• Testing against multiple MAUI versions
• CI/CD scenarios where you need version control
• Working with preview/beta versions

• .NET SDK (MAUI workload not strictly required)
• Access to NuGet feeds containing MAUI packages

We will only be testing with the latest nightly build MAUI controls package. Add this feed to your local NuGet.config. Typical locations for NuGet.config:

• Windows: %AppData%\NuGet\NuGet.config (e.g., C:\Users\<username>\AppData\Roaming\NuGet\NuGet.config)
• macOS/Linux: ~/.nuget/NuGet/NuGet.config

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="maui-nightly" value="https://pkgs.dev.azure.com/xamarin/public/_packaging/maui-nightly/nuget/v3/index.json" />
  </packageSources>
</configuration>

Navigate to the Microsoft.Maui.Controls package on the nightly feed (or use tools like NuGet Package Explorer or browse the feed's index) to find the latest version (e.g., 8.0.0-nightly.8832+sha.feb791fc7-azdo.8163102). Open the .csproj for the project being tested and replace the package versions for Microsoft.Maui.Controls and Microsoft.Maui.Controls.Compatibility:

<ItemGroup Condition="$(MajorFrameworkVersion) >= 8.0">
    <PackageReference Include="Microsoft.Maui.Controls" Version="8.0.0-nightly.8832+sha.feb791fc7-azdo.8163102" />
    <PackageReference Include="Microsoft.Maui.Controls.Compatibility" Version="8.0.0-nightly.8832+sha.feb791fc7-azdo.8163102" />
</ItemGroup>

Note: you can also set the values to $(MauiVersion) and set a <MauiVersion> node with the version you want to use. See Method 2, below.

This mode is similar to Workloads Mode but allows specifying any available NuGet version for MauiVersion. It requires setting UseMaui=true.

You will need to manually add the target frameworks to the <TargetFrameworks> node when you use this method. For example, running the project on iOS and Android will require:

<!-- Instead of: <TargetFrameworks>$(MauiManualTestsPlatforms)</TargetFrameworks> do the line below -->
<TargetFrameworks>net10.0-ios;net10.0-android</TargetFrameworks>

Depending on the .NET version you want to use, replace net10.0 prefix with the version you want to use, for example: net9.0.

dotnet build -p:UseMaui=true -p:MauiVersion=8.0.0-nightly.8832+sha.feb791fc7-azdo.8163102

<PropertyGroup>
    <UseMaui>true</UseMaui>
    <MauiVersion>8.0.0-nightly.8832+sha.feb791fc7-azdo.8163102</MauiVersion>
</PropertyGroup>

Note: make sure to add the <UseMaui>true</UseMaui> tag before the first node that has a condition that checks for this value.

When UseMaui == 'true', the project:

• Uses PackageReference instead of ProjectReference
• References these NuGet packages:
  • Microsoft.Maui.Controls.Maps
  • Microsoft.Maui.Controls.Compatibility
• Uses the version specified in $(MauiVersion) property
• Core MAUI dependencies are resolved via the SDK or NuGet, depending on the context

<PropertyGroup>
    <UseMaui>true</UseMaui>
    <MauiVersion>10.0.0</MauiVersion>
</PropertyGroup>

<PropertyGroup>
    <UseMaui>true</UseMaui>
    <MauiVersion>10.0.0-preview.7.25406.3</MauiVersion>
</PropertyGroup>

# Search for available versions
nuget list Microsoft.Maui.Controls -AllVersions -PreRelease

Find-Package Microsoft.Maui.Controls -AllVersions -IncludePrerelease

You do NOT need to remove the conditional ItemGroups from the project file. These are intentionally designed to work automatically based on the UseMaui property:

<!-- These ItemGroups are CONDITIONAL and switch automatically -->
<ItemGroup Condition=" '$(UseMaui)' != 'true' ">
  <!-- Used ONLY in Source Code Mode -->
  <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
</ItemGroup>

<ItemGroup Condition=" '$(UseMaui)' != 'true' ">
  <!-- Used ONLY in Source Code Mode - ProjectReferences to local source -->
  <ProjectReference Include="..\..\..\Core\src\Core.csproj" />
  <ProjectReference Include="..\..\src\Xaml\Controls.Xaml.csproj" />
  <ProjectReference Include="..\..\src\Core\Controls.Core.csproj" />
  <!-- ... other project references ... -->
</ItemGroup>

<ItemGroup Condition=" '$(UseMaui)' == 'true' ">
  <!-- Used ONLY in NuGet Package Mode -->
  <PackageReference Include="Microsoft.Maui.Controls.Maps" Version="$(MauiVersion)" />
  <PackageReference Include="Microsoft.Maui.Controls.Compatibility" Version="$(MauiVersion)" />
</ItemGroup>

• Source Code Mode (UseMaui != 'true'): Uses ProjectReferences and Microsoft.Extensions.DependencyInjection
• Workload/NuGet Mode (UseMaui == 'true'): Uses specific MAUI NuGet packages for add-ons; core dependencies are handled by the SDK or NuGet
• The project automatically switches between these modes without any manual changes to the ItemGroups.

The project supports multiple target frameworks based on $(MauiManualTestsPlatforms):

• net10.0-android - Android applications
• net10.0-ios - iOS applications
• net10.0-maccatalyst - macOS Catalyst applications
• net10.0-windows10.0.17763.0 - Windows applications
• net10.0-tizen - Tizen applications

# Android
dotnet build -f net10.0-android

# iOS (requires macOS)
dotnet build -f net10.0-ios

# Windows
dotnet build -f net10.0-windows10.0.17763.0

# All platforms
dotnet build

• Android SDK 21+ (as specified in SupportedOSPlatformVersion)
• Java 11 or higher

• macOS development machine
• Xcode with iOS 15.0+ SDK
• Valid Apple Developer account for device deployment

• Windows 10 version 1809 (build 17763) or higher
• Windows App SDK

Please file ALL bugs here: https://github.com/dotnet/maui/issues. Make sure to tag any regressions with the i/regression label.

Please disable tests for any bugs which are not regressions. This can be accomplished by setting the state of the Test Case to Design. Please also leave a comment with a link to the issue. Make sure to track the filed issue so that the test can be reactivated in the future.

Solution: Clear NuGet cache and restore:

dotnet nuget cache clear --all
dotnet restore --no-cache

Solution: Install or update MAUI workload:

dotnet workload install maui

Solution: Check platform-specific requirements and ensure proper SDKs are installed.

# Verify .NET SDK
dotnet --version

# List installed workloads
dotnet workload list

# Check project target frameworks
dotnet list reference

# Clean and rebuild
dotnet clean
dotnet restore
dotnet build

1. Use Source Code Mode only when working on MAUI framework itself
2. Use Workload Mode for standard app development
3. Use NuGet Mode for testing specific versions or CI/CD scenarios
4. Always restore packages before building: dotnet restore
5. Keep workloads updated regularly: dotnet workload update
6. Pin specific versions in production scenarios
7. Test across multiple platforms