01-10-2023 · 9 min lezen

MAUI Developer

Hoe je kunt bijdragen

WERKDOCUMENT!!

Dit project loopt nog en dit document wordt regelmatig bijgewerkt. Laatste update: 15-10-2023

.NET MAUI vanaf de broncode bouwen en integreren (op Windows)

Deze handleiding beschrijft de stappen om de .NET MAUI-repository vanaf de broncode te bouwen, te draaien en te integreren in je eigen applicatie op Windows. Let op: dit document is werk in uitvoering en kan nog wijzigen.

Platformcompatibiliteit: De stappen zijn getest op Windows 11.

VEREISTEN

Zorg voordat je begint dat je het volgende op orde hebt:

  • Windows 11 op een pc
  • De nieuwste versie van Visual Studio 22 Preview
  • GIT
  • Android SDK's

TODO: De optimale Mac-setup bepalen. Ik heb één Mac met macOS Ventura en één met Sonoma (de nieuwste versie, al wordt die nog niet officieel ondersteund door Visual Studio).

Voorbereiding

Broncode

Voordat je MAUI in je applicatie integreert, heb je de broncode nodig. Volg deze stappen:

  1. Ga naar https://github.com/dotnet/maui en fork het project naar je eigen GitHub-account met de knop "Fork".
  2. Clone het project naar je werkstation.
  3. Stel de upstream-repository in.
  4. Controleer de upstream-instelling.
Voorbeeld van het clonen van het project naar je werkstation:
cd  c:
cd mkdir src
cd src
git clone git@github.com:USERNAME/maui.git

Resultaat: c:\src\maui

Let op: ik raad een korte mappenstructuur op de C:-schijf aan vanwege de padlengtebeperkingen van Windows 11. In Windows 10 kun je korte padlengtes uitschakelen, maar in Windows 11 is die functie buggy. Dat kan tot problemen leiden, vooral met bepaalde packages zoals Plugin.Firebase, die op Windows 11 dan veel compileerfouten geven.

Voorbeeld van het instellen van de upstream-repository:
git remote add upstream https://github.com/dotnet/maui.git
Voorbeeld van het controleren van de upstream-instelling:
git remote -v

Houd je broncode actueel met de laatste upstream-wijzigingen

Maak er een gewoonte van om je broncode regelmatig bij te werken met de laatste wijzigingen uit de upstream-repository.

Voorbeeld:
git checkout main
git fetch upstream
git merge upstream/main

Omgevingsvariabelen

Om de tooling en scripts te vertellen waar de Android SDK op een Windows-systeem staat, maak je als volgt een omgevingsvariabele aan:

  1. Ga naar omgevingsvariabelen
  2. Voeg een gebruikersvariabele toe voor jouw gebruiker
    • Variabele: ANDROID_HOME
    • Waarde: LOCATIE_VAN_JE_SDK (bijvoorbeeld C:\Android\Sdk)
  3. Herstart Windows

Visual Studio

Zorg dat de benodigde SDK in Visual Studio is geïnstalleerd:

  1. Open Visual Studio Installer
  2. Kies Modify bij Visual Studio 2022 Preview.
  3. Ga naar het tabblad Individual Components en zoek op 20348.
  4. Selecteer Windows 10 SDK 10.0.20348.0
  5. Klik op modify

Bouwen

De volgende stap is het bouwen van de build-tasks, zodat commando's als cake beschikbaar komen in dotnet.

  1. Open een terminal (PowerShell, CMD of GitBash).
  2. Voer de volgende dotnet-commando's uit in de map van je git-checkout.
Voorbeeld:
cd c:
cd src/maui
dotnet tool restore
dotnet cake --target=VS --workloads=global

Problemen oplossen

Krijg je bij het uitvoeren van dotnet cake --target=VS --workloads=global een fout zoals:

FAILURE: Build failed with an exception.

  * What went wrong:
  Could not determine the dependencies of task ':maui:verifyReleaseResources'.

  > SDK location not found. Define location with an ANDROID_SDK_ROOT environment variable or by setting the sdk.dir   path in your project's local properties file at 'C:\src\maui\src\Core\AndroidNative\local.properties'.
Zo los je dit op:

Open C:\src\maui\Microsoft.Maui-dev.sln Deze solution wordt automatisch geopend als dotnet cake --target=VS --workloads=global klaar is. Controleer dat de omgevingsvariabele ANDROID_HOME (in Windows) naar de juiste map wijst, bijvoorbeeld C:\Android\Sdk. Die map is de hoofdmap voor alle Android SDK-onderdelen. Herstart je systeem na deze wijziging.

Meer informatie: https://developer.android.com/tools/variables

Validatie

Laten we nu een eerste controle doen of alles goed werkt. Als Visual Studio nog niet openstaat, start hem dan en open C:\src\maui\Microsoft.Maui-dev.sln

  1. Ga naar het menu build
  2. Klik op build solution

Let op: bij de eerste run kun je uitvoer zien als "Build: 57 succeeded, 12 failed, 0 up-to-date, 0 skipped." De mislukte projecten zijn waarschijnlijk voorbeeld- of testprojecten, met mogelijk deze fout:

Error NETSDK1047 Assets file '<PROJECT_PATH>\obj\project.assets.json' doesn't have a target for 'net7.0-ios/ios-arm64'. Ensure that restore has run and that you have included 'net7.0-ios' in the TargetFrameworks for your project. You may also need to include 'ios-arm64' in your project's RuntimeIdentifiers.

Met dank aan @vhugo voor de oplossing: voeg dit blok toe aan de .csproj-bestanden van de betreffende projecten:

<PropertyGroup Condition="'$(Configuration)|$(TargetFramework)|$(Platform)'=='Debug|net7.0-ios|AnyCPU'">
    <RuntimeIdentifier>ios-arm64</RuntimeIdentifier>
</PropertyGroup>

Houd er rekening mee dat deze aanpassing het draaien op simulators kan blokkeren, waardoor je een fysiek toestel nodig hebt.

Packagen

Als alles compileert, kun je wijzigingen in de broncode maken. Om een nieuwe workload te maken voor gebruik in je eigen applicatie gebruik je dotnet cake. Sluit Visual Studio en voer in een terminal de volgende commando's uit:

Voorbeeld:
cd "c:\src\maui"
dotnet tool restore
dotnet cake --target=VS --pack --sln="c:\src\MyApp\MyApp.sln" --verbose

Vervang c:\src\MyApp\MyApp.sln door het pad naar de solution van jouw applicatie.

Resultaat: Visual Studio opent nu je applicatie met de MAUI-workloads die je zojuist hebt gebouwd.

Je applicatie bouwen

Vanaf hier kun je je applicatie ontwikkelen en bouwen met de lokaal gepackagede MAUI-workloads. De eerste keer dat ik mijn applicatie wilde bouwen, liep ik tegen een paar fouten aan. Zie de sectie Problemen oplossen hieronder voor oplossingen.

Voorbeeld:

cd "c:\src\maui"
dotnet tool restore
dotnet cake --target=VS --pack --sln="c:\src\MyApp\MyApp.sln" --verbose

Problemen oplossen

Hier staan oplossingen voor problemen die je kunt tegenkomen bij het bouwen van je eigen applicatie met je eigen MAUI-versie:

Foutmeldingen

Het kan zijn dat je deze melding krijgt:

Error	XA1018	Specified AndroidManifest file does not exist: C:\src\MyApp\MyApp\AndroidManifest.xml.	C:\src\maui\bin\dotnet\packs\Microsoft.Android.Sdk.Windows\33.0.68\tools\Xamarin.Android.Common.targets	574

Er lijkt om onduidelijke redenen een probleem te zijn met het vinden van het AndroidManifest.xml-bestand op de verwachte plek Platforms\Android\AndroidManifest.xml. Ik heb hier (nog) geen oplossing voor. Een workaround is om Platforms\Android\AndroidManifest.xml handmatig naar de voorgestelde map te kopiëren.

Ontbrekende Android-emulators

Bij het starten van Visual Studio via het dotnet cake-commando bleken sommige Android-emulators te ontbreken. Na de kopieeractie hierboven verschenen de emulators weer in de lijst.

Dependencies (uitroepteken)

Bij het starten van Visual Studio met het dotnet cake-commando kan er een uitroepteken staan op het dependencies-icoon van net7.0-android33.0 en net7.0-ios. Het is onduidelijk of dat normaal is, aangezien we Visual Studio via een commando en met een eigen MAUI-workload-package hebben gestart.

Specifiek gaat het om de packages microsoft.Maui.Controls (7.0.100-dev) en microsoft.Maui.Controls.Compatibility (7.0.100-dev)

Na het kopiëren van het AndroidManifest.xml-bestand en het starten van de build kun je referentiefouten tegenkomen zoals:

Error	CS0246	The type or namespace name 'ContentPage' could not be found (are you missing a using directive or an assembly reference?)	MyApp (net7.0-android33.0), MyApp (net7.0-ios)	C:\src\MyApp\MyApp\MainPage.xaml.cs

Deze fouten komen waarschijnlijk voort uit de dependency-problemen waar het uitroepteken op wijst.

Daarnaast kun je een fout zien als:

Build started...
NuGet package restore failed. Please see Error List window for detailed warnings and errors.
Error occurred while restoring NuGet packages: Object reference not set to an instance of an object.

Om dit op te lossen leeg je eerst de NuGet-packagecache in Visual Studio:

  1. Ga naar het menu Tools
  2. Ga naar het submenu NuGet Package Manager
  3. Kies Package Manager Settings
  4. Klik in het optiemenu op Clear All NuGET storage

Sluit daarna Visual Studio en voer in Windows PowerShell dit commando uit:

dotnet cake --target=VS --pack --sln="c:\src\MyApp\MyApp.sln" --verbose

Visual Studio opent opnieuw. Ga naar de PowerShell binnen Visual Studio en voer deze commando's uit:

dotnet workload restore

Controleer of er iets zichtbaar is als 'Pack Microsoft.Maui.Sdk version 7.0.100-dev is already installed.' Daarna:

msbuild -t:restore
msbuild -t:build -restore
msbuild

TODO: Uitzoeken waarom dit niet in één commando werkt; msbuild -t:build -restore zou genoeg moeten zijn. Maar om de een of andere reden heeft het wat extra overtuigingskracht nodig :'-)

.NET 8.0

Wil je .NET 8.0 gebruiken voor MAUI, haal dan gewoon de nieuwste upstream/main-branch op! De main-branch draait inmiddels op .NET 8. Hoe controleer je dat? Ga naar de hoofdmap en open het bestand Directory.Build.props. Zoek daarin naar 'MauiDotNetVersionMajor'; de waarde hoort in de huidige versie 8 te zijn.

Vereisten

Zorg dat je de nieuwste versie van Visual Studio 2022 Preview hebt (ik heb getest met versie 17.8.0 Preview 2.0).

Voorbeeld:
cd "c:\src\maui"
git checkout main
git fetch upstream
git checkout -b MyFirstNet8MauiManualBuild upstream/main
git push -u origin

Wisselen vanaf een oudere .NET7-branch

Werk je met meerdere branches op verschillende .NET-versies, dan kan het wisselen daartussen allerlei problemen geven. Maak voor een soepele overgang de bin/Obj-mappen schoon en herstel je tools.

Voorbeeld:
cd "c:\src\maui"
git checkout MyBranchOnAnotherVersion
dotnet cake --clean
dotnet tool restore

Bouwen

Het bouwen en gebruiken van deze branch werkt hetzelfde als beschreven in de sectie Je applicatie bouwen hierboven. Mogelijk is er één extra stap nodig: dotnet restore.

In PowerShell (buiten Visual Studio):

Voorbeeld:
dotnet tool restore
dotnet cake --target=VS --workloads=global

Resultaat: Visual Studio opent met Microsoft.Maui-windows.slnf geladen.

Daarna, in het PowerShell-venster van Visual Studio:

Voorbeeld:
dotnet workload restore
dotnet restore

Nu zou je de broncode moeten kunnen bouwen. Mogelijk zijn er twee projecten die niet bouwen, maar dat lijkt voorlopig geen probleem. Wil je MAUI handmatig gebruiken, sluit dan Visual Studio en voer in Windows PowerShell dit commando uit:

dotnet cake --target=VS --pack --sln="c:\src\MyApp\MyApp.sln" --verbose

Problemen oplossen

Ik liep tegen de fout Unhandled exception: Microsoft.Build.Exceptions.InvalidProjectFileException: The imported project aan bij het draaien van dotnet restore aan het einde. Gelukkig gaf deze fout bij mij geen noemenswaardige problemen.

@TODO: Ik ga uitzoeken wat deze fout is, of hij opgelost moet worden en wat mogelijke oplossingen zijn.

Leesvoer

dotnet restore

Een .NET-project verwijst meestal naar externe libraries in NuGet-packages die extra functionaliteit leveren. Die externe dependencies staan in het projectbestand (.csproj of .vbproj). Als je het commando dotnet restore uitvoert, zoekt de .NET CLI deze dependencies via NuGet op en downloadt ze waar nodig.

Meer informatie: https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-restore

dotnet tool restore

Het commando dotnet tool restore zoekt het tool-manifestbestand dat geldt voor de huidige map en installeert de tools die daarin staan.

Meer informatie: https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-tool-restore

Cake

Cake (C# Make) is een gratis en open source cross-platform build-automatiseringssysteem met een C#-DSL voor taken als code compileren, bestanden en mappen kopiëren, unittests draaien, bestanden comprimeren en NuGet-packages bouwen.

Meer informatie: https://cakebuild.net/

dotnet cake

Cake .NET Tool is een runner waarmee je Cake-scripts kunt uitvoeren.

Meer informatie: https://cakebuild.net/docs/running-builds/runners/dotnet-tool

Handige commando's

Workloads tonen: dotnet workload list Geïnstalleerde dotnet SDK's tonen: dotnet --list-sdks

MAUI Developer
Bekijk alle verhalen →