Dela via

Länka en .NET MAUI iOS-app

  • Artikel

När den skapar din app kan .NET Multi-Platform App UI (.NET MAUI) använda en länkare med namnet ILLink för att minska appens totala storlek. ILLink minskar storleken genom att analysera den mellanliggande kod som kompilatorn producerar. Den tar bort oanvända metoder, egenskaper, fält, händelser, structs och klasser för att skapa en app som endast innehåller kod- och sammansättningsberoenden som krävs för att köra appen.

Linker-beteende

Länkaren stöder tre lägen för .NET MAUI-appar på iOS och Mac Catalyst:

  • Länka inte. Om du inaktiverar länkning ser du till att sammansättningar inte ändras.
  • Endast länka SDK-bibliotek. I det här läget lämnar länkaren dina sammansättningar orörda och minskar storleken på SDK-sammansättningarna genom att ta bort typer och medlemmar som appen inte använder.
  • Länka alla sammansättningar. När den länkar alla sammansättningar utför länkaren ytterligare optimeringar för att göra appen så liten som möjligt. Den ändrar den mellanliggande koden för källkoden, vilket kan bryta din app om du använder funktioner med en metod som länkarens statiska analys inte kan identifiera. I dessa fall kan du behöva göra justeringar i källkoden för att appen ska fungera korrekt.

Linker-beteende kan konfigureras för varje byggkonfiguration av din app.

Varning

Om du aktiverar länkaren för appens felsökningskonfiguration kan det hindra felsökningen eftersom det kan ta bort egenskapsåtkomster som gör att du kan kontrollera tillståndet för dina objekt.

Så här konfigurerar du länkningsbeteende i Visual Studio:

  1. I Solution Explorer högerklicka på ditt .NET MAUI-appprojekt och välj Egenskaper. Navigera sedan till fliken iOS > Build och ställ in listrutan Linker-beteende till önskat länkbeteende.

    Skärmbild av länkningsbeteendet för iOS i Visual Studio.

Bevara kod

När du använder trimmern tar den ibland bort kod som du kanske har anropat dynamiskt, även indirekt. Du kan instruera trimmern att bevara medlemmar genom att kommentera dem med attributet DynamicDependency. Det här attributet kan användas för att uttrycka ett beroende av antingen en typ och delmängd av medlemmar eller för specifika medlemmar.

Viktig

Alla medlemmar i BCL:n som inte kan fastställas statiskt för att användas av appen måste tas bort.

Attributet DynamicDependency kan tillämpas på konstruktorer, fält och metoder:

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

I det här exemplet ser DynamicDependency till att metoden Helper behålls. Utan attributet skulle trimning ta bort Helper från MyAssembly eller ta bort MyAssembly helt om det inte refereras någon annanstans.

Attributet anger vilken medlem som ska behållas via en string eller via attributet DynamicallyAccessedMembers. Typen och sammansättningen är antingen implicita i attributkontexten eller anges uttryckligen i attributet (efter Type, eller av strings för typen och sammansättningsnamnet).

Typ- och medlemssträngarna använder en variant av C#-dokumentationens kommentars-ID-sträng format, utan medlemsprefixet. Medlemssträngen ska inte innehålla namnet på deklareringstypen och kan utelämna parametrar för att behålla alla medlemmar i det angivna namnet. I följande exempel visas giltiga användningsområden:

[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<>))]

Bevara sammansättningar

Det går att ange sammansättningar som ska undantas från trimningsprocessen, samtidigt som andra sammansättningar kan trimmas. Den här metoden kan vara användbar när du inte enkelt kan använda attributet DynamicDependency eller inte styr koden som trimmas.

När den trimmar alla sammansättningar kan du be trimmern att hoppa över en sammansättning genom att ange ett TrimmerRootAssembly MSBuild-objekt i projektfilen:

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

Note

Det .dll tillägget krävs inte när du anger egenskapen TrimmerRootAssembly MSBuild.

Om trimmern hoppar över en samling anses den vara rotad, vilket innebär att den och alla dess statiskt förstådda beroenden behålls. Du kan hoppa över ytterligare sammansättningar genom att lägga till fler TrimmerRootAssembly MSBuild-egenskaper i <ItemGroup>.

Bevara sammansättningar, typer och medlemmar

Du kan ge trimmern en XML-beskrivningsfil som anger vilka assemblies, typer och medlemmar som måste behållas.

Om du vill undanta en medlem från trimningsprocessen när du trimmar alla sammansättningar anger du det TrimmerRootDescriptor MSBuild-objektet i projektfilen till XML-filen som definierar vilka medlemmar som ska undantas:

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

XML-filen använder sedan trimmer-beskrivande format för att definiera vilka medlemmar som ska undantas:

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

I det här exemplet anger XML-filen en metod som används dynamiskt av appen, vilket utesluts från trimning.

När en sammansättning, typ eller medlem visas i XML är standardåtgärden bevarande, vilket innebär att oavsett om trimmern tror att den används eller inte bevaras den i utdata.

Not

Bevarandetaggar är tvetydigt inkluderande. Om du inte anger nästa detaljnivå kommer den att innehålla alla underordnade. Om en sammansättning visas utan några typer bevaras alla sammansättningstyper och medlemmar.

Markera en sammansättning som trimsäker

Om du har ett bibliotek i projektet, eller om du är utvecklare av ett återanvändbart bibliotek och du vill att trimmern ska behandla sammansättningen som trimmad, kan du markera sammansättningen som trimsäker genom att lägga till egenskapen IsTrimmable MSBuild i projektfilen för sammansättningen:

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

Detta markerar din sammansättning som "trimmningsbar" och aktiverar trimvarningar för det projektet. Att vara "trimmingsbar" innebär att din sammansättning anses vara kompatibel med trimning och inte bör ha några trimvarningar när sammansättningen byggs. När de används i en trimmad app tas sammansättningens oanvända medlemmar bort i de slutliga utdata.

När du använder Native AOT-distribution i .NET 9+ tilldelar inställningen MSBuild-egenskapen IsAotCompatible till true, vilket också tilldelar värdet true till egenskapen IsTrimmable och aktiverar ytterligare AOT-analyskompilatoregenskaper. Mer information om AOT-analysverktyg finns i AOT-kompatibilitetsanalysverktyg. Mer information om Native AOT-distribution för .NET MAUI finns i Native AOT-distribution.

Om du anger egenskapen IsTrimmable MSBuild till true i projektfilen infogas attributet AssemblyMetadata i sammansättningen:

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

Du kan också lägga till attributet AssemblyMetadata i sammansättningen utan att ha lagt till egenskapen IsTrimmable MSBuild i projektfilen för din sammansättning.

Obs.

Om egenskapen IsTrimmable MSBuild har angetts för en sammansättning åsidosätter detta attributet AssemblyMetadata("IsTrimmable", "True"). På så sätt kan du välja en sammansättning till trimning även om den inte har attributet eller att inaktivera trimning av en sammansättning som har attributet.

Ignorera analysvarningar

När trimmern är aktiverad tar den bort IL som inte kan nås statiskt. Appar som använder reflektion eller andra mönster som skapar dynamiska beroenden kan därför brytas. För att varna för sådana mönster bör biblioteksförfattare, när de markerar en sammansättning som trimsäker, ange MSBuild-egenskapen SuppressTrimAnalysisWarnings som false.

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

Att inte undertrycka varningar för trimanalys kommer att inkludera varningar för hela appen, inklusive din egen kod, bibliotekskod och SDK-kod.

Visa detaljerade varningar

Trimanalys ger högst en varning för varje sammansättning som kommer från en PackageReference, vilket indikerar att sammansättningens interna enheter inte är kompatibla med trimning. När du som biblioteksförfattare markerar en sammansättning som trimsäker bör du aktivera enskilda varningar för alla sammansättningar genom att ange egenskapen TrimmerSingleWarn MSBuild till false:

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

Den här inställningen visar alla detaljerade varningar i stället för att komprimera dem till en enda varning per sammansättning.