Bagikan melalui

Opsi pemangkasan

  • Artikel

Properti dan item MSBuild yang dijelaskan dalam artikel ini memengaruhi perilaku penyebaran mandiri yang dipangkas. Beberapa opsi menyebutkan ILLink, yang merupakan nama alat yang mendasar yang mengimplementasikan pemangkasan. Untuk informasi selengkapnya tentang alat yang mendasar, lihat dokumentasi Pemangkas.

Pemangkasan dengan PublishTrimmed diperkenalkan dalam .NET Core 3.0. Opsi lain tersedia di .NET 5 dan versi yang lebih baru.

Mengaktifkan pemangkasan

  • <PublishTrimmed>true</PublishTrimmed>

    Aktifkan pemangkasan selama penerbitan. Pengaturan ini juga menonaktifkan fitur yang tidak kompatibel dengan trim dan memungkinkan analisis pemangkasan selama build. Di aplikasi .NET 8 dan yang lebih baru, pengaturan ini juga memungkinkan pengikatan konfigurasi dan meminta generator sumber delegasi.

Catatan

Jika Anda menentukan pemangkasan sebagai diaktifkan dari baris perintah, pengalaman penelusuran kesalahan Anda akan berbeda dan Anda mungkin mengalami bug tambahan di produk akhir.

Tempatkan pengaturan ini dalam file proyek untuk memastikan bahwa pengaturan berlaku selama dotnet build, bukan hanya dotnet publish.

Pengaturan ini memungkinkan pemangkasan dan pemangkasan semua rakitan secara default. Di .NET 6, hanya rakitan yang memilih untuk memangkas melalui [AssemblyMetadata("IsTrimmable", "True")] (ditambahkan dalam proyek yang ditetapkan <IsTrimmable>true</IsTrimmable>) yang dipangkas secara default. Anda dapat kembali ke perilaku sebelumnya dengan menggunakan <TrimMode>partial</TrimMode>.

Pengaturan ini memangkas rakitan apa pun yang telah dikonfigurasi untuk pemangkasan. Dengan Microsoft.NET.Sdk dalam .NET 6, ini mencakup rakitan apa pun dengan [AssemblyMetadata("IsTrimmable", "True")], yang merupakan kasus untuk rakitan runtime .NET. Di .NET 5, rakitan dari paket runtime netcoreapp dikonfigurasi untuk pemangkasan melalui <IsTrimmable> metadata MSBuild. SDK lain mungkin menentukan default yang berbeda.

Pengaturan ini juga memungkinkan penganalisis Roslyn kompatibilitas pemangkasan dan menonaktifkan fitur yang tidak kompatibel dengan pemangkasan.

Pemangkasan granularitas

TrimMode Gunakan properti untuk mengatur granularitas pemangkasan ke atau partial full. Pengaturan default untuk aplikasi konsol (dan, mulai dari .NET 8, aplikasi Web SDK) adalah full:

<TrimMode>full</TrimMode>

Untuk hanya memangkas rakitan yang telah memilih untuk memangkas, atur properti ke partial:

<TrimMode>partial</TrimMode>

Jika Anda mengubah mode pemangkasan menjadi partial, Anda dapat memilih rakitan individual untuk memangkas dengan menggunakan <TrimmableAssembly> item MSBuild.

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

Ini setara dengan pengaturan [AssemblyMetadata("IsTrimmable", "True")] saat membangun perakitan.

Pengaturan granularitas berikut mengontrol bagaimana IL yang tidak digunakan secara agresif dibuang. Ini dapat diatur sebagai properti yang memengaruhi semua rakitan input pemangkas, atau sebagai metadata pada rakitan individual, yang mengambil alih pengaturan properti.

  • <TrimMode>link</TrimMode>

    Aktifkan pemangkasan tingkat anggota, yang menghapus anggota yang tidak digunakan dari jenis. Ini adalah default dalam .NET 6+.

  • <TrimMode>copyused</TrimMode>

    Aktifkan pemangkasan tingkat perakitan, yang menyimpan seluruh rakitan jika ada bagian darinya yang digunakan (dengan cara yang dipahami secara statis).

Rakitan dengan <IsTrimmable>true</IsTrimmable> metadata tetapi tidak ada eksplisit TrimMode yang akan menggunakan global TrimMode. Default TrimMode untuk Microsoft.NET.Sdk berada link di .NET 6+, dan copyused di versi sebelumnya.

Memangkas rakitan tambahan

Di .NET 6+, PublishTrimmed pangkas rakitan dengan atribut tingkat rakitan berikut:

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

Pustaka kerangka kerja memiliki atribut ini. Di .NET 6+, Anda juga dapat memilih untuk memangkas pustaka tanpa atribut ini, menentukan rakitan berdasarkan nama (tanpa .dll ekstensi).

Pemangkasan pengaturan untuk rakitan individual

Saat menerbitkan aplikasi yang dipangkas, SDK menghitung panggilan ItemGroup ManagedAssemblyToLink yang mewakili kumpulan file yang akan diproses untuk pemangkasan. ManagedAssemblyToLink mungkin memiliki metadata yang mengontrol perilaku pemangkasan per perakitan. Untuk mengatur metadata ini, buat target yang berjalan sebelum target bawaan PrepareForILLink . Contoh berikut menunjukkan cara mengaktifkan pemangkasan MyAssembly.

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

Anda juga dapat menggunakan target ini untuk mengambil alih perilaku pemangkasan yang ditentukan oleh penulis pustaka, dengan mengatur <IsTrimmable>false</IsTrimmable> untuk perakitan dengan [AssemblyMetadata("IsTrimmable", "True"]).

Jangan menambahkan atau menghapus item dari ManagedAssemblyToLink, karena SDK menghitung set ini selama penerbitan dan mengharapkannya tidak berubah. Metadata yang didukung adalah:

  • <IsTrimmable>true</IsTrimmable>

    Mengontrol apakah rakitan yang diberikan dipangkas.

  • <TrimMode>copyused</TrimMode> atau <TrimMode>link</TrimMode>

    Mengontrol granularitas pemangkasan rakitan ini. Metadata ini lebih diutamakan daripada global TrimMode. Pengaturan TrimMode pada rakitan menyiratkan <IsTrimmable>true</IsTrimmable>.

  • <TrimmerSingleWarn>True</TrimmerSingleWarn>

    Kontrol apakah akan menampilkan peringatan tunggal untuk rakitan ini.

Rakitan akar

Jika rakitan tidak dipangkas, itu dianggap "berakar", yang berarti bahwa itu dan semua dependensi yang dipahami secara statis akan disimpan. Rakitan tambahan dapat "di-root" berdasarkan nama (tanpa .dll ekstensi):

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

Deskriptor akar

Cara lain untuk menentukan root untuk analisis adalah menggunakan file XML yang menggunakan format deskriptor pemangkas. Ini memungkinkan Anda membasar anggota tertentu alih-alih rakitan keseluruhan.

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

Misalnya, MyRoots.xml mungkin mengakar metode tertentu yang diakses secara dinamis oleh aplikasi:

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

Peringatan analisis

  • <SuppressTrimAnalysisWarnings>false</SuppressTrimAnalysisWarnings>

    Aktifkan peringatan analisis pemangkasan.

Pemangkasan menghapus IL yang tidak dapat dijangkau secara statis. Aplikasi yang menggunakan refleksi atau pola lain yang membuat dependensi dinamis mungkin rusak dengan pemangkasan. Untuk memperingatkan tentang pola tersebut, atur <SuppressTrimAnalysisWarnings> ke false. Pengaturan ini akan menampilkan peringatan tentang seluruh aplikasi, termasuk kode, kode pustaka, dan kode kerangka kerja Anda sendiri.

Penganalisis Roslyn

Pengaturan PublishTrimmed di .NET 6+ juga memungkinkan penganalisis Roslyn yang menunjukkan serangkaian peringatan analisis terbatas . Anda juga dapat mengaktifkan atau menonaktifkan penganalisis secara independen dari PublishTrimmed.

  • <EnableTrimAnalyzer>true</EnableTrimAnalyzer>

    Aktifkan penganalisis Roslyn untuk subset peringatan analisis pemangkasan.

Menutupi peringatan

Anda dapat menekan kode peringatan individual menggunakan properti MSBuild biasa yang dihormati oleh toolchain, termasuk NoWarn, , WarningsAsErrorsWarningsNotAsErrors, dan TreatWarningsAsErrors. Ada opsi tambahan yang mengontrol perilaku peringatan sebagai kesalahan ILLink secara independen:

  • <ILLinkTreatWarningsAsErrors>false</ILLinkTreatWarningsAsErrors>

    Jangan perlakukan peringatan ILLink sebagai kesalahan. Ini mungkin berguna untuk menghindari mengubah peringatan analisis pemangkasan menjadi kesalahan saat memperlakukan peringatan kompilator sebagai kesalahan secara global.

Tampilkan peringatan terperinci

Dalam .NET 6+, analisis pemangkasan menghasilkan paling banyak satu peringatan untuk setiap rakitan yang berasal dari PackageReference, yang menunjukkan bahwa internal rakitan tidak kompatibel dengan pemangkasan. Anda juga dapat menampilkan peringatan individual untuk semua rakitan:

  • <TrimmerSingleWarn>false</TrimmerSingleWarn>

    Tampilkan semua peringatan terperinci, alih-alih menciutkannya ke satu peringatan per perakitan.

Menghapus simbol

Simbol biasanya dipangkas agar sesuai dengan rakitan yang dipangkas. Anda juga dapat menghapus semua simbol:

  • <TrimmerRemoveSymbols>true</TrimmerRemoveSymbols>

    Hapus simbol dari aplikasi yang dipangkas, termasuk PDB yang disematkan dan file PDB terpisah. Ini berlaku untuk kode aplikasi dan dependensi apa pun yang disertakan dengan simbol.

SDK juga memungkinkan untuk menonaktifkan dukungan debugger menggunakan properti DebuggerSupport. Ketika dukungan debugger dinonaktifkan, pemangkasan akan menghapus simbol secara otomatis (TrimmerRemoveSymbols akan default ke true).

Memangkas fitur pustaka kerangka kerja

Beberapa area fitur pustaka kerangka kerja dilengkapi dengan arahan pemangkas yang memungkinkan untuk menghapus kode untuk fitur yang dinonaktifkan.

Properti MSBuild Deskripsi
AutoreleasePoolSupport Saat diatur ke false, menghapus kode yang membuat kumpulan penghapusan otomatis pada platform yang didukung. false adalah default untuk .NET SDK.
DebuggerSupport Saat diatur ke false, menghapus kode yang memungkinkan pengalaman penelusuran kesalahan yang lebih baik. Pengaturan ini juga menghapus simbol.
EnableUnsafeBinaryFormatterSerialization Saat diatur ke false, menghapus dukungan serialisasi BinaryFormatter. Untuk informasi selengkapnya, lihat Metode serialisasi BinaryFormatter usang dan implementasi BinaryFormatter dalam kotak dihapus dan selalu dilemparkan.
EnableUnsafeUTF7Encoding Saat diatur ke false, menghapus kode pengodean UTF-7 yang tidak aman. Untuk informasi selengkapnya, lihat Jalur kode UTF-7 sudah usang.
EventSourceSupport Saat diatur ke false, menghapus kode dan logika terkait EventSource.
HttpActivityPropagationSupport Saat diatur ke false, menghapus kode yang terkait dengan dukungan diagnostik untuk System.Net.Http.
InvariantGlobalization Saat diatur ke true, menghapus kode dan data khusus globalisasi. Untuk mengetahui informasi selengkapnya, lihat Mode Invarian.
MetadataUpdaterSupport Saat diatur ke false, menghapus logika khusus pembaruan metadata yang terkait dengan hot reload.
MetricsSupport Saat diatur ke false, menghapus dukungan untuk System.Diagnostics.Metrics instrumentasi.
StackTraceSupport (.NET 8+) Saat diatur ke false, menghapus dukungan untuk menghasilkan jejak tumpukan (misalnya, Environment.StackTrace atau Exception.ToString) oleh runtime. Jumlah informasi yang dihapus dari string pelacakan tumpukan mungkin bergantung pada opsi penyebaran lainnya. Opsi ini tidak memengaruhi jejak tumpukan yang dihasilkan oleh debugger.
UseNativeHttpHandler Saat diatur ke true, menggunakan implementasi HttpMessageHandler platform default untuk Android dan iOS dan menghapus implementasi terkelola.
UseSystemResourceKeys Saat diatur ke true, hapus pesan pengecualian untuk System.* rakitan. Ketika pengecualian dilemparkan dari System.* rakitan, pesan adalah ID sumber daya yang disederhanakan alih-alih pesan lengkap.
XmlResolverIsNetworkingEnabledByDefault (.NET 8+) Saat diatur ke false, menghapus dukungan untuk menyelesaikan URL non-file di System.Xml. Hanya penyelesaian sistem file yang didukung.

Properti ini menyebabkan kode terkait dipangkas dan juga menonaktifkan fitur melalui file runtimeconfig . Untuk informasi selengkapnya tentang properti ini, termasuk opsi runtimeconfig yang sesuai, lihat sakelar fitur. Beberapa SDK mungkin memiliki nilai default untuk properti ini.

Fitur kerangka kerja dinonaktifkan saat pemangkasan

Fitur berikut tidak kompatibel dengan pemangkasan karena memerlukan kode yang tidak dirujuk secara statis. Fitur-fitur ini dinonaktifkan secara default di aplikasi yang dipangkas.

Peringatan

Aktifkan fitur-fitur ini dengan risiko Anda sendiri. Mereka cenderung memutus aplikasi yang dipangkas tanpa pekerjaan tambahan untuk mempertahankan kode yang direferensikan secara dinamis.

  • <BuiltInComInteropSupport>

    Dukungan COM bawaan dinonaktifkan.

  • <CustomResourceTypesSupport>

    Penggunaan jenis sumber daya kustom tidak didukung. Jalur kode ResourceManager yang menggunakan pantulan untuk jenis sumber daya kustom dipangkas.

  • <EnableCppCLIHostActivation>

    Aktivasi host C++/CLI dinonaktifkan.

  • <EnableUnsafeBinaryFormatterInDesigntimeLicenseContextSerialization>

    DesigntimeLicenseContextSerializer penggunaan BinaryFormatter serialisasi dinonaktifkan.

  • <StartupHookSupport>

    Menjalankan kode sebelumnya Main dengan DOTNET_STARTUP_HOOKS tidak didukung. Untuk informasi selengkapnya, lihat hook startup host.