MAUI.net Tecniche di organizzazione sorgente
MAUI.net Tecniche di organizzazione sorgente
INDICE – MAUI.net Tecniche di organizzazione sorgente
- Introduzione a .NET MAUI e l’architettura Single Project
- Struttura delle cartelle e organizzazione del progetto
- Gestione delle risorse condivise: immagini, font e asset
- Pattern MVVM e separazione delle responsabilità
- Codice platform-specific: strategie di implementazione
- Dependency Injection e inversione del controllo
- Librerie di classe e riutilizzo del codice
- Best practice per il multi-targeting
- Conclusioni e formazione continua
1. INTRODUZIONE A .NET MAUI E L’ARCHITETTURA SINGLE PROJECT
.NET Multi-platform App UI (MAUI) rappresenta l’evoluzione naturale di Xamarin.Forms, portando con sé un cambio di paradigma fondamentale nell’organizzazione del codice: il Single Project. Dopo 15 anni di esperienza nello sviluppo .NET, possiamo affermare che questa innovazione risolve molti dei problemi che affliggevano gli sviluppatori nelle architetture multi-progetto tradizionali.
Il Single Project consente di gestire tutte le piattaforme target (Android, iOS, Windows, macOS) da un unico progetto .NET, eliminando la necessità di mantenere progetti separati per ogni piattaforma. Questo approccio unificato semplifica drasticamente la gestione delle dipendenze, delle risorse e della configurazione del progetto.
La struttura fondamentale di un progetto MAUI include:
- Una cartella
Platformscon sottocartelle per ciascuna piattaforma (Android, iOS, Windows, MacCatalyst) - Una cartella
Resourcescentralizzata per asset condivisi - File di configurazione unificati come
MauiProgram.csche rappresenta l’entry point dell’applicazione
Questa architettura sfrutta il multi-targeting di .NET, compilando solo il codice rilevante per la piattaforma di destinazione durante il build. L’approccio permette di raggiungere fino all’85% di riutilizzo del codice, minimizzando significativamente lo sforzo di manutenzione.
2. STRUTTURA DELLE CARTELLE E ORGANIZZAZIONE DEL PROGETTO
Una corretta organizzazione delle cartelle è fondamentale per mantenere il progetto scalabile e manutenibile nel tempo. Basandoci sull’esperienza consolidata e sulle best practice Microsoft, consigliamo la seguente struttura:
MyMauiApp/
├── Platforms/
│ ├── Android/
│ ├── iOS/
│ ├── Windows/
│ └── MacCatalyst/
├── Resources/
│ ├── Images/
│ ├── Fonts/
│ ├── Raw/
│ ├── Splash/
│ └── AppIcon/
├── Models/
├── ViewModels/
├── Views/
│ └── Pages/
├── Services/
│ └── Interfaces/
├── Helpers/
├── Controls/
└── App.xaml
La cartella Platforms contiene esclusivamente codice specifico per piattaforma. È importante mantenere questo codice al minimo, delegando la logica comune a livelli superiori.
Le cartelle Models, ViewModels e Views seguono il pattern MVVM (Model-View-ViewModel), che approfondiremo nel paragrafo 4. Questa separazione garantisce testabilità e manutenibilità del codice.
La cartella Services ospita le implementazioni dei servizi dell’applicazione, con una sottocartella Interfaces per le astrazioni. Questo approccio facilita l’iniezione delle dipendenze e il testing.
I file XAML delle pagine dovrebbero essere organizzati nella cartella Views/Pages, mentre eventuali controlli custom riutilizzabili vanno in Controls. Ogni componente XAML è accompagnato dal suo file code-behind (.xaml.cs).
3. GESTIONE DELLE RISORSE CONDIVISE: IMMAGINI, FONT E ASSET
Una delle innovazioni più significative di MAUI è la gestione centralizzata delle risorse. A differenza di Xamarin.Forms, dove era necessario creare versioni multiple di ogni risorsa per ogni piattaforma, MAUI genera automaticamente le risorse ottimizzate durante il build.
Immagini
Le immagini vanno posizionate nella cartella Resources/Images/. MAUI supporta nativamente SVG, che vengono convertiti in bitmap alle risoluzioni appropriate per ogni piattaforma.
Nel file di progetto (.csproj), le immagini sono registrate così:
<ItemGroup>
<MauiImage Include="Resources\Images\*" />
<MauiImage Update="Resources\Images\logo.svg"
Resize="True"
BaseSize="300,300" />
</ItemGroup>
Per risorse platform-specific con lo stesso nome, si possono creare sottocartelle condizionali:
<ItemGroup>
<MauiImage Include="Resources\Images\iOS\**"
Condition="$(TargetFramework.Contains('-ios'))" />
<MauiImage Include="Resources\Images\Android\**"
Condition="$(TargetFramework.Contains('-android'))" />
</ItemGroup>
Font
I font personalizzati vengono registrati nel MauiProgram.cs:
builder
.UseMauiApp<App>()
.ConfigureFonts(fonts =>
{
fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
});
Questa configurazione rende i font disponibili cross-platform con un singolo alias referenziabile in XAML o C#.
Asset Raw
Per file che devono essere inclusi senza elaborazione (HTML, JSON, video), si usa la cartella Resources/Raw/:
<ItemGroup>
<MauiAsset Include="Resources\Raw\**"
LogicalName="%(RecursiveDir)%(Filename)%(Extension)" />
</ItemGroup>
4. PATTERN MVVM E SEPARAZIONE DELLE RESPONSABILITÀ
Il pattern Model-View-ViewModel è lo standard de facto per applicazioni MAUI. Dopo anni di implementazioni, possiamo confermare che una corretta applicazione del pattern MVVM riduce drasticamente i bug e migliora la testabilità.
Model
I modelli rappresentano le entità dati dell’applicazione. Devono essere POCO (Plain Old CLR Objects) senza dipendenze verso la UI:
namespace MyMauiApp.Models
{
public class Product
{
public int Id { get; set; }
public string Name { get; set; }
public decimal Price { get; set; }
public string ImageUrl { get; set; }
}
}
ViewModel
I ViewModel implementano INotifyPropertyChanged (o meglio ancora, ereditano da ObservableObject del CommunityToolkit.Mvvm):
using CommunityToolkit.Mvvm.ComponentModel;
using CommunityToolkit.Mvvm.Input;
namespace MyMauiApp.ViewModels
{
public partial class ProductViewModel : ObservableObject
{
[ObservableProperty]
private string productName;
[ObservableProperty]
private decimal price;
[RelayCommand]
private async Task LoadProduct()
{
// Logica di caricamento
}
}
}
Il CommunityToolkit.Mvvm fornisce source generator che riducono drasticamente il boilerplate code.
View
Le View sono file XAML con code-behind minimo. Il ViewModel viene iniettato tramite Dependency Injection:
namespace MyMauiApp.Views.Pages
{
public partial class ProductPage : ContentPage
{
public ProductPage(ProductViewModel viewModel)
{
InitializeComponent();
BindingContext = viewModel;
}
}
}
Nel XAML si fa binding alle proprietà del ViewModel:
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
x:Class="MyMauiApp.Views.Pages.ProductPage">
<StackLayout>
<Label Text="{Binding ProductName}" />
<Label Text="{Binding Price, StringFormat='{0:C}'}" />
<Button Text="Load" Command="{Binding LoadProductCommand}" />
</StackLayout>
</ContentPage>
5. CODICE PLATFORM-SPECIFIC: STRATEGIE DI IMPLEMENTAZIONE
Esistono tre approcci principali per gestire codice specifico per piattaforma in MAUI.
Approccio 1: Cartelle Platform
Il codice viene posizionato direttamente nelle sottocartelle di Platforms/. Questo codice viene compilato solo quando si builda per la piattaforma corrispondente:
Platforms/
├── Android/
│ └── Services/
│ └── DeviceInfoService.cs
└── iOS/
└── Services/
└── DeviceInfoService.cs
Approccio 2: Conditional Compilation
Si utilizzano direttive di pre-processore per includere codice platform-specific in un unico file:
public class DeviceOrientationService
{
public DeviceOrientation GetOrientation()
{
#if ANDROID
IWindowManager windowManager = Android.App.Application.Context
.GetSystemService(Context.WindowService)
.JavaCast<IWindowManager>();
SurfaceOrientation orientation = windowManager.DefaultDisplay.Rotation;
bool isLandscape = orientation == SurfaceOrientation.Rotation90 ||
orientation == SurfaceOrientation.Rotation270;
return isLandscape ? DeviceOrientation.Landscape : DeviceOrientation.Portrait;
#elif IOS
UIInterfaceOrientation orientation = UIApplication.SharedApplication.StatusBarOrientation;
bool isPortrait = orientation == UIInterfaceOrientation.Portrait ||
orientation == UIInterfaceOrientation.PortraitUpsideDown;
return isPortrait ? DeviceOrientation.Portrait : DeviceOrientation.Landscape;
#else
return DeviceOrientation.Undefined;
#endif
}
}
Approccio 3: Partial Classes con Multi-targeting
Si definisce una classe parziale condivisa e implementazioni platform-specific in file separati:
File condiviso Services/DeviceInfo.cs:
namespace MyMauiApp.Services
{
public partial class DeviceInfo
{
public partial string GetDeviceModel();
public partial string GetOsVersion();
}
}
File Platforms/Android/Services/DeviceInfo.cs:
namespace MyMauiApp.Services
{
public partial class DeviceInfo
{
public partial string GetDeviceModel()
{
return Android.OS.Build.Model;
}
public partial string GetOsVersion()
{
return Android.OS.Build.VERSION.Release;
}
}
}
File Platforms/iOS/Services/DeviceInfo.cs:
using UIKit;
namespace MyMauiApp.Services
{
public partial class DeviceInfo
{
public partial string GetDeviceModel()
{
return UIDevice.CurrentDevice.Model;
}
public partial string GetOsVersion()
{
return UIDevice.CurrentDevice.SystemVersion;
}
}
}
6. DEPENDENCY INJECTION E INVERSIONE DEL CONTROLLO
MAUI include nativamente il container DI di Microsoft.Extensions.DependencyInjection. La registrazione dei servizi avviene in MauiProgram.cs:
public static class MauiProgram
{
public static MauiApp CreateMauiApp()
{
var builder = MauiApp.CreateBuilder();
builder
.UseMauiApp<App>()
.ConfigureFonts(fonts =>
{
fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
});
// Registrazione servizi
builder.Services.AddSingleton<IApiService, ApiService>();
builder.Services.AddTransient<IProductRepository, ProductRepository>();
// Registrazione ViewModels
builder.Services.AddTransient<ProductViewModel>();
// Registrazione Views
builder.Services.AddTransient<ProductPage>();
return builder.Build();
}
}
Lifetime dei servizi
AddSingleton: una sola istanza per l’intera applicazioneAddScoped: istanza per scope (utile con DbContext)AddTransient: nuova istanza ad ogni richiesta
Per servizi platform-specific, si può utilizzare la registrazione condizionale:
#if ANDROID
builder.Services.AddSingleton<IDeviceService, AndroidDeviceService>();
#elif IOS
builder.Services.AddSingleton<IDeviceService, IOSDeviceService>();
#endif
Oppure, più elegantemente, sfruttando il multi-targeting con un’interfaccia comune:
// File condiviso
public interface IToastService
{
void ShowToast(string message);
}
// Registrazione
builder.Services.AddSingleton<IToastService, ToastService>();
Le implementazioni platform-specific vanno nelle rispettive cartelle Platforms/.
7. LIBRERIE DI CLASSE E RIUTILIZZO DEL CODICE
Per massimizzare il riutilizzo del codice, è consigliabile separare la logica business in librerie dedicate.
Tipi di librerie
- .NET Standard 2.0/2.1 Class Library: per codice completamente platform-agnostic (modelli, logica business, validazione)
- .NET 6/7/8 Class Library: per codice che non richiede API platform-specific ma utilizza feature moderne di .NET
- .NET MAUI Class Library: per componenti riutilizzabili che necessitano di API MAUI (custom controls, behaviors)
Struttura consigliata per soluzioni enterprise
MySolution/
├── MyApp.MAUI/ (Progetto MAUI principale)
├── MyApp.Core/ (.NET Standard library - Models, Interfaces)
├── MyApp.Services/ (.NET 6+ library - Business Logic)
├── MyApp.Data/ (.NET 6+ library - Data Access)
└── MyApp.UI.Shared/ (MAUI Class Library - Custom Controls)
Creazione di una MAUI Class Library
Nel file .csproj della libreria:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFrameworks>net8.0;net8.0-android;net8.0-ios</TargetFrameworks>
<UseMaui>true</UseMaui>
<SingleProject>true</SingleProject>
</PropertyGroup>
</Project>
Per facilitare l’integrazione, si può creare un extension method per MauiAppBuilder:
namespace MyApp.UI.Shared
{
public static class AppBuilderExtensions
{
public static MauiAppBuilder UseMySharedUI(this MauiAppBuilder builder)
{
// Registrazione di servizi, handler, ecc.
builder.Services.AddTransient<CustomControl>();
return builder;
}
}
}
E utilizzarlo nel MauiProgram.cs:
builder
.UseMauiApp<App>()
.UseMySharedUI();
8. BEST PRACTICE PER IL MULTI-TARGETING
Organizzazione file condizionali
Per file platform-specific con naming convention, si può configurare il multi-targeting nel .csproj:
<ItemGroup>
<!-- Esclude file *.iOS.cs quando non si compila per iOS -->
<Compile Remove="**\*.iOS.cs" />
<None Include="**\*.iOS.cs"
Exclude="$(DefaultItemExcludes);$(DefaultExcludesInProjectFolder)" />
<Compile Include="**\*.iOS.cs"
Condition="$(TargetFramework.Contains('-ios'))" />
</ItemGroup>
<ItemGroup>
<!-- Esclude file *.Android.cs quando non si compila per Android -->
<Compile Remove="**\*.Android.cs" />
<None Include="**\*.Android.cs"
Exclude="$(DefaultItemExcludes);$(DefaultExcludesInProjectFolder)" />
<Compile Include="**\*.Android.cs"
Condition="$(TargetFramework.Contains('-android'))" />
</ItemGroup>
Questo permette di avere file come:
Services/
├── PaymentService.cs (Codice condiviso)
├── PaymentService.Android.cs (Implementazione Android)
└── PaymentService.iOS.cs (Implementazione iOS)
Gestione delle API platform-specific
Quando si accede a API native, è importante utilizzare gli namespace condizionali:
#if ANDROID
using Android.Content;
using Android.Views;
#elif IOS
using UIKit;
using Foundation;
#endif
Testing e debug multi-platform
Per verificare la corretta compilazione condizionale, è utile impostare simboli di debug custom nel .csproj:
<PropertyGroup>
<DefineConstants Condition="$(TargetFramework.Contains('-android'))">
$(DefineConstants);ANDROID
</DefineConstants>
<DefineConstants Condition="$(TargetFramework.Contains('-ios'))">
$(DefineConstants);IOS
</DefineConstants>
</PropertyGroup>
Performance e ottimizzazione
Per Android e iOS, considerare:
- Utilizzo di
ConfigureAwait(false)nelle operazioni async per evitare context switch non necessari - Implementazione di caching per risorse frequentemente accedute
- Lazy loading delle pagine per ridurre il tempo di startup
- Profiling con Xamarin Profiler per identificare memory leak
9. CONCLUSIONI E FORMAZIONE CONTINUA – MAUI.net Tecniche di organizzazione sorgente
L’organizzazione efficace del sorgente in un progetto MAUI.NET richiede una pianificazione attenta dall’inizio del progetto. Le strategie descritte in questo articolo – dall’architettura Single Project alla corretta implementazione del pattern MVVM, dalla gestione delle risorse condivise alle tecniche di multi-targeting – rappresentano il frutto di anni di esperienza consolidata nella community .NET e nelle best practice ufficiali Microsoft.
È fondamentale sottolineare che la tecnologia evolve continuamente e con essa le best practice. Uno degli aspetti spesso sottovalutati nello sviluppo software è l’investimento nella formazione continua del team IT. La preparazione adeguata del personale non solo accelera l’adozione di nuove tecnologie come MAUI.NET, ma previene errori costosi durante lo sviluppo e riduce significativamente i rischi di progetto.
Un team preparato è in grado di:
- Implementare architetture solide e scalabili fin dall’inizio
- Evitare anti-pattern comuni che generano debito tecnico
- Sfruttare appieno le potenzialità del framework
- Risolvere problemi complessi in modo efficiente
- Mantenere alta la qualità del codice nel tempo
Per questo motivo, consiglio vivamente di investire in percorsi formativi strutturati. Innovaformazione offre corsi specifici per aziende che vogliono adottare MAUI.NET con competenza e professionalità.
CORSO MAUI.NET – INNOVAFORMAZIONE
Innovaformazione propone il Corso MAUI.NET, progettato specificamente per le esigenze delle aziende che desiderano formare il proprio team IT sullo sviluppo multipiattaforma con .NET MAUI.
Caratteristiche del corso:
- Modalità: Online in classe virtuale con sessioni live e interattive
- Calendario personalizzabile: da concordare in base alle esigenze aziendali
- Contenuti pratici: esempi reali, best practice e case study aziendali
- Finanziamento: possibilità di accedere ai fondi Fondimpresa per la formazione finanziata
- Supporto completo: Innovaformazione può seguire il cliente in tutto l’iter del piano formativo finanziato, dalla presentazione della domanda alla rendicontazione finale
Il corso copre tutti gli aspetti fondamentali dello sviluppo MAUI, dall’architettura del progetto all’implementazione di funzionalità avanzate, con un focus particolare sulle tecniche di organizzazione del codice e sulle best practice per lo sviluppo enterprise.
Richiedi un preventivo personalizzato:
📧 Email: info@innovaformazione.net
📞 Telefono: 3471012275 (Dario Carrassi)
Non esitare a contattare Innovaformazione per discutere delle esigenze formative del tuo team e scoprire come strutturare un percorso su misura per la tua azienda, sfruttando anche le opportunità di finanziamento disponibili tramite Fondimpresa.
Per altri articoli sul mondo IT consigliamo di navigare sul nostro blog tramite questo LINK.
Articoli correlati
Claude Code con Arduino
Novità .Net 11
Backdoor nei modelli AI open-weight
Opportunità di lavoro Bari
Spieghiamo il Weight space programming
