maui-architecture
Skill1 starsChanged 7 months agoMITView on GitHub
Extension of dotnet-architecture for .NET MAUI apps. Covers MAUI-specific layers: SQLite model attributes, AutoMapper profiles, AppDatabase registration, ViewModels (CommunityToolkit.Mvvm), XAML Pages, Shell navigation, and MauiProgram.cs DI. Use AFTER or TOGETHER WITH dotnet-architecture for the backend layers (DTO, Domain, Infra.Interfaces, Infra, Application).
In this repository39 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- readme-generatorSkill
- add-react-i18nSkill
- band-album-campaignSkill
- band-music-reflectionSkill
- band-streaming-launchSkill
- ckm:banner-designSkill
- ckm:brandSkill
- deploy-prodSkill
- ckm:designSkill
- ckm:design-systemSkill
- docker-compose-configSkill
- doc-managerSkill
- dotnet-architectureSkill
- dotnet-doc-controllerSkill
- dotnet-envSkill
- dotnet-fluent-validationSkill
- dotnet-graphqlSkill
- dotnet-multi-tenantSkill
- dotnet-test-apiSkill
- dotnet-testSkill
- frontend-designSkill
- gitversionSkill
- mermaid-chartSkill
- nauth-guideSkill
- nnews-guideSkill
- react-alertSkill
- react-architectureSkill
- react-archSkill
- react-modalSkill
- readme-generatorSkill
- ckm:slidesSkill
- social-media-assetsSkill
- social-media-schedulingSkill
- social-post-authoringSkill
- ckm:ui-stylingSkill
- ui-ux-pro-maxSkill
- wsl-dockerSkill
- ztools-guideSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 20
Run dotnet sln list and ls to discover project names and folder layout.
- Distinctive: line 23
Check existing UI strings to detect the app language and match it.
- Very specific: line 103
Add to InitializeAsync(): await _database.CreateTableAsync<{Entity}>().
- Very specific: line 241
Use x:DataType for compiled bindings
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
.NET MAUI Presentation Layer — Extension of dotnet-architecture
You are an expert assistant that helps developers implement the MAUI presentation layer for entities whose backend layers (DTO, Domain, Infra.Interfaces, Infra, Application) follow the Clean Architecture defined in the dotnet-architecture skill.
This skill is an EXTENSION — it covers ONLY MAUI-specific concerns. For backend layers, invoke or follow dotnet-architecture.
Input
The user will describe the entity to create or modify: $ARGUMENTS
Before You Start
- Run
dotnet-architecturefirst (or confirm backend layers already exist) — this skill assumes DTO, Domain Model, Repository Interface, Domain Service, Infra Repository, and Application DI are already in place. - Run
dotnet sln listandlsto discover project names and folder layout. - The placeholder
{App}stands for the actual root namespace. Replace it everywhere. - Read at least one existing entity end-to-end (Model → Mapper → ViewModel → Page) to match style.
- Check existing UI strings to detect the app language and match it.
What This Skill Covers
| Layer | Responsibility |
| Infra — AutoMapper (Mappings) | Profile mapping Domain Model ↔ DTO in Infra/Mappings/ |
| Infra — AppDatabase | SQLite table registration |
| MAUI — ViewModels | MVVM with CommunityToolkit.Mvvm, binds to DTOs |
| MAUI — Pages | XAML + code-behind with DI |
| MAUI — Shell | Navigation registration |
| MAUI — MauiProgram.cs | DI for Repos, AppServices, ViewModels, Pages |
What This Skill Does NOT Cover (handled by dotnet-architecture)
- DTO creation (
{Entity}Info) - Domain Model (rich entity with Validate/Update/Create)
- Infra.Interfaces (Repository/AppService interfaces)
- Domain Services
- Infra Repository implementation
- Application DI (
DependencyInjection.cs)
Architecture Context
Mapping Flow
DB (SQLite) → Repository → Model (Domain) → AutoMapper → {Entity}Info (DTO) → ViewModel → Page
Page → ViewModel → {Entity}Info (DTO) → AutoMapper → Model (Domain) → Repository → DBMAUI-Specific Conventions
- ViewModels bind to DTOs (
{Entity}Info), never to Domain Models directly - Singleton for repos/services/appservices — Transient for ViewModels/Pages
- AutoMapper registered once, scans Infra assembly for all Profiles
- Domain Models use SQLite attributes (
[PrimaryKey],[AutoIncrement],[Table],[Indexed]) — this is the only infrastructure concern allowed on Domain Models in MAUI apps CommunityToolkit.Mvvmsource generators:[ObservableObject],[ObservableProperty],[RelayCommand]
Packages: sqlite-net-pcl + SQLitePCLRaw.bundle_green, CommunityToolkit.Mvvm, AutoMapper.Extensions.Microsoft.DependencyInjection
Step-by-Step Implementation (MAUI Layers Only)
Step 1: AutoMapper Profile — {App}.Infra/Mappings/{Entity}Profile.cs
Recommended: Use AutoMapper (
AutoMapper.Extensions.Microsoft.DependencyInjection) to map between Domain Models and DTOs. It eliminates repetitive manual mapping code, reduces bugs from forgotten properties, and keeps the mapping logic centralized in Profile classes. Register once withAddAutoMapper(assembly)and all Profiles are auto-discovered.
using AutoMapper;
using {App}.DTOs;
using {App}.Models;
namespace {App}.Mappings;
public class {Entity}Profile : Profile
{
public {Entity}Profile()
{
CreateMap<{Entity}, {Entity}Info>(); // Model → DTO (read)
CreateMap<{Entity}Info, {Entity}>() // DTO → Model (write)
.ForMember(dest => dest.CreatedAt, opt => opt.Ignore())
.ForMember(dest => dest.UpdatedAt, opt => opt.Ignore());
}
}Conventions:
- One Profile per entity in
{App}.Infra/Mappings/ - Model → Info: direct map (all readable props)
- Info → Model: ignore managed fields (
CreatedAt,UpdatedAt) — the entity'sUpdate()/Create()methods control those - AutoMapper auto-discovered via
AddAutoMapper(assembly)in DI
Step 2: Register Table — {App}.Infra/Context/AppDatabase.cs
Add to InitializeAsync(): await _database.CreateTableAsync<{Entity}>();
Step 3: List ViewModel — {App}/ViewModels/{Entity}ListViewModel.cs
public partial class {Entity}ListViewModel : ObservableObject
{
private readonly I{Entity}Repository _{entity}Repository;
private readonly IMapper _mapper;
public {Entity}ListViewModel(I{Entity}Repository repo, IMapper mapper)
{ _{entity}Repository = repo; _mapper = mapper; }
[ObservableProperty] private ObservableCollection<{Entity}Info> _items = [];
[ObservableProperty] private bool _isLoading;
[ObservableProperty] private bool _isEmpty;
[RelayCommand]
private async Task LoadItemsAsync()
{
IsLoading = true;
try
{
var models = await _{entity}Repository.GetAllAsync();
Items = new(_mapper.Map<List<{Entity}Info>>(models));
IsEmpty = Items.Count == 0;
}
finally { IsLoading = false; }
}
[RelayCommand]
private async Task DeleteAsync({Entity}Info item)
{
if (!await Shell.Current.DisplayAlert("Delete", $"Delete \"{item.Name}\"?", "Yes", "No")) return;
await _{entity}Repository.DeleteAsync(item.Id); Items.Remove(item); IsEmpty = Items.Count == 0;
}
[RelayCommand]
private async Task GoToDetailAsync({Entity}Info item) =>
await Shell.Current.GoToAsync("{Entity}DetailPage", new Dictionary<string, object> { { "{Entity}Info", item } });
}Step 4: Detail ViewModel — {App}/ViewModels/{Entity}DetailViewModel.cs
public partial class {Entity}DetailViewModel : ObservableObject, IQueryAttributable
{
private readonly I{Entity}Repository _{entity}Repository;
private readonly IMapper _mapper;
public {Entity}DetailViewModel(I{Entity}Repository repo, IMapper mapper)
{ _{entity}Repository = repo; _mapper = mapper; }
[ObservableProperty] private int _{entity}Id;
[ObservableProperty] private string _name = string.Empty;
[ObservableProperty] private bool _isSaving;
[ObservableProperty] private bool _isNewItem = true;
[ObservableProperty] private string _pageTitle = "New {Entity}";
public void ApplyQueryAttributes(IDictionary<string, object> query)
{
if (query.TryGetValue("{Entity}Info", out var obj) && obj is {Entity}Info info)
{ {Entity}Id = info.Id; Name = info.Name; IsNewItem = false; PageTitle = "Edit {Entity}"; }
}
[RelayCommand]
private async Task SaveAsync()
{
IsSaving = true;
try
{
var entity = IsNewItem ? {Entity}.Create(Name) : (await _{entity}Repository.GetByIdAsync({Entity}Id))!;
if (!IsNewItem) entity.Update(Name);
var error = entity.Validate();
if (error != null) { await Shell.Current.DisplayAlert("Error", error, "OK"); return; }
await _{entity}Repository.SaveAsync(entity);
await Shell.Current.GoToAsync("..");
}
catch (InvalidOperationException ex) { await Shell.Current.DisplayAlert("Error", ex.Message, "OK"); }
finally { IsSaving = false; }
}
[RelayCommand] private async Task GoBackAsync() => await Shell.Current.GoToAsync("..");
}ViewModel conventions:
- ViewModels bind to
{Entity}Info(DTO), not Models IMapperinjected for conversions- Navigation passes DTOs
- Save/Update goes through domain entity methods (Create/Update/Validate) for business rules
[ObservableProperty]on_camelCasefields[RelayCommand]on{Method}Asyncmethods
Step 5: List Page XAML — {App}/Pages/{Entity}ListPage.xaml
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
xmlns:vm="clr-namespace:{App}.ViewModels"
xmlns:dto="clr-namespace:{App}.DTOs;assembly={App}.DTO"
x:Class="{App}.Pages.{Entity}ListPage"
x:DataType="vm:{Entity}ListViewModel"
Title="{Entities}">
<Grid RowDefinitions="*,Auto" Padding="16">
<ActivityIndicator Grid.Row="0" IsRunning="{Binding IsLoading}" IsVisible="{Binding IsLoading}"
HorizontalOptions="Center" VerticalOptions="Center" />
<Label Grid.Row="0" Text="No items yet" IsVisible="{Binding IsEmpty}"
FontSize="18" HorizontalOptions="Center" VerticalOptions="Center" />
<CollectionView Grid.Row="0" ItemsSource="{Binding Items}" SelectionMode="None">
<CollectionView.ItemTemplate>
<DataTemplate x:DataType="dto:{Entity}Info">
<SwipeView>
<SwipeView.RightItems><SwipeItems>
<SwipeItem Text="Delete" BackgroundColor="#E53935"
Command="{Binding Source={RelativeSource AncestorType={x:Type vm:{Entity}ListViewModel}}, Path=DeleteCommand}"
CommandParameter="{Binding}" />
</SwipeItems></SwipeView.RightItems>
<Frame Margin="0,4" Padding="16" CornerRadius="12" BorderColor="Transparent">
<Frame.GestureRecognizers>
<TapGestureRecognizer
Command="{Binding Source={RelativeSource AncestorType={x:Type vm:{Entity}ListViewModel}}, Path=GoToDetailCommand}"
CommandParameter="{Binding}" />
</Frame.GestureRecognizers>
<Label Text="{Binding Name}" FontSize="16" FontAttributes="Bold" />
</Frame>
</SwipeView>
</DataTemplate>
</CollectionView.ItemTemplate>
</CollectionView>
<Button Grid.Row="1" Text="+ New" Command="{Binding GoToDetailCommand}"
FontSize="16" HeightRequest="56" CornerRadius="28" Margin="0,12,0,0" />
</Grid>
</ContentPage>XAML conventions:
- DTOs need
assembly={App}.DTOin xmlns - ViewModels in MAUI do NOT need assembly qualifier
- Use
x:DataTypefor compiled bindings
Step 6: Page Code-Behind — {App}/Pages/{Entity}ListPage.xaml.cs
public partial class {Entity}ListPage : ContentPage
{
private readonly {Entity}ListViewModel _viewModel;
public {Entity}ListPage({Entity}ListViewModel viewModel)
{ InitializeComponent(); BindingContext = _viewModel = viewModel; }
protected override async void OnAppearing()
{ base.OnAppearing(); await _viewModel.LoadItemsCommand.ExecuteAsync(null); }
}Step 7: DI Registration — {App}/MauiProgram.cs
// AutoMapper — scans Infra assembly for all Profiles (register ONCE)
builder.Services.AddAutoMapper(typeof(AppDatabase).Assembly);
// Application Services (Domain Services — registered via Application project)
builder.Services.AddApplicationServices();
// Infrastructure
builder.Services.AddSingleton<I{Entity}AppService, {Entity}AppService>(); // AppService (if needed)
builder.Services.AddSingleton<I{Entity}Repository, {Entity}Repository>(); // Repository
// MAUI Presentation
builder.Services.AddTransient<{Entity}ListViewModel>(); // ViewModels
builder.Services.AddTransient<{Entity}DetailViewModel>();
builder.Services.AddTransient<{Entity}ListPage>(); // Pages
builder.Services.AddTransient<{Entity}DetailPage>();Key points:
AddApplicationServices()comes from{App}.Applicationproject — registers all Domain Services- Domain Services are NOT registered individually in
MauiProgram.cs - Singleton for repos/services/appservices — Transient for ViewModels/Pages
- AutoMapper registered once, scans assembly for all Profiles
Step 8: Shell Navigation — AppShell
In .xaml: <ShellContent Title="{Entities}" ContentTemplate="{DataTemplate pages:{Entity}ListPage}" Route="{Entity}ListPage" />
In .xaml.cs: Routing.RegisterRoute("{Entity}DetailPage", typeof({Entity}DetailPage));
Step 9: Unit Tests — {App}.Tests/Services/{Entity}RepositoryTests.cs
public class {Entity}RepositoryTests : IAsyncLifetime
{
private AppDatabase _database = null!;
private {Entity}Repository _repository = null!;
private string _dbPath = null!;
public async Task InitializeAsync()
{
_dbPath = Path.Combine(Path.GetTempPath(), $"test_{Guid.NewGuid()}.db3");
_database = new AppDatabase(_dbPath); await _database.InitializeAsync();
_repository = new {Entity}Repository(_database);
}
public Task DisposeAsync() { if (File.Exists(_dbPath)) File.Delete(_dbPath); return Task.CompletedTask; }
[Fact] public async Task SaveAsync_Insert() { Assert.Equal(1, await _repository.SaveAsync({Entity}.Create("Test"))); }
[Fact] public async Task GetAllAsync() { /* save 2, assert count == 2 */ }
[Fact] public async Task SaveAsync_Update() { /* save, Update(), save again, assert new value */ }
[Fact] public async Task DeleteAsync() { /* save, delete, get returns null */ }
// Mapper tests
[Fact] public void MapModelToInfo()
{
var config = new MapperConfiguration(cfg => cfg.AddProfile<{Entity}Profile>());
var mapper = config.CreateMapper();
var model = {Entity}.Create("Test");
var info = mapper.Map<{Entity}Info>(model);
Assert.Equal(model.Name, info.Name);
}
}Checklist
| # | Layer | File | Notes |
| 0 | Backend | Run dotnet-architecture skill | DTO, Domain, Infra.Interfaces, Infra Repo, Application DI |
| 1 | Infra | {App}.Infra/Mappings/{Entity}Profile.cs | AutoMapper Profile: Model ↔ Info |
| 2 | Infra | Modify AppDatabase.cs → CreateTableAsync<{Entity}>() | SQLite table |
| 3-4 | MAUI | ViewModels/{Entity}ListViewModel.cs + {Entity}DetailViewModel.cs | MVVM |
| 5-6 | MAUI | Pages/{Entity}ListPage.xaml(.cs) + {Entity}DetailPage.xaml(.cs) | UI |
| 7 | MAUI | Modify MauiProgram.cs | DI: Repos, AppServices, VMs, Pages + AddApplicationServices() |
| 8 | MAUI | Modify AppShell.xaml + .xaml.cs | Navigation |
| 9 | Tests | {Entity}RepositoryTests.cs + mapper tests | Verification |
Response Guidelines
- Confirm backend exists — Check that DTO, Domain Model, Repository Interface/Implementation, and Application DI are in place. If not, run
dotnet-architecturefirst. - Discover first —
dotnet sln list, read existing entities to match patterns - Order — Mapper → AppDatabase → ViewModels → Pages → MauiProgram.cs → Shell → Tests
- Build after each layer to catch errors early
- Match the app language in UI strings
- ViewModels bind to DTOs — never to Domain Models directly
- Mapper — one Profile per entity in
Infra/Mappings/ - Singleton for repos/services/appservices — Transient for ViewModels/Pages
- Domain logic stays in Domain — no business rules in ViewModels or Pages
- AutoMapper registered once in
MauiProgram.cs, scans Infra assembly
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

