Een .NET MAUI Android-app koppelen

Wanneer de app wordt gebouwd, kan .NET Multi-Platform App UI (.NET MAUI) een linker gebruiken die ILLink wordt genoemd om de totale grootte van de app te verminderen. ILLink verkleint de grootte door de tussenliggende code te analyseren die door de compiler wordt geproduceerd. Hiermee worden ongebruikte methoden, eigenschappen, velden, gebeurtenissen, structs en klassen verwijderd om een app te produceren die alleen code- en assemblyafhankelijkheden bevat die nodig zijn om de app uit te voeren.

Linkergedrag

Met de linker kunt u uw .NET MAUI Android-apps knippen. Wanneer bijsnijden is ingeschakeld, laat de linker uw assembly's ongewijzigd en vermindert de grootte van de SDK-assembly's door typen en leden te verwijderen die uw app niet gebruikt.

Linkergedrag kan worden geconfigureerd voor elke build-configuratie van uw app. Bijsnijden is standaard uitgeschakeld voor foutopsporingsversies en ingeschakeld voor release-builds.

Waarschuwing

Als u de linker inschakelt voor de configuratie van foutopsporing in uw app, kan dit uw ervaring met foutopsporing belemmeren, omdat het eigenschapstoegangen kan verwijderen waarmee u de status van uw objecten kunt controleren.

Zorg ervoor dat bijsnijden is ingeschakeld:

1. Klik in Visual Studio in Solution Explorermet de rechtermuisknop op uw .NET MAUI-app-project en selecteer Eigenschappen. Navigeer vervolgens naar het tabblad Android->-opties en zorg ervoor dat bijsnijden is ingeschakeld voor de buildconfiguratie van de release:

   

Code behouden

Wanneer u de trimmer gebruikt, wordt soms de code verwijderd die u mogelijk dynamisch of zelfs indirect hebt aangeroepen. U kunt de trimmer instrueren om leden te behouden door aantekeningen te maken met het kenmerk DynamicDependency. Dit kenmerk kan worden gebruikt om een afhankelijkheid uit te drukken op een type en subset van leden, of bij specifieke leden.

Belangrijk

Elk lid in de BCL dat niet statisch kan worden bepaald om door de app te worden gebruikt, moet worden verwijderd.

Het kenmerk DynamicDependency kan worden toegepast op constructors, velden en methoden:

[DynamicDependency("Helper", "MyType", "MyAssembly")]
static void RunHelper()
{
    var helper = Assembly.Load("MyAssembly").GetType("MyType").GetMethod("Helper");
    helper.Invoke(null, null);
}

In dit voorbeeld zorgt de DynamicDependency ervoor dat de methode Helper wordt bewaard. Zonder het kenmerk wordt Helper uit MyAssembly verwijderd of wordt MyAssembly volledig verwijderd als er elders niet naar wordt verwezen.

Het kenmerk specificeert het lid dat moet worden bewaard via een string of via het kenmerk DynamicallyAccessedMembers. Het type en de assembly zijn impliciet in de kenmerkcontext of expliciet opgegeven in het kenmerk (door Typeof door strings voor het type en de assemblynaam).

Het type en de lidstrings gebruiken een variatie van de opmerking-ID-tekenreeks in het C#-documentatieformaat , zonder het ledenvoorvoegsel. De lidnaam mag niet de naam van het declaratietype bevatten en kan parameters weglaten om alle leden met de opgegeven naam weer te geven. In de volgende voorbeelden worden geldige toepassingen weergegeven:

[DynamicDependency("Method()")]
[DynamicDependency("Method(System,Boolean,System.String)")]
[DynamicDependency("MethodOnDifferentType()", typeof(ContainingType))]
[DynamicDependency("MemberName")]
[DynamicDependency("MemberOnUnreferencedAssembly", "ContainingType", "UnreferencedAssembly")]
[DynamicDependency("MemberName", "Namespace.ContainingType.NestedType", "Assembly")]
// generics
[DynamicDependency("GenericMethodName``1")]
[DynamicDependency("GenericMethod``2(``0,``1)")]
[DynamicDependency("MethodWithGenericParameterTypes(System.Collections.Generic.List{System.String})")]
[DynamicDependency("MethodOnGenericType(`0)", "GenericType`1", "UnreferencedAssembly")]
[DynamicDependency("MethodOnGenericType(`0)", typeof(GenericType<>))]

Assemblages behouden

Het is mogelijk om assembly's op te geven die moeten worden uitgesloten van het bijsnijdproces, terwijl andere assembly's kunnen worden ingekort. Deze methode kan handig zijn wanneer u het kenmerk DynamicDependency niet eenvoudig kunt gebruiken of de code die wordt ingekort niet kunt beheren.

Wanneer alle assembly's worden bijgesneden, kunt u de trimmer vertellen een assembly over te slaan door een TrimmerRootAssembly MSBuild-item in het projectbestand in te stellen:

<ItemGroup>
  <TrimmerRootAssembly Include="MyAssembly" />
</ItemGroup>

Notitie

De .dll-extensie is niet vereist bij het instellen van de eigenschap TrimmerRootAssembly MSBuild.

Als de trimmer een assembly overslaat, wordt het beschouwd als geroot, wat betekent dat het en alle statisch bekende afhankelijkheden worden bewaard. U kunt extra assemblies overslaan door meer TrimmerRootAssembly MSBuild-eigenschappen toe te voegen aan <ItemGroup>.

Assemblages, typen en leden behouden

U kunt een XML-beschrijvingsbestand doorgeven aan de trimmer, dat aangeeft welke assemblies, typen en leden moeten worden bewaard.

Als u een lid wilt uitsluiten van het bijsnijden tijdens het bijsnijden van alle assembly's, stelt u het TrimmerRootDescriptor MSBuild-item in het projectbestand in op het XML-bestand dat de leden definieert die moeten worden uitgesloten:

<ItemGroup>
  <TrimmerRootDescriptor Include="MyRoots.xml" />
</ItemGroup>

Het XML-bestand gebruikt vervolgens de trimmer descriptor-indeling om te definiëren welke leden moeten worden uitgesloten:

<linker>
  <assembly fullname="MyAssembly">
    <type fullname="MyAssembly.MyClass">
      <method name="DynamicallyAccessedMethod" />
    </type>
  </assembly>
</linker>

In dit voorbeeld geeft het XML-bestand een methode op die dynamisch wordt geopend door de app, die wordt uitgesloten van bijsnijden.

Wanneer een assembly, type of lid wordt vermeld in de XML, is de standaardactie behoud, wat betekent dat, ongeacht of de trimmer denkt dat het wordt gebruikt of niet, het behouden blijft in de uitvoer.

Notitie

De bewarings-tags zijn op een dubbelzinnige manier inclusief. Als u het volgende niveau van detail niet opgeeft, worden alle bijbehorende elementen opgenomen. Als een assembly zonder type wordt weergegeven, blijven alle typen en leden van de assembly behouden.

Een samenstelling markeren als veilig voor inkorting

Als u een bibliotheek in uw project hebt of als u een ontwikkelaar bent van een herbruikbare bibliotheek en u wilt dat de trimmer uw assembly als bijsnijdbaar behandelt, kunt u de assembly als trim veilig markeren door de eigenschap IsTrimmable MSBuild toe te voegen aan het projectbestand voor de assembly:

<PropertyGroup>
    <IsTrimmable>true</IsTrimmable>
</PropertyGroup>

Hiermee markeert u de assembly als 'trimmable' en schakelt u trimwaarschuwingen voor dat project in. "‘Trimmable’ zijn betekent dat uw assembly als compatibel wordt beschouwd met trimmen en geen trimwaarschuwingen mag hebben tijdens het bouwen van de assembly." Wanneer deze wordt gebruikt in een bijgesneden app, worden de ongebruikte leden van de assembly verwijderd in de uiteindelijke uitvoer.

Wanneer u systeemeigen AOT-implementatie gebruikt in .NET 9+, stelt u de eigenschap IsAotCompatible MSBuild in op true wijst u ook een waarde van true toe aan de eigenschap IsTrimmable en schakelt u extra build-eigenschappen van AOT Analyzer in. Zie AOT-compatibiliteitsanalysatorenvoor meer informatie over AOT-analysatoren. Voor meer informatie over Native AOT-implementatie voor .NET MAUI, zie Native AOT-implementatie.

Als u de eigenschap IsTrimmable MSBuild instelt op true in uw projectbestand, wordt het kenmerk AssemblyMetadata in uw assembly ingevoegd:

[assembly: AssemblyMetadata("IsTrimmable", "True")]

U kunt ook het kenmerk AssemblyMetadata aan uw assembly toevoegen zonder dat u de eigenschap IsTrimmable MSBuild hebt toegevoegd aan het projectbestand voor uw assembly.

Notitie

Als de MSBuild-eigenschap IsTrimmable voor een assembly is ingesteld, overschrijft dit het kenmerk AssemblyMetadata("IsTrimmable", "True"). Hiermee kunt u een assembly kiezen voor bijsnijden, zelfs als deze niet beschikt over het kenmerk of om het bijsnijden van een assembly met het kenmerk uit te schakelen.

Analysewaarschuwingen onderdrukken

Wanneer de trimmer is ingeschakeld, wordt IL verwijderd die niet statisch bereikbaar is. Apps die gebruikmaken van weerspiegeling of andere patronen die dynamische afhankelijkheden maken, kunnen hierdoor worden verbroken. Als u een waarschuwing wilt geven over dergelijke patronen, moeten bibliotheekauteurs bij het markeren van een assembly als 'trim safe' de eigenschap SuppressTrimAnalysisWarnings MSBuild instellen op false:

<PropertyGroup>
  <SuppressTrimAnalysisWarnings>false</SuppressTrimAnalysisWarnings>
</PropertyGroup>

Het onderdrukken van trimanalysewaarschuwingen bevat waarschuwingen over de hele app, inclusief uw eigen code, bibliotheekcode en SDK-code.

Gedetailleerde waarschuwingen weergeven

Bij trimanalyse wordt maximaal één waarschuwing gegenereerd voor elke assembly die afkomstig is van een PackageReference, wat aangeeft dat de interne onderdelen van de assembly niet compatibel zijn met bijsnijden. Wanneer u als schrijver van een bibliotheek een assembly als trimveilig markeert, dient u afzonderlijke waarschuwingen voor alle assembly's in te schakelen door de eigenschap TrimmerSingleWarn MSBuild in te stellen op false:

<PropertyGroup>
  <TrimmerSingleWarn>false</TrimmerSingleWarn>
</PropertyGroup>

Met deze instelling worden alle gedetailleerde waarschuwingen weergegeven, in plaats van ze samen te vouwen tot één waarschuwing per assembly.