Opcje przycinania

Następujące właściwości i elementy programu MSBuild mają wpływ na zachowanie przycinanych wdrożeń samodzielnie zawartych. 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 tylko na platformie .NET 5 i nowszych wersjach.

Włączanie przycinania

• <PublishTrimmed>true</PublishTrimmed>

  Włącz przycinanie podczas publikowania. Powoduje to również wyłączenie niezgodnych funkcji przycinania i umożliwia analizę przycinania podczas kompilacji.

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 usterki 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 przycinanie i domyślnie przycina wszystkie zestawy. W programie .NET 6 tylko zestawy, które zdecydowały się na przycinanie za pośrednictwem programu [AssemblyMetadata("IsTrimmable", "True")] , zostaną domyślnie przycięte. Możesz wrócić do poprzedniego zachowania przy użyciu polecenia <TrimMode>partial</TrimMode>.

To ustawienie powoduje przycinanie wszystkich zestawów skonfigurowanych do przycinania. W przypadku Microsoft.NET.Sdk platformy .NET 6 obejmuje to wszystkie zestawy z [AssemblyMetadata("IsTrimmable", "True")]programem , co jest w przypadku zestawów środowiska uruchomieniowego platformy .NET. Na platformie .NET 5 zestawy z pakietu uruchomieniowego netcoreapp są konfigurowane do przycinania za pośrednictwem <IsTrimmable> metadanych programu MSBuild. Inne zestawy SDK mogą definiować różne wartości domyślne.

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.

Następujące ustawienia szczegółowości określają, jak agresywnie nieużywane il jest odrzucane. Można to ustawić jako właściwość wpływającą na wszystkie zestawy wejściowe trimmer lub jako metadane dla pojedynczego zestawu, który zastępuje ustawienie właściwości.

• <TrimMode>link</TrimMode>

  Włącz przycinanie na poziomie elementu członkowskiego, które usuwa nieużywane elementy członkowskie z typów. Jest to ustawienie domyślne w programie .NET 6+.

• <TrimMode>copyused</TrimMode>

  Włącz przycinanie na poziomie zestawu, które utrzymuje cały zestaw, jeśli jest używana jakakolwiek część zestawu (w sposób statycznie zrozumiały).

Zestawy z metadanymi <IsTrimmable>true</IsTrimmable> , ale nie będą jawnie TrimMode używać globalnego TrimModeelementu . Wartość domyślna Microsoft.NET.SdkTrimMode to link .NET 6+, a copyused w poprzednich wersjach.

Przycinanie dodatkowych zestawów

W programie .NET 6 lub nowszym PublishTrimmed zestawy są przycinane przy użyciu następującego atrybutu na poziomie zestawu:

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

Biblioteki struktury mają ten atrybut. W programie .NET 6 lub nowszym możesz również wyrazić zgodę na przycinanie biblioteki bez tego atrybutu, określając zestaw według nazwy (bez .dll rozszerzenia).

Ustawienia przycinania poszczególnych zestawów

Podczas publikowania przyciętej aplikacji zestaw SDK oblicza wywołaną nazwę ManagedAssemblyToLink reprezentującą ItemGroup zestaw plików do przetworzenia na potrzeby przycinania. ManagedAssemblyToLink może mieć metadane, które steruje zachowaniem przycinania na zestaw. Aby ustawić te metadane, utwórz element docelowy uruchamiany przed wbudowanym PrepareForILLink elementem docelowym. W poniższym przykładzie pokazano, jak włączyć przycinanie obiektu MyAssembly.

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

Można również użyć tego polecenia, aby zastąpić zachowanie przycinania określone przez autora biblioteki, ustawiając zestaw za pomocą [AssemblyMetadata("IsTrimmable", "True"])polecenia <IsTrimmable>false</IsTrimmable> .

Nie dodawaj ani nie usuwaj elementów do/z ManagedAssemblyToLink, ponieważ zestaw SDK oblicza ten zestaw podczas publikowania i oczekuje, że nie ulegnie zmianie. Obsługiwane metadane to:

• <IsTrimmable>true</IsTrimmable>

  Określ, czy dany zestaw jest przycinany.

• <TrimMode>copyused</TrimMode> lub <TrimMode>link</TrimMode>

  Kontroluj stopień szczegółowości przycinania tego zestawu. Ma to pierwszeństwo przed globalnym TrimModeelementem . Ustawienie TrimMode zestawu oznacza .<IsTrimmable>true</IsTrimmable>

• <TrimmerSingleWarn>True</TrimmerSingleWarn> lub <TrimmerSingleWarn>False</TrimmerSingleWarn>

  Określ, czy mają być wyświetlane pojedyncze ostrzeżenia dla tego 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 wykorzenić określoną metodę, 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. Będzie to obejmować ostrzeżenia dotyczące całej aplikacji, w tym własny kod, kod biblioteki i kod 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 spowoduje automatyczne usunięcie symboli (TrimmerRemoveSymbols domyślnie będzie mieć wartość 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.

• <AutoreleasePoolSupport>false</AutoreleasePoolSupport> (domyślne)

  Usuń kod, który tworzy pule wersji automatycznych na obsługiwanych platformach. Zobacz AutoreleasePool for managed threads (Pula automatycznej wersji dla zarządzanych wątków). Jest to ustawienie domyślne dla zestawu .NET SDK.

• <DebuggerSupport>false</DebuggerSupport>

  Usuń kod, który umożliwia lepsze debugowanie środowisk. To ustawienie powoduje również usunięcie symboli.

• <EnableUnsafeBinaryFormatterSerialization>false</EnableUnsafeBinaryFormatterSerialization>

  Usuń obsługę serializacji BinaryFormatter. Aby uzyskać więcej informacji, zobacz Metody serializacji BinaryFormatter są przestarzałe.

• <EnableUnsafeUTF7Encoding>false</EnableUnsafeUTF7Encoding>

  Usuń niezabezpieczony kod kodowania UTF-7. Aby uzyskać więcej informacji, zobacz Ścieżki kodu UTF-7 są przestarzałe.

• <EventSourceSupport>false</EventSourceSupport>

  Usuń kod lub logikę powiązaną z usługą EventSource.

• <HttpActivityPropagationSupport>false</HttpActivityPropagationSupport>

  Usuń kod związany z obsługą diagnostyki dla pliku System.Net.Http.

• <InvariantGlobalization>true</InvariantGlobalization>

  Usuń kod i dane specyficzne dla globalizacji. Aby uzyskać więcej informacji, zobacz Tryb niezmienny.

• <MetadataUpdaterSupport>false</MetadataUpdaterSupport>

  Usuń logikę specyficzną dla aktualizacji metadanych związaną z ponownym ładowaniem na gorąco.

• <StackTraceSupport>false</StackTraceSupport> (.NET 8+)

  Usuń obsługę generowania śladów stosu (na przykład Environment.StackTrace, lub Exception.ToString) przez środowisko uruchomieniowe. Ilość informacji, które zostaną usunięte 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>true</UseNativeHttpHandler>

  Użyj domyślnej implementacji platformy HttpMessageHandler dla systemu Android/iOS i usuń implementację zarządzaną.

• <UseSystemResourceKeys>true</UseSystemResourceKeys>

  Usuń komunikaty wyjątków dla System.* zestawów. W przypadku zgłoszenia wyjątku System.* z zestawu komunikat będzie uproszczonym identyfikatorem zasobu zamiast pełnego komunikatu.

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

Następujące funkcje są niezgodne z przycinaniem, ponieważ wymagają kodu, do którego nie odwołuje się statycznie. Są one 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 usługi 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.