|
| 1 | +# MAUI Quick Start Guide - Test Results and Findings |
| 2 | + |
| 3 | +## Summary |
| 4 | +I successfully implemented the MAUI quick start guide from the Mapsui documentation. The guide is generally accurate and easy to follow, but there are several issues that need to be addressed in the documentation. |
| 5 | + |
| 6 | +## Test Environment |
| 7 | +- **Operating System**: Linux (Ubuntu) |
| 8 | +- **.NET SDK Version**: 9.0.307, 10.0.100 |
| 9 | +- **MAUI Workload Version**: 10.0.0 |
| 10 | +- **Mapsui.Maui Package Version**: 5.0.0 |
| 11 | +- **Target Framework**: net9.0-android (simplified for testing on Linux) |
| 12 | + |
| 13 | +## Issues Found |
| 14 | + |
| 15 | +### 1. ❌ CRITICAL: Incorrect .NET Version in Documentation |
| 16 | +**Current Documentation Says**: "Create a new .NET 7.0 MAUI application" |
| 17 | +**Issue**: .NET 7 is out of support and will show errors with modern SDKs |
| 18 | +**Recommended Fix**: Update to ".NET 9.0 MAUI application" (or latest LTS version) |
| 19 | +**Impact**: High - Users will encounter build errors or warnings about unsupported frameworks |
| 20 | + |
| 21 | +### 2. ⚠️ Missing Prerequisites |
| 22 | +**Issue**: The guide doesn't mention that users need to install MAUI templates and workloads first |
| 23 | +**Required Steps** (not in guide): |
| 24 | +```bash |
| 25 | +# Install MAUI templates (if not already installed) |
| 26 | +dotnet new install Microsoft.Maui.Templates |
| 27 | + |
| 28 | +# Restore/install required workloads |
| 29 | +dotnet workload restore |
| 30 | +``` |
| 31 | +**Recommended Fix**: Add a "Prerequisites" section before Step 1 |
| 32 | +**Impact**: Medium - Users may get confusing error messages about missing templates |
| 33 | + |
| 34 | +### 3. ⚠️ Multi-Platform Target Framework Issues |
| 35 | +**Issue**: The default MAUI template targets multiple platforms (iOS, Android, MacCatalyst, Windows), but building all platforms requires specific OS environments |
| 36 | +**Example**: Building iOS/MacCatalyst requires macOS |
| 37 | +**Current Workaround**: Users may need to modify the `.csproj` file to target only platforms available on their system |
| 38 | +**Recommended Fix**: Add a note about platform-specific build requirements |
| 39 | +**Impact**: Medium - Users on Linux/Windows may encounter build errors for iOS targets |
| 40 | + |
| 41 | +### 4. ✅ Package Installation Works Correctly |
| 42 | +**Step 2**: `Install-Package Mapsui.Maui` works as expected |
| 43 | +**Note**: The guide shows Package Manager Console syntax (`PM>`), which is Visual Studio specific |
| 44 | +**Recommendation**: Add alternative command for CLI users: |
| 45 | +```bash |
| 46 | +dotnet add package Mapsui.Maui |
| 47 | +``` |
| 48 | + |
| 49 | +### 5. ✅ SkiaSharp Configuration Works |
| 50 | +**Step 3**: The `.UseSkiaSharp()` configuration in `MauiProgram.cs` is correct |
| 51 | +**Result**: Build succeeds with proper namespace import |
| 52 | +**Code verified**: |
| 53 | +```csharp |
| 54 | +using SkiaSharp.Views.Maui.Controls.Hosting; |
| 55 | + |
| 56 | +builder |
| 57 | + .UseMauiApp<App>() |
| 58 | + .UseSkiaSharp() |
| 59 | + .ConfigureFonts(fonts => ... |
| 60 | +``` |
| 61 | + |
| 62 | +### 6. ✅ MapControl Implementation Works |
| 63 | +**Step 4**: Replacing the MainPage constructor works as documented |
| 64 | +**Result**: Build succeeds |
| 65 | +**Code verified**: |
| 66 | +```csharp |
| 67 | +public MainPage() |
| 68 | +{ |
| 69 | + InitializeComponent(); |
| 70 | + |
| 71 | + var mapControl = new Mapsui.UI.Maui.MapControl(); |
| 72 | + mapControl.Map?.Layers.Add(Mapsui.Tiling.OpenStreetMap.CreateTileLayer()); |
| 73 | + Content = mapControl; |
| 74 | +} |
| 75 | +``` |
| 76 | + |
| 77 | +### 7. ℹ️ Build Warnings (Not Guide-Related) |
| 78 | +**Warning Found**: `CS0618: 'Application.MainPage.set' is obsolete` |
| 79 | +**Location**: `App.xaml.cs` (part of default MAUI template, not the quick start guide) |
| 80 | +**Impact**: None - This is a template issue, not a guide issue |
| 81 | +**Note**: Not related to the Mapsui quick start instructions |
| 82 | + |
| 83 | +## What Works Well |
| 84 | + |
| 85 | +1. ✅ The guide structure is clear and easy to follow |
| 86 | +2. ✅ The code examples are accurate and work as written |
| 87 | +3. ✅ The SkiaSharp dependency explanation is helpful |
| 88 | +4. ✅ The troubleshooting section addresses known issues |
| 89 | +5. ✅ Step-by-step progression is logical |
| 90 | + |
| 91 | +## Recommendations for Documentation Updates |
| 92 | + |
| 93 | +### High Priority |
| 94 | +1. **Update .NET version from 7 to 9** in Step 1 |
| 95 | + - Current: "Create a new .NET 7.0 MAUI application" |
| 96 | + - Updated: "Create a new .NET 9.0 MAUI application" |
| 97 | + |
| 98 | +### Medium Priority |
| 99 | +2. **Add Prerequisites section**: |
| 100 | + ``` |
| 101 | + **Prerequisites:** |
| 102 | + - .NET 9.0 SDK or later installed |
| 103 | + - MAUI workload installed: `dotnet workload install maui` |
| 104 | + - For Visual Studio users: MAUI workload selected during installation |
| 105 | + ``` |
| 106 | + |
| 107 | +3. **Add CLI alternative for package installation** in Step 2: |
| 108 | + ``` |
| 109 | + **Option A (Package Manager Console in Visual Studio):** |
| 110 | + PM> Install-Package Mapsui.Maui |
| 111 | + |
| 112 | + **Option B (Command Line):** |
| 113 | + dotnet add package Mapsui.Maui |
| 114 | + ``` |
| 115 | + |
| 116 | +4. **Add note about platform requirements**: |
| 117 | + ``` |
| 118 | + **Note:** Building for iOS/MacCatalyst requires macOS with Xcode installed. |
| 119 | + Building for Windows requires Windows with Visual Studio. |
| 120 | + You can modify the target frameworks in the .csproj file if needed. |
| 121 | + ``` |
| 122 | + |
| 123 | +### Low Priority |
| 124 | +5. Consider adding a note about the implicit package reference warning in .NET 8+ |
| 125 | +6. Consider adding a screenshot of what the final result looks like |
| 126 | + |
| 127 | +## Testing Limitations |
| 128 | + |
| 129 | +⚠️ **Important**: I was unable to actually run the application because: |
| 130 | +- Running MAUI Android apps requires an Android emulator or device |
| 131 | +- Running on Linux in a headless environment doesn't support GUI applications |
| 132 | +- The build succeeds, which validates the code, but runtime behavior wasn't tested |
| 133 | + |
| 134 | +**Recommendation**: The guide should still add a note about what users should expect to see: |
| 135 | +``` |
| 136 | +**Step 5:** Run it and you should see a map of the world. |
| 137 | +- The map should display OpenStreetMap tiles |
| 138 | +- You should be able to pan and zoom the map |
| 139 | +- Initial view shows the entire world |
| 140 | +``` |
| 141 | + |
| 142 | +## Conclusion |
| 143 | + |
| 144 | +The MAUI quick start guide is well-written and the technical steps are accurate. The main issue is the **outdated .NET version reference (7.0 instead of 9.0)**, which you already identified. With this update and the additional prerequisites information, the guide will be more user-friendly and reduce confusion for new users. |
| 145 | + |
| 146 | +**Overall Assessment**: ⭐⭐⭐⭐ (4/5 stars) |
| 147 | +- Deducted one star for the outdated .NET version reference |
| 148 | +- Otherwise excellent, clear, and accurate documentation |
0 commit comments