Propojení aplikace .NET MAUI Mac Catalyst

Když sestaví aplikaci, může uživatelské rozhraní .NET Multi-Platform App UI (.NET MAUI) použít linker, který zavolá, ILLink aby se snížila celková velikost 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:

• Neodpojujte. Zakázání propojení zajišťuje, že se sestavení nezmění.
• Propojte pouze sestavení sady SDK. V tomto režimu linker opustí sestavení nedotčená a zmenší velikost sestavení sady SDK odebráním typů a členů, které vaše aplikace nepoužívá.
• Propojte všechna sestavení. Když propojí všechna sestavení, linker provede další optimalizace, aby byla vaše aplikace 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.

Upozorňující

Povolení linkeru pro konfiguraci ladění vaší aplikace může bránit ladění prostředí, protože může odebrat přístupové objekty vlastností, které umožňují zkontrolovat stav objektů.

Poznámka:

Visual Studio pro Mac plánujeme do 31. srpna 2024 v souladu s Moderní zásady životního cyklu Od Microsoftu Visual Studio pro Mac 17.6 bude nadále podporován až do 31. srpna 2024 s servisními aktualizacemi problémů se zabezpečením a aktualizovanými platformami od Společnosti Apple. Další informace, včetně alternativních možností vývoje na Macu, najdete v tématu Co se děje s Visual Studio pro Mac?.

Konfigurace chování linkeru v Visual Studio pro Mac:

1. V okně řešení klikněte pravým tlačítkem na projekt aplikace .NET MAUI a vyberte Vlastnosti.

2. V okně Vlastnosti projektu vyberte kartu Build Mac Catalyst Build (Sestavení > Mac Catalyst > Build ).

3. V okně Vlastnosti projektu se ujistěte, že je rozevírací seznam Konfigurace nastavený na Release (Uvolnit) a nastavte rozevírací seznam Chování linkeru na požadované chování linkeru:

   

4. V okně Vlastnosti projektu klikněte na tlačítko OK.

Zachování kódu

Při použití linkeru někdy odebere kód, který jste mohli volat dynamicky, dokonce i nepřímo. Linkeru můžete dát pokyn, aby zachoval členy tak, že je označí 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 zajistíte, že Helper se metoda zachová. Bez atributu by propojení odebralo HelperMyAssembly nebo úplně odebralo MyAssembly , pokud na něj nikde neodkazuje.

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 formátu řetězce ID komentáře dokumentace jazyka C# bez předpony člena. Řetězec člena by neměl obsahovat název deklarujícího typu a může vynechat parametry pro zachování všech členů zadaného názvu. 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 propojení, a zároveň umožnit propojení jiných sestavení. Tento přístup může být užitečný, když atribut nemůžete snadno použít DynamicDependency nebo neřídíte kód, který je propojený.

Když propojí všechna sestavení, můžete linkeru říct, aby přeskočí sestavení nastavením TrimmerRootAssembly vlastnosti MSBuild ve <ItemGroup> značce v souboru projektu:

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

Poznámka:

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

Pokud linker přeskočí sestavení, považuje se za kořenové, což znamená, že se zachovávají 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ů

Linkeru 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 propojení při propojení všech sestavení, nastavte TrimmerRootDescriptor vlastnost MSBuild ve <ItemGroup> značce v souboru projektu na soubor XML, který definuje členy, které mají vyloučit:

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

Soubor XML pak pomocí formátu popisovače popisovače definuje, které členy mají být vyloučeny z propojení:

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

V tomto příkladu soubor XML určuje metodu, která je dynamicky přístupná aplikací, která je vyloučena z propojení.

Pokud je sestavení, typ nebo člen uveden v xml, výchozí akce je zachování, což znamená, že bez ohledu na to, zda linker považuje za použitý nebo ne, je zachován ve výstupu.

Poznámka:

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

Označení sestavení jako bezpečného linkeru

Pokud máte v projektu knihovnu nebo jste vývojář opakovaně použitelné knihovny a chcete, aby linker zachází s sestavením jako propojitelným, můžete sestavení označit jako bezpečné linker přidáním IsTrimmable vlastnosti MSBuild do souboru projektu pro sestavení:

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

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

IsTrimmable Nastavení vlastnosti MSBuild do true souboru projektu vloží AssemblyMetadata atribut 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 AssemblyMetadata("IsTrimmable", "True") atribut. To umožňuje vyjádřit výslovný souhlas se sestavením do oříznutí, i když nemá atribut, nebo zakázat oříznutí sestavení, které má atribut.

Potlačení upozornění analýzy

Když je linker 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, při označení sestavení jako bezpečné linkeru by autoři knihoven měli nastavit SuppressTrimAnalysisWarnings vlastnost MSBuild na false:

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

Upozornění analýzy oříznutí potlačí upozornění na celou aplikaci, včetně vlastního kódu, kódu knihovny a kódu sady SDK.

Zobrazit podrobná upozornění

Analýza oříznutí vytvoří pro každé sestavení, které pochází z PackageReference, maximálně jedno upozornění, které indikuje, že vnitřní hodnoty sestavení nejsou kompatibilní s oříznutím. Když jako autor knihovny označíte sestavení jako bezpečné linker, měli byste povolit jednotlivá upozornění pro všechna sestavení nastavením TrimmerSingleWarn 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í.

Viz také

• ILLink