Opzioni di trimming

Le proprietà e gli elementi di MSBuild descritti in questo articolo influisce sul comportamento delle distribuzioni tagliate e autonome. Alcune delle opzioni indicano ILLink, che è il nome dello strumento sottostante che implementa il trimming. Per altre informazioni sullo strumento sottostante, vedere la documentazione di trimmer.

Il trimming con PublishTrimmed è stato introdotto in .NET Core 3.0. Le altre opzioni sono disponibili in .NET 5 e versioni successive.

Abilita trimming

• <PublishTrimmed>true</PublishTrimmed>

  Abilita il trimming durante la pubblicazione. Questa impostazione disattiva anche le funzionalità non compatibili con il taglio e abilita l'analisi del taglio durante la compilazione. Nelle app .NET 8 e successive questa impostazione abilita anche l'associazione di configurazione e i generatori di origine delegati della richiesta.

Inserire questa impostazione nel file di progetto per assicurarsi che l'impostazione venga applicata durante dotnet build, non solo durante dotnet publish.

Questa impostazione consente di tagliare e tagliare tutti gli assembly per impostazione predefinita. In .NET 6 sono stati tagliati per impostazione predefinita solo gli assembly che hanno scelto di tagliare tramite [AssemblyMetadata("IsTrimmable", "True")] (aggiunti nei progetti che impostano <IsTrimmable>true</IsTrimmable>). È possibile tornare al comportamento precedente usando <TrimMode>partial</TrimMode>.

Questa impostazione abilita anche l'analizzatore Roslyn per la compatibilità di trim e disabilita le funzionalità incompatibili con il trimming.

Granularità trimming

Utilizzare la TrimMode proprietà per impostare la granularità di trimming su partial o full. L'impostazione predefinita per le app console (e, a partire da .NET 8, app Web SDK) è full:

<TrimMode>full</TrimMode>

Per eseguire il trimming solo sugli assembly che hanno accodato esplicitamente il trimming, impostare la proprietà su partial:

<TrimMode>partial</TrimMode>

Se si modifica la modalità di trimming in partial, è possibile acconsentire esplicitamente ai singoli assembly per eseguire il trimming usando un elemento MSBuild <TrimmableAssembly>.

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

Equivale all'impostazione [AssemblyMetadata("IsTrimmable", "True")] durante la compilazione dell'assembly.

Assembly radice

Se un assembly non viene tagliato, viene considerato "rooted", il che significa che verranno mantenute tutte le relative dipendenze comprensibili in modo statico. Gli assembly aggiuntivi possono essere "rooted" per nome (senza l'estensione .dll ):

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

Descrittori radice

Un altro modo per specificare le radici per l'analisi consiste nell'usare un file XML che usa il formato del descrittore trimmer. In questo modo è possibile eseguire la radice di membri specifici anziché un intero assembly.

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

Ad esempio, MyRoots.xml potrebbe eseguire la radice di un metodo specifico a cui l'applicazione accede in modo dinamico:

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

Avvisi di analisi

• <SuppressTrimAnalysisWarnings>false</SuppressTrimAnalysisWarnings>

  Abilitare gli avvisi di analisi di trimming.

Trimming rimuove IL che non è raggiungibile in modo statico. Le app che usano reflection o altri modelli che creano dipendenze dinamiche potrebbero essere interrotte tagliando. Per attivare avvisi su tali modelli, impostare su <SuppressTrimAnalysisWarnings> false. Questa impostazione visualizzerà avvisi sull'intera app, inclusi il codice, il codice della libreria e il codice del framework.

Analizzatori Roslyn

L'impostazione PublishTrimmed in .NET 6+ abilita anche un analizzatore Roslyn che mostra un set limitato di avvisi di analisi. È anche possibile abilitare o disabilitare l'analizzatore indipendentemente da PublishTrimmed.

• <EnableTrimAnalyzer>true</EnableTrimAnalyzer>

  Abilitare un analizzatore Roslyn per un subset di avvisi di analisi di trimming.

Non visualizzare gli avvisi

È possibile eliminare i singoli codici di avviso usando le normali proprietà di MSBuild rispettate dalla toolchain, tra cui NoWarn, WarningsAsErrors, WarningsNotAsErrors e TreatWarningsAsErrors. È disponibile un'opzione aggiuntiva che controlla il comportamento di avviso come errore ilLink in modo indipendente:

• <ILLinkTreatWarningsAsErrors>false</ILLinkTreatWarningsAsErrors>

  Non considerare gli avvisi ILLink come errori. Ciò può essere utile per evitare di trasformare gli avvisi di analisi di taglio in errori quando si considerano gli avvisi del compilatore come errori a livello globale.

Mostra avvisi dettagliati

In .NET 6+, l'analisi di trimming genera al massimo un avviso per ogni assembly proveniente da un PackageReference, a indicare che gli elementi interni dell'assembly non sono compatibili con il trimming. È anche possibile visualizzare singoli avvisi per tutti gli assembly:

• <TrimmerSingleWarn>false</TrimmerSingleWarn>

  Mostra tutti gli avvisi dettagliati, invece di compressione in un singolo avviso per assembly.

Rimuovere i simboli

Sui simboli viene in genere eseguito il trimming in modo che corrispondano agli assembly su cui è stato eseguito il trimming. È anche possibile rimuovere tutti i simboli:

• <TrimmerRemoveSymbols>true</TrimmerRemoveSymbols>

  Rimuovere i simboli dall'applicazione tagliata, inclusi i FILE PDB incorporati e i file PDB separati. Questo vale sia per il codice dell'applicazione che per le dipendenze fornite con simboli.

L'SDK consente anche di disabilitare il supporto del debugger usando la proprietà DebuggerSupport. Quando il supporto del debugger è disabilitato, il taglio rimuove automaticamente i simboli (TrimmerRemoveSymbols il valore predefinito è true).

Trim framework library features

Diverse aree di funzionalità delle librerie framework includono direttive trimmer che consentono di rimuovere il codice per le funzionalità disabilitate.

Queste proprietà causano il taglio del codice correlato e disabilitano anche le funzionalità tramite il file runtimeconfig. Per altre informazioni su queste proprietà, incluse le opzioni runtimeconfig corrispondenti, vedere Opzioni delle funzionalità. Alcuni SDK potrebbero avere valori predefiniti per queste proprietà.

Funzionalità del framework disabilitate durante il trimming

Le funzionalità seguenti non sono compatibili con il taglio perché richiedono codice a cui non viene fatto riferimento staticamente. Queste funzionalità sono disabilitate per impostazione predefinita nelle app tagliate.

• <BuiltInComInteropSupport>

  Il supporto COM predefinito è disabilitato.

• <CustomResourceTypesSupport>

  L'uso di tipi di risorse personalizzati non è supportato. I percorsi di codice ResourceManager che usano la reflection per i tipi di risorse personalizzati vengono eliminati.

• <EnableCppCLIHostActivation>

  L'attivazione dell'host C++/CLI è disabilitata.

• <EnableUnsafeBinaryFormatterInDesigntimeLicenseContextSerialization>

  L'uso DesigntimeLicenseContextSerializer della serializzazione BinaryFormatter è disabilitato.

• <StartupHookSupport>

  L'esecuzione del codice prima Main di con DOTNET_STARTUP_HOOKS non è supportata. Per ulteriori informazioni, vedere Host startup hook (Hook di avvio degli host).