133 lines
7.2 KiB
Markdown
133 lines
7.2 KiB
Markdown
# Fixiy — Agent Guide
|
|
|
|
## Project Overview
|
|
|
|
Fixiy is a **.NET MAUI Blazor Hybrid** app that shares its entire UI with a **Blazor Server Web App** via a Razor Class Library (RCL). All pages and components live in `Fixiy.Shared` and are consumed by both host projects without modification.
|
|
|
|
- **App ID:** `it.integry.fixiy`
|
|
- **Solution:** `Fixiy.sln`
|
|
- **SDK:** .NET 10 (`global.json` — `rollForward: latestMajor`)
|
|
- **NuGet source:** Private feed — see `NuGet.Config` (`https://nuget.studioml.it/repository/nuget-group/index.json`)
|
|
- **Platforms:** Android 26+, iOS 15+, Web (Blazor Server)
|
|
|
|
## Repository Structure
|
|
|
|
```
|
|
Fixiy.sln
|
|
├── Fixiy.Maui/ # .NET MAUI Blazor Hybrid host (Android + iOS)
|
|
│ ├── MauiProgram.cs # DI root — registers MAUI services + IntegryApiClient
|
|
│ ├── Services/FormFactor.cs # MAUI implementation of IFormFactor (uses DeviceInfo)
|
|
│ ├── Platforms/ # Platform-specific entry points (Android, iOS, …)
|
|
│ └── Resources/ # App icons, splash, fonts, images
|
|
├── Fixiy.Shared/ # Razor Class Library — all shared UI
|
|
│ ├── Components/
|
|
│ │ ├── Layout/ # MainLayout.razor, NavBar.razor, NavMenu.razor
|
|
│ │ ├── Pages/ # Routable pages (e.g., Home.razor)
|
|
│ │ └── SingleElements/ # Reusable components (e.g., NoDataAvailable.razor)
|
|
│ ├── Interfaces/IFormFactor.cs # Platform abstraction interface
|
|
│ ├── InteractiveRenderSettings.cs # Shared render mode constants (nulled in MAUI)
|
|
│ └── _Imports.razor # Global using directives for shared components
|
|
└── Fixiy.Web/ # Blazor Server Web App host
|
|
├── Program.cs # DI root — registers web services + IntegryApiClient
|
|
└── Services/FormFactor.cs # Web implementation of IFormFactor
|
|
```
|
|
|
|
## Tech Stack
|
|
|
|
| Layer | Technology |
|
|
|-------|-----------|
|
|
| Mobile host | .NET MAUI Blazor Hybrid — `net10.0-android`, `net10.0-ios` |
|
|
| Web host | Blazor Server (ASP.NET Core, `net10.0`) |
|
|
| Shared UI | Razor Class Library (`Fixiy.Shared`, `net10.0`) |
|
|
| Client SDK | `IntegryApiClient` — MAUI / Core / Blazor variants (private NuGet) |
|
|
| Fonts | OpenSans via MAUI font registration |
|
|
|
|
## Build & Run
|
|
|
|
**Prerequisites:** .NET SDK 10, MAUI workload (`dotnet workload install maui`) for mobile builds.
|
|
|
|
```bash
|
|
# Restore (requires private NuGet credentials — see NuGet.Config)
|
|
dotnet restore Fixiy.sln
|
|
|
|
# Run Blazor Web App (no platform SDK required)
|
|
dotnet run --project Fixiy.Web/Fixiy.Web.csproj
|
|
|
|
# Build MAUI for Android (requires MAUI workload)
|
|
dotnet build Fixiy.Maui/Fixiy.Maui.csproj -f net10.0-android
|
|
|
|
# Build MAUI for iOS (requires macOS + Xcode)
|
|
dotnet build Fixiy.Maui/Fixiy.Maui.csproj -f net10.0-ios
|
|
```
|
|
|
|
## Key Patterns and Conventions
|
|
|
|
### 1. InteractiveRenderSettings pattern
|
|
|
|
`Fixiy.Shared/InteractiveRenderSettings.cs` exposes `static IComponentRenderMode?` properties (`InteractiveServer`, `InteractiveAuto`, `InteractiveWebAssembly`). In `Fixiy.Web` these remain set to real render modes. In `Fixiy.Maui`, `MauiProgram.ConfigureBlazorHybridRenderModes()` sets all three to `null` — MAUI Blazor Hybrid does not support server or WASM render modes.
|
|
|
|
**Always use the property, not the constant, in shared components:**
|
|
|
|
```razor
|
|
@* Wrong — hard-coded constant, crashes in MAUI *@
|
|
@rendermode="RenderMode.InteractiveServer"
|
|
|
|
@* Correct — resolves to null in MAUI, InteractiveServer in Web *@
|
|
@rendermode="@InteractiveServer"
|
|
```
|
|
|
|
### 2. IFormFactor platform abstraction
|
|
|
|
`IFormFactor` (in `Fixiy.Shared/Interfaces/`) provides `GetFormFactor()` and `GetPlatform()`. Each host project provides its own implementation registered in DI. Inject `IFormFactor` in shared components; **never call `DeviceInfo` or other MAUI APIs from `Fixiy.Shared`**.
|
|
|
|
### 3. IntegryApiClient registration
|
|
|
|
Both DI roots register IntegryApiClient with the same `appToken` and `useLoginAzienda: true`.
|
|
|
|
- MAUI: `.UseIntegry(appToken, useLoginAzienda: true)` on `MauiAppBuilder`
|
|
- Web: `builder.Services.UseIntegry(appToken, useLoginAzienda: true)`
|
|
|
|
The app token must match across both registrations. It is currently declared as a `const` in `MauiProgram.cs` and a `const string` in `Fixiy.Web/Program.cs`.
|
|
|
|
### 4. Adding a new page
|
|
|
|
1. Create `Fixiy.Shared/Components/Pages/YourPage.razor` with `@page "/your-route"`
|
|
2. No extra registration required — `Routes.razor` discovers pages via assembly scanning
|
|
3. Add a navigation entry to `Fixiy.Shared/Components/Layout/NavMenu.razor` if user-accessible
|
|
|
|
### 5. Adding a platform-specific service
|
|
|
|
1. Define the interface in `Fixiy.Shared/Interfaces/IYourService.cs`
|
|
2. Implement in `Fixiy.Maui/Services/YourService.cs` (may use MAUI APIs)
|
|
3. Implement in `Fixiy.Web/Services/YourService.cs` (BCL only)
|
|
4. Register in `Fixiy.Maui/MauiProgram.cs` as `AddSingleton<IYourService, YourService>()`
|
|
5. Register in `Fixiy.Web/Program.cs` as `AddScoped<IYourService, YourService>()`
|
|
|
|
## Maintenance Matrix
|
|
|
|
| When you change… | Also update… |
|
|
|------------------|-------------|
|
|
| `Fixiy.Shared/Interfaces/IFormFactor.cs` | `Fixiy.Maui/Services/FormFactor.cs` and `Fixiy.Web/Services/FormFactor.cs` |
|
|
| Any interface in `Fixiy.Shared/Interfaces/` | Both platform `Services/` implementations + both DI roots |
|
|
| `InteractiveRenderSettings.cs` (add/remove property) | `MauiProgram.ConfigureBlazorHybridRenderModes()` — must null all new properties |
|
|
| `Fixiy.Shared/_Imports.razor` | Verify imports are valid in both MAUI and Web (no platform-only namespaces) |
|
|
| IntegryApiClient package version | Update in all three `.csproj` files consistently |
|
|
| App token | Update in both `Fixiy.Maui/MauiProgram.cs` and `Fixiy.Web/Program.cs` |
|
|
| `Fixiy.Shared/Components/Layout/NavMenu.razor` | Review navigation works on both platforms |
|
|
|
|
## CI/CD
|
|
|
|
No CI pipeline is currently configured. The project uses a private NuGet feed (`NuGet.Config`). For CI builds:
|
|
|
|
- Set `NUGET_USERNAME` and `NUGET_PASSWORD` (or PAT) as CI secrets
|
|
- Build only `Fixiy.Web` in standard CI; MAUI builds require platform-specific agents with MAUI workloads
|
|
- See `.github/workflows/copilot-setup-steps.yml` for environment setup reference
|
|
|
|
## Common Pitfalls
|
|
|
|
- **Render mode constants in shared code:** Use `@InteractiveServer` (property from `InteractiveRenderSettings`) never `RenderMode.InteractiveServer`. The MAUI host nulls these via `ConfigureBlazorHybridRenderModes()`.
|
|
- **MAUI APIs in Fixiy.Shared:** `DeviceInfo`, `FileSystem`, `Connectivity`, and other `Microsoft.Maui.*` APIs are not available in the RCL. Define a new `IFormFactor`-style interface instead.
|
|
- **Private NuGet feed:** All `dotnet restore` calls require credentials. In CI, add the source credentials via environment secrets — the `NuGet.Config` `<clear/>` directive removes all default sources.
|
|
- **MAUI workload for builds:** `dotnet workload install maui` is required before building `Fixiy.Maui`. Standard CI runners (Ubuntu) don't have it by default.
|
|
- **Service lifetimes:** MAUI registers platform services as `Singleton` (long-lived app); Web registers them as `Scoped` (per request). Interfaces must not assume a specific lifetime.
|