.NET MAUI im Überblick

Die Kladde läuft nach K2 im Browser. Dieser Kurs gibt ihr eine zweite Oberfläche: eine App für Telefon und Desktop, geschrieben mit C# und XAML, aus einer einzigen Codebasis. Das Werkzeug dafür heißt .NET MAUI. Diese Lektion klärt, was es ist und was es nicht ist, richtet Ihren Rechner ein und startet die Vorlage auf einem Android-Emulator und unter Windows. Am Ende liegt src/Kladde.App neben den Projekten aus K2, und Sie haben mit Hot Reload gesehen, wie schnell man in diesem Projekttyp eine Oberfläche ändern kann.

Der Kurs setzt K2 voraus: C# und async, die Web-API der Kladde mit ihrer Anmeldung, die Buchungsansicht als Blazor-Komponente und xUnit. Das wiederholt dieser Kurs nicht. Wo er darauf aufbaut, steht ein Verweis.

Was .NET MAUI ist

.NET Multi-platform App UI, kurz .NET MAUI, ist ein Rahmenwerk für native Apps für Mobilgeräte und Desktop mit C# und XAML. Aus einer gemeinsamen Codebasis entstehen Apps für Android, iOS, macOS und Windows. Es ist quelloffen und die Weiterentwicklung von Xamarin.Forms, vom Mobilen auf den Desktop erweitert, mit Steuerelementen, die von Grund auf neu gebaut wurden.

Wichtig für das Verständnis ist, was MAUI nicht tut: Es zeichnet keine eigene Oberfläche, die überall gleich aussieht. Ihr Code spricht mit der Schicht der MAUI-Steuerelemente, und diese Schicht benutzt die Steuerelemente der jeweiligen Plattform. Bei Bedarf kann Ihr Code auch die Plattform direkt aufrufen. Darunter liegt die .NET-Klassenbibliothek, die für alle Plattformen dieselbe ist; deshalb lassen sich Fachlogik, Tests und Modelle teilen.

Für Android, iOS und macOS ist die Laufzeit nach Learn Mono, für Windows die .NET-Core-CLR. Für diesen Kurs genügt, dass Sie auf Android und Windows üben und dieselbe Oberfläche auf beiden sehen.

Was MAUI mitbringt

• Steuerelemente, um Daten anzuzeigen, Aktionen auszulösen, Sammlungen darzustellen und Werte zu wählen,
• eine Layout-Engine und mehrere Seitentypen, darunter die Shell für die Navigation,
• Datenbindung, die Sie in W2.2.1 für MVVM brauchen,
• plattformübergreifende Schnittstellen für Gerätefunktionen: Sensoren, Netzstatus, Geräteinformationen, Zwischenablage, Dateiauswahl, sicher gespeicherte Schlüssel-Wert-Paare, Sprachausgabe und Anmeldeabläufe im Browser, die bei einer App-Adresse zurückkehren,
• ein Zeichenfeld für eigene Grafik,
• ein Projekt für alle Plattformen und Hot Reload.

Die Schnittstellen für Netzstatus und sichere Speicherung benutzen Sie in W2.2.2.

Für wen und wofür

Learn nennt drei Gründe für MAUI: Sie schreiben plattformübergreifende Apps in XAML und C# aus einer Codebasis, Sie teilen Layout und Gestaltung, und Sie teilen Code, Tests und Fachlogik. Für die Kladde heißt das: Die Regeln, die Sie in K1 und K2 schon haben, bleiben C#. Neu ist die Oberfläche.

Was MAUI in diesem Kurs nicht ist

• Keine Schule für iOS. Für iOS braucht es einen Mac im Netz; der Kurs beschreibt den Weg, die Übungen laufen auf Android und Windows.
• Keine Spieleentwicklung.
• Keine Einführung in C# oder in Entra ID. Beides bringen Sie aus K0 bis K2 mit.
• Keine zweite Webseite. Wer Webtechnik in der App nutzen will, bekommt in W2.3.1 Blazor Hybrid.

Plattformgrenzen: was MAUI in .NET 10 braucht

Auf Microsoft Learn steht für .NET 10 folgende Mindestausstattung der Ziele:

Apps mit Blazor in MAUI (W2.3) haben strengere Grenzen: Android 7.0 (API 24), iOS 16.4 und macOS 12, dazu eine aktuelle WebView der Plattform. Samsung liefert zusätzlich eine Unterstützung für Tizen; sie ist nicht Teil dieses Kurses.

Zwei Dinge sollten Sie schon jetzt mitnehmen. Erstens: Die Vorlagen von .NET 10 setzen für Android den Wert SupportedOSPlatformVersion auf 24 statt 21. API 21 wird weiter unterstützt; Learn empfiehlt aber, bestehende Projekte auf 24 zu heben, damit Abstürze durch fehlende Java-Funktionen ausbleiben. Zweitens: Für .NET 11 nennt Learn als Mindestwert für Android die API 24. Der Kurs bleibt bei .NET 10, die Zahl ist nur ein Ausblick.

Welche Versionen von Xcode, Android-SDK, JDK und Windows App SDK zu einer MAUI-Version passen, ändert sich mit jeder Ausgabe. Learn verweist dafür auf die Tabelle „Release versions“ im GitHub-Wiki von dotnet/maui. Dieser Kurs nennt deshalb keine Nummern. Schlagen Sie vor dem Einrichten dort nach.

Werkzeuge

Sie haben zwei Wege, und beide sind in Ordnung:

Ihr Betriebssystem bestimmt, was Sie bauen können (Visual Studio erreicht iOS von Windows aus über einen Mac im Netz):

Apps für iOS und Mac Catalyst bauen, signieren und installieren Sie nur auf einem Mac mit passender Xcode-Version. Mit einer Apple-ID und der Mitgliedschaft im Apple Developer Program lassen sich Geräte bespielen und Apps in den Store bringen. Für Debug-Builds gibt es von Windows aus „Hot Restart“ auf ein iOS-Gerät; auch das setzt die kostenpflichtige Mitgliedschaft voraus. Learn nennt für Mac Catalyst nur Visual Studio Code als Werkzeug zum Starten und Debuggen. Das sind die Gründe, warum dieser Kurs iOS beschreibt, aber nicht übt.

Der Workload

Das Rahmenwerk kommt in .NET 10 als .NET-Workload und als mehrere NuGet-Pakete. Der Vorteil: Sie können ein Projekt an eine bestimmte Version binden und Vorabversionen leicht ausprobieren. Ohne Visual Studio installieren Sie ihn so:

dotnet workload install maui

Unter Windows und macOS erscheint danach in der Liste der Workload maui:

dotnet workload list

Haben Sie ihn mit dem Visual-Studio-Installer eingerichtet, stehen dort stattdessen android, maui-windows, maccatalyst und ios. Unter macOS braucht der erste Befehl sudo; unter Linux heißt der Workload maui-android.

Android einrichten

Für Android brauchen Sie das Java-SDK, das Android-SDK und einen Emulator. Mit Visual Studio übernimmt das der erste Start einer Android-App: Es lädt das Standard-SDK, legt einen virtuellen Android-Geräte-Eintrag an (AVD) und fragt mehrmals nach den Lizenzen. Bestätigen Sie sie nur, wenn Sie sie gelesen haben.

Mit Visual Studio Code gibt es mehrere Wege. Der empfohlene benutzt ein MSBuild-Ziel, das die Abhängigkeiten selbst installiert, wenn Sie ein Projekt haben:

dotnet new maui -n "MeineApp"
cd MeineApp
dotnet build -t:InstallAndroidDependencies -f:net10.0-android -p:AndroidSdkDirectory="C:\Android\Sdk" -p:AcceptAndroidSDKLicenses=True

Learn zeigt dieses Beispiel mit net9.0-android. Für .NET 10 heißt die Zielplattform net10.0-android. Der Pfad zum SDK sollte weder Leerzeichen noch Nicht-ASCII-Zeichen enthalten. Mit -p:AcceptAndroidSDKLicenses=True erklären Sie, dass Sie die Lizenzen angenommen haben. Der Pfad C:\Android\Sdk ist hier nur ein Beispiel.

Die Erweiterung für Visual Studio Code prüft die Umgebung mit dem Befehl .NET MAUI: Configure Android und der Auswahl Refresh Android environment. Sie sucht JAVA_HOME und ANDROID_HOME; Learn empfiehlt, beide Umgebungsvariablen zu setzen. Welche Version des JDK passt, steht nicht einheitlich in Learn: Die Installationsseite nennt das Microsoft Build of OpenJDK 17, die Seite zu den Neuerungen in .NET 10 sagt, dass .NET für Android jetzt auch mit JDK 21 baut. Maßgeblich ist die Tabelle „Release versions“.

Ein Emulator läuft nur schnell, wenn die Hardwarebeschleunigung eingeschaltet ist. Learn warnt ausdrücklich, dass er sonst sehr langsam läuft. Unter Windows auf ARM (zum Beispiel Surface Pro X) läuft der Android-Emulator nicht, weil er x64 braucht; dort nehmen Sie ein echtes Gerät per USB. Der Emulator hat keine virtuelle Hardware für Bluetooth, NFC, SD-Karte, Kopfhörer und USB.

Windows als Ziel

Windows als Ziel braucht keinen Emulator: Die App läuft als Fenster auf dem Rechner, auf dem Sie entwickeln. Ein neues MAUI-Projekt wird nach Learn standardmäßig als unverpackte App bereitgestellt. Für verpackte Apps (MSIX) muss der Entwicklermodus von Windows eingeschaltet sein: Einstellungen, Datenschutz und Sicherheit, „Für Entwickler“ (Windows 11), dort „Entwicklermodus“. Das Einschalten verlangt Administratorrechte und kann auf Geräten einer Firma gesperrt sein. Fragt Visual Studio beim Bauen nach dem Entwicklermodus, folgen Sie dem Link zu den Einstellungen für Entwickler. Die Bezeichnungen der Einstellungsseiten ändern sich zwischen Windows-Versionen.

Die Vorlage anlegen

Auf der Kommandozeile erzeugt dotnet new maui ein Projekt mit XAML-Oberfläche. Das ist der kürzeste Weg, und er sieht in beiden Werkzeugen gleich aus:

dotnet new maui -n Kladde.App -o src\Kladde.App

Mit Visual Studio wählen Sie Create a new project, filtern auf MAUI, nehmen die Vorlage .NET MAUI App, geben Namen und Ort an und wählen die .NET-Version. Mit Visual Studio Code ist es Create .NET Project (oder .NET: New Project… in der Befehlspalette) und die Vorlage .NET MAUI App; das Projekt muss in einem leeren Ordner entstehen.

Lassen Sie sich vom Namen nicht stören: Kladde.App ist der Projektname und zugleich der Standard-Namensraum der Klassen.

Was die Vorlage anlegt

Learn nennt vier wichtige Codedateien:

Dazu kommen die Ordner Platforms und Resources. Beginnen Sie mit der Einstiegsklasse:

namespace MyMauiApp;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>();

        return builder.Build();
    }
}

So sieht die kleinste mögliche Fassung aus. Die Vorlage hängt weitere Zeilen an den Builder, zum Beispiel für Schriften. Jede Plattform ruft CreateMauiApp auf und bekommt eine MauiApp zurück. Es gibt also genau einen Einstieg, auch wenn vier Plattformen starten. Registrierungen für Dependency Injection kommen später dazu, in W2.2.1.

Die Klasse App leitet von Application ab und erzeugt das Fenster:

namespace MyMauiApp;

public class App : Application
{
    public App()
    {
        InitializeComponent();
    }

    protected override Window CreateWindow(IActivationState? activationState)
    {
        return new Window(new AppShell());
    }
}

AppShell ist eine von Shell abgeleitete Klasse, die die sichtbare Gliederung der App beschreibt. Die Seite der Vorlage, MainPage, leitet von ContentPage ab. Beim Start läuft die Kette: MauiProgram baut die App, der Konstruktor von App entsteht, CreateWindow erzeugt AppShell, und AppShell zeigt MainPage. Dessen Konstruktor ruft InitializeComponent, das die Objekte aus der XAML-Datei anlegt, sie zu einem Baum verbindet und als Inhalt der Seite setzt.

Vor .NET 9 stand in App stattdessen eine Zuweisung an MainPage. Wenn Sie ältere Beispiele finden, die MainPage = new AppShell(); schreiben, ist das die alte Form. Mit .NET 10 gilt CreateWindow.

Ein Projekt, mehrere Plattformen

MAUI arbeitet mit einem Projekt: einem SDK-Projekt, das mehrere Zielplattformen anspricht (Multi-Targeting). Das bringt Learn so auf den Punkt: ein gemeinsames Projekt für alle Plattformen, eine vereinfachte Auswahl des Ziels zum Starten, gemeinsame Ressourcedateien, ein einziges Manifest mit Titel, ID und Version der App, Zugriff auf plattformspezifische Schnittstellen, und ein gemeinsamer Einstieg.

Der Ordner Platforms hat je Plattform einen Unterordner mit den plattformspezifischen Ressourcen und dem Code, der die App dort startet. Beim Bauen für Android gehen nur die Dateien aus Platforms\Android in das Paket, nicht die der anderen. Wo Sie plattformeigenen Code brauchen, nutzen Sie partielle Klassen oder die bedingte Kompilierung:

#if ANDROID
                  handler.PlatformView.SetBackgroundColor(Colors.Red.ToPlatform());
#elif IOS
                  handler.PlatformView.BackgroundColor = Colors.Red.ToPlatform();
                  handler.PlatformView.BorderStyle = UIKit.UITextBorderStyle.Line;
#elif WINDOWS
                  handler.PlatformView.Background = Colors.Red.ToPlatform();
#endif

Dieses Beispiel aus Learn setzt die Hintergrundfarbe eines Steuerelements: Jede Plattform hat dafür ihren eigenen Aufruf. In diesem Kurs brauchen Sie solchen Code nicht; er zeigt nur, dass der Weg zur Plattform offen bleibt.

Der Ordner Resources enthält die gemeinsamen Ressourcen. Jede Bilddatei dient als Quelle, aus der beim Bauen die Auflösungen der Plattformen erzeugt werden. Welche Ordner gelten, stellt die Projektdatei ein; die Aktion ergibt sich aus dem Ordner:

<ItemGroup>
    <!-- Images -->
    <MauiImage Include="Resources\Images\*" />

    <!-- Fonts -->
    <MauiFont Include="Resources\Fonts\*" />

    <!-- Raw assets -->
    <MauiAsset Include="Resources\Raw\*" />
</ItemGroup>

XAML-Dateien bekommen automatisch die Aktion MauiXaml. Eine plattformeigene Ressource, etwa ein Bild in Platforms\Android\Resources\drawable-xhdpi, gewinnt gegen die gemeinsame. Titel, ID und Version der App stehen in einem Ort und werden beim Bauen mit dem Manifest jeder Plattform zusammengeführt; in Visual Studio finden Sie sie unter den Eigenschaften des Projekts bei MAUI Shared.

Was neu ist in .NET 10

Die Seite „What’s new in .NET MAUI for .NET 10“ ist lang. Für Ihre Arbeit zählt Folgendes. Die Liste zeigt außerdem, was Sie in alten Tutorials nicht mehr nachbauen sollten:

Die Zeile zur Android-API 36 hatte bei den Vorabversionen eine Falle: Visual Studio und Visual Studio Code kannten die Version noch nicht und meldeten den Fehler XA5207. Ob das mit Ihrer Werkzeugversion noch eine Rolle spielt, sehen Sie am Fehlertext.

Android-Apps starten Sie damit auch auf der Kommandozeile, wenn ein Emulator läuft:

dotnet run -f net10.0-android -p:AdbTarget=-e

Learn zeigt dotnet run -p:AdbTarget=-e ohne -f. Ein MAUI-Projekt hat mehrere Zielplattformen; -f ist die Option von dotnet run, die eine auswählt.

Starten: Emulator und Windows

Visual Studio. Wählen Sie in der Symbolleiste im Menü Debug Target die Android-Emulatoren und einen Eintrag, oder Windows Machine. Beim ersten Android-Start richtet Visual Studio SDK und Emulator ein (siehe oben). Die Vorlage hat die Schaltfläche Click me; jedes Drücken erhöht einen Zähler.

Visual Studio Code. Prüfen Sie zuerst die Umgebung (.NET MAUI: Configure Android, dann Refresh Android environment). In der Statusleiste unten stellt ein Klick auf die geschweiften Klammern { } das Debug Target ein; die Befehle .NET MAUI: Pick Android Device und .NET MAUI: Pick Windows Device tun dasselbe. Gestartet wird mit F5 oder der Schaltfläche Run. Fragt Visual Studio Code nach einem Debugger, wählen Sie C# und die Startkonfiguration Ihres Projekts.

iOS und Mac, beschrieben. Mit Visual Studio unter Windows koppeln Sie einen Mac als Build-Host (Pair to Mac). Danach wählen Sie als Ziel einen iOS-Simulator; Visual Studio baut, startet den „Remote iOS Simulator for Windows“ und installiert die App dort. Auf dem Mac selbst arbeiten Sie mit Visual Studio Code, wählen .NET MAUI: Pick iOS Device und starten mit F5. Für ein echtes iOS-Gerät brauchen Sie die Apple-ID in Xcode, einen eingeschalteten Entwicklermodus auf dem Gerät und, im Developer Program, die Registrierung des Geräts im Team.

Fehler, die oft sind

Für alles, was hier nicht steht, führt die Seite „Troubleshooting known issues“ in der MAUI-Dokumentation weiter.

Hot Reload

Hot Reload ist der Grund, warum die Arbeit an einer App angenehm sein kann. Zwei Arten gibt es:

• .NET Hot Reload wendet Änderungen an C#-Code an, während die App läuft, ohne neu zu bauen und ohne dass Sie anhalten oder einen Haltepunkt erreichen müssen.
• XAML Hot Reload wendet gespeicherte oder getippte Änderungen an XAML an. Der Zustand der Navigation und die Daten bleiben erhalten, weil die Seite nicht neu aufgebaut wird; nur die geänderten Eigenschaften werden gesetzt.

Voraussetzungen und Grenzen nach Learn:

Learn nennt außerdem als Fehlerquelle, wenn Hot Reload ohne Meldung nichts tut: Alle .cs-Dateien müssen als UTF-8 mit BOM gespeichert sein. Dateien ohne BOM, wie viele Editoren sie unter Linux oder macOS erzeugen, können dazu führen, dass XAML Hot Reload still versagt. In Visual Studio Code stellen Sie das in der Statusleiste mit Save with Encoding ein. Die Ausgabe des Hot-Reload-Fensters (in Visual Studio unter View, Output, Hot Reload) zeigt Statusmeldungen.

cd MauiProbe
dotnet run -f net10.0-android -p:AdbTarget=-e

Die Kladde: eine App neben der Webanwendung

Mit dieser Lektion hat die Kladde ein neues Projekt: src/Kladde.App, eine App, die auf Android und Windows startet und noch die Seite der Vorlage zeigt. Die Projekte aus K2 (Kladde.Core, Kladde.Data, Kladde.Web und die übrigen) ändern Sie nicht. Die App wird die Web-API der Kladde nutzen, ab W2.2.2, und die Regeln der Kladde bleiben dort, wo sie sind. In W2.1.2 bauen Sie die ersten eigenen Seiten: eine Kontaktliste und die Termine des Tages, noch mit festen Beispieldaten im Code.

Was Sie jetzt können

• Sie erklären, was .NET MAUI ist, wie die vier Plattformen angesprochen werden und was nach Learn in .NET 10 mindestens vorausgesetzt ist.
• Sie richten Workload, Android-SDK, Emulator und Windows als Ziel ein und wissen, was für iOS fehlt: ein Mac im Netz.
• Sie ordnen MauiProgram, App, AppShell, Platforms und Resources zu und wissen, wo plattformeigener Code steht.
• Sie starten die App auf einem Android-Emulator und unter Windows und nutzen Hot Reload, mit seinen Grenzen.
• Sie kennen die Neuerungen und Abkündigungen von .NET 10, die in älteren Tutorials noch anders stehen, und haben Kladde.App angelegt.

Weiterlesen

• What is .NET MAUI?: was MAUI ist, die Architektur und was es bietet.
• Supported platforms for .NET MAUI apps: Mindestversionen je Plattform.
• Installation: Visual Studio, Visual Studio Code, Workload, Android und Apple.
• Build your first app: die Vorlage Schritt für Schritt für Android, iOS, Mac und Windows.
• Target multiple platforms from .NET MAUI single project: Ressourcen, Manifest, Platforms-Ordner, Einstieg.
• Deploy and debug your .NET MAUI app on Windows: Entwicklermodus, verpackt und unverpackt.
• XAML Hot Reload for .NET MAUI: Einstellungen, Grenzen und Fehlersuche.
• What’s new in .NET MAUI for .NET 10: alle Änderungen und Abkündigungen.
• Release versions: welche Versionen von Xcode, Android-SDK, JDK und Windows App SDK zu welcher MAUI-Version gehören.