Udostępnij za pośrednictwem

Opcje przycinania

  • Artykuł

Właściwości i elementy programu MSBuild opisane w tym artykule wpływają na zachowanie przycinanych, samodzielnych wdrożeń. Niektóre opcje wspominają ILLink, czyli nazwę bazowego narzędzia implementującego przycinanie. Aby uzyskać więcej informacji na temat podstawowego narzędzia, zobacz dokumentację programu Trimmer.

Przycinanie z PublishTrimmed programem zostało wprowadzone na platformie .NET Core 3.0. Inne opcje są dostępne na platformie .NET 5 i nowszych wersjach.

Włączanie przycinania

  • <PublishTrimmed>true</PublishTrimmed>

    Włącz przycinanie podczas publikowania. To ustawienie wyłącza również niezgodne funkcje przycinania i umożliwia analizę przycinania podczas kompilacji. W aplikacjach platformy .NET 8 i nowszych to ustawienie umożliwia również powiązanie konfiguracji i generatory źródeł delegatów żądań.

Uwaga

Jeśli określisz przycinanie jako włączone w wierszu polecenia, środowisko debugowania będzie się różnić i może wystąpić dodatkowe błędy w końcowym produkcie.

Umieść to ustawienie w pliku projektu, aby upewnić się, że ustawienie ma zastosowanie w programie dotnet build, a nie tylko dotnet publish.

To ustawienie umożliwia domyślnie przycinanie i przycina wszystkie zestawy. Na platformie .NET 6 tylko zestawy, które zdecydowały się na przycinanie za pośrednictwem ( [AssemblyMetadata("IsTrimmable", "True")] dodane w projektach, które zestaw ) <IsTrimmable>true</IsTrimmable>zostały domyślnie przycięte. Możesz wrócić do poprzedniego zachowania przy użyciu polecenia <TrimMode>partial</TrimMode>.

To ustawienie umożliwia również przycinanie analizatora Roslyn i wyłącza funkcje niezgodne z przycinaniem.

Stopień szczegółowości przycinania

TrimMode Użyj właściwości , aby ustawić stopień szczegółowości przycinania na partial wartość lub full. Ustawieniem domyślnym dla aplikacji konsoli (a począwszy od platformy .NET 8 aplikacje zestawu Web SDK) jest full:

<TrimMode>full</TrimMode>

Aby przyciąć tylko zestawy, które zdecydowały się na przycinanie, ustaw właściwość na partial:

<TrimMode>partial</TrimMode>

Jeśli zmienisz tryb przycinania na partial, możesz wyrazić zgodę na przycinanie poszczególnych zestawów przy użyciu <TrimmableAssembly> elementu MSBuild.

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

Jest to równoważne ustawieniu [AssemblyMetadata("IsTrimmable", "True")] podczas kompilowania zestawu.

Zestawy główne

Jeśli zestaw nie zostanie przycięty, zostanie uznany za "zakorzeniony", co oznacza, że i wszystkie jego statycznie zrozumiałe zależności będą przechowywane. Dodatkowe zestawy mogą być "zakorzenione" według nazwy (bez .dll rozszerzenia):

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

Deskryptory główne

Innym sposobem określania katalogów głównych do analizy jest użycie pliku XML, który używa formatu deskryptora trimmer. Umożliwia to root określonych elementów członkowskich zamiast całego zestawu.

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

Na przykład MyRoots.xml może utworzyć katalog główny określonej metody, która jest dynamicznie uzyskiwana przez aplikację:

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

Ostrzeżenia dotyczące analizy

  • <SuppressTrimAnalysisWarnings>false</SuppressTrimAnalysisWarnings>

    Włącz ostrzeżenia dotyczące analizy przycinania.

Przycinanie usuwa il, który nie jest statycznie osiągalny. Aplikacje korzystające z odbicia lub innych wzorców tworzących zależności dynamiczne mogą zostać przerwane przez przycinanie. Aby ostrzec o takich wzorcach, ustaw wartość <SuppressTrimAnalysisWarnings> false. To ustawienie spowoduje wyświetlanie ostrzeżeń dotyczących całej aplikacji, w tym własnego kodu, kodu biblioteki i kodu platformy.

Analizator Roslyn

Ustawienie PublishTrimmed w programie .NET 6+ umożliwia również analizator Roslyn, który pokazuje ograniczony zestaw ostrzeżeń analizy. Można również włączyć lub wyłączyć analizator niezależnie od PublishTrimmed.

  • <EnableTrimAnalyzer>true</EnableTrimAnalyzer>

    Włącz analizator Roslyn dla podzbioru ostrzeżeń analizy przycinania.

Pomijanie ostrzeżeń

Poszczególne kody ostrzegawcze można pominąć przy użyciu zwykłych właściwości programu MSBuild szanowanych przez łańcuch narzędzi, w tym NoWarn, WarningsAsErrors, WarningsNotAsErrorsi TreatWarningsAsErrors. Istnieje dodatkowa opcja, która steruje zachowaniem funkcji ILLink ostrzegaj jako błąd niezależnie:

  • <ILLinkTreatWarningsAsErrors>false</ILLinkTreatWarningsAsErrors>

    Nie traktuj ostrzeżeń ILLink jako błędów. Może to być przydatne, aby uniknąć przekształcania ostrzeżeń analizy przycinania w błędy podczas traktowania ostrzeżeń kompilatora jako błędów globalnie.

Pokaż szczegółowe ostrzeżenia

W przypadku platformy .NET 6+analiza przycinania generuje co najwyżej jedno ostrzeżenie dla każdego zestawu pochodzącego z PackageReferenceelementu , co wskazuje, że elementy wewnętrzne zestawu nie są zgodne z przycinaniem. Można również wyświetlić poszczególne ostrzeżenia dla wszystkich zestawów:

  • <TrimmerSingleWarn>false</TrimmerSingleWarn>

    Pokaż wszystkie szczegółowe ostrzeżenia, zamiast zwijać je do jednego ostrzeżenia dla każdego zestawu.

Usuwanie symboli

Symbole są zwykle przycinane w celu dopasowania do przyciętych zestawów. Możesz również usunąć wszystkie symbole:

  • <TrimmerRemoveSymbols>true</TrimmerRemoveSymbols>

    Usuń symbole z przyciętej aplikacji, w tym osadzone pliki PDB i oddzielne pliki PDB. Dotyczy to zarówno kodu aplikacji, jak i wszystkich zależności, które są dostarczane z symbolami.

Zestaw SDK umożliwia również wyłączenie obsługi debugera przy użyciu właściwości DebuggerSupport. Gdy obsługa debugera jest wyłączona, przycinanie powoduje automatyczne usunięcie symboli (TrimmerRemoveSymbols wartość domyślna to true).

Przycinanie funkcji biblioteki platformy

Kilka obszarów funkcji bibliotek struktury zawiera dyrektywy trimmer, które umożliwiają usunięcie kodu dla funkcji wyłączonych.

Właściwość MSBuild opis
AutoreleasePoolSupport Gdy jest ustawiona wartość false, usuwa kod, który tworzy pule wersji automatycznych na obsługiwanych platformach. false jest wartością domyślną zestawu .NET SDK.
DebuggerSupport Gdy jest ustawiona wartość false, usuwa kod, który umożliwia lepsze debugowanie środowisk. To ustawienie powoduje również usunięcie symboli.
EnableUnsafeBinaryFormatterSerialization Gdy jest ustawiona wartość false, usuwa obsługę serializacji BinaryFormatter. Aby uzyskać więcej informacji, zobacz BinaryFormatter serialization methods are obsolete and In-box BinaryFormatter implementation delete and always throws (Metody serializacji BinaryFormatter są przestarzałe , a implementacja BinaryFormatter została usunięta i zawsze zgłaszana).
EnableUnsafeUTF7Encoding Gdy jest ustawiona wartość false, usuwa niezabezpieczony kod kodowania UTF-7. Aby uzyskać więcej informacji, zobacz Ścieżki kodu UTF-7 są przestarzałe.
EventSourceSupport Gdy jest ustawiona wartość false, usuwa kod i logikę związaną z usługą EventSource.
HttpActivityPropagationSupport Gdy jest ustawiona wartość false, usuwa kod związany z obsługą diagnostyki dla programu System.Net.Http.
InvariantGlobalization Gdy jest ustawiona wartość true, usuwa kod i dane specyficzne dla globalizacji. Aby uzyskać więcej informacji, zobacz Tryb niezmienny.
MetadataUpdaterSupport W przypadku ustawienia na falsewartość , usuwa logikę specyficzną dla aktualizacji metadanych związaną z ponownym ładowaniem na gorąco.
MetricsSupport Gdy jest ustawiona wartość false, usuwa obsługę System.Diagnostics.Metrics instrumentacji.
StackTraceSupport (.NET 8+) Gdy jest ustawiona wartość false, usuwa obsługę generowania śladów stosu (na przykład Environment.StackTrace lub Exception.ToString) przez środowisko uruchomieniowe. Ilość informacji usuniętych z ciągów śledzenia stosu może zależeć od innych opcji wdrażania. Ta opcja nie ma wpływu na ślady stosu generowane przez debugery.
UseNativeHttpHandler W przypadku ustawienia na truewartość program używa domyślnej implementacji platformy HttpMessageHandler dla systemów Android i iOS i usuwa zarządzaną implementację.
UseSystemResourceKeys W przypadku ustawienia na truewartość , usuwa komunikaty wyjątków dla System.* zestawów. Gdy wyjątek jest zgłaszany z System.* zestawu, komunikat jest uproszczonym identyfikatorem zasobu zamiast pełnego komunikatu.
XmlResolverIsNetworkingEnabledByDefault (.NET 8+) W przypadku ustawienia na falsewartość program usuwa obsługę rozpoznawania adresów URL innych niż pliki w programie System.Xml. Obsługiwane jest tylko rozpoznawanie systemu plików.

Te właściwości powodują przycinanie powiązanego kodu, a także wyłączanie funkcji za pośrednictwem pliku runtimeconfig . Aby uzyskać więcej informacji na temat tych właściwości, w tym odpowiednich opcji konfiguracji środowiska uruchomieniowego, zobacz przełączniki funkcji. Niektóre zestawy SDK mogą mieć wartości domyślne dla tych właściwości.

Funkcje struktury wyłączone podczas przycinania

Poniższe funkcje są niezgodne z przycinaniem, ponieważ wymagają kodu, do którego nie odwołuje się statycznie. Te funkcje są domyślnie wyłączone w aplikacjach przycinanych.

Ostrzeżenie

Włącz te funkcje na własne ryzyko. Mogą one spowodować przerwanie przycinanych aplikacji bez dodatkowej pracy w celu zachowania dynamicznie przywoływanego kodu.

  • <BuiltInComInteropSupport>

    Wbudowana obsługa modelu COM jest wyłączona.

  • <CustomResourceTypesSupport>

    Użycie niestandardowych typów zasobów nie jest obsługiwane. Ścieżki kodu ResourceManager, które używają odbicia dla niestandardowych typów zasobów, są przycinane.

  • <EnableCppCLIHostActivation>

    Aktywacja hosta C++/CLI jest wyłączona.

  • <EnableUnsafeBinaryFormatterInDesigntimeLicenseContextSerialization>

    DesigntimeLicenseContextSerializer korzystanie z BinaryFormatter serializacji jest wyłączone.

  • <StartupHookSupport>

    Uruchamianie kodu przed Main użyciem DOTNET_STARTUP_HOOKS polecenia nie jest obsługiwane. Aby uzyskać więcej informacji, zobacz host startuphook.