🧩 MAUI Base Project Template

A clean and modular .NET MAUI base project designed for scalability, maintainability, and clarity.
It follows the MVVM (Model–View–ViewModel) pattern and includes dependency injection, configuration loading, popups, reusable controls, and localization support out of the box.

---

📦 Overview

This project serves as a starting point for building cross‑platform MAUI applications.
It contains all the essential building blocks already organized in a production‑ready structure, so you can focus on implementing your domain logic.

---

🧱 Project Structure

Maui_Base/
├── App.xaml / AppShell.xaml           → Main app entry and navigation structure
├── MauiProgram.cs                     → Dependency injection and app configuration
│
├── Models/                            → Data models used across the app
│   └── ConfigModel.cs
│
├── ViewModels/                        → MVVM ViewModels that handle logic and bindings
│   └── (Example: ConfigViewModel.cs)
│
├── Services/
│   ├── Interfaces/                    → Contracts that define service behavior
│   │   └── IConfigService.cs
│   │   └── I...
│   └── Implementations/               → Concrete service implementations
│       └── ConfigService.cs
│       └── ...cs
│
├── Views/
│   ├── Popups/                        → UI overlays and modal popups (CommunityToolkit.Maui)
│   │   └── ConfigLoadingPopup.xaml
│   ├── Controls/                          → Reusable UI components (ContentView) used within pages/popups
│   │   └──(Examples: LoadingOverlay.xaml, Snackbar.xaml, CustomButton.xaml)
│   └── MainPage.xaml                  → Main user interface
│
├── Converters/                        → Value converters for data binding
│   └── (Example: BoolToVisibilityConverter.cs)
│
├── Resources/
│   ├── Raw/                           → App‑packaged files (read‑only at runtime)
│   │   └── config.xml                 → Default configuration template (copied to AppData on first run)
│   └── Strings/                       → Localization resource files (.resx)
│       ├── AppResources.resx          → Default (English) resources
│       └── AppResources.es.resx       → Spanish translation
│
└── Helpers/                           → Utility classes for reusable logic
    └── LocalizationHelper.cs

Controls vs Popups (Why both?)

• Controls/ are reusable visual components (usually ContentView) embedded inside pages or popups. They encapsulate small UI chunks (e.g., a LoadingOverlay, a Snackbar, or a CustomButton) and do not manage navigation or modal behavior.
• Views/Popups/ are modal overlays derived from CommunityToolkit.Maui.Views.Popup. They sit on top of the current UI, can be blocking (user must wait), can return a value, and are ideal for short workflows (confirmations, input prompts) or progress screens (e.g., the configuration loading popup).

---

⚙️ Key Features

• ✅ MVVM Toolkit – lightweight data binding and property notifications (CommunityToolkit.Mvvm)
• ✅ Dependency Injection – configured via MauiProgram.cs
• ✅ Service Layer – clean separation between logic and data access
• ✅ Config Service – loads XML configuration with progress reporting and in‑memory cache
• ✅ Logs Service – save logs in a file
• ✅ Popup System – blocking UI overlays for long‑running tasks (CommunityToolkit.Maui.Views)
• ✅ Reusable Controls – small visual building blocks for consistent UI patterns
• ✅ Localization (i18n) – dynamic culture switching via .resx files
• ✅ Clean Folder Layout – intuitive separation of concerns

---

🌍 Localization

The project uses standard .resx files for text translation.

• AppResources.resx → English (default)
• AppResources.es.resx → Spanish translation

At startup, the ConfigService reads the <UI Language="..."/> tag from config.xml and automatically switches the app culture.

Example from config.xml:

<Config>
  <Database Host="localhost" Port="3306" User="root" Password="1234" />
  <UI Language="es-ES" />
  <Features EnableLogs="true" />
</Config>

Using resources in C#:

using Maui_Base.Resources;

var message = AppResources.ConfigurationLoadedSuccessfully;

Using resources in XAML:

xmlns:resx="clr-namespace:Maui_Base.Resources"

<Label Text="{x:Static resx:AppResources.ConfigurationLoadedSuccessfully}" />

Make sure your .resx files are set to Build Action: EmbeddedResource and Custom Tool: ResXFileCodeGenerator.
If desired, set Custom Tool Namespace to Maui_Base.Resources to generate a clean AppResources class.

---

🔧 Configuration Service (XML + Progress + Caching)

• Looks for config.xml under FileSystem.AppDataDirectory.
• If missing, copies the default Resources/Raw/config.xml into AppData (first run).
• Parses <Database/>, <UI/>, and <Features/>.
• Reports progress via IProgress<string> for UI popups.
• Caches the loaded ConfigModel in memory and provides ReloadAsync when needed.

Interface:

public interface IConfigService
{
    Task<ConfigModel> LoadConfigAsync(IProgress<string>? progress = null);
    Task<ConfigModel> ReloadAsync(IProgress<string>? progress = null);
    ConfigModel? Current { get; }
}

DI registration (MauiProgram.cs):

builder.Services.AddSingleton<IConfigService, ConfigService>();

---

🪟 Startup + Blocking Popup (CommunityToolkit.Maui)

The app shows a blocking popup while reading config.xml.
Snippet inside App.xaml.cs using CreateWindow:

protected override Window CreateWindow(IActivationState? activationState)
{
    var window = new Window(new AppShell());

    window.Created += async (_, _) =>
    {
        var popup = new ConfigLoadingPopup();
        Application.Current?.MainPage?.ShowPopup(popup);

        var progress = new Progress<string>(msg => popup.UpdateMessage(msg));

        try
        {
            var config = await _configService.LoadConfigAsync(progress);
            // config is now cached, and culture is set based on config.UI.Language
        }
        catch (Exception ex)
        {
            await popup.ShowErrorAsync(ex.Message);
        }
        finally
        {
            popup.Close();
        }
    };

    return window;
}

Popup basics (XAML root):

<toolkit:Popup
    xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
    CanBeDismissedByTappingOutsideOfPopup="False"
    Color="#80000000">
    <!-- Popup content -->
</toolkit:Popup>

Ensure the Toolkit is installed and registered:

builder.UseMauiCommunityToolkit();

---

🧠 Tech Stack

• .NET 9 / .NET MAUI
• MVVM Toolkit (CommunityToolkit.Mvvm)
• CommunityToolkit.Maui (Popups, Converters, etc.)
• C# 12
• XAML UI Layer

---

🚀 How to Run

1. Clone the repository

   git clone https://github.com/yourusername/Maui_Base.git
   cd Maui_Base

2. Open the solution in Visual Studio 2022 (v17.10+)
3. Ensure required workloads are installed (MAUI, Android/iOS/Windows)
4. Run the project (F5) on your preferred target (Windows, Android emulator, etc.)

---

🧩 Future Improvements

• Add a BaseViewModel class with IsBusy, Title, and unified error handling
• Implement logging and analytics service
• Add unit tests for services and ViewModels
• Include theme management (dark/light mode)
• Add a DialogService abstraction for alerts/confirmations from ViewModels

---

🧑‍💻 Author

Alex
Industrial Engineer & Software Developer
Building automation, digitalization and cross‑platform solutions.

---

📄 License

To be defined.