Delen via

Een .NET MAUI iOS-app koppelen

  • Artikel

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

De linker ondersteunt drie modussen voor .NET MAUI-apps op iOS en Mac Catalyst.

  • Koppelniet. Als u koppelingen uitschakelt, zorgt u ervoor dat assembly's niet worden gewijzigd.
  • Koppel alleen SDK-assemblies. In deze modus 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.
  • Alle assemblies koppelen. Wanneer alle assembly's worden gekoppeld, voert het verbindingsprogramma extra optimalisaties uit om uw app zo klein mogelijk te maken. Het wijzigt de tussenliggende code voor uw broncode, waardoor uw app mogelijk stukgaat als u functies gebruikt met een benadering die de statische analyse van de linker niet kan detecteren. In dergelijke gevallen moet u mogelijk aanpassingen aan uw broncode aanbrengen om uw app correct te laten werken.

Linkergedrag kan worden geconfigureerd voor elke buildconfiguratie van uw app.

Waarschuwing

Als u de linker inschakelt voor de foutopsporingsconfiguratie van uw app, kan dit uw foutopsporingservaring belemmeren, omdat hiermee eigenschappentoegangsmethoden kunnen worden verwijderd waarmee u de status van uw objecten kunt inspecteren.

Linkergedrag configureren in Visual Studio:

  1. Klik in Solution Explorer met de rechtermuisknop op uw .NET MAUI-app-project en selecteer Eigenschappen. Navigeer vervolgens naar het tabblad iOS > Build en stel de vervolgkeuzelijst voor het linker-gedrag in op het gewenste linkergedrag.

    schermopname van het linkergedrag voor iOS in Visual Studio.

Code behouden

Wanneer u de trimmer gebruikt, wordt soms de code verwijderd die u mogelijk zelfs indirect dynamisch 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 MyAssembly volledig verwijderd als er elders niet naar wordt verwezen.

Het kenmerk specificeert het lid dat behouden moet blijven 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 opmerkings-ID-tekenreeks van de C#-documentatie in formaat , zonder het lidvoorvoegsel. De ledenstring mag de naam van het type waarin het wordt gedeclareerd niet bevatten en mag parameters weglaten om alle leden met de opgegeven naam te matchen. 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 deze beschouwd als geroot, wat betekent dat zowel deze als alle statisch begrepen afhankelijkheden behouden blijven. U kunt extra assemblages overslaan door extra TrimmerRootAssembly MSBuild-eigenschappen toe te voegen aan de <ItemGroup>.

Assemblages, typen en leden bewaren

U kunt een XML-beschrijvingsbestand aan de trimmer doorgeven 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 element wordt vermeld in de XML, is de standaardactie behoud, wat betekent dat, ongeacht of de trimmer denkt dat het wordt gebruikt of niet, deze in de uitvoer behouden blijft.

Notitie

De beheer tags zijn op een dubbelzinnige manier alomvattend. Als u het volgende detailniveau niet opgeeft, worden alle kinderen opgenomen. Als een assembly zonder typen wordt vermeld, blijven alle typen en leden van de assembly behouden.

Een samenstelling als trimveilig markeren

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 "knipbaar" en worden trimwaarschuwingen voor dat project ingeschakeld. Trimmable zijn betekent dat uw assemblage als compatibel wordt geacht met het bijsnijden en geen bijsnijwaarschuwingen mag hebben wanneer de assemblage wordt samengesteld. 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. Voor meer informatie over AOT-analyzers, zie AOT-compatibiliteitsanalyzers. 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 eigenschap IsTrimmable MSBuild is ingesteld voor een assembly, wordt het kenmerk AssemblyMetadata("IsTrimmable", "True") overschreven. 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 trimveilig de eigenschap SuppressTrimAnalysisWarnings MSBuild instellen op false.

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

Het niet onderdrukken van trimanalysewaarschuwingen zal waarschuwingen bevatten 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 auteur van een bibliotheek een assembly als veilig markeert, moet u afzonderlijke waarschuwingen voor alle assembly's inschakelen 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.