Propojení aplikace .NET MAUI Mac Catalyst

Při sestavování vaší aplikace může uživatelské rozhraní .NET Multi-platform App UI (.NET MAUI) použít linker ILLink ke snížení celkové velikosti aplikace. ILLink zmenšuje velikost analýzou zprostředkujícího kódu vytvořeného kompilátorem. Odebere nepoužívané metody, vlastnosti, pole, události, struktury a třídy a vytvoří aplikaci, která obsahuje pouze závislosti kódu a sestavení, které jsou nezbytné ke spuštění aplikace.

Chování linkeru

Linker podporuje tři režimy pro aplikace .NET MAUI v systémech iOS a Mac Catalyst:

• Nespojujte. Zakázání propojení zajišťuje, že se sestavení nezmění.
• Pouze propojujte sestavení SDK. V tomto režimu linker zanechá vaše sestavení nedotčená a zmenší velikost sestavení SDK odebráním těch typů a členů, které vaše aplikace nepoužívá.
• Propojte všechna sestavení. Když propojí všechna sestavení, Linker provede další optimalizace, aby vaše aplikace byla co nejmenší. Upraví zprostředkující kód pro váš zdrojový kód, který může poškodit aplikaci, pokud používáte funkce pomocí přístupu, který statická analýza linkeru nedokáže rozpoznat. V těchto případech možná budete muset upravit zdrojový kód, aby aplikace správně fungovala.

Chování linkeru je možné nakonfigurovat pro každou konfiguraci sestavení vaší aplikace.

Upozornění

Povolení linkeru pro konfiguraci ladění vaší aplikace může omezit vaše ladicí schopnosti, protože může odebrat přístupové metody vlastností, které umožňují zkontrolovat stav vašich objektů.

Pokud chcete nakonfigurovat chování linkeru v editoru Visual Studio Code, měli byste přidat vlastnost sestavení $(MtouchLink) do skupiny vlastností v souboru .csproj vaší aplikace. Tato vlastnost sestavení by měla být nastavena na None hodnotu, SdkOnly, nebo Full.

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

Alternativně můžete určit chování linkeru prostřednictvím rozhraní příkazového řádku při sestavování a publikování aplikace. Další informace najdete v tématu Publikování aplikace .NET MAUI Mac Catalyst.

Důležité

$(MtouchLink) Vlastnost sestavení je možné pro každou konfiguraci sestavení pro vaši aplikaci nastavit samostatně.

Zachování kódu

Když použijete zatřižovač, někdy se odebere kód, který jste mohli volat dynamicky, dokonce i nepřímo. Můžete instruovat zastřihovač, aby členy zachoval tím, že je označíte atributem DynamicDependency. Tento atribut lze použít k vyjádření závislosti na typu a podmnožině členů nebo na konkrétních členech.

Důležité

Každý člen seznamu BCL, který nelze staticky určit, aby ji aplikace používala, se může odebrat.

Atribut DynamicDependency lze použít u konstruktorů, polí a metod:

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

V tomto příkladu DynamicDependency zajišťuje, že metoda Helper je ponechána. Bez atributu by oříznutí odebralo Helper z MyAssembly nebo úplně odebralo MyAssembly, pokud na něj není odkazováno jinde.

Atribut určuje člena, který má být zachován prostřednictvím string atributu nebo prostřednictvím atributu DynamicallyAccessedMembers . Typ a sestavení jsou buď implicitní v kontextu atributu, nebo explicitně zadané v atributu (podle Type, nebo podle strings pro typ a název sestavení).

Typ a členské řetězce používají variantu ID řetězce pro komentář v dokumentaci v jazyce C#, a to bez předpony člena. Řetězec člena by neměl obsahovat název deklarujícího typu a může vynechat parametry pro zahrnutí všech členů se specifikovaným názvem. Následující příklady ukazují platné použití:

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

Zachování sestavení

Je možné určit sestavení, která by měla být vyloučena z procesu oříznutí, a zároveň umožnit oříznutí jiných sestavení. Tento přístup může být užitečný, když nemůžete snadno použít atribut DynamicDependency nebo neřídíte kód, který je upravován.

Při ořezávání všech sestavení můžete trimmeru zadat, aby přeskočil určité sestavení, nastavením položky MSBuild v souboru projektu:

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

Poznámka:

Rozšíření .dll není nutné při nastavování TrimmerRootAssembly vlastnosti MSBuild.

Pokud vystřihovač přeskočí sestavení, považuje se za kořenové, což znamená, že je zachováno jak toto sestavení, tak i všechny jeho staticky pochopitelné závislosti. Další sestavení můžete přeskočit přidáním dalších TrimmerRootAssembly vlastností nástroje MSBuild do objektu <ItemGroup>.

Zachování sestavení, typů a členů

Můžete předat soubor popisu XML, který určuje, která sestavení, typy a členy je třeba zachovat.

Chcete-li vyloučit člena z procesu oříznutí při oříznutí všech sestavení, nastavte TrimmerRootDescriptor položku MSBuild v souboru projektu na soubor XML, který definuje členy, které mají vyloučit:

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

Soubor XML pak používá formát popisovače k definování, které členy vyloučit:

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

V tomto příkladu soubor XML určuje metodu, k níž aplikace dynamicky přistupuje a která je vyloučena z trimmování.

Pokud je sestavení, typ nebo člen uveden v souboru XML, výchozí akcí je zachování, což znamená, že bez ohledu na to, zda trimmer považuje jeho použití za potřebné nebo ne, je ve výstupu zachována.

Poznámka:

Značky zachování jsou nejednoznačně inkluzivní. Pokud nezadáte další úroveň detailu, systém zahrne všechny podřízené položky. Pokud je sestavení uvedené bez jakýchkoli typů, zachovají se všechny typy a členy sestavení.

Označit sestavení jako bezpečné pro ořezávání

Pokud máte v projektu knihovnu nebo jste vývojář opakovaně použitelné knihovny a chcete, aby nástroj pro oříznutí zacházel se sestavením jako oříznutelným, můžete sestavení označit jako ořezatelné přidáním vlastnosti IsTrimmable MSBuild do souboru projektu tohoto sestavení:

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

Tím se vaše sestavení označí jako "možné oříznout" a povolí upozornění na ořezání pro daný projekt. Být "oříznutelný" znamená, že vaše sestavení je považováno za kompatibilní s oříznutím a při jeho sestavení by nemělo obsahovat žádná varování na oříznutí. Při použití v aplikaci s ořezáním se nepoužívané členy sestavení odeberou v konečném výstupu.

Při použití nativního nasazení AOT v .NET 9+ nastaví nastavení IsAotCompatible vlastnosti MSBuild na true také hodnotu true pro vlastnost IsTrimmable a aktivuje další vlastnosti sestavení analyzátoru AOT. Další informace o analyzátorech AOT najdete v tématu analyzátory kompatibility AOT. Další informace o nativním nasazení AOT pro .NET MAUI naleznete v tématu nativní nasazení AOT.

Nastavení této vlastnosti MSBuild v souboru projektu vloží atribut AssemblyMetadata do sestavení:

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

Alternativně můžete přidat AssemblyMetadata atribut do sestavení bez přidání IsTrimmable vlastnosti MSBuild do souboru projektu pro sestavení.

Poznámka:

IsTrimmable Pokud je vlastnost MSBuild nastavena pro sestavení, přepíše atribut AssemblyMetadata("IsTrimmable", "True"). To vám umožňuje povolit oříznutí sestavení, i když nemá atribut, nebo zakázat oříznutí sestavení, které atribut má.

Potlačit varování související s analýzou

Když je zatřižovač povolený, odebere il, který není staticky dostupný. Aplikace, které používají reflexi nebo jiné vzory, které vytvářejí dynamické závislosti, můžou být v důsledku toho porušené. Chcete-li upozornit na takové vzory, měli by autoři knihovny při označování sestavení jako bezpečné pro optimalizaci nastavit vlastnost MSBuild na false.

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

Upozornění analýzy oříznutí, pokud nebudou potlačena, budou zahrnovat upozornění o celé aplikaci, včetně vašeho vlastního kódu, kódu knihovny a kódu sady SDK.

Zobrazit podrobná upozornění

Analýza trimmování vytvoří pro každé sestavení, které přichází z PackageReference, maximálně jedno upozornění, které naznačuje, že interní komponenty sestavení nejsou kompatibilní s trimmováním. Jako autor knihovny, když označíte sestavení jako připravené k oříznutí, měli byste povolit jednotlivá upozornění pro všechna sestavení nastavením vlastnosti MSBuild na false:

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

Toto nastavení zobrazuje všechna podrobná upozornění místo jejich sbalení do jednoho upozornění na každé sestavení.