Delen via

Een .NET MAUI Mac Catalyst-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 koppelingstool ondersteunt drie modi voor .NET MAUI-apps op iOS en Mac Catalyst.

  • Koppelniet. Als u koppelingen uitschakelt, zorgt u ervoor dat assembly's niet worden gewijzigd.
  • Alleen SDK-assemblies koppelen. 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 assemblages koppelen. Wanneer alle assembly's worden gekoppeld, voert de koppelaar extra optimalisaties uit om uw app zo klein mogelijk te maken. Hiermee wijzigt u de tussenliggende code voor uw broncode, waardoor uw app mogelijk niet meer werkt als u functies gebruikt door een aanpak te hanteren 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 bouwconfiguratie van uw app.

Waarschuwing

Als u de linker inschakelt voor de debugconfiguratie van uw app, kan dit uw debugervaring beïnvloeden, omdat hiermee eigenschapsaccesseurs kunnen worden verwijderd die u in staat stellen de status van uw objecten te inspecteren.

Als u het linkergedrag in Visual Studio Code wilt configureren, moet u de eigenschap $(MtouchLink) build toevoegen aan een eigenschapsgroep in het bestand .csproj van uw app. Deze build-eigenschap moet worden ingesteld op None, SdkOnlyof Full:

<PropertyGroup Condition="'$(Configuration)|$(TargetFramework)|$(Platform)'=='Debug|net8.0-maccatalyst|AnyCPU'">
  <MtouchLink>SdkOnly</MtouchLink>
</PropertyGroup>

U kunt ook het linkergedrag opgeven via de CLI bij het bouwen en publiceren van uw app. Zie voor meer informatie Een .NET MAUI Mac Catalyst-app publiceren.

Belangrijk

De eigenschap $(MtouchLink) build kan afzonderlijk worden ingesteld voor elke buildconfiguratie voor uw app.

Code behouden

Wanneer je de trimmer gebruikt, verwijdert deze soms code die je mogelijk dynamisch, 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 zou het bijwerken Helper uit MyAssembly verwijderen of MyAssembly volledig verwijderen als er nergens anders naar wordt verwezen.

Het kenmerk geeft het lid op 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 lidtekenreeksen gebruiken een variatie van de tekenreeks voor opmerkings-id van de C#-documentatie indeling, zonder het lidvoorvoegsel. De string van het lid mag de naam van het declaratietype niet bevatten en kan parameters weglaten om alle leden met de opgegeven naam te behouden. 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 assembly's overslaan door meer TrimmerRootAssembly MSBuild-eigenschappen toe te voegen aan de <ItemGroup>.

Assemblies, typen en leden bewaren

U kunt een XML-beschrijvingsbestand aan de trimmer doorgeven dat aangeeft welke assembly's, 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 preserveren de standaardactie, wat betekent dat, ongeacht of de trimmer denkt dat het wordt gebruikt of niet, het behouden blijft in de uitvoer.

Notitie

De behoudtags zijn op een dubbelzinnige manier inclusief. Als u het volgende detailniveau niet opgeeft, worden alle subelementen opgenomen. Als een assembly zonder typen wordt weergegeven, blijven alle typen en leden van de assembly behouden.

Een assemblage markeren als veilig voor trimmen

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. Als een assembly 'trimmable' is, wordt deze als compatibel beschouwd met trimmen en mogen er geen trimwaarschuwingen zijn bij het bouwen van de assembly. Wanneer deze wordt gebruikt in een ingekorte app, worden de ongebruikte onderdelen 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. Raadpleeg AOT-compatibiliteitsanalyzersvoor meer informatie over AOT-analyzers. Voor meer informatie over systeemeigen 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 IsTrimmable MSBuild-eigenschap is ingesteld voor een assembly, overschrijft dit het AssemblyMetadata("IsTrimmable", "True")-kenmerk. 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. Om te waarschuwen voor 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 niet onderdrukken van trimanalysewaarschuwingen zal waarschuwingen bevatten over de gehele 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 voor trimming markeert, moet u afzonderlijke waarschuwingen voor alle assembly's inschakelen door de MSBuild-eigenschap TrimmerSingleWarn 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.