Opties voor bijsnijden

De volgende MSBuild-eigenschappen en -items beïnvloeden het gedrag van bijgesneden zelf-ingesloten implementaties. Enkele van de opties vermelden ILLink, wat de naam is van het onderliggende hulpprogramma dat bijsnijden implementeert. Zie de documentatie van Trimmer voor meer informatie over het onderliggende hulpprogramma.

Bijsnijden met PublishTrimmed is geïntroduceerd in .NET Core 3.0. De andere opties zijn alleen beschikbaar in .NET 5 en nieuwere versies.

Bijsnijden inschakelen

• <PublishTrimmed>true</PublishTrimmed>

  Schakel bijsnijden in tijdens het publiceren. Met deze instelling schakelt u ook incompatibele functies voor knippen uit en schakelt u tijdens de build een trimanalyse in. In .NET 8- en hoger-apps schakelt deze instelling ook de configuratiebinding in en vraagt u gemachtigde brongeneratoren aan.

Notitie

Als u bijsnijden opgeeft zoals ingeschakeld vanaf de opdrachtregel, verschilt uw foutopsporingservaring en kunnen er extra fouten optreden in het eindproduct.

Plaats deze instelling in het projectbestand om ervoor te zorgen dat de instelling van toepassing is, dotnet buildniet alleen dotnet publish.

Met deze instelling kunt u standaard alle assembly's bijsnijden en knippen. In .NET 6 werden alleen assembly's die zich hebben aangemeld voor bijsnijden [AssemblyMetadata("IsTrimmable", "True")] via, standaard ingekort. U kunt terugkeren naar het vorige gedrag met behulp van <TrimMode>partial</TrimMode>.

Met deze instelling worden alle assembly's bijgesneden die zijn geconfigureerd voor bijsnijden. Met Microsoft.NET.Sdk .NET 6 omvat dit alle assembly's met [AssemblyMetadata("IsTrimmable", "True")], wat het geval is voor de .NET Runtime-assembly's. In .NET 5 worden assembly's van het netcoreapp-runtimepakket geconfigureerd voor bijsnijden via <IsTrimmable> MSBuild-metagegevens. Andere SDK's kunnen verschillende standaardwaarden definiëren.

Met deze instelling wordt ook de trimcompatibiliteit Roslyn Analyzer ingeschakeld en worden functies uitgeschakeld die niet compatibel zijn met bijsnijden.

Granulariteit bijsnijden

Gebruik de TrimMode eigenschap om de granulariteit van het bijsnijden in te stellen op partial of full. De standaardinstelling voor console-apps (en vanaf .NET 8, Web SDK-apps) is full:

<TrimMode>full</TrimMode>

Als u alleen assembly's wilt bijsnijden die zijn aangemeld voor bijsnijden, stelt u de eigenschap partialin op:

<TrimMode>partial</TrimMode>

Als u de trimmodus partialwijzigt in , kunt u afzonderlijke assembly's inschakelen om bij te snijden met behulp van een <TrimmableAssembly> MSBuild-item.

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

Dit komt overeen met de instelling [AssemblyMetadata("IsTrimmable", "True")] bij het bouwen van de assembly.

Met de volgende granulariteitsinstellingen bepaalt u hoe agressief ongebruikte IL wordt verwijderd. Dit kan worden ingesteld als een eigenschap die van invloed is op alle invoerassembly's van de trimmer of als metagegevens op een afzonderlijke assembly, waardoor de instelling van de eigenschap wordt overschreven.

• <TrimMode>link</TrimMode>

  Schakel het bijsnijden op lidniveau in, waardoor ongebruikte leden uit typen worden verwijderd. Dit is de standaardwaarde in .NET 6+.

• <TrimMode>copyused</TrimMode>

  Schakel het bijsnijden op assemblyniveau in, waardoor een hele assembly wordt bijgehouden als een deel ervan wordt gebruikt (statisch begrepen).

Assembly's met <IsTrimmable>true</IsTrimmable> metagegevens, maar niet expliciet TrimMode zullen de globale TrimModegebruiken. De standaardwaarde Microsoft.NET.Sdk TrimMode is link in .NET 6+ en copyused in eerdere versies.

Extra assembly's knippen

In .NET 6+ PublishTrimmed worden assembly's bijgeknipt met het volgende kenmerk op assemblyniveau:

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

De frameworkbibliotheken hebben dit kenmerk. In .NET 6+ kunt u er ook voor kiezen om bij te snijden voor een bibliotheek zonder dit kenmerk, waarbij u de assembly op naam opgeeft (zonder de .dll extensie).

Instellingen voor bijsnijden voor afzonderlijke assembly's

Bij het publiceren van een bijgesneden app berekent de SDK een ItemGroup aangeroepen naam ManagedAssemblyToLink die de set bestanden vertegenwoordigt die moeten worden verwerkt voor bijsnijden. ManagedAssemblyToLink kan metagegevens bevatten waarmee het bijsnijdgedrag per assembly wordt bepaald. Als u deze metagegevens wilt instellen, maakt u een doel dat wordt uitgevoerd vóór het ingebouwde PrepareForILLink doel. In het volgende voorbeeld ziet u hoe u bijsnijden kunt MyAssemblyinschakelen.

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

U kunt dit doel ook gebruiken om het bijsnijdgedrag te overschrijven dat is opgegeven door de auteur van de bibliotheek, door de instelling <IsTrimmable>false</IsTrimmable> voor een assembly met [AssemblyMetadata("IsTrimmable", "True"]).

Voeg geen items toe aan of verwijder items uit ManagedAssemblyToLink, omdat de SDK deze set tijdens het publiceren berekent en verwacht dat deze niet wordt gewijzigd. De ondersteunde metagegevens zijn:

• <IsTrimmable>true</IsTrimmable>

  Bepalen of de opgegeven assembly wordt ingekort.

• <TrimMode>copyused</TrimMode> of <TrimMode>link</TrimMode>

  De granulariteit van deze assembly bepalen. Deze metagegevens hebben voorrang op het algemene TrimMode. Instelling TrimMode voor een assembly impliceert <IsTrimmable>true</IsTrimmable>.

• <TrimmerSingleWarn>True</TrimmerSingleWarn>

  Bepalen of er enkele waarschuwingen voor deze assembly moeten worden weergegeven.

Hoofdassembly's

Als een assembly niet wordt ingekort, wordt deze beschouwd als 'geroot', wat betekent dat het en alle statisch begrepen afhankelijkheden worden bewaard. Extra assembly's kunnen op naam worden geroot (zonder de .dll extensie):

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

Hoofddescriptors

Een andere manier om hoofdmappen voor analyse op te geven, is het gebruik van een XML-bestand dat gebruikmaakt van de indeling van de trimmerdescriptor. Hiermee kunt u specifieke leden rooten in plaats van een hele assembly.

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

U kunt bijvoorbeeld MyRoots.xml een specifieke methode rooten die dynamisch wordt geopend door de toepassing:

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

Analysewaarschuwingen

• <SuppressTrimAnalysisWarnings>false</SuppressTrimAnalysisWarnings>

  Schakel waarschuwingen voor trimanalyse in.

Met bijsnijden wordt IL verwijderd die niet statisch bereikbaar is. Apps die gebruikmaken van weerspiegeling of andere patronen die dynamische afhankelijkheden maken, kunnen worden verbroken door bij te snijden. Als u wilt waarschuwen voor dergelijke patronen, stelt u deze in <SuppressTrimAnalysisWarnings> op false. Deze instelling geeft waarschuwingen weer over de hele app, inclusief uw eigen code, bibliotheekcode en frameworkcode.

Roslyn Analyzer

Instelling PublishTrimmed in .NET 6+ maakt ook een Roslyn-analysefunctie mogelijk die een beperkte set analysewaarschuwingen weergeeft. U kunt de analyse ook onafhankelijk van PublishTrimmed.

• <EnableTrimAnalyzer>true</EnableTrimAnalyzer>

  Schakel een Roslyn Analyzer in voor een subset van trimanalysewaarschuwingen.

Waarschuwingen onderdrukken

U kunt afzonderlijke waarschuwingscodes onderdrukken met de gebruikelijke MSBuild-eigenschappen die worden gerespecteerd door de toolchain, waaronder NoWarn, WarningsAsErrors, WarningsNotAsErrorsen TreatWarningsAsErrors. Er is een extra optie waarmee het ILLink-gedrag voor waarschuwen als-fout onafhankelijk wordt beheerd:

• <ILLinkTreatWarningsAsErrors>false</ILLinkTreatWarningsAsErrors>

  IlLink-waarschuwingen worden niet als fouten behandeld. Dit kan handig zijn om te voorkomen dat u trimanalysewaarschuwingen kunt omzetten in fouten bij het behandelen van compilerwaarschuwingen als fouten wereldwijd.

Gedetailleerde waarschuwingen weergeven

In .NET 6+ produceert trimanalyse maximaal één waarschuwing voor elke assembly die afkomstig is van een PackageReference, wat aangeeft dat de interne onderdelen van de assembly niet compatibel zijn met bijsnijden. U kunt ook afzonderlijke waarschuwingen voor alle assembly's weergeven:

• <TrimmerSingleWarn>false</TrimmerSingleWarn>

  Alle gedetailleerde waarschuwingen weergeven in plaats van ze samen te vouwen tot één waarschuwing per assembly.

Symbolen verwijderen

Symbolen worden meestal ingekort zodat ze overeenkomen met de bijgesneden assembly's. U kunt ook alle symbolen verwijderen:

• <TrimmerRemoveSymbols>true</TrimmerRemoveSymbols>

  Verwijder symbolen uit de bijgesneden toepassing, inclusief ingesloten PDBs en afzonderlijke PDB-bestanden. Dit geldt voor zowel de toepassingscode als eventuele afhankelijkheden die bij symbolen worden geleverd.

De SDK maakt het ook mogelijk om ondersteuning voor foutopsporingsprogramma's uit te schakelen met behulp van de eigenschap DebuggerSupport. Wanneer ondersteuning voor foutopsporingsprogramma's is uitgeschakeld, worden symbolen automatisch verwijderd (TrimmerRemoveSymbols wordt standaard ingesteld op true).

Frameworkbibliotheekfuncties bijsnijden

Verschillende functiegebieden van de frameworkbibliotheken worden geleverd met trimmerrichtlijnen waarmee de code voor uitgeschakelde functies kan worden verwijderd.

• <AutoreleasePoolSupport>false</AutoreleasePoolSupport> (standaard)

  Verwijder code waarmee automatischreleasepools op ondersteunde platforms worden gemaakt. Zie AutoreleasePool voor beheerde threads. Dit is de standaardwaarde voor de .NET SDK.

• <DebuggerSupport>false</DebuggerSupport>

  Verwijder code die betere foutopsporingservaringen mogelijk maakt. Met deze instelling worden ook symbolen verwijderd.

• <EnableUnsafeBinaryFormatterSerialization>false</EnableUnsafeBinaryFormatterSerialization>

  Ondersteuning voor serialisatie van BinaryFormatter verwijderen. Zie BinaryFormatter-serialisatiemethoden zijn verouderd voor meer informatie.

• <EnableUnsafeUTF7Encoding>false</EnableUnsafeUTF7Encoding>

  Verwijder onveilige UTF-7-coderingscode. Zie UTF-7-codepaden zijn verouderd voor meer informatie.

• <EventSourceSupport>false</EventSourceSupport>

  Verwijder gerelateerde code of logica voor EventSource.

• <HttpActivityPropagationSupport>false</HttpActivityPropagationSupport>

  Verwijder code met betrekking tot diagnostische ondersteuning voor System.Net.Http.

• <InvariantGlobalization>true</InvariantGlobalization>

  Verwijder globalisatiespecifieke code en gegevens. Zie de invariantmodus voor meer informatie.

• <MetadataUpdaterSupport>false</MetadataUpdaterSupport>

  Verwijder updatelogica voor metagegevens met betrekking tot hot-reload.

• <MetricsSupport>false</MetricsSupport>

  Hiermee verwijdert u ondersteuning voor instrumentatie van System.Diagnostics.Metrics.

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

  Verwijder ondersteuning voor het genereren van stack-traceringen (bijvoorbeeld Environment.StackTrace, of Exception.ToString) door de runtime. De hoeveelheid informatie die uit stacktraceringstekenreeksen wordt verwijderd, kan afhankelijk zijn van andere implementatieopties. Deze optie heeft geen invloed op stack-traceringen die worden gegenereerd door foutopsporingsprogramma's.

• <UseNativeHttpHandler>true</UseNativeHttpHandler>

  Gebruik de standaardplatform implementatie van HttpMessageHandler voor Android/iOS en verwijder de beheerde implementatie.

• <UseSystemResourceKeys>true</UseSystemResourceKeys>

  Strook uitzonderingsberichten voor System.* assembly's. Wanneer er een uitzondering wordt gegenereerd vanuit een System.* assembly, is het bericht een vereenvoudigde resource-id in plaats van het volledige bericht.

Deze eigenschappen zorgen ervoor dat de gerelateerde code wordt ingekort en dat functies ook worden uitgeschakeld via het runtimeconfig-bestand . Zie functieswitches voor meer informatie over deze eigenschappen, inclusief de bijbehorende runtimeconfiguratieopties. Sommige SDK's hebben mogelijk standaardwaarden voor deze eigenschappen.

Frameworkfuncties uitgeschakeld bij bijsnijden

De volgende functies zijn niet compatibel met bijsnijden, omdat ze code vereisen waarnaar niet statisch wordt verwezen. Deze functies zijn standaard uitgeschakeld in bijgesneden apps.

Waarschuwing

Schakel deze functies op eigen risico in. Het is waarschijnlijk dat ze bijgesneden apps breken zonder extra werk om de dynamisch verwezen code te behouden.

• <BuiltInComInteropSupport>

  Ingebouwde COM-ondersteuning is uitgeschakeld.

• <CustomResourceTypesSupport>

  Het gebruik van aangepaste resourcetypen wordt niet ondersteund. ResourceManager-codepaden die gebruikmaken van weerspiegeling voor aangepaste resourcetypen, worden ingekort.

• <EnableCppCLIHostActivation>

  Activering van C++/CLI-host is uitgeschakeld.

• <EnableUnsafeBinaryFormatterInDesigntimeLicenseContextSerialization>

  DesigntimeLicenseContextSerializer het gebruik van BinaryFormatter serialisatie is uitgeschakeld.

• <StartupHookSupport>

  Het uitvoeren van code voordat Main met DOTNET_STARTUP_HOOKS wordt niet ondersteund. Zie de opstarthook van de host voor meer informatie.