Comprehensive step-by-step guide to develop a cross-platform .NET MAUI

 

Step 1: Environment Setup

1.1 Install Prerequisites

• .NET SDK 8+ – Download here

• Visual Studio 2022/2025 with:

  • .NET MAUI workload

  • Android/iOS workloads (optional for mobile testing)

  • Desktop development with .NET

Open Visual Studio Installer → Modify → Check ".NET Multi-platform App UI development" → Install

1.2 Verify Installation

Open terminal or command prompt:

dotnet --version
dotnet workload list

---

 Step 2: Create a New MAUI App

Using CLI:

dotnet new maui -n MyMauiApp
cd MyMauiApp

Using Visual Studio:

• File → New → Project → "MAUI App" → Next

• Name your project → Choose folder → Create

---

Step 3: Understand the Project Structure

• MainPage.xaml / .cs – UI and code-behind

• App.xaml / .cs – Application resources and navigation

• Platforms/ – Platform-specific code (Android, iOS, Windows, MacCatalyst)

• Resources/ – Images, fonts, styles

• MauiProgram.cs – Dependency injection and app configuration

---

Step 4: Build the UI

Use XAML (for declarative UI) or C# (programmatic UI).

Example (MainPage.xaml):

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             x:Class="MyMauiApp.MainPage">
    <VerticalStackLayout Padding="30">
        <Label Text="Hello, MAUI!" FontSize="32" HorizontalOptions="Center" />
        <Button Text="Click Me" Clicked="OnCounterClicked" />
    </VerticalStackLayout>
</ContentPage>

Code-Behind (MainPage.xaml.cs):

private int count = 0;
private void OnCounterClicked(object sender, EventArgs e)
{
    count++;
    ((Button)sender).Text = $"Clicked {count} times";
}

---

Step 5: Run and Test the App

Platforms you can test on:

• Android – Emulator or physical device

• iOS – Xcode & Mac required

• Windows – Direct

• Mac Catalyst – Mac required

Run:

dotnet build
dotnet run

Or click Run in Visual Studio and choose the platform/device.

---

Step 6: Add Features

You can integrate:

• MVVM architecture (Model-View-ViewModel)

• Data binding

• Navigation

• Dependency Injection

• SQLite/local storage

• APIs (HTTPClient, REST APIs)

---

Step 7: Platform-Specific Code (If Needed)

Use:

#if ANDROID
// Android-specific code
#elif IOS
// iOS-specific code
#endif

Or use DependencyService / Dependency Injection to write platform-specific services.

---

Step 8: Debugging and Diagnostics

Use:

• Breakpoints

• Visual Studio Diagnostic Tools

• Console logs (Debug.WriteLine)

• Hot Reload

---

Step 9: Publish the App

Windows:

dotnet publish -f:net8.0-windows10.0.19041.0 -c Release -o ./publish

Android:

• Create an APK or AAB

• Sign with a certificate

• Use Android Studio tools or MAUI CLI

iOS:

• Requires Mac

• Sign with Apple developer account

• Use Xcode to archive and upload

MacCatalyst:

• Publish from Mac environment

---

Step 10: Maintain and Scale

• Use NuGet packages

• Write unit tests

• Implement CI/CD

• Add analytics and crash reporting (e.g., App Center, Firebase)

---

Optional: MAUI Libraries and Tools

• CommunityToolkit.Maui

• SkiaSharp for 2D drawing

• Prism / MVVM Toolkit

• SQLite-net or EF Core