Inbyggd AOT-distribution på iOS och Mac Catalyst

Native AOT-implementation genererar en .NET Multi-platform App UI (.NET MAUI)-app på iOS och Mac Catalyst som har sammanställts i förväg (AOT) till native kod. Native AOT utför statiska programanalys, fullständig optimering av din app, vilket är aggressivt när det gäller att ta bort kod som inte är statiskt refererad och förgenerering av kod.

När du publicerar och distribuerar en intern AOT-app får du följande fördelar:

• Minskad storlek på apppaket.
• Snabbare starttid.
• Snabbare byggtid.

Intern AOT medför begränsningar för användningen av vissa aspekter av .NET-körningen och bör endast användas i scenarier där appens storlek och prestanda är viktiga. Du måste anpassa dina appar till interna AOT-krav, vilket innebär att de är helt trimmade och AOT-kompatibla. Mer information om interna AOT-begränsningar finns i Interna AOT-begränsningar.

När den interna AOT-distributionen är aktiverad analyserar byggsystemet din kod och alla dess beroenden för att kontrollera om den är lämplig för fullständig trimning och AOT-kompilering. Om inkompatibiliteter identifieras skapas trimnings- och AOT-varningar. En enskild trimnings- eller AOT-varning innebär att appen inte är kompatibel med Native AOT-distribution och att den kanske inte fungerar korrekt. När du skapar en app för intern AOT-distribution bör du därför granska och korrigera alla trimnings- och AOT-varningar. Om du inte gör detta kan det leda till undantag vid körning eftersom nödvändig kod kan ha tagits bort. Om du undertrycker varningarna måste den AOT-distribuerade appen testas noggrant för att kontrollera att funktionaliteten inte har ändrats från den otrimmade appen. Mer information finns i Introduktion till trimningsvarningar och Introduktion till AOT-varningar.

Inbyggda AOT-prestandafördelar

När du publicerar och distribuerar en intern AOT-app skapas en app som vanligtvis är upp till 2,5 gånger mindre och en app som startar upp till 2 gånger snabbare. De exakta prestandafördelarna beror dock på flera faktorer som omfattar den plattform som används, den enhet som appen körs på och själva appen.

Följande diagram visar appaketstorleken för en dotnet new maui app på iOS och Mac Catalyst i olika distributionsmodeller:

Föregående diagram visar att intern AOT vanligtvis producerar mer än 2x mindre appar för både iOS och Mac Catalyst jämfört med standarddistributionsmodellen.

Följande diagram visar genomsnittlig starttid, på specifik maskinvara, för en dotnet new maui app på iOS och Mac Catalyst i Mono- och Native AOT-distribution:

Föregående diagram visar att intern AOT vanligtvis har upp till 2 gånger snabbare starttider på iOS-enheter och 1,2 gånger snabbare starttid på Mac Catalyst, jämfört med Mono-distribution.

Följande diagram visar den genomsnittliga byggtiden, på specifik maskinvara, för en dotnet new maui app på iOS och Mac Catalyst i olika distributionsmodeller:

Föregående diagram visar att vanligtvis intern AOT har upp till 2,8 gånger snabbare byggtider på iOS-enheter jämfört med standarddistributionsmodellen. För Mac Catalyst är byggtiderna jämförbara för enskilda ARM64-appar, men är något långsammare för universella appar jämfört med Mono-distribution.

Publicera med Native AOT

Den inhemska AOT-distributionsmodellen är aktiverad med byggegenskapen $(PublishAot) och kommandot dotnet publish. I följande exempel visas hur du ändrar en projektfil för att aktivera intern AOT-distribution på iOS och Mac Catalyst:

<PropertyGroup>
  <!-- enable trimming and AOT analyzers on all platforms -->
  <IsAotCompatible>true</IsAotCompatible>

  <!-- select platforms to use with NativeAOT -->
  <PublishAot Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios'">true</PublishAot>
  <PublishAot Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'maccatalyst'">true</PublishAot>
</PropertyGroup>

Om du ställer in byggegenskapen $(IsAotCompatible) på true, för alla plattformar, aktiveras trimning och AOT-analyzers. Dessa analysverktyg hjälper dig att identifiera kod som inte är kompatibel med trimning eller AOT.

Villkorsstyrd inställning $(PublishAot) till true, för iOS och Mac Catalyst, möjliggör dynamisk kodanvändningsanalys under kompilering och intern AOT-kompilering under publiceringen. Intern AOT-analys innehåller all appkod och alla bibliotek som appen är beroende av.

Det enda sättet att verifiera att en native AOT-app fungerar korrekt är att publicera den med dotnet publish och kontrollera att det inte finns några varningar för trimning eller AOT som genereras av koden och dess beroenden. I synnerhet dotnet build -t:Publish är inte ekvivalent med dotnet publish.

Använd följande dotnet publish kommando för att publicera din app på iOS och Mac Catalyst med hjälp av intern AOT-distribution:

# iOS
dotnet publish -f net9.0-ios -r ios-arm64

# Mac Catalyst
dotnet publish -f net9.0-maccatalyst -r maccatalyst-arm64
dotnet publish -f net9.0-maccatalyst -r maccatalyst-x64

# Universal Mac Catalyst apps
# (when <RuntimeIdentifiers>maccatalyst-x64;maccatalyst-arm64</RuntimeIdentifiers> is set in the project file)
dotnet publish -f net9.0-maccatalyst

Interna AOT-begränsningar

Intern AOT medför begränsningar för användningen av vissa aspekter av .NET-körningen och bör endast användas i scenarier där appens storlek och prestanda är viktiga. Det kräver att du anpassar dina appar till interna AOT-krav, vilket innebär att de är helt trimmade och AOT-kompatibla, och detta kan kräva mycket arbete. Förutom .NET-begränsningarna för intern AOT-distribution har intern AOT-distribution för .NET MAUI ytterligare begränsningar.

Bibliotek från tredje part som dina appar är beroende av kanske inte är AOT-kompatibla. Det enda sättet att se till att ett bibliotek är trimnings- och AOT-kompatibelt är att publicera din app med hjälp av Native AOT-distribution och dotnet publish kommandot och se om Native AOT-kompilatorn genererar några varningar för biblioteket. Information om hur du gör dina egna bibliotek AOT-kompatibla finns i Så här gör du bibliotek kompatibla med inbyggd AOT.

Reflektion och dynamisk kod

Native AOT-distribution begränsar användningen av reflektion i koden och dess beroenden, och det kan bli nödvändigt att använda annoteringar för att hjälpa den Native AOT-kompilatorn att förstå reflektionsmönster. När kompilatorn stöter på ett reflektionsmönster kan den inte analysera statiskt och därför inte kan skapa appen, den skapar trimvarningar. Intern AOT hindrar dig också från att använda dynamisk kod i din app. Kompilering System.Linq.Expressions fungerar till exempel inte som förväntat och det går inte att läsa in och köra assemblies vid körning. När kompilatorn stöter på ett dynamiskt mönster som den inte kan kompilera i förväg, kommer den att ge en AOT-varning.

I .NET MAUI-appen innebär det att:

• Alla XAML måste kompileras i förväg. Se därför till att du inte har inaktiverat XAML-kompilering och att alla bindningar kompileras. Mer information finns i XAML-kompilering och kompilerade bindningar.
• Alla bindningsuttryck måste använda kompilerade bindningar i stället för en bindningssökväg som är inställd på en sträng. Mer information finns i Kompilerade bindningar.
• Implicita konverteringsoperatorer kanske inte anropas när du tilldelar ett värde av en inkompatibel typ till en egenskap i XAML, eller när två egenskaper av olika typer använder en databindning. I stället bör du definiera en TypeConverter för din typ och koppla den till typen med hjälp av TypeConverterAttribute. Mer information finns i Definiera en TypeConverter för att ersätta en implicit konverteringsoperator.
• Det går inte att parsa XAML vid exekvering med LoadFromXaml-metoden. Detta kan göras säkert genom att annotera alla typer som kan läsas in vid körning med DynamicallyAccessedMembers-attributet eller DynamicDependency-attributet, men detta är mycket felbenäget och rekommenderas inte.
• Att ta emot navigeringsdata med hjälp av QueryPropertyAttribute fungerar inte. I stället bör du implementera IQueryAttributable-gränssnittet på typer som måste acceptera frågeparametrar. Mer information finns i Bearbeta navigeringsdata med en enda metod.
• Egenskapen SearchHandler.DisplayMemberName kanske inte fungerar. I stället bör du ange en ItemTemplate för att definiera resultatets SearchHandler utseende. Mer information finns i Definiera sökresultatobjektets utseende.
• Det går inte att anpassa användargränssnittets OnPlatform utseende med XAML-markeringstillägget. I stället bör du använda OnPlatform<T> klassen . Mer information finns i Anpassa användargränssnittets utseende baserat på plattformen.
• Det går inte att anpassa användargränssnittets OnIdiom utseende med XAML-markeringstillägget. I stället bör du använda OnIdiom<T> klassen . Mer information finns i Anpassa användargränssnittets utseende baserat på enhetens formspråk.

Mer information om trimvarningar finns i Introduktion till trimningsvarningar. Mer information om AOT-varningar finns i Introduktion till AOT-varningar.

Anpassa en app till intern AOT-distribution

Använd följande checklista för att anpassa din app till interna AOT-distributionskrav:

Inbyggt AOT-diagnostikstöd för iOS och Mac Catalyst

Native AOT och Mono delar en delmängd av funktioner för diagnostik och instrumentering. På grund av Monos utbud av diagnostikverktyg kan det vara fördelaktigt att diagnostisera och felsöka problem i Mono i stället för intern AOT. Appar som är trimnings- och AOT-kompatibla bör inte ha beteendemässiga skillnader, så undersökningar gäller ofta för båda runtime-miljöerna.

I följande tabell visas diagnostikstöd med intern AOT på iOS och Mac Catalyst:

Följande avsnitt innehåller ytterligare information om det här diagnostikstödet.

Observerbarhet och telemetri

Spårning av .NET MAUI-program på mobila plattformar aktiveras via dotnet-dsrouter som ansluter diagnostikverktyg med .NET-program som körs på iOS och Mac Catalyst, via TCP/IP. Intern AOT är dock för närvarande inte kompatibelt med det här scenariot eftersom det inte stöder EventPipe/DiagnosticServer-komponenter som skapats med TCP/IP-stacken. Observerbarhet kan fortfarande uppnås uttryckligen i koden.

Diagnostik under utvecklingsfasen

.NET CLI-verktyg innehåller separata kommandon för build och publish. dotnet build (eller Start Debugging (F5) i Visual Studio Code) använder Mono som standard när du skapar eller startar .NET MAUI iOS- eller Mac Catalyst-program. Endast dotnet publish skapar ett internt AOT-program om den här distributionsmodellen är aktiverad i projektfilen.

Alla diagnostikverktyg fungerar inte sömlöst med publicerade interna AOT-program. Men alla program som är trimnings- och AOT-kompatibla (dvs. de som inte producerar några trim- och AOT-varningar vid byggtiden) bör inte ha beteendemässiga skillnader mellan Mono och Native AOT. Därför är alla diagnostikverktyg för .NET-utvecklingstid, till exempel Hot Reload, fortfarande tillgängliga för utvecklare under utvecklingscykeln för mobilprogram.

Inbyggd felsökning

När du kör .NET MAUI iOS- eller Mac Catalyst-programmet under utvecklingen körs det som standard på Mono. Men om Native AOT-distribution är aktiverad i projektfilen förväntas beteendet vara detsamma mellan Mono och Native AOT när programmet inte producerar några trim- och AOT-varningar under byggtiden. Förutsatt att ditt program uppfyller detta krav kan du använda visual Studio Code-standardmotorn för hanterad felsökning för utveckling och testning.

Efter publiceringen är Native AOT-applikationer äkta inbyggda binärfiler, så det hanterade felsökningsprogrammet fungerar inte med dem. Den interna AOT-kompilatorn genererar dock helt inbyggda körbara filer som du kan felsöka med lldb. Felsökningen av en Mac Catalyst-app med lldb sker direkt eftersom den körs i samma system. Felsökning av NativeAOT iOS-program kräver dock ytterligare arbete.

Felsöka .NET MAUI iOS-program med intern AOT

.NET MAUI iOS-program som är kompatibla med intern AOT och som är korrekt konfigurerade och publicerade med den här distributionsmodellen kan debuggas på följande sätt:

1. Publicera din app med intern AOT-inriktning ios-arm64 och notera följande information:

   • Programnamn (refereras nedan som <app-name>).
   • Paketidentifierare (refereras nedan som <bundle-identifier>).
   • Sökväg till det publicerade programmets .ipa-arkivfil (refereras nedan som <path-to-ipa>).

2. Hämta ditt fysiska enhets-ID (se nedan som <device-identifier>):

   xcrun devicectl list devices
   

3. Installera appen på din fysiska enhet:

   xcrun devicectl device install app --device <device-identifier> <path-to-ipa>
   

4. Starta appen på din fysiska enhet:

   xcrun devicectl device process launch --device <device-identifier> --start-stopped <bundle-identifier>
   

5. Öppna lldb och anslut till din fysiska enhet:

   (lldb) device select <device-identifier>
   (lldb) device process attach -n <app-name>
   

När du har slutfört de här stegen kan du börja felsöka ditt interna AOT .NET MAUI iOS-program med lldb.

Symbolfilens betydelse

Som standard tas felsökningssymbolerna bort från programmets binära fil till en .dSYM-fil . Den här filen används av felsökningsverktyg och verktyg för post mortem-analys för att visa information om lokala variabler, radnummer i källkod, och för att återskapa stacktraceringar av kraschdumpar. Därför är det viktigt att bevara symbolfilen innan du skickar programmet till App Store.

CPU-profilering

Xcode-instrument kan användas för att samla in CPU-exempel på ett internt AOT-program.

Heapanalys

Heap-analys stöds just nu inte med Native AOT.

Se även

• Optimera en .NET MAUI app