Sdílet prostřednictvím

Možnosti oříznutí

  • Článek

Vlastnosti a položky nástroje MSBuild popsané v tomto článku ovlivňují chování oříznutých, samostatných nasazení. Některé z možností zmínky ILLink, což je název základního nástroje, který implementuje oříznutí. Další informace o základním nástroji najdete v dokumentaci k trimmeru.

V .NET Core 3.0 jsme zavedli oříznutí PublishTrimmed . Ostatní možnosti jsou k dispozici v .NET 5 a novějších verzích.

Povolení oříznutí

  • <PublishTrimmed>true</PublishTrimmed>

    Povolte oříznutí během publikování. Toto nastavení také vypne nekompatibilní funkce oříznutí a povolí analýzu oříznutí během sestavování. V aplikacích .NET 8 a novějších umožňuje toto nastavení také generátory zdrojů pro konfiguraci a delegování požadavků.

Poznámka:

Pokud zadáte oříznutí tak, jak je povoleno z příkazového řádku, prostředí ladění se bude lišit a v konečném produktu se můžou vyskytnout další chyby.

Toto nastavení umístěte do souboru projektu, abyste zajistili, že se toto nastavení použije nejen během dotnet builddotnet publish.

Toto nastavení umožňuje oříznout a oříznout všechna sestavení ve výchozím nastavení. V .NET 6 byly ve výchozím nastavení oříznuty pouze sestavení, která se přihlásila k oříznutí prostřednictvím [AssemblyMetadata("IsTrimmable", "True")] (přidáno do projektů, které nastavují <IsTrimmable>true</IsTrimmable>). K předchozímu chování se můžete vrátit pomocí funkce <TrimMode>partial</TrimMode>.

Toto nastavení oříznou všechna sestavení nakonfigurovaná pro oříznutí. V Microsoft.NET.Sdk .NET 6 to zahrnuje všechna sestavení s [AssemblyMetadata("IsTrimmable", "True")], což je případ pro sestavení modulu runtime .NET. V .NET 5 jsou sestavení z balíčku netcoreapp runtime nakonfigurovaná pro oříznutí prostřednictvím <IsTrimmable> metadat NÁSTROJE MSBuild. Jiné sady SDK můžou definovat jiné výchozí hodnoty.

Toto nastavení také umožňuje analyzátor Roslyn kompatibilní s oříznutím a zakáže funkce nekompatibilní s oříznutím.

Oříznutí členitosti

TrimMode Pomocí vlastnosti nastavte členitost oříznutí na hodnotu nebo partial full. Výchozí nastavení pro konzolové aplikace (počínaje rozhraním .NET 8 a webovými aplikacemi SDK) je full:

<TrimMode>full</TrimMode>

Chcete-li oříznout pouze sestavení, která mají výslovný souhlas s oříznutím, nastavte vlastnost na partial:

<TrimMode>partial</TrimMode>

Pokud změníte režim oříznutí na partial, můžete vyjádřit výslovný souhlas s individuálními sestaveními k oříznutí pomocí <TrimmableAssembly> položky NÁSTROJE MSBuild.

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

Toto nastavení odpovídá nastavení [AssemblyMetadata("IsTrimmable", "True")] při sestavování sestavení.

Následující členitost nastavení určuje, jak agresivně nevyužité IL je zahozeno. To lze nastavit jako vlastnost, která ovlivňuje všechna vstupní sestavení pro zatřižování, nebo jako metadata pro jednotlivá sestavení, která přepíší nastavení vlastnosti.

  • <TrimMode>link</TrimMode>

    Povolte oříznutí na úrovni člena, který odebere nepoužívané členy z typů. Toto je výchozí hodnota v .NET 6 nebo novější.

  • <TrimMode>copyused</TrimMode>

    Povolte oříznutí na úrovni sestavení, které udržuje celé sestavení, pokud se používá jakákoli jeho část (staticky srozumitelným způsobem).

Sestavení s <IsTrimmable>true</IsTrimmable> metadaty, ale nebudou explicitně TrimMode používat globální TrimMode. Výchozí hodnota TrimMode Microsoft.NET.Sdk je link v .NET 6+ a copyused v předchozích verzích.

Oříznout další sestavení

V rozhraní .NET 6+ PublishTrimmed oříznou sestavení s následujícím atributem na úrovni sestavení:

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

Knihovny architektury mají tento atribut. V .NET 6 nebo novějších můžete také vyjádřit výslovný souhlas s oříznutím pro knihovnu bez tohoto atributu .dll a zadat sestavení podle názvu (bez rozšíření).

Nastavení oříznutí pro jednotlivá sestavení

Při publikování oříznuté aplikace sada SDK vypočítá ItemGroup volání ManagedAssemblyToLink , které představuje sadu souborů, které se mají zpracovat pro oříznutí. ManagedAssemblyToLink může mít metadata, která řídí chování oříznutí na sestavení. Pokud chcete nastavit tato metadata, vytvořte cíl, který se spustí před předdefinovaný PrepareForILLink cíl. Následující příklad ukazuje, jak povolit oříznutí MyAssembly.

<Target Name="ConfigureTrimming"
        BeforeTargets="PrepareForILLink">
  <ItemGroup>
    <ManagedAssemblyToLink Condition="'%(Filename)' == 'MyAssembly'">
      <IsTrimmable>true</IsTrimmable>
    </ManagedAssemblyToLink>
  </ItemGroup>
</Target>

Tento cíl můžete také použít k přepsání chování oříznutí určené autorem knihovny nastavením <IsTrimmable>false</IsTrimmable> sestavení s [AssemblyMetadata("IsTrimmable", "True"]).

Nepřidávejte ani neodebívejte položky, ManagedAssemblyToLinkprotože sada SDK tuto sadu vypočítá během publikování a očekává, že se nezmění. Podporovaná metadata jsou:

  • <IsTrimmable>true</IsTrimmable>

    Určuje, zda je dané sestavení oříznuto.

  • <TrimMode>copyused</TrimMode> nebo <TrimMode>link</TrimMode>

    Řídí členitost oříznutí tohoto sestavení. Tato metadata mají přednost před globálním TrimMode. Nastavení TrimMode sestavení znamená <IsTrimmable>true</IsTrimmable>.

  • <TrimmerSingleWarn>True</TrimmerSingleWarn>

    Určuje, zda se mají zobrazit jednotlivá upozornění pro toto sestavení.

Kořenová sestavení

Pokud se sestavení neořízne, považuje se za "rooted", což znamená, že se zachová a všechny jeho staticky pochopené závislosti. Další sestavení mohou být "rooted" podle názvu (bez .dll rozšíření):

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

Kořenové popisovače

Dalším způsobem, jak určit kořeny pro analýzu, je použití souboru XML, který používá formát popisovače popisovače. Díky tomu můžete kořenit konkrétní členy místo celého sestavení.

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

Může například MyRoots.xml za rootovat konkrétní metodu, která je dynamicky přístupná aplikací:

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

Upozornění analýzy

  • <SuppressTrimAnalysisWarnings>false</SuppressTrimAnalysisWarnings>

    Povolte upozornění analýzy oříznutí.

Oříznutí odebere IL, které není staticky dostupné. Aplikace, které používají reflexi nebo jiné vzory, které vytvářejí dynamické závislosti, můžou být přerušeny oříznutím. Chcete-li upozornit na takové vzory, nastavte <SuppressTrimAnalysisWarnings> na falsehodnotu . Toto nastavení zobrazí upozornění na celou aplikaci, včetně vlastního kódu, kódu knihovny a kódu architektury.

Analyzátor Roslyn

Nastavení PublishTrimmed v .NET 6+ také umožňuje analyzátor Roslyn, který zobrazuje omezenou sadu upozornění analýzy. Analyzátor můžete také povolit nebo zakázat nezávisle na PublishTrimmed.

  • <EnableTrimAnalyzer>true</EnableTrimAnalyzer>

    Povolení analyzátoru Roslyn pro podmnožinu upozornění analýzy oříznutí

Potlačení upozornění

Můžete potlačit jednotlivé kódy upozornění pomocí obvyklých vlastností nástroje MSBuild respektovaných sadou nástrojů, včetně NoWarn, WarningsAsErrors, WarningsNotAsErrorsa TreatWarningsAsErrors. Existuje další možnost, která nezávisle řídí chování upozornění ILLink jako chyby:

  • <ILLinkTreatWarningsAsErrors>false</ILLinkTreatWarningsAsErrors>

    Nezacházejte s upozorněními ILLink jako s chybami. To může být užitečné, abyste se vyhnuli globálnímu zpracování upozornění analýzy oříznutí na chyby při zacházení s upozorněními kompilátoru jako s chybami.

Zobrazit podrobná upozornění

V rozhraní .NET 6+ vytvoří analýza oříznutí maximálně jedno upozornění pro každé sestavení, které pochází z PackageReference, označující, že vnitřní hodnoty sestavení nejsou kompatibilní s oříznutím. Můžete také zobrazit jednotlivá upozornění pro všechna sestavení:

  • <TrimmerSingleWarn>false</TrimmerSingleWarn>

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

Odebrání symbolů

Symboly se obvykle oříznou tak, aby odpovídaly oříznutým sestavením. Můžete také odebrat všechny symboly:

  • <TrimmerRemoveSymbols>true</TrimmerRemoveSymbols>

    Odeberte symboly z oříznuté aplikace, včetně vložených souborů PDB a samostatných souborů PDB. To platí pro kód aplikace i všechny závislosti, které jsou součástí symbolů.

Sada SDK také umožňuje zakázat podporu ladicího programu pomocí vlastnosti DebuggerSupport. Pokud je podpora ladicího programu zakázaná, oříznutí automaticky odebere symboly (TrimmerRemoveSymbols výchozí hodnota je true).

Střih funkcí knihovny architektury

Několik oblastí funkcí knihoven architektury obsahuje direktivy trimmeru, které umožňují odebrat kód pro zakázané funkce.

Vlastnost MSBuild Popis
AutoreleasePoolSupport Pokud je tato možnost nastavená, falseodebere kód, který vytvoří fondy automatického odstranění na podporovaných platformách. false je výchozí pro sadu .NET SDK.
DebuggerSupport Při nastavení odebere falsekód, který umožňuje lepší možnosti ladění. Toto nastavení také odebere symboly.
EnableUnsafeBinaryFormatterSerialization Při nastavení na false, odebere BinaryFormatter serializace podpora. Další informace naleznete v tématu BinaryFormatter serializace metody jsou zastaralé a In-box BinaryFormatter implementace odstraněna a vždy vyvolá.
EnableUnsafeUTF7Encoding Pokud je nastavena hodnota false, odebere nezabezpečený kód kódování UTF-7. Další informace naleznete v tématu Cesty kódu UTF-7 jsou zastaralé.
EventSourceSupport Pokud je nastavená hodnota false, odebere kód a logiku související s EventSource.
HttpActivityPropagationSupport Pokud je nastavená hodnota false, odebere kód související s podporou diagnostiky pro System.Net.Http.
InvariantGlobalization Pokud je nastavená hodnota true, odebere kód a data specifická pro globalizaci. Další informace naleznete v tématu Invariantní režim.
MetadataUpdaterSupport Pokud je nastavená hodnota false, odebere logiku specifickou pro aktualizaci metadat související s opětovným načítáním za provozu.
MetricsSupport Pokud je nastavená hodnota false, odebere podporu System.Diagnostics.Metrics instrumentace.
StackTraceSupport (.NET 8+) Pokud je tato možnost nastavená, falseodebere podporu generování trasování zásobníku (například Environment.StackTrace Exception.ToString) modulem runtime. Množství informací odebraných z trasovacích řetězců zásobníku může záviset na jiných možnostech nasazení. Tato možnost nemá vliv na trasování zásobníku generované ladicím programem.
UseNativeHttpHandler Při nastavení použije truevýchozí implementaci HttpMessageHandler platformy pro Android a iOS a odebere spravovanou implementaci.
UseSystemResourceKeys Pokud je nastavená hodnota true, odstraní zprávy výjimek pro System.* sestavení. Při vyvolání výjimky ze System.* sestavení je zpráva zjednodušené ID prostředku místo celé zprávy.
XmlResolverIsNetworkingEnabledByDefault (.NET 8+) Pokud je nastavená hodnota false, odebere podporu pro překlad adres URL, které nejsou soubory v souboru .System.Xml Podporuje se pouze překlad systému souborů.

Tyto vlastnosti způsobují oříznutí souvisejícího kódu a také zakázání funkcí prostřednictvím souboru runtimeconfig . Další informace o těchto vlastnostech, včetně odpovídajících možností modulu runtimeconfig , naleznete v tématu přepínače funkcí. Některé sady SDK můžou mít výchozí hodnoty pro tyto vlastnosti.

Funkce rozhraní zakázané při oříznutí

Následující funkce nejsou kompatibilní s oříznutím, protože vyžadují kód, na který se staticky neodkazuje. Tyto funkce jsou ve výchozím nastavení zakázané v oříznutých aplikacích.

Upozorňující

Povolte tyto funkce na vlastní nebezpečí. Pravděpodobně přeruší oříznuté aplikace bez další práce, aby zachovaly dynamicky odkazovaný kód.

  • <BuiltInComInteropSupport>

    Integrovaná podpora modelu COM je zakázaná.

  • <CustomResourceTypesSupport>

    Použití vlastních typů prostředků se nepodporuje. Cesty kódu ResourceManager, které používají reflexi pro vlastní typy prostředků, jsou oříznuté.

  • <EnableCppCLIHostActivation>

    Aktivace hostitele C++/CLI je zakázaná.

  • <EnableUnsafeBinaryFormatterInDesigntimeLicenseContextSerialization>

    DesigntimeLicenseContextSerializerBinaryFormatter použití serializace je zakázáno.

  • <StartupHookSupport>

    Spuštění kódu před Main spuštěním DOTNET_STARTUP_HOOKS není podporováno. Další informace najdete v tématu háček pro spuštění hostitele.