Bagikan melalui

Referensi MSBuild untuk proyek SDK .NET

  • Artikel

Halaman ini adalah referensi untuk properti MSBuild dan item yang dapat Anda gunakan untuk mengonfigurasi proyek .NET.

Catatan

Halaman ini adalah pekerjaan yang sedang berlangsung dan tidak mencantumkan semua properti MSBuild yang berguna untuk SDK .NET. Untuk daftar properti MSBuild umum, lihat Properti MSBuild Umum.

Properti validasi rakitan

Properti dan item ini diteruskan ke ValidateAssemblies tugas. Untuk informasi selengkapnya tentang validasi perakitan, lihat Validasi perakitan.

Properti MSBuild berikut ini didokumentasikan di bagian ini:

Catatan

Properti ini bukan bagian dari .NET SDK (belum). Untuk menggunakannya, Anda juga harus menambahkan PackageReference ke Microsoft.DotNet.ApiCompat.Task.

Selain itu, properti berikut yang didokumenkan dalam properti Validasi paket juga berlaku untuk validasi perakitan:

ApiCompatStrictMode

Ketika diatur ke true, ApiCompatStrictMode properti menentukan bahwa pemeriksaan kompatibilitas API harus dilakukan dalam mode ketat.

<PropertyGroup>
  <ApiCompatStrictMode>true</ApiCompatStrictMode>
</PropertyGroup>

ApiCompatValidateAssemblies

Properti ApiCompatValidateAssemblies memungkinkan serangkaian validasi pada rakitan yang ditentukan. Untuk informasi selengkapnya, lihat Validasi rakitan.

<PropertyGroup>
  <ApiCompatValidateAssemblies>true</ApiCompatValidateAssemblies>
</PropertyGroup>

Properti kerangka kerja

Properti MSBuild berikut ini didokumentasikan di bagian ini:

TargetFramework

Properti TargetFramework menentukan versi kerangka kerja target untuk aplikasi. Untuk daftar moniker kerangka kerja target yang valid, lihat Kerangka kerja target dalam proyek bergaya SDK.

<PropertyGroup>
  <TargetFramework>net8.0</TargetFramework>
</PropertyGroup>

Untuk mengetahui informasi selengkapnya, lihat Kerangka kerja target dalam proyek bergaya SDK.

TargetFrameworks

Gunakan properti TargetFrameworks saat Anda ingin aplikasi menargetkan beberapa platform. Untuk daftar moniker kerangka kerja target yang valid, lihat Kerangka kerja target dalam proyek bergaya SDK.

Catatan

Properti ini diabaikan jika TargetFramework (tunggal) ditentukan.

<PropertyGroup>
  <TargetFrameworks>net8.0;net462</TargetFrameworks>
</PropertyGroup>

Untuk mengetahui informasi selengkapnya, lihat Kerangka kerja target dalam proyek bergaya SDK.

NetStandardImplicitPackageVersion

Catatan

Properti ini hanya berlaku untuk proyek yang menggunakan netstandard1.x. Ini tidak berlaku untuk proyek yang menggunakan netstandard2.x.

Gunakan properti NetStandardImplicitPackageVersion saat Anda ingin menentukan versi kerangka kerja yang lebih rendah dari versi metapackage. File proyek dalam contoh berikut menargetkan netstandard1.3 tetapi menggunakan versi 1.6.0 dari NETStandard.Library.

<PropertyGroup>
  <TargetFramework>netstandard1.3</TargetFramework>
  <NetStandardImplicitPackageVersion>1.6.0</NetStandardImplicitPackageVersion>
</PropertyGroup>

Properti atribut rakitan

GenerateAssemblyInfo

Properti GenerateAssemblyInfo mengontrol pembuatan atribut AssemblyInfo untuk proyek. Nilai defaultnya adalah true. Gunakan false untuk menonaktifkan pembuatan file:

<PropertyGroup>
  <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
</PropertyGroup>

Pengaturan GeneratedAssemblyInfoFile mengontrol nama file yang dibuat.

Ketika nilai GenerateAssemblyInfo adalah true, properti proyek terkait paket diubah menjadi atribut rakitan.

Untuk informasi selengkapnya tentang membuat atribut rakitan menggunakan file proyek, lihat Mengatur atribut perakitan dalam file proyek.

GeneratedAssemblyInfoFile

Properti GeneratedAssemblyInfoFile mendefinisikan jalur relatif atau absolut dari file info perakitan yang dibuat. Default ke file bernama [project-name]. AssemblyInfo. [cs|vb] dalam direktori $(IntermediateOutputPath) (biasanya obj).

<PropertyGroup>
  <GeneratedAssemblyInfoFile>assemblyinfo.cs</GeneratedAssemblyInfoFile>
</PropertyGroup>

Properti paket

Properti deskriptif

Anda dapat menentukan properti seperti PackageId, PackageVersion, PackageIcon, Title, dan Description untuk menjelaskan paket yang dibuat dari proyek Anda. Untuk mengetahui informasi tentang properti ini dan properti lainnya, lihat target paket.

<PropertyGroup>
  ...
  <PackageId>ClassLibDotNetStandard</PackageId>
  <Version>1.0.0</Version>
  <Authors>John Doe</Authors>
  <Company>Contoso</Company>
</PropertyGroup>

PackRelease

Properti PackRelease ini mirip dengan properti PublishRelease , kecuali mengubah perilaku dotnet packdefault . Properti ini diperkenalkan dalam .NET 7.

<PropertyGroup>
  <PackRelease>true</PackRelease>
</PropertyGroup>

Catatan

  • Mulai dari .NET 8 SDK, PackRelease default ke true. Untuk informasi selengkapnya, lihat 'dotnet pack' menggunakan konfigurasi Rilis.
  • .NET 7 SDK saja: Untuk menggunakan PackRelease dalam proyek yang merupakan bagian dari solusi Visual Studio, Anda harus mengatur variabel DOTNET_CLI_ENABLE_PACK_RELEASE_FOR_SOLUTIONS lingkungan ke true (atau nilai lainnya). Untuk solusi yang memiliki banyak proyek, pengaturan variabel ini meningkatkan waktu yang diperlukan untuk mengemas.

Properti validasi paket

Properti dan item ini diteruskan ke ValidatePackage tugas. Untuk informasi selengkapnya tentang validasi paket, lihat Gambaran umum validasi paket.

Untuk properti untuk tugas, ValidateAssemblies lihat Properti validasi rakitan.

Properti dan item MSBuild berikut ini didokumenkan di bagian ini:

ApiCompatEnableRuleAttributesMustMatch

Saat diatur ke true, ApiCompatEnableRuleAttributesMustMatch properti mengaktifkan aturan validasi yang memeriksa apakah atribut cocok. Default adalah false.

<PropertyGroup>
  <ApiCompatEnableRuleAttributesMustMatch>true</ApiCompatEnableRuleAttributesMustMatch>
</PropertyGroup>

ApiCompatEnableRuleCannotChangeParameterName

Saat diatur ke true, ApiCompatEnableRuleCannotChangeParameterName properti mengaktifkan aturan validasi yang memeriksa apakah nama parameter telah berubah dalam metode publik. Default adalah false.

<PropertyGroup>
  <ApiCompatEnableRuleCannotChangeParameterName>true</ApiCompatEnableRuleCannotChangeParameterName>
</PropertyGroup>

ApiCompatExcludeAttributesFile

Item ApiCompatExcludeAttributesFile menentukan jalur ke file yang berisi atribut yang akan dikecualikan dalam format DocId .

<ItemGroup>
  <ApiCompatExcludeAttributesFile Include="ApiCompatExcludedAttributes.txt" />
  <ApiCompatExcludeAttributesFile Include="ApiCompatBaselineExcludedAttributes.txt" />
</ItemGroup>

ApiCompatGenerateSuppressionFile

Properti ApiCompatGenerateSuppressionFile menentukan apakah akan menghasilkan file supresi kompatibilitas.

<PropertyGroup>
  <ApiCompatGenerateSuppressionFile>true</ApiCompatGenerateSuppressionFile>
</PropertyGroup>

ApiCompatPermitUncessarySuppressions

Properti ApiCompatPermitUnnecessarySuppressions menentukan apakah akan mengizinkan supresi yang tidak perlu dalam file supresi.

Default adalah false.

<PropertyGroup>
  <ApiCompatPermitUnnecessarySuppressions>true</ApiCompatPermitUnnecessarySuppressions>
</PropertyGroup>

ApiCompatPreserveUncessarySuppressions

Properti ApiCompatPreserveUnnecessarySuppressions menentukan apakah akan mempertahankan supresi yang tidak perlu saat meregenerasi file supresi. Ketika file supresi yang ada diregenerasi, kontennya dibaca, dideserialisasi ke dalam serangkaian supresi, lalu disimpan dalam daftar. Beberapa supresi mungkin tidak lagi diperlukan jika ketidaksesuaian telah diperbaiki. Ketika supresi diserialisasikan kembali ke disk, Anda dapat memilih untuk menyimpan semua ekspresi (deserialisasi) yang ada dengan mengatur properti ini ke true.

Default adalah false.

<PropertyGroup>
  <ApiCompatPreserveUnnecessarySuppressions>true</ApiCompatPreserveUnnecessarySuppressions>
</PropertyGroup>

ApiCompatRespectInternals

Properti ApiCompatRespectInternals menentukan apakah internal API harus diperiksa kompatibilitasnya selain public API.

<PropertyGroup>
  <ApiCompatRespectInternals>true</ApiCompatRespectInternals>
</PropertyGroup>

ApiCompatSuppressionFile

Item ApiCompatSuppressionFile menentukan jalur ke satu atau beberapa file supresi untuk dibaca. Jika tidak ditentukan, file <supresi project-directory>/CompatibilitySuppressions.xml dibaca (jika ada).

<ItemGroup>
  <ApiCompatSuppressionFile Include="CompatibilitySuppressions.xml;CompatibilitySuppressions.WasmThreads.xml" />
</ItemGroup>

ApiCompatSuppressionOutputFile

Properti ApiCompatSuppressionOutputFile menentukan jalur ke file supresi yang akan ditulis ketika <ApiCompatGenerateSuppressionFile> adalah true. Jika tidak ditentukan, item pertama ApiCompatSuppressionFile digunakan.

EnablePackageValidation

Properti EnablePackageValidation memungkinkan serangkaian validasi pada paket setelah tugas Pack. Untuk mengetahui informasi selengkapnya, lihat validasi paket.

<PropertyGroup>
  <EnablePackageValidation>true</EnablePackageValidation>
</PropertyGroup>

EnableStrictModeForBaselineValidation

Saat diatur ke true, EnableStrictModeForBaselineValidation properti mengaktifkan mode ketat untuk pemeriksaan garis besar paket. Default adalah false.

EnableStrictModeForCompatibleFrameworksInPackage

Saat diatur ke true, EnableStrictModeForCompatibleFrameworksInPackage properti memungkinkan mode ketat untuk rakitan yang kompatibel berdasarkan kerangka kerja targetnya. Default adalah false.

EnableStrictModeForCompatibleTfms

Saat diatur ke true, EnableStrictModeForCompatibleTfms properti memungkinkan mode ketat untuk rakitan kontrak dan implementasi untuk semua kerangka kerja target yang kompatibel. Default adalah true.

NoWarn

Properti NoWarn menentukan ID diagnostik untuk ditekan.

<PropertyGroup>
  <NoWarn>$(NoWarn);PKV0001</NoWarn>
</PropertyGroup>

PackageValidationBaselineFrameworkToIgnore

Item PackageValidationBaselineFrameworkToIgnore menentukan kerangka kerja target untuk diabaikan dari paket garis besar. String kerangka kerja harus sama persis dengan nama folder dalam paket garis besar.

<ItemGroup>
  <PackageValidationBaselineFrameworkToIgnore Include="netcoreapp2.1" />
</ItemGroup>

PackageValidationBaselineName

Properti PackageValidationBaselineName menentukan nama paket garis besar untuk memvalidasi paket saat ini. Jika tidak ditentukan, PackageId nilai digunakan.

PackageValidationBaselineVersion

Properti PackageValidationBaselineVersion menentukan versi paket garis besar untuk memvalidasi paket saat ini.

PackageValidationReferencePath

Item PackageValidationReferencePath menentukan jalur direktori tempat perakitan referensi dapat ditemukan per TFM.

<ItemGroup>
  <PackageValidationReferencePath Include="path/to/reference-assembly" TargetFramework="net7.0" />
</ItemGroup>

RoslynAssembliesPath

Properti RoslynAssembliesPath menentukan jalur ke direktori yang berisi rakitan Microsoft.CodeAnalysis yang ingin Anda gunakan. Anda hanya perlu mengatur properti ini jika Anda ingin menguji dengan pengkompilasi yang lebih baru daripada apa yang ada di SDK.

Properti MSBuild berikut ini didokumentasikan di bagian ini:

AppendTargetFrameworkToOutputPath

Properti AppendTargetFrameworkToOutputPath mengontrol apakah moniker kerangka kerja target (TFM) ditambahkan ke jalur output (yang ditentukan oleh OutputPath). .NET SDK otomatis menambahkan kerangka kerja target dan, jika ada, pengidentifikasi runtime ke jalur output. Mengatur AppendTargetFrameworkToOutputPath ke false mencegah TFM ditambahkan ke jalur output. Namun, tanpa TFM di jalur output, beberapa artefak build dapat saling menimpa.

Misalnya, untuk aplikasi .NET 5, jalur output berubah dari bin\Debug\net5.0 ke bin\Debug dengan pengaturan berikut:

<PropertyGroup>
  <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
</PropertyGroup>

AppendRuntimeIdentifierToOutputPath

Properti AppendRuntimeIdentifierToOutputPath mengontrol apakah pengidentifikasi runtime (RID) ditambahkan ke jalur output. .NET SDK otomatis menambahkan kerangka kerja target dan, jika ada, pengidentifikasi runtime ke jalur output. Mengatur AppendRuntimeIdentifierToOutputPath ke false mencegah RID ditambahkan ke jalur output.

Misalnya, untuk aplikasi .NET 5 dan RID dari win-x64, pengaturan berikut mengubah jalur output dari bin\Debug\net5.0\win-x64 menjadi bin\Debug\net5.0:

<PropertyGroup>
  <AppendRuntimeIdentifierToOutputPath>false</AppendRuntimeIdentifierToOutputPath>
</PropertyGroup>

CopyLocalLockFileAssemblies

Properti CopyLocalLockFileAssemblies ini berguna untuk proyek plugin yang memiliki dependensi pada pustaka lain. Jika Anda mengatur properti ini ke true, dependensi paket NuGet transitif apa pun disalin ke direktori output. Itu berarti Anda dapat menggunakan output dotnet build untuk menjalankan plugin di komputer apa pun.

<PropertyGroup>
  <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
</PropertyGroup>

Nilai CopyLocalLockFileAssemblies default dapat bervariasi berdasarkan jenis output. Misalnya, untuk pustaka kelas, nilai defaultnya adalah false, sedangkan untuk aplikasi konsol defaultnya adalah true. Anda dapat menentukan properti ini secara eksplisit untuk mengambil alih default jika diperlukan.

Tip

Atau, Anda dapat menggunakan dotnet publish untuk menerbitkan pustaka kelas. Untuk mengetahui informasi selengkapnya, lihat dotnet publish.

ErrorOnDuplicatePublishOutputFiles

Properti ErrorOnDuplicatePublishOutputFiles berkaitan dengan apakah SDK membuat kesalahan NETSDK1148 saat MSBuild mendeteksi file duplikat dalam output penerbitan, tetapi tidak dapat menentukan file mana yang akan dihapus. Atur properti ErrorOnDuplicatePublishOutputFiles ke false jika Anda tidak ingin kesalahan dihasilkan.

<PropertyGroup>
  <ErrorOnDuplicatePublishOutputFiles>false</ErrorOnDuplicatePublishOutputFiles>
</PropertyGroup>

Properti ini diperkenalkan di .NET 6.

GenerateRuntimeConfigDevFile

Dimulai dengan .NET 6 SDK, file [Appname].runtimesettings.dev.json tidak lagi dibuat secara default pada waktu kompilasi. Jika Anda masih ingin file ini dibuat, atur properti GenerateRuntimeConfigDevFile ke true.

<PropertyGroup>
  <GenerateRuntimeConfigDevFile>true</GenerateRuntimeConfigDevFile>
</PropertyGroup>

GenerateRuntimeConfigurationFiles

Properti GenerateRuntimeConfigurationFiles mengontrol apakah opsi konfigurasi runtime disalin dari file runtimeconfig.template.json ke file [appname].runtimeconfig.json. Untuk aplikasi yang memerlukan file runtimeconfig.json, yaitu, yang OutputType-nya merupakan Exe, properti ini default ke true.

<PropertyGroup>
  <GenerateRuntimeConfigurationFiles>true</GenerateRuntimeConfigurationFiles>
</PropertyGroup>

GenerateSatelliteAssembliesForCore

Properti GenerateSatelliteAssembliesForCore mengontrol apakah rakitan satelit dibuat menggunakan csc.exe atau Al.exe (Assembly Linker) dalam proyek .NET Framework. (Proyek .NET Core dan .NET 5+ selalu menggunakan csc.exe untuk membuat rakitan satelit.) Untuk proyek .NET Framework, rakitan satelit dibuat oleh al.exe, secara default. Dengan mengatur properti GenerateSatelliteAssembliesForCore ke true, rakitan satelit dibuat oleh csc.exe sebagai gantinya. Menggunakan csc.exe dapat menguntungkan dalam situasi berikut:

<PropertyGroup>
  <GenerateSatelliteAssembliesForCore>true</GenerateSatelliteAssembliesForCore>
</PropertyGroup>

IsPublishable

Properti IsPublishable memungkinkan target Publish berjalan. Properti ini hanya memengaruhi proses yang menggunakan file .*proj dan target Publish, seperti perintah dotnet publish. Properti tidak memengaruhi penerbitan di Visual Studio, yang menggunakan target PublishOnly. Nilai defaultnya adalah true.

Properti ini berguna jika Anda menjalankan dotnet publish di file solusi, karena memungkinkan pemilihan proyek otomatis yang harus diterbitkan.

<PropertyGroup>
  <IsPublishable>false</IsPublishable>
</PropertyGroup>

PreserveCompilationContext

Properti PreserveCompilationContext memungkinkan aplikasi yang dibuat atau diterbitkan untuk mengompilasi lebih banyak kode saat runtime menggunakan pengaturan yang sama yang digunakan pada waktu build. Rakitan yang direferensikan pada waktu build akan disalin ke subdirektori ref dari direktori output. Nama rakitan referensi disimpan dalam file .deps.json aplikasi bersama dengan opsi yang diteruskan ke kompilator. Anda dapat mengambil informasi ini menggunakan properti DependencyContext.CompileLibraries dan DependencyContext.CompilationOptions.

Fungsionalitas ini sebagian besar digunakan secara internal oleh halaman ASP.NET Core MVC dan Razor untuk mendukung kompilasi run-time file Razor.

<PropertyGroup>
  <PreserveCompilationContext>true</PreserveCompilationContext>
</PropertyGroup>

PreserveCompilationReferences

Properti PreserveCompilationReferences mirip dengan properti PreserveCompilationContext, kecuali properti hanya menyalin rakitan yang direferensikan ke direktori penerbitan, dan bukan file .deps.json.

<PropertyGroup>
  <PreserveCompilationReferences>true</PreserveCompilationReferences>
</PropertyGroup>

Untuk mengetahui informasi selengkapnya, lihat Properti SDK Razor.

ProduceReferenceAssemblyInOutDir

Di .NET 5 dan versi yang lebih lama, rakitan referensi selalu ditulis ke direktori OutDir. Di .NET 6 dan versi yang lebih baru, Anda dapat menggunakan properti ProduceReferenceAssemblyInOutDir untuk mengontrol apakah rakitan referensi ditulis ke direktori OutDir. Nilai defaultnya adalah false, dan rakitan referensi hanya ditulis ke direktori IntermediateOutputPath. Atur nilai ke true untuk menulis rakitan referensi ke direktori OutDir.

<PropertyGroup>
  <ProduceReferenceAssemblyInOutDir>true</ProduceReferenceAssemblyInOutDir>
</PropertyGroup>

Untuk mengetahui informasi selengkapnya, lihat Menulis rakitan referensi ke output perantara.

PublishDocumentationFile

Ketika properti ini adalah true, file dokumentasi XML untuk proyek, jika dibuat, disertakan dalam output penerbitan untuk proyek. Properti ini default ke true.

Tip

Atur GenerateDocumentationFile ke true untuk menghasilkan file dokumentasi XML pada waktu kompilasi.

PublishDocumentationFiles

Properti ini adalah bendera pengaktifan untuk beberapa properti lain yang mengontrol apakah berbagai jenis file dokumentasi XML disalin ke direktori penerbitan secara default, yaitu PublishDocumentationFile dan PublishReferencesDocumentationFiles. Jika properti tersebut tidak diatur, dan properti ini diatur, maka properti tersebut akan default ke true. Properti ini default ke true.

PublishReferencesDocumentationFiles

Ketika properti ini adalah true, file dokumentasi XML untuk referensi proyek disalin ke direktori penerbitan, alih-alih hanya aset run-time seperti file DLL. Properti ini default ke true.

PublishRelease

Properti PublishRelease menginformasikan dotnet publish untuk menggunakan Release konfigurasi secara default alih-alih Debug konfigurasi. Properti ini diperkenalkan dalam .NET 7.

<PropertyGroup>
  <PublishRelease>true</PublishRelease>
</PropertyGroup>

Catatan

  • Mulai dari .NET 8 SDK, PublishRelease default untuk true proyek yang menargetkan .NET 8 atau yang lebih baru. Untuk informasi selengkapnya, lihat 'penerbitan dotnet' menggunakan konfigurasi Rilis.
  • Properti ini tidak memengaruhi perilaku dotnet build /t:Publish, dan hanya mengubah konfigurasi hanya saat menerbitkan melalui .NET CLI.
  • .NET 7 SDK saja: Untuk menggunakan PublishRelease dalam proyek yang merupakan bagian dari solusi Visual Studio, Anda harus mengatur variabel DOTNET_CLI_ENABLE_PUBLISH_RELEASE_FOR_SOLUTIONS lingkungan ke true (atau nilai lainnya). Saat menerbitkan solusi dengan variabel ini diaktifkan, nilai proyek PublishRelease yang dapat dieksekusi lebih diutamakan dan mengalirkan konfigurasi default baru ke proyek lain dalam solusi. Jika solusi berisi beberapa proyek yang dapat dieksekusi atau tingkat atas dengan nilai yang berbeda , PublishReleasesolusi tidak akan berhasil diterbitkan. Untuk solusi yang memiliki banyak proyek, penggunaan pengaturan ini meningkatkan waktu yang diperlukan untuk menerbitkan.

PublishSelfContained

Properti PublishSelfContained menginformasikan dotnet publish untuk menerbitkan aplikasi sebagai aplikasi mandiri. Properti ini berguna saat Anda tidak dapat menggunakan --self-contained argumen untuk perintah terbitkan dotnet—misalnya, saat Anda menerbitkan di tingkat solusi. Dalam hal ini, Anda dapat menambahkan PublishSelfContained properti MSBuild ke proyek atau file Directory.Build.Props .

Properti ini diperkenalkan dalam .NET 7. Ini mirip dengan properti SelfContained , kecuali khusus untuk publish kata kerja. Disarankan untuk menggunakan PublishSelfContained alih-alih SelfContained.

<PropertyGroup>
  <PublishSelfContained>true</PublishSelfContained>
</PropertyGroup>

RollForward

Properti RollForward mengontrol cara aplikasi memilih runtime saat beberapa versi runtime tersedia. Nilai ini adalah output ke .runtimeconfig.json sebagai pengaturan rollForward.

<PropertyGroup>
  <RollForward>LatestMinor</RollForward>
</PropertyGroup>

Atur RollForward ke salah satu nilai berikut:

Nilai Deskripsi
Minor Default jika tidak ditentukan.
Pindah ke versi kecil terendah yang lebih tinggi, jika versi kecil yang diminta tidak ada. Jika ada versi kecil yang diminta, kebijakan LatestPatch digunakan.
Major Pindah ke versi besar yang lebih tinggi yang tersedia, dan versi kecil terendah, jika versi besar yang diminta tidak ada. Jika ada versi besar yang diminta, kebijakan Minor digunakan.
LatestPatch Maju ke versi patch paling tinggi. Nilai ini menonaktifkan pindah ke versi kecil.
LatestMinor Pindah ke versi kecil tertinggi, meskipun ada versi kecil yang diminta.
LatestMajor Pindah ke versi besar tertinggi dan kecil tertinggi, meskipun ada versi besar yang diminta.
Disable Jangan pindah, hanya ikat ke versi yang ditentukan. Kebijakan ini tidak disarankan untuk penggunaan umum karena menonaktifkan kemampuan untuk berpindah ke patch terbaru. Nilai ini hanya disarankan untuk pengujian.

Untuk mengetahui informasi selengkapnya, lihat Mengontrol perilaku berpindah.

RuntimeFrameworkVersion

Properti RuntimeFrameworkVersion menentukan versi runtime yang akan digunakan saat menerbitkan. Tentukan versi runtime:

<PropertyGroup>
  <RuntimeFrameworkVersion>5.0.7</RuntimeFrameworkVersion>
</PropertyGroup>

Saat menerbitkan aplikasi yang bergantung pada kerangka kerja, nilai ini menentukan versi minimum yang diperlukan. Saat menerbitkan aplikasi mandiri, nilai ini menentukan versi yang tepat yang diperlukan.

RuntimeIdentifier

Properti RuntimeIdentifier memungkinkan Anda menentukan pengidentifikasi runtime (RID) tunggal untuk proyek. RID memungkinkan penerbitan penyebaran mandiri.

<PropertyGroup>
  <RuntimeIdentifier>linux-x64</RuntimeIdentifier>
</PropertyGroup>

RuntimeIdentifiers

Properti RuntimeIdentifiers memungkinkan Anda menentukan daftar pengidentifikasi runtime (RID) yang dibatasi titik koma untuk proyek. Gunakan properti ini jika Anda perlu menerbitkan untuk beberapa runtime. RuntimeIdentifiers digunakan pada waktu pemulihan untuk memastikan aset yang tepat ada dalam grafik.

Tip

RuntimeIdentifier (tunggal) dapat menyediakan build yang lebih cepat saat hanya satu runtime yang diperlukan.

<PropertyGroup>
  <RuntimeIdentifiers>win-x64;osx-x64;linux-x64</RuntimeIdentifiers>
</PropertyGroup>

SatelliteResourceLanguages

Properti SatelliteResourceLanguages memungkinkan Anda menentukan bahasa mana yang ingin Anda pertahankan rakitan sumber daya satelitnya selama build dan penerbitan. Banyak paket NuGet termasuk rakitan satelit sumber daya yang dilokalkan dalam paket utama. Untuk proyek yang mereferensikan paket NuGet ini yang tidak memerlukan sumber daya yang dilokalkan, rakitan yang dilokalkan tidak perlu meningkatkan ukuran output build dan penerbitan. Dengan menambahkan properti SatelliteResourceLanguages ke file proyek Anda, hanya rakitan lokal untuk bahasa yang Anda tentukan yang akan disertakan dalam output build dan penerbitan. Misalnya, dalam file proyek berikut, hanya rakitan satelit sumber daya Inggris (AS) dan Jerman (Jerman) yang akan dipertahankan.

<PropertyGroup>
  <SatelliteResourceLanguages>en-US;de-DE</SatelliteResourceLanguages>
</PropertyGroup>

Catatan

  • Anda harus menentukan properti ini dalam proyek yang mereferensikan paket NuGet dengan rakitan satelit sumber daya yang dilokalkan.

  • Untuk menentukan beberapa bahasa sebagai argumen ke dotnet publish, Anda harus menambahkan tiga pasang tanda kutip di sekitar pengidentifikasi bahasa. Contohnya:

    dotnet msbuild multi.msbuildproj -p:SatelliteResourceLanguages="""de;en"""

SelfContained

Properti SelfContained menginformasikan dotnet build dan dotnet publish untuk membangun atau menerbitkan aplikasi sebagai aplikasi mandiri. Properti ini berguna ketika Anda tidak dapat menggunakan --self-contained argumen dengan perintah dotnet —misalnya, saat Anda menerbitkan di tingkat solusi. Dalam hal ini, Anda dapat menambahkan SelfContained properti MSBuild ke proyek atau file Directory.Build.Props .

Properti ini mirip dengan properti PublishSelfContained . Disarankan untuk menggunakan PublishSelfContained alih-alih SelfContained jika memungkinkan.

<PropertyGroup>
  <SelfContained>true</SelfContained>
</PropertyGroup>

UseAppHost

Properti UseAppHost mengontrol apakah executable native dibuat untuk penyebaran atau tidak. Executable native diperlukan untuk penyebaran mandiri. Executable yang bergantung pada kerangka kerja dibuat secara default. Atur properti UseAppHost ke false untuk menonaktifkan pembuatan executable.

<PropertyGroup>
  <UseAppHost>false</UseAppHost>
</PropertyGroup>

Untuk mengetahui informasi selengkapnya tentang penyebaran, lihat penyebaran aplikasi .NET.

Banyak properti MSBuild tersedia untuk menyempurnakan pemangkasan, yang merupakan fitur yang memangkas kode yang tidak digunakan dari penyebaran mandiri. Opsi ini dibahas secara rinci di Opsi pemangkasan. Tabel berikut ini menyediakan referensi cepat.

Properti Nilai Deskripsi
PublishTrimmed true atau false Mengontrol apakah pemangkasan diaktifkan selama penerbitan.
TrimMode full atau partial Defaultnya adalah full. Mengontrol granularitas pemangkasan.
SuppressTrimAnalysisWarnings true atau false Mengontrol apakah peringatan analisis pemangkasan dihasilkan.
EnableTrimAnalyzer true atau false Mengontrol apakah subset peringatan analisis pemangkasan dihasilkan. Anda dapat mengaktifkan analisis meskipun PublishTrimmed diatur ke false.
ILLinkTreatWarningsAsErrors true atau false Mengontrol apakah peringatan pemangkasan diperlakukan sebagai kesalahan. Misalnya, Anda mungkin ingin mengatur properti ini ke false saat TreatWarningsAsErrors diatur ke true.
TrimmerSingleWarn true atau false Mengontrol apakah satu peringatan per rakitan ditampilkan atau semua peringatan.
TrimmerRemoveSymbols true atau false Mengontrol apakah semua simbol dihapus dari aplikasi yang dipangkas.

Properti MSBuild berikut ini didokumentasikan di bagian ini:

Opsi kompilator C#, seperti LangVersion dan Nullable, juga dapat ditentukan sebagai properti MSBuild dalam file proyek Anda. Untuk mengetahui informasi selengkapnya, lihat Opsi kompilator C#.

ContinuousIntegrationBuild

Properti ContinuousIntegrationBuild menunjukkan apakah build dijalankan pada server integrasi berkelanjutan (CI). Ketika diatur ke true, properti ini memungkinkan pengaturan yang hanya berlaku untuk build resmi dibandingkan dengan build lokal pada komputer pengembang. Misalnya, jalur file tersimpan dinormalisasi untuk build resmi. Tetapi pada komputer pengembangan lokal, debugger tidak dapat menemukan file sumber lokal jika jalur file dinormalisasi.

Catatan

Saat ini, atur properti ini agar true berfungsi hanya jika Anda menambahkan referensi paket penyedia SourceLink tertentu atau <SourceRoot Include="$(MyDirectory)" /> item. Untuk informasi selengkapnya, lihat masalah dotnet/roslyn 55860.

Anda dapat menggunakan variabel sistem CI Anda untuk mengatur ContinuousIntegrationBuild properti secara kondisional. Misalnya, nama variabel untuk Azure Pipelines adalah TF_BUILD:

<PropertyGroup Condition="'$(TF_BUILD)' == 'true'">
  <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
</PropertyGroup>

Untuk GitHub Actions, nama variabelnya adalah GITHUB_ACTIONS:

<PropertyGroup Condition="'$(GITHUB_ACTIONS)' == 'true'">
  <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
</PropertyGroup>

CopyDebugSymbolFilesFromPackages

Ketika properti ini diatur ke true, semua file simbol (juga dikenal sebagai file PDB) dari PackageReference item dalam proyek disalin ke output build. File-file ini dapat memberikan jejak tumpukan yang lebih informatif untuk pengecualian dan membuat cadangan memori dan jejak aplikasi yang sedang berjalan lebih mudah dipahami. Namun, termasuk file-file ini menghasilkan peningkatan ukuran bundel penyebaran.

Properti ini diperkenalkan dalam .NET SDK 7.0.100, meskipun defaultnya tidak ditentukan.

CopyDocumentationFilesFromPackages

Ketika properti ini diatur ke true, semua file dokumentasi XML yang dihasilkan dari PackageReference item dalam proyek disalin ke output build. Perhatikan bahwa mengaktifkan fitur ini akan menghasilkan peningkatan ukuran bundel penyebaran.

Properti ini diperkenalkan dalam .NET SDK 7.0.100, meskipun defaultnya tidak ditentukan.

DisableImplicitFrameworkDefines

Properti DisableImplicitFrameworkDefines mengontrol apakah SDK membuat simbol pra-prosesor atau tidak untuk kerangka kerja target dan platform untuk proyek .NET. Saat properti ini diatur ke false atau tidak diatur (yang merupakan nilai default) simbol pra-prosesor dihasilkan untuk:

  • Kerangka kerja tanpa versi (NETFRAMEWORK, NETSTANDARD, NET)
  • Kerangka kerja dengan versi (NET48, NETSTANDARD2_0, NET6_0)
  • Kerangka kerja dengan batas minimum versi (NET48_OR_GREATER, NETSTANDARD2_0_OR_GREATER, NET6_0_OR_GREATER)

Untuk mengetahui informasi selengkapnya tentang moniker kerangka kerja target dan simbol pra-prosesor implisit ini, lihat Kerangka kerja target.

Selain itu, jika Anda menentukan kerangka kerja target khusus sistem operasi dalam proyek (misalnya net6.0-android), simbol praprosesor berikut dibuat:

  • Platform tanpa versi (ANDROID, IOS, WINDOWS)
  • Platform dengan versi (IOS15_1)
  • Kerangka kerja dengan batas minimum versi (IOS15_1_OR_GREATER)

Untuk mengetahui informasi selengkapnya tentang moniker kerangka kerja target khusus sistem operasi, lihat TFM khusus OS.

Terakhir, jika kerangka kerja target Anda menyiratkan dukungan untuk kerangka kerja target yang lebih lama, simbol prapemroses untuk kerangka kerja lama tersebut dikeluarkan. Misalnya, net6.0 menyiratkan dukungan untuk net5.0 dan sebagainya sepanjang perjalanan kembali ke .netcoreapp1.0. Jadi, untuk setiap kerangka kerja target ini, simbol Kerangka Kerja dengan batas minimum versi akan ditentukan.

DocumentationFile

Properti DocumentationFile memungkinkan Anda menentukan nama file untuk file XML yang berisi dokumentasi untuk pustaka. Agar IntelliSense berfungsi dengan benar dengan dokumentasi Anda, nama file harus sama dengan nama rakitan dan harus berada di direktori yang sama dengan rakitan. Jika Anda tidak menentukan properti ini tetapi mengatur GenerateDocumentationFile ke true, nama file dokumentasi default ke nama rakitan Anda tetapi dengan ekstensi file .xml. Karena alasan ini, sering kali lebih mudah untuk menghapus properti ini dan menggunakan properti GenerateDocumentationFile sebagai gantinya.

Jika Anda menentukan properti ini tetapi mengatur GenerateDocumentationFile ke false, kompilator tidak membuat file dokumentasi. Jika Anda menentukan properti ini dan menghapus properti GenerateDocumentationFile, kompilator benar-benar membuat file dokumentasi.

<PropertyGroup>
  <DocumentationFile>path/to/file.xml</DocumentationFile>
</PropertyGroup>

EmbeddedResourceUseDependentUponConvention

Properti EmbeddedResourceUseDependentUponConvention menentukan apakah nama file manifes sumber daya dibuat dari informasi jenis dalam file sumber yang terletak bersama dengan file sumber daya. Misalnya, jika Form1.resx berada di folder yang sama dengan Form1.cs, dan EmbeddedResourceUseDependentUponConvention diatur ke true, file .resources yang dibuat mengambil namanya dari jenis pertama yang ditentukan dalam Form1.cs. Jika MyNamespace.Form1 adalah jenis pertama yang ditentukan dalam Form1.cs, nama file yang dihasilkan adalah MyNamespace.Form1.resources.

Catatan

Jika metadata LogicalName, ManifestResourceName, atau DependentUpon ditentukan untuk item EmbeddedResource, nama file manifes yang dibuat untuk file sumber daya tersebut didasarkan pada metadata tersebut sebagai gantinya.

Secara default, dalam proyek .NET baru yang menargetkan .NET Core 3.0 atau versi yang lebih baru, properti ini diatur ke true. Jika diatur ke false, dan tidak ada metadata LogicalName, ManifestResourceName, atau DependentUpon ditentukan untuk item EmbeddedResource dalam file proyek, nama file manifes sumber daya didasarkan pada namespace layanan akar untuk proyek dan jalur file relatif ke file .resx. Untuk mengetahui informasi selengkapnya, lihat Cara file manifes sumber daya diberi nama.

<PropertyGroup>
  <EmbeddedResourceUseDependentUponConvention>true</EmbeddedResourceUseDependentUponConvention>
</PropertyGroup>

EnablePreviewFeatures

Properti EnablePreviewFeatures menentukan apakah proyek Anda bergantung pada API atau rakitan apa pun yang dihiasi dengan atribut RequiresPreviewFeaturesAttribute. Atribut ini digunakan untuk menandakan bahwa API atau rakitan menggunakan fitur yang dianggap dalam pratinjau untuk versi SDK yang digunakan. Fitur pratinjau tidak didukung dan dapat dihapus dalam versi mendatang. Untuk mengaktifkan penggunaan fitur pratinjau, atur properti ke True.

<PropertyGroup>
  <EnablePreviewFeatures>True</EnablePreviewFeatures>
</PropertyGroup>

Saat proyek berisi properti ini diatur ke True, atribut tingkat rakitan berikut ditambahkan ke file AssemblyInfo.cs:

[assembly: RequiresPreviewFeatures]

Penganalisis memperingatkan apakah atribut ini ada pada dependensi untuk proyek yang mana EnablePreviewFeatures tidak diatur ke True.

Penulis pustaka yang ingin mengirim rakitan pratinjau harus mengatur properti ini ke True. Jika rakitan perlu dikirim dengan campuran API pratinjau dan non-pratinjau, lihat bagian GenerateRequiresPreviewFeaturesAttribute di bawah ini.

EnableWindowsTargeting

Atur EnableWindowsTargeting properti ke true untuk membangun aplikasi Windows (misalnya, aplikasi Formulir Windows atau Windows Presentation Foundation) pada platform non-Windows. Jika Anda tidak mengatur properti ini ke true, Anda akan mendapatkan NETSDK1100 peringatan build. Kesalahan ini terjadi karena penargetan dan paket runtime tidak diunduh secara otomatis pada platform yang tidak didukung. Dengan mengatur properti ini, paket tersebut diunduh saat penargetan silang.

Catatan

Properti ini saat ini disarankan untuk memungkinkan pengembangan pada platform non-Windows. Tetapi ketika aplikasi siap dirilis, aplikasi harus dibangun di Windows. Saat membangun pada platform non-Windows, output mungkin tidak sama seperti saat membangun di Windows. Secara khusus, executable tidak ditandai sebagai aplikasi Windows (yang berarti bahwa ia akan selalu meluncurkan jendela konsol) dan tidak akan memiliki ikon yang disematkan.

<PropertyGroup>
  <EnableWindowsTargeting>true</EnableWindowsTargeting>
</PropertyGroup>

GenerateDocumentationFile

Properti GenerateDocumentationFile mengontrol apakah kompilator menghasilkan file dokumentasi XML untuk pustaka Anda. Jika Anda mengatur properti ini ke true dan tidak menentukan nama file melalui properti DocumentationFile, file XML yang dihasilkan ditempatkan di direktori output yang sama dengan rakitan Anda dan memiliki nama file yang sama (tetapi dengan ekstensi .xml).

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Untuk mengetahui informasi selengkapnya tentang membuat dokumentasi dari komentar kode, lihat Komentar dokumentasi XML (C#), Mendokumentasikan kode Anda dengan XML (Visual Basic), atau Mendokumentasikan kode Anda dengan XML (F#).

GenerateRequiresPreviewFeaturesAttribute

Properti GenerateRequiresPreviewFeaturesAttribute terkait erat dengan properti EnablePreviewFeatures. Jika pustaka Anda menggunakan fitur pratinjau tetapi Anda tidak ingin seluruh rakitan ditandai dengan atribut RequiresPreviewFeaturesAttribute, yang akan mengharuskan konsumen mengaktifkan fitur pratinjau, atur properti ini ke False.

<PropertyGroup>
    <EnablePreviewFeatures>True</EnablePreviewFeatures>
    <GenerateRequiresPreviewFeaturesAttribute>False</GenerateRequiresPreviewFeaturesAttribute>
</PropertyGroup>

Penting

Jika mengatur properti GenerateRequiresPreviewFeaturesAttribute ke False, Anda harus yakin untuk menghias semua API publik yang mengandalkan fitur pratinjau dengan RequiresPreviewFeaturesAttribute.

OptimizeImplicitlyTriggeredBuild

Untuk mempercepat waktu build, build yang secara implisit dipicu oleh Visual Studio melewati analisis kode, termasuk analisis yang dapat diubah ke null. Visual Studio memicu build implisit saat Anda menjalankan pengujian, misalnya. Namun, build implisit hanya dioptimalkan jika TreatWarningsAsErrors bukan true. Jika Anda telah mengatur TreatWarningsAsErrors ke true tetapi masih ingin build yang dipicu secara implisit dioptimalkan, Anda dapat mengatur OptimizeImplicitlyTriggeredBuild ke True. Untuk menonaktifkan pengoptimalan build untuk build yang dipicu secara implisit, atur OptimizeImplicitlyTriggeredBuild ke False.

<PropertyGroup>
    <OptimizeImplicitlyTriggeredBuild>True</OptimizeImplicitlyTriggeredBuild>
</PropertyGroup>

DisableRuntimeMarshalling

Properti memungkinkan DisableRuntimeMarshalling Anda menentukan bahwa Anda ingin menonaktifkan dukungan marshalling runtime untuk proyek Anda. Jika properti ini diatur ke true, maka DisableRuntimeMarshallingAttribute ditambahkan ke rakitan dan P/Invokes atau interop berbasis delegasi akan mengikuti aturan untuk marshalling runtime yang dinonaktifkan.

<PropertyGroup>
    <DisableRuntimeMarshalling>True</DisableRuntimeMarshalling>
</PropertyGroup>

Properti penyertaan item default

Properti MSBuild berikut ini didokumentasikan di bagian ini:

Untuk mengetahui informasi selengkapnya, lihat Penyertaan dan pengecualian default.

DefaultItemExcludes

Gunakan properti DefaultItemExcludes untuk menentukan pola glob untuk file dan folder yang harus dikecualikan dari penyertaan, pengecualian, dan penghapusan glob. Secara default, folder ./bin dan ./obj dikecualikan dari pola glob.

<PropertyGroup>
  <DefaultItemExcludes>$(DefaultItemExcludes);**/*.myextension</DefaultItemExcludes>
</PropertyGroup>

DefaultItemExcludesInProjectFolder

Gunakan properti DefaultItemExcludesInProjectFolder untuk menentukan pola glob untuk file dan folder di folder proyek yang harus dikecualikan dari penyertaan, pengecualian, dan penghapusan glob. Secara default, folder yang dimulai dengan titik (.), seperti .git dan .vs, dikecualikan dari pola glob.

Properti ini sangat mirip dengan properti DefaultItemExcludes, kecuali hanya mempertimbangkan file dan folder di folder proyek. Saat pola glob secara tidak sengaja akan mencocokkan item di luar folder proyek dengan jalur relatif, gunakan properti DefaultItemExcludesInProjectFolder alih-alih properti DefaultItemExcludes.

<PropertyGroup>
  <DefaultItemExcludesInProjectFolder>$(DefaultItemExcludesInProjectFolder);**/myprefix*/**</DefaultItemExcludesInProjectFolder>
</PropertyGroup>

EnableDefaultItems

Properti EnableDefaultItems mengontrol apakah item kompilasi, item sumber daya yang disematkan, dan item None disertakan secara implisit dalam proyek. Nilai defaultnya adalah true. Atur properti EnableDefaultItems ke false untuk menonaktifkan semua penyertaan file implisit.

<PropertyGroup>
  <EnableDefaultItems>false</EnableDefaultItems>
</PropertyGroup>

EnableDefaultCompileItems

Properti EnableDefaultCompileItems mengontrol apakah item kompilasi disertakan secara implisit dalam proyek. Nilai defaultnya adalah true. Atur properti EnableDefaultCompileItems ke false untuk menonaktifkan penyertaan implisit *.cs dan file ekstensi bahasa lainnya.

<PropertyGroup>
  <EnableDefaultCompileItems>false</EnableDefaultCompileItems>
</PropertyGroup>

EnableDefaultEmbeddedResourceItems

Properti EnableDefaultEmbeddedResourceItems mengontrol apakah item sumber daya tersemat disertakan secara implisit dalam proyek. Nilai defaultnya adalah true. Atur EnableDefaultEmbeddedResourceItems properti ke false untuk menonaktifkan penyertaan implisit file sumber daya tersemat.

<PropertyGroup>
  <EnableDefaultEmbeddedResourceItems>false</EnableDefaultEmbeddedResourceItems>
</PropertyGroup>

EnableDefaultNoneItems

Properti EnableDefaultNoneItems mengontrol apakah item None (file yang tidak memiliki peran dalam proses build) secara implisit disertakan dalam proyek. Nilai defaultnya adalah true. Atur properti EnableDefaultNoneItems ke false untuk menonaktifkan penyertaan implisit item None.

<PropertyGroup>
  <EnableDefaultNoneItems>false</EnableDefaultNoneItems>
</PropertyGroup>

Properti analisis kode

Properti MSBuild berikut ini didokumentasikan di bagian ini:

AnalysisLevel

Properti AnalysisLevel memungkinkan Anda menentukan sekumpulan penganalisis kode untuk dijalankan sesuai dengan rilis .NET. Setiap rilis .NET, mulai dari .NET 5, memiliki sekumpulan aturan analisis kode. Dari kumpulan tersebut, aturan yang diaktifkan secara default untuk rilis tersebut akan menganalisis kode Anda. Misalnya, jika Anda meningkatkan ke .NET 8 tetapi tidak ingin kumpulan aturan analisis kode default berubah, atur AnalysisLevel ke 7.

<PropertyGroup>
  <AnalysisLevel>preview</AnalysisLevel>
</PropertyGroup>

Secara opsional, mulai dari .NET 6, Anda dapat menentukan nilai majemuk untuk properti ini yang juga menentukan seberapa agresif untuk mengaktifkan aturan. Nilai campuran mengambil formulir <version>-<mode>, yang mana nilai <mode> adalah salah satu nilai AnalysisMode. Contoh berikut menggunakan versi pratinjau penganalisis kode, dan mengaktifkan sekumpulan aturan yang direkomendasikan.

<PropertyGroup>
  <AnalysisLevel>preview-recommended</AnalysisLevel>
</PropertyGroup>

Nilai default:

  • Jika proyek Anda menargetkan .NET 5 atau yang lebih baru, atau jika Anda telah menambahkan properti AnalysisMode, nilai defaultnya adalah latest.
  • Jika tidak, properti ini dihilangkan kecuali Anda menambahkannya ke file proyek secara eksplisit.

Tabel berikut ini menunjukkan nilai yang dapat Anda tentukan.

Nilai Makna
latest Penganalisis kode terbaru yang telah dirilis digunakan. Ini adalah default.
latest-<mode> Penganalisis kode terbaru yang telah dirilis digunakan. Nilai <mode> menentukan aturan mana yang diaktifkan.
preview Penganalisis kode terbaru digunakan, meskipun masih dalam pratinjau.
preview-<mode> Penganalisis kode terbaru digunakan, meskipun masih dalam pratinjau. Nilai <mode> menentukan aturan mana yang diaktifkan.
8.0 Sekumpulan aturan yang tersedia untuk rilis .NET 8 digunakan, bahkan jika aturan yang lebih baru tersedia.
8.0-<mode> Sekumpulan aturan yang tersedia untuk rilis .NET 8 digunakan, bahkan jika aturan yang lebih baru tersedia. Nilai <mode> menentukan aturan mana yang diaktifkan.
8 Sekumpulan aturan yang tersedia untuk rilis .NET 8 digunakan, bahkan jika aturan yang lebih baru tersedia.
8-<mode> Sekumpulan aturan yang tersedia untuk rilis .NET 8 digunakan, bahkan jika aturan yang lebih baru tersedia. Nilai <mode> menentukan aturan mana yang diaktifkan.
7.0 Sekumpulan aturan yang tersedia untuk rilis .NET 7 digunakan, bahkan jika aturan yang lebih baru tersedia.
7.0-<mode> Sekumpulan aturan yang tersedia untuk rilis .NET 7 digunakan, bahkan jika aturan yang lebih baru tersedia. Nilai <mode> menentukan aturan mana yang diaktifkan.
7 Sekumpulan aturan yang tersedia untuk rilis .NET 7 digunakan, bahkan jika aturan yang lebih baru tersedia.
7-<mode> Sekumpulan aturan yang tersedia untuk rilis .NET 7 digunakan, bahkan jika aturan yang lebih baru tersedia. Nilai <mode> menentukan aturan mana yang diaktifkan.
6.0 Sekumpulan aturan yang tersedia untuk rilis .NET 6 digunakan, meskipun aturan yang lebih baru tersedia.
6.0-<mode> Sekumpulan aturan yang tersedia untuk rilis .NET 6 digunakan, meskipun aturan yang lebih baru tersedia. Nilai <mode> menentukan aturan mana yang diaktifkan.
6 Sekumpulan aturan yang tersedia untuk rilis .NET 6 digunakan, meskipun aturan yang lebih baru tersedia.
6-<mode> Sekumpulan aturan yang tersedia untuk rilis .NET 6 digunakan, meskipun aturan yang lebih baru tersedia. Nilai <mode> menentukan aturan mana yang diaktifkan.
5.0 Sekumpulan aturan yang tersedia untuk rilis .NET 5 digunakan, meskipun aturan yang lebih baru tersedia.
5.0-<mode> Sekumpulan aturan yang tersedia untuk rilis .NET 5 digunakan, meskipun aturan yang lebih baru tersedia. Nilai <mode> menentukan aturan mana yang diaktifkan.
5 Sekumpulan aturan yang tersedia untuk rilis .NET 5 digunakan, meskipun aturan yang lebih baru tersedia.
5-<mode> Sekumpulan aturan yang tersedia untuk rilis .NET 5 digunakan, meskipun aturan yang lebih baru tersedia. Nilai <mode> menentukan aturan mana yang diaktifkan.

Catatan

  • Mulai dari .NET 6, jika Anda mengatur EnforceCodeStyleInBuild ke true, properti ini memengaruhi aturan gaya kode (IDEXXXX) (selain aturan kualitas kode).
  • Jika menetapkan nilai gabungan untuk AnalysisLevel, Anda tidak perlu menentukan AnalysisMode. Namun, jika Anda melakukannya, AnalysisLevel lebih diutamakan daripada AnalysisMode.
  • Properti ini tidak berpengaruh pada analisis kode dalam proyek yang tidak mereferensikan SDK proyek, misalnya, proyek .NET Framework warisan yang mereferensikan paket NuGet Microsoft.CodeAnalysis.NetAnalyzers.

AnalysisLevel<Category>

Properti ini sama dengan AnalysisLevel, kecuali hanya berlaku untuk kategori aturan analisis kode tertentu. Properti ini memungkinkan Anda menggunakan versi penganalisis kode yang berbeda untuk kategori tertentu, atau mengaktifkan atau menonaktifkan aturan pada tingkat yang berbeda dengan kategori aturan lainnya. Jika Anda menghilangkan properti ini untuk kategori aturan tertentu, properti tersebut default ke nilai AnalysisLevel. Nilai yang tersedia sama dengan nilai untuk AnalysisLevel.

<PropertyGroup>
  <AnalysisLevelSecurity>preview</AnalysisLevelSecurity>
</PropertyGroup>

<PropertyGroup>
  <AnalysisLevelSecurity>preview-recommended</AnalysisLevelSecurity>
</PropertyGroup>

Tabel berikut mencantumkan nama properti untuk setiap kategori aturan.

Nama properti Kategori aturan
<AnalysisLevelDesign> Aturan desain
<AnalysisLevelDocumentation> Aturan dokumentasi
<AnalysisLevelGlobalization> Aturan globalisasi
<AnalysisLevelInteroperability> Aturan portabilitas dan interoperabilitas
<AnalysisLevelMaintainability> Aturan pemeliharaan
<AnalysisLevelNaming> Aturan penamaan
<AnalysisLevelPerformance> Aturan performa
<AnalysisLevelSingleFile> Aturan aplikasi file tunggal
<AnalysisLevelReliability> Aturan keandalan
<AnalysisLevelSecurity> Aturan keamanan
<AnalysisLevelStyle> Aturan gaya kode (IDEXXXX)
<AnalysisLevelUsage> Aturan penggunaan

AnalysisMode

.NET SDK dikirim dengan semua aturan kualitas kode "CA". Secara default, hanya beberapa aturan yang diaktifkan sebagai peringatan build di setiap rilis .NET. Properti AnalysisMode ini memungkinkan Anda menyesuaikan sekumpulan aturan yang diaktifkan secara default. Anda dapat beralih ke mode analisis yang lebih agresif yang mana Anda dapat menolak aturan satu per satu, atau mode analisis yang lebih konservatif tempat Anda dapat memilih aturan tertentu. Misalnya, jika Anda ingin mengaktifkan semua aturan sebagai peringatan build, atur nilainya ke All.

<PropertyGroup>
  <AnalysisMode>All</AnalysisMode>
</PropertyGroup>

Tabel berikut ini memperlihatkan nilai opsi yang tersedia. Nilai tersebut tercantum dalam urutan peningkatan jumlah aturan yang diaktifkan.

Nilai Deskripsi
None Semua aturan dinonaktifkan. Anda dapat secara selektif memilih aturan individual untuk mengaktifkannya.
Default Mode default, saat aturan tertentu diaktifkan sebagai peringatan build, aturan tertentu diaktifkan sebagai saran IDE Visual Studio, dan sisanya dinonaktifkan.
Minimum Mode yang lebih agresif daripada Default mode. Saran tertentu yang sangat disarankan untuk penegakan build diaktifkan sebagai peringatan build. Untuk melihat aturan mana yang disertakan, periksa %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.editorconfig file.
Recommended Mode yang lebih agresif daripada Minimum mode, di mana lebih banyak aturan diaktifkan sebagai peringatan build. Untuk melihat aturan mana yang disertakan, periksa %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.editorconfig file.
All Semua aturan diaktifkan sebagai peringatan* build. Anda dapat secara selektif keluar dari aturan individual untuk menonaktifkannya.

* Aturan berikut tidak diaktifkan dengan mengatur AnalysisMode ke All atau dengan mengatur AnalysisLevel ke latest-all: CA1017, CA1045, CA1005, CA1014, CA1060, CA1021, dan aturan penganalisis metrik kode (CA1501, CA1502, CA1505, CA1506, dan CA1509). Aturan warisan ini mungkin tidak digunakan lagi dalam versi mendatang. Namun, Anda masih dapat mengaktifkannya satu per satu menggunakan dotnet_diagnostic.CAxxxx.severity = <severity> entri.

Catatan

  • Mulai dari .NET 6, jika Anda mengatur EnforceCodeStyleInBuild ke true, properti ini memengaruhi aturan gaya kode (IDEXXXX) (selain aturan kualitas kode).
  • Jika Anda menggunakan nilai gabungan untuk AnalysisLevel, misalnya, <AnalysisLevel>8-recommended</AnalysisLevel>, Anda dapat menghilangkan properti ini sepenuhnya. Namun, jika Anda menentukan kedua properti, AnalysisLevel lebih diutamakan daripada AnalysisMode.
  • Properti ini tidak berpengaruh pada analisis kode dalam proyek yang tidak mereferensikan SDK proyek, misalnya, proyek .NET Framework warisan yang mereferensikan paket NuGet Microsoft.CodeAnalysis.NetAnalyzers.

AnalysisMode<Category>

Properti ini sama dengan AnalysisMode, kecuali hanya berlaku untuk kategori aturan analisis kode tertentu. Properti ini memungkinkan Anda mengaktifkan atau menonaktifkan aturan pada tingkat yang berbeda dengan kategori aturan lainnya. Jika Anda menghilangkan properti ini untuk kategori aturan tertentu, properti tersebut default ke nilai AnalysisMode. Nilai yang tersedia sama dengan nilai untuk AnalysisMode.

<PropertyGroup>
  <AnalysisModeSecurity>All</AnalysisModeSecurity>
</PropertyGroup>

Tabel berikut mencantumkan nama properti untuk setiap kategori aturan.

Nama properti Kategori aturan
<AnalysisModeDesign> Aturan desain
<AnalysisModeDocumentation> Aturan dokumentasi
<AnalysisModeGlobalization> Aturan globalisasi
<AnalysisModeInteroperability> Aturan portabilitas dan interoperabilitas
<AnalysisModeMaintainability> Aturan pemeliharaan
<AnalysisModeNaming> Aturan penamaan
<AnalysisModePerformance> Aturan performa
<AnalysisModeSingleFile> Aturan aplikasi file tunggal
<AnalysisModeReliability> Aturan keandalan
<AnalysisModeSecurity> Aturan keamanan
<AnalysisModeStyle> Aturan gaya kode (IDEXXXX)
<AnalysisModeUsage> Aturan penggunaan

CodeAnalysisTreatWarningsAsErrors

Properti CodeAnalysisTreatWarningsAsErrors memungkinkan Anda mengonfigurasi apakah peringatan analisis kualitas kode (CAxxxx) harus diperlakukan sebagai peringatan dan merusak build. Jika Anda menggunakan bendera -warnaserror saat membuat proyek, peringatan analisis kualitas kode .NET juga diperlakukan sebagai kesalahan. Jika tidak ingin peringatan analisis kualitas kode diperlakukan sebagai kesalahan, Anda dapat mengatur properti MSBuild CodeAnalysisTreatWarningsAsErrors ke false dalam file proyek Anda.

<PropertyGroup>
  <CodeAnalysisTreatWarningsAsErrors>false</CodeAnalysisTreatWarningsAsErrors>
</PropertyGroup>

EnableNETAnalyzers

Analisis kualitas kode .NET diaktifkan, secara default, untuk proyek yang menargetkan .NET 5 atau versi yang lebih baru. Jika Anda mengembangkan menggunakan SDK .NET 5+, Anda dapat mengaktifkan analisis kode .NET untuk proyek gaya SDK yang menargetkan versi .NET sebelumnya dengan mengatur properti EnableNETAnalyzers ke true. Untuk menonaktifkan analisis kode dalam proyek apa pun, atur properti ini ke false.

<PropertyGroup>
  <EnableNETAnalyzers>true</EnableNETAnalyzers>
</PropertyGroup>

Catatan

Properti ini berlaku khusus untuk penganalisis bawaan di SDK .NET 5+. Ini tidak boleh digunakan saat Anda menginstal paket analisis kode NuGet.

EnforceCodeStyleInBuild

Analisis gaya kode .NET dinonaktifkan, secara default, pada build untuk semua proyek .NET. Anda dapat mengaktifkan analisis gaya kode untuk proyek .NET dengan mengatur properti EnforceCodeStyleInBuild ke true.

<PropertyGroup>
  <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
</PropertyGroup>

Semua aturan gaya kode yang dikonfigurasi menjadi peringatan atau kesalahan akan dijalankan pada pelanggaran build dan laporan.

_SkipUpgradeNetAnalyzersNuGetWarning

Properti _SkipUpgradeNetAnalyzersNuGetWarning memungkinkan Anda mengonfigurasi apakah Anda menerima peringatan jika menggunakan penganalisis kode dari paket NuGet yang sudah kedaluearsa jika dibandingkan dengan penganalisis kode di SDK .NET terbaru. Peringatan terlihat mirip dengan:

SDK .NET memiliki penganalisis yang lebih baru dengan versi '6.0.0' daripada versi '5.0.3' dari paket 'Microsoft.CodeAnalysis.NetAnalyzers' yang disediakan. Perbarui atau hapus referensi paket ini.

Untuk menghapus peringatan ini dan terus menggunakan versi penganalisis kode dalam paket NuGet, atur _SkipUpgradeNetAnalyzersNuGetWarning ke true dalam file proyek Anda.

<PropertyGroup>
  <_SkipUpgradeNetAnalyzersNuGetWarning>true</_SkipUpgradeNetAnalyzersNuGetWarning>
</PropertyGroup>

Properti konfigurasi runtime

Anda dapat mengonfigurasi beberapa perilaku runtime dengan menentukan properti MSBuild dalam file proyek aplikasi. Untuk informasi tentang cara lain mengonfigurasi perilaku runtime, lihat Pengaturan konfigurasi runtime.

AutoreleasePoolSupport

Properti AutoreleasePoolSupport mengonfigurasi apakah setiap utas terkelola menerima NSAutoreleasePool implisit saat berjalan pada platform macOS yang didukung. Untuk informasi selengkapnya, lihat AutoreleasePool untuk utas terkelola.

<PropertyGroup>
  <AutoreleasePoolSupport>true</AutoreleasePoolSupport>
</PropertyGroup>

ConcurrentGarbageCollection

Properti ConcurrentGarbageCollection mengonfigurasi apakah pengumpulan sampah latar belakang (bersamaan) diaktifkan. Atur nilai ke false untuk menonaktifkan pengumpulan sampah latar belakang. Untuk mengetahui informasi selengkapnya, lihat Pengumpulan sampah latar belakang.

<PropertyGroup>
  <ConcurrentGarbageCollection>false</ConcurrentGarbageCollection>
</PropertyGroup>

InvariantGlobalization

Properti InvariantGlobalization mengonfigurasi apakah aplikasi berjalan dalam mode globaliasi-invarian, yang berarti tidak memiliki akses ke data khusus kultur. Atur nilai ke true untuk dijalankan dalam mode globalisasi-invarian. Untuk mengetahui informasi selengkapnya, lihat Mode Invarian.

<PropertyGroup>
  <InvariantGlobalization>true</InvariantGlobalization>
</PropertyGroup>

PredefinedCulturesOnly

Di .NET 6 dan versi yang lebih baru, properti PredefinedCulturesOnly mengonfigurasi apakah aplikasi dapat membuat kultur selain kultur invarian saat mode globalisasi-invarian diaktifkan. Default adalah true. Atur nilai ke false untuk memungkinkan pembuatan budaya baru apa pun dalam mode globalisasi-invarian.

<PropertyGroup>
  <PredefinedCulturesOnly>false</PredefinedCulturesOnly>
</PropertyGroup>

Untuk mengetahui informasi selengkapnya, lihat Pembuatan kultur dan pemetaan kasus dalam mode globalisasi-invarian.

RetainVMGarbageCollection

Properti RetainVMGarbageCollection mengonfigurasi pengumpul sampah untuk menempatkan segmen memori yang dihapus pada daftar siaga untuk penggunaan di masa mendatang atau melepaskannya. Mengatur nilai untuk true memberi tahu pengumpul sampah untuk menempatkan segmen pada daftar siaga. Untuk mengetahui informasi selengkapnya, lihat Mempertahankan VM.

<PropertyGroup>
  <RetainVMGarbageCollection>true</RetainVMGarbageCollection>
</PropertyGroup>

ServerGarbageCollection

Properti ServerGarbageCollection mengonfigurasi apakah aplikasi menggunakan pengumpulan sampah stasiun kerja atau pengumpulan sampah server. Atur nilai ke true untuk menggunakan pengumpulan sampah server. Untuk mengetahui informasi selengkapnya, lihat Stasiun kerja vs. server.

<PropertyGroup>
  <ServerGarbageCollection>true</ServerGarbageCollection>
</PropertyGroup>

ThreadPoolMaxThreads

Properti ThreadPoolMaxThreads mengonfigurasi jumlah maksimum rangkaian untuk kumpulan rangkaian pekerja. Untuk mengetahui informasi selengkapnya, lihat Rangkaian maksimum.

<PropertyGroup>
  <ThreadPoolMaxThreads>20</ThreadPoolMaxThreads>
</PropertyGroup>

ThreadPoolMinThreads

Properti ThreadPoolMinThreads mengonfigurasi jumlah minimum rangkaian untuk kumpulan rangkaian pekerja. Untuk mengetahui informasi selengkapnya, lihat Rangkaian minimum.

<PropertyGroup>
  <ThreadPoolMinThreads>4</ThreadPoolMinThreads>
</PropertyGroup>

TieredCompilation

Properti TieredCompilation mengonfigurasi apakah kompilator just-in-time (JIT) menggunakan kompilasi bertingkat. Atur nilai ke false untuk menonaktifkan kompilasi bertingkat. Untuk mengetahui informasi selengkapnya, lihat Kompilasi bertingkat.

<PropertyGroup>
  <TieredCompilation>false</TieredCompilation>
</PropertyGroup>

TieredCompilationQuickJit

Properti TieredCompilationQuickJit mengonfigurasi apakah kompilator JIT menggunakan JIT cepat. Atur nilai ke false untuk menonaktifkan JIT cepat. Untuk mengetahui informasi selengkapnya, lihat JIT cepat.

<PropertyGroup>
  <TieredCompilationQuickJit>false</TieredCompilationQuickJit>
</PropertyGroup>

TieredCompilationQuickJitForLoops

Properti TieredCompilationQuickJitForLoops mengonfigurasi apakah kompilator JIT menggunakan JIT cepat pada metode yang berisi perulangan. Atur nilai ke true untuk mengaktifkan JIT cepat pada metode yang berisi perulangan. Untuk mengetahui informasi selengkapnya, lihat JIT cepat untuk perulangan.

<PropertyGroup>
  <TieredCompilationQuickJitForLoops>true</TieredCompilationQuickJitForLoops>
</PropertyGroup>

TieredPGO

Properti TieredPGO mengontrol apakah pengoptimalan yang dipandu profil dinamis atau berjenjang (PGO) diaktifkan. Atur nilai ke true untuk mengaktifkan PGO bertingkat. Untuk informasi selengkapnya, lihat Pengoptimalan yang dipandu profil.

<PropertyGroup>
  <TieredPGO>true</TieredPGO>
</PropertyGroup>

UseWindowsThreadPool

Properti UseWindowsThreadPool mengonfigurasi apakah manajemen utas kumpulan utas didelegasikan ke kumpulan utas Windows (hanya Windows). Nilai defaultnya adalah false, dalam hal ini kumpulan utas .NET digunakan. Untuk informasi selengkapnya, lihat Kumpulan utas Windows.

<PropertyGroup>
  <UseWindowsThreadPool>true</UseWindowsThreadPool>
</PropertyGroup>

Properti MSBuild berikut ini didokumentasikan di bagian ini:

AssetTargetFallback

Properti AssetTargetFallback memungkinkan Anda menentukan versi kerangka kerja tambahan yang kompatibel untuk referensi proyek dan paket NuGet. Misalnya, jika Anda menentukan dependensi paket menggunakan PackageReference tetapi paket tersebut tidak berisi aset yang kompatibel dengan TargetFramework proyek, properti AssetTargetFallback mulai diputar. Kompatibilitas paket yang direferensikan diperiksa ulang menggunakan setiap kerangka kerja target yang ditentukan dalam AssetTargetFallback. Properti ini menggantikan PackageTargetFallback properti yang tidak digunakan lagi.

Anda dapat mengatur properti AssetTargetFallback ke satu atau beberapa versi kerangka kerja target.

<PropertyGroup>
  <AssetTargetFallback>net461</AssetTargetFallback>
</PropertyGroup>

DisableImplicitFrameworkReferences

Properti DisableImplicitFrameworkReferences mengontrol item FrameworkReference implisit saat menargetkan .NET Core 3.0 dan versi yang lebih baru. Saat menargetkan .NET Core 2.1 atau .NET Standard 2.0 dan versi yang lebih lama, properti mengontrol item PackageReference implisit ke paket dalam metapackage. (Metapackage adalah paket berbasis kerangka kerja yang hanya terdiri dari dependensi pada paket lain.) Properti ini juga mengontrol referensi implisit seperti System dan System.Core saat menargetkan .NET Framework.

Atur properti ini ke true untuk menonaktifkan item FrameworkReference implisit atau PackageReference. Jika mengatur properti ini ke true, Anda dapat menambahkan referensi eksplisit hanya ke kerangka kerja atau paket yang dibutuhkan.

<PropertyGroup>
  <DisableImplicitFrameworkReferences>true</DisableImplicitFrameworkReferences>
</PropertyGroup>

DisableTransitiveFrameworkReferenceDownloads

Atur DisableTransitiveFrameworkReferenceDownloads properti ke true untuk menghindari pengunduhan runtime tambahan dan paket penargetan yang tidak langsung dirujuk oleh proyek Anda.

<PropertyGroup>
  <DisableTransitiveFrameworkReferenceDownloads>true</DisableTransitiveFrameworkReferenceDownloads>
</PropertyGroup>

DisableTransitiveProjectReferences

Properti DisableTransitiveProjectReferences mengontrol referensi proyek implisit. Atur properti ini ke true untuk menonaktifkan item implisit ProjectReference . Menonaktifkan referensi proyek implisit menghasilkan perilaku non-transitif yang mirip dengan sistem proyek warisan.

Ketika properti ini , trueproperti ini memiliki efek yang mirip dengan pengaturan PrivateAssets="All" pada semua dependensi proyek dependensi.

Jika Anda mengatur properti ini ke true, Anda dapat menambahkan referensi eksplisit hanya ke proyek yang Anda butuhkan.

<PropertyGroup>
  <DisableTransitiveProjectReferences>true</DisableTransitiveProjectReferences>
</PropertyGroup>

KelolaPackageVersionsCentrally

Properti ManagePackageVersionsCentrally diperkenalkan di .NET 7. Dengan mengaturnya ke true dalam file Directory.Packages.props di akar repositori Anda, Anda dapat mengelola dependensi umum dalam proyek Anda dari satu lokasi. Tambahkan versi untuk dependensi paket umum menggunakan PackageVersion item dalam file Directory.Packages.props . Kemudian, dalam file proyek individual, Anda dapat menghilangkan Version atribut dari item apa pun PackageReference yang merujuk ke paket yang dikelola secara terpusat.

Contoh file Directory.Packages.props :

<PropertyGroup>
  <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
</PropertyGroup>
...
<ItemGroup>
  <PackageVersion Include="Microsoft.Extensions.Configuration" Version="7.0.0" />
</ItemGroup>

File proyek individual:

<ItemGroup>
  <PackageReference Include="Microsoft.Extensions.Configuration" />
</ItemGroup>

Untuk informasi selengkapnya, lihat manajemen paket pusat (CPM).

Memulihkan paket yang direferensikan menginstal semua dependensi langsungnya dan semua dependensi dari dependensi tersebut. Anda dapat menyesuaikan pemulihan paket dengan menentukan properti seperti RestorePackagesPath dan RestoreIgnoreFailedSources. Untuk mengetahui informasi selengkapnya tentang properti ini dan properti lainnya, lihat memulihkan target.

<PropertyGroup>
  <RestoreIgnoreFailedSource>true</RestoreIgnoreFailedSource>
</PropertyGroup>

UseMauiEssentials

Atur UseMauiEssentials properti ke true untuk mendeklarasikan referensi eksplisit ke proyek atau paket yang bergantung pada MAUI Essentials. Pengaturan ini memastikan bahwa proyek Anda menarik referensi kerangka kerja yang diketahui dengan benar untuk MAUI Essentials. Jika proyek Anda mereferensikan proyek yang menggunakan MAUI Essentials tetapi Anda tidak mengatur properti ini ke true, Anda mungkin mengalami peringatan NETSDK1186build .

<PropertyGroup>
  <UseMauiEssentials>true</UseMauiEssentials>
</PropertyGroup>

ValidateExecutableReferencesMatchSelfContained

Properti ValidateExecutableReferencesMatchSelfContained dapat digunakan untuk menonaktifkan kesalahan yang terkait dengan referensi proyek executable. Jika .NET mendeteksi bahwa proyek executable mandiri mereferensikan proyek executable yang tergantung pada kerangka kerja, atau sebaliknya, proyek tersebut masing-masing menghasilkan kesalahan NETSDK1150 dan NETSDK1151. Untuk menghindari kesalahan ini saat referensi disengaja, atur ValidateExecutableReferencesMatchSelfContained properti ke false.

<PropertyGroup>
  <ValidateExecutableReferencesMatchSelfContained>false</ValidateExecutableReferencesMatchSelfContained>
</PropertyGroup>

WindowsSdkPackageVersion

Properti WindowsSdkPackageVersion dapat digunakan untuk mengambil alih versi Paket penargetan SDK Windows. Properti ini diperkenalkan di .NET 5, dan menggantikan penggunaan item FrameworkReference untuk tujuan ini.

<PropertyGroup>
  <WindowsSdkPackageVersion>10.0.19041.18</WindowsSdkPackageVersion>
</PropertyGroup>

Catatan

Sebaiknya jangan mengesampingkan versi SDK Windows, karena paket penargetan SDK Windows disertakan dengan SDK .NET 5+. Sebagai gantinya, untuk mereferensikan paket SDK Windows terbaru, perbarui versi SDK .NET Anda. Properti ini hanya boleh digunakan dalam kasus yang jarang terjadi seperti menggunakan paket pratinjau atau perlu mengambil alih versi C#/WinRT.

Properti berikut digunakan untuk meluncurkan aplikasi dengan perintah dotnet run:

RunArguments

Properti RunArguments menentukan argumen yang diteruskan ke aplikasi saat dijalankan.

<PropertyGroup>
  <RunArguments>-mode dryrun</RunArguments>
</PropertyGroup>

Tip

Anda dapat menentukan argumen tambahan yang akan diteruskan ke aplikasi dengan menggunakan opsi -- untuk dotnet run.

RunWorkingDirectory

Properti RunWorkingDirectory menentukan direktori kerja untuk proses aplikasi yang akan dimulai. Ini bisa menjadi jalur absolut atau jalur yang relatif terhadap direktori proyek. Jika Anda tidak menentukan direktori, OutDir digunakan sebagai direktori kerja.

<PropertyGroup>
  <RunWorkingDirectory>c:\temp</RunWorkingDirectory>
</PropertyGroup>

Menguji properti terkait proyek

Properti MSBuild berikut ini didokumentasikan di bagian ini:

IsTestProject

Properti IsTestProject menandakan bahwa proyek adalah proyek pengujian. Ketika properti ini diatur ke true, validasi untuk memeriksa apakah proyek mereferensikan executable mandiri dinonaktifkan. Itu karena proyek pengujian memiliki OutputType dari Exe tetapi biasanya memanggil API dalam executable yang dirujuk daripada mencoba menjalankan. Selain itu, jika proyek mereferensikan proyek tempat IsTestProject diatur ke true, proyek pengujian tidak divalidasi sebagai referensi yang dapat dieksekusi.

Properti ini terutama diperlukan untuk dotnet test skenario dan tidak berdampak saat menggunakan vstest.console.exe.

Catatan

Jika proyek Anda menentukan MSTest SDK, Anda tidak perlu mengatur properti ini. Ini diatur secara otomatis. Demikian pula, properti ini diatur secara otomatis untuk proyek yang mereferensikan paket NuGet Microsoft.NET.Test.Sdk yang ditautkan ke VSTest.

IsTestingPlatformApplication

Saat proyek Anda mereferensikan paket Microsoft.Testing.Platform.MSBuild , pengaturan IsTestingPlatformApplication ke true (yang juga merupakan nilai default jika tidak ditentukan) melakukan hal berikut:

  • Menghasilkan titik masuk ke proyek pengujian.
  • Menghasilkan file konfigurasi.
  • Mendeteksi ekstensi.

Mengatur properti untuk false menonaktifkan dependensi transitif ke paket. Dependensi transitif adalah ketika proyek yang mereferensikan proyek lain yang mereferensikan paket tertentu berulah seolah-olah mereferensikan paket. Anda biasanya akan mengatur properti ini ke false dalam proyek non-pengujian yang mereferensikan proyek pengujian. Untuk informasi selengkapnya, lihat kesalahan CS8892.

Jika proyek pengujian Anda mereferensikan MSTest, NUnit, atau xUnit, properti ini diatur ke nilai yang sama dengan EnableMSTestRunner, EnableNUnitRunner, atau UseMicrosoftTestingPlatformRunner (untuk xUnit).

Aktifkan[NugetPackageNameWithoutDots]

Gunakan properti dengan pola Enable[NugetPackageNameWithoutDots] untuk mengaktifkan atau menonaktifkan ekstensi Microsoft.Testing.Platform.

Misalnya, untuk mengaktifkan ekstensi crash dump (paket NuGet Microsoft.Testing.Extensions.CrashDump), atur ke EnableMicrosoftTestingExtensionsCrashDump true.

Untuk informasi selengkapnya, lihat Mengaktifkan atau menonaktifkan ekstensi.

EnableAspireTesting

Ketika Anda menggunakan proyek MSTest SDK, Anda dapat menggunakan EnableAspireTesting properti untuk membawa semua dependensi dan arahan default using yang Anda butuhkan untuk pengujian dengan Aspire dan MSTest. Properti ini tersedia di MSTest 3.4 dan versi yang lebih baru.

Untuk informasi selengkapnya, lihat Menguji dengan .NET Aspire.

AktifkanPlaywright

Ketika Anda menggunakan proyek MSTest SDK, Anda dapat menggunakan EnablePlaywright properti untuk membawa semua dependensi dan arahan default using yang Anda butuhkan untuk pengujian dengan Playwright dan MSTest. Properti ini tersedia di MSTest 3.4 dan versi yang lebih baru.

Untuk informasi selengkapnya, lihat Playwright.

EnableMSTestRunner

Properti EnableMSTestRunner mengaktifkan atau menonaktifkan penggunaan pelari MSTest. Pelari MSTest adalah alternatif ringan dan portabel untuk VSTest. Properti ini tersedia di MSTest 3.2 dan versi yang lebih baru.

Catatan

Jika proyek Anda menentukan MSTest SDK, Anda tidak perlu mengatur properti ini. Ini diatur secara otomatis.

EnableNUnitRunner

Properti EnableNUnitRunner mengaktifkan atau menonaktifkan penggunaan runner NUnit. Pelari NUnit adalah alternatif ringan dan portabel untuk VSTest. Properti ini tersedia di NUnit3TestAdapter di versi 5.0 dan yang lebih baru.

HasilkanTestingPlatformEntryPoint

GenerateTestingPlatformEntryPoint Mengatur properti untuk false menonaktifkan pembuatan otomatis titik masuk program dalam proyek pengujian MSTest, NUnit, atau xUnit. Anda mungkin ingin mengatur properti ini ke false ketika Anda menentukan titik entri secara manual, atau ketika Anda mereferensikan proyek pengujian dari executable yang juga memiliki titik masuk.

Untuk informasi selengkapnya, lihat kesalahan CS8892.

Untuk mengontrol pembuatan titik masuk dalam proyek VSTest, gunakan GenerateProgramFile properti .

TestingPlatformCaptureOutput

Properti TestingPlatformCaptureOutput mengontrol apakah semua output konsol yang dapat dieksekusi pengujian tulis diambil dan disembunyikan dari pengguna saat Anda menggunakan dotnet test untuk menjalankan Microsoft.Testing.Platform pengujian. Secara default, output konsol disembunyikan. Output ini mencakup banner, informasi versi, dan informasi pengujian yang diformat. Atur properti ini ke false untuk menampilkan informasi ini bersama dengan output MSBuild.

Untuk informasi selengkapnya, lihat Menampilkan output platform lengkap.

TestingPlatformCommandLineArguments

Properti TestingPlatformCaptureOutput memungkinkan Anda menentukan argumen baris perintah ke aplikasi pengujian saat Anda menggunakan dotnet test untuk menjalankan Microsoft.Testing.Platform pengujian. Cuplikan file proyek berikut menunjukkan contoh.

<PropertyGroup>
  ...
  <TestingPlatformCommandLineArguments>--minimum-expected-tests 10</TestingPlatformCommandLineArguments>
</PropertyGroup>

TestingPlatformDotnetTestSupport

Properti TestingPlatformDotnetTestSupport memungkinkan Anda menentukan apakah VSTest digunakan saat Anda menggunakan dotnet test untuk menjalankan pengujian. Jika Anda mengatur properti ini ke true, VSTest dinonaktifkan dan semua Microsoft.Testing.Platform pengujian dijalankan secara langsung.

Jika Anda memiliki solusi yang berisi proyek pengujian VSTest serta proyek MSTest, NUnit, atau XUnit, Anda harus melakukan satu panggilan per mode (yaitu, dotnet test tidak akan menjalankan pengujian dari VSTest dan platform yang lebih baru dalam satu panggilan).

PengujianPlatformShowTestsFailure

Properti TestingPlatformShowTestsFailure memungkinkan Anda mengontrol apakah satu kegagalan atau semua kesalahan dalam pengujian yang gagal dilaporkan saat Anda menggunakan dotnet test untuk menjalankan pengujian. Secara default, kegagalan pengujian dirangkum ke dalam file .log , dan satu kegagalan per proyek pengujian dilaporkan ke MSBuild. Untuk menampilkan kesalahan per pengujian yang gagal, atur properti ini ke true dalam file proyek Anda.

TestingExtensionsProfile

Saat Anda menggunakan SDK proyek MSTest, TestingExtensionsProfile properti memungkinkan Anda memilih profil untuk digunakan. Tabel berikut ini memperlihatkan nilai yang diizinkan.

Nilai Deskripsi
Default Mengaktifkan ekstensi yang direkomendasikan untuk versi MSTest.SDK ini.
None Tidak ada ekstensi yang diaktifkan.
AllMicrosoft Aktifkan semua ekstensi yang dikirim oleh Microsoft (termasuk ekstensi dengan lisensi terbatas).

Untuk informasi selengkapnya, lihat profil pelari MSTest.

UseVSTest

Atur UseVSTest properti ke true untuk beralih dari runner MSTest ke runner VSTest saat menggunakan proyek MSTest SDK.

Properti MSBuild berikut ini didokumentasikan di bagian ini:

AppHostDotNetSearch

Properti AppHostDotNetSearch mengonfigurasi bagaimana executable asli yang dihasilkan untuk aplikasi akan mencari penginstalan .NET. Properti ini hanya berdampak pada executable yang dihasilkan pada publikasi, bukan build.

<PropertyGroup>
  <AppHostDotNetSearch>Global</AppHostDotNetSearch>
</PropertyGroup>

Tabel berikut ini mencantumkan nilai yang valid. Anda dapat menentukan beberapa nilai, dipisahkan oleh titik koma.

Nilai Makna
AppLocal Folder yang dapat dieksekusi aplikasi
AppRelative Jalur relatif terhadap aplikasi yang dapat dieksekusi seperti yang ditentukan oleh AppHostRelativeDotNet
EnvironmentVariables DOTNET_ROOT[_<arch>] Nilai variabel lingkungan
Global Lokasi penginstalan global terdaftar dan default

Properti ini diperkenalkan di .NET 9.

AppHostRelativeDotNet

Properti AppHostRelativeDotNet memungkinkan menentukan jalur relatif untuk aplikasi yang dapat dieksekusi untuk mencari penginstalan .NET saat dikonfigurasi untuk melakukannya. AppHostRelativeDotNet Mengatur properti menyiratkan yaitu AppHostDotNetSearch AppRelative. Properti ini hanya berdampak pada executable yang dihasilkan pada publikasi, bukan build.

<PropertyGroup>
  <AppHostRelativeDotNet>./relative/path/to/runtime</AppHostRelativeDotNet>
</PropertyGroup>

Properti ini diperkenalkan di .NET 9.

EnableComHosting

Properti EnableComHosting menunjukkan bahwa rakitan menyediakan server COM. Mengatur EnableComHosting ke true juga menyiratkan bahwa EnableDynamicLoading adalah true.

<PropertyGroup>
  <EnableComHosting>True</EnableComHosting>
</PropertyGroup>

Untuk mengetahui informasi selengkapnya, lihat Mengekspos komponen .NET ke COM.

EnableDynamicLoading

Properti EnableDynamicLoading menunjukkan bahwa rakitan adalah komponen yang dimuat secara dinamis. Komponen dapat berupa pustaka COM atau pustaka non-COM yang dapat digunakan dari host asli atau digunakan sebagai plugin. Mengatur properti ini ke true memiliki efek berikut:

  • File .runtimeconfig.json dibuat.
  • RollForward diatur ke LatestMinor.
  • Referensi NuGet disalin secara lokal.
<PropertyGroup>
  <EnableDynamicLoading>true</EnableDynamicLoading>
</PropertyGroup>

Properti file yang dibuat

Properti berikut menyangkut kode dalam file yang dibuat:

DisableImplicitNamespaceImports

Properti DisableImplicitNamespaceImports dapat digunakan untuk menonaktifkan impor namespace implisit dalam proyek Visual Basic yang menargetkan .NET 6 atau versi yang lebih baru. Namespace implisit adalah namespace default yang diimpor secara global dalam proyek Visual Basic. Atur properti ini ke true untuk menonaktifkan impor namespace implisit.

<PropertyGroup>
  <DisableImplicitNamespaceImports>true</DisableImplicitNamespaceImports>
</PropertyGroup>

ImplicitUsings

Properti ImplicitUsings dapat digunakan untuk mengaktifkan dan menonaktifkan arahan global using implisit dalam proyek C# yang menargetkan .NET 6 atau versi yang lebih baru dan C# 10 atau versi yang lebih baru. Jika fitur diaktifkan, SDK .NET menambahkan direktif global using untuk sekumpulan namespace default berdasarkan jenis SDK proyek. Atur properti ini ke true atau enable untuk mengaktifkan arahan global using implisit. Untuk menonaktifkan arahan global using implisit, hapus properti atau atur ke false atau disable.

<PropertyGroup>
  <ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>

Catatan

Templat untuk proyek C# baru yang menargetkan .NET 6 atau yang lebih baru telah mengatur ImplicitUsings ke enable secara default.

Untuk menentukan arahan global using eksplisit, tambahkan item Menggunakan.

Item

Item MSBuild adalah input ke dalam sistem build. Item ditentukan sesuai dengan jenisnya, yang merupakan nama elemen. Misalnya, Compile dan Reference adalah dua jenis item umum. Jenis item tambahan berikut ini disediakan oleh SDK .NET:

Anda dapat menggunakan salah satu atribut item standar, misalnya, Include dan Update, pada item ini. Gunakan Include untuk menambahkan item baru, dan gunakan Update untuk mengubah item yang sudah ada. Misalnya, Update sering digunakan untuk memodifikasi item yang secara implisit telah ditambahkan oleh SDK .NET.

AssemblyMetadata

Item AssemblyMetadata menentukan atribut rakitan AssemblyMetadataAttribute pasangan kunci-nilai. Metadata Include menjadi kunci, dan metadata Value menjadi nilai.

<ItemGroup>
  <AssemblyMetadata Include="Serviceable" Value="True" />
</ItemGroup>

InternalsVisibleTo

Item InternalsVisibleTo menghasilkan atribut rakitan InternalsVisibleToAttribute untuk rakitan teman yang ditentukan.

<ItemGroup>
  <InternalsVisibleTo Include="MyProject.Tests" />
</ItemGroup>

Jika rakitan teman ditandatangani, Anda dapat menentukan metadata Key opsional untuk menentukan kunci publik lengkapnya. Jika Anda tidak menentukan metadata Key dan $(PublicKey) tersedia, kunci tersebut akan digunakan. Jika tidak, tidak ada kunci publik yang ditambahkan ke atribut.

FrameworkReference

Item FrameworkReference menentukan referensi ke kerangka kerja bersama .NET.

Atribut Include menentukan ID kerangka kerja.

Cuplikan file proyek dalam contoh berikut mereferensikan kerangka kerja bersama Microsoft.AspNetCore.App.

<ItemGroup>
  <FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>

PackageReference

Item PackageReference menentukan referensi ke paket NuGet.

Atribut Include menentukan ID paket. Atribut Version menentukan versi atau rentang versi. Untuk mengetahui informasi tentang cara menentukan versi minimum, versi maksimum, rentang, atau kecocokan persis, lihat Rentang versi.

Cuplikan file proyek dalam contoh berikut mereferensikan paket System.Runtime.

<ItemGroup>
  <PackageReference Include="System.Runtime" Version="4.3.0" />
</ItemGroup>

Anda juga dapat mengontrol aset dependensi menggunakan metadata seperti PrivateAssets.

<ItemGroup>
  <PackageReference Include="Contoso.Utility.UsefulStuff" Version="3.6.0">
    <PrivateAssets>all</PrivateAssets>
  </PackageReference>
</ItemGroup>

Untuk mengetahui informasi selengkapnya, lihat Referensi paket di file proyek.

TrimmerRootAssembly

Item TrimmerRootAssembly memungkinkan Anda mengecualikan rakitan dari pemangkasan. Pemangkasan adalah proses menghapus bagian runtime yang tidak digunakan dari aplikasi yang dikemas. Dalam beberapa kasus, pemangkasan mungkin salah menghapus referensi yang diperlukan.

XML berikut mengecualikan rakitan System.Security dari pemangkasan.

<ItemGroup>
  <TrimmerRootAssembly Include="System.Security" />
</ItemGroup>

Untuk mengetahui informasi selengkapnya, lihat Opsi pemangkasan.

Menggunakan

Item Using memungkinkan Anda menyertakan namespace secara global di seluruh proyek C#, sehingga Anda tidak perlu menambahkan arahan using untuk namespace di bagian atas file sumber Anda. Item ini mirip dengan item Import yang dapat digunakan untuk tujuan yang sama dalam proyek Visual Basic. Properti ini tersedia mulai dari .NET 6.

<ItemGroup>
  <Using Include="My.Awesome.Namespace" />
</ItemGroup>

Anda juga dapat menggunakan item Using untuk menentukan arahan using <alias> dan using static <type> global.

<ItemGroup>
  <Using Include="My.Awesome.Namespace" Alias="Awesome" />
</ItemGroup>

Contohnya:

  • <Using Include="Microsoft.AspNetCore.Http.Results" Alias="Results" /> memancarkan global using Results = global::Microsoft.AspNetCore.Http.Results;
  • <Using Include="Microsoft.AspNetCore.Http.Results" Static="True" /> memancarkan global using static global::Microsoft.AspNetCore.Http.Results;

Untuk informasi selengkapnya, lihat arahan dan using static <type> arahan aliasusing.

Metadata item

Selain atribut item MSBuild standar, tag metadata item berikut disediakan oleh SDK .NET:

CopyToPublishDirectory

Metadata CopyToPublishDirectory pada item MSBuild mengontrol kapan item disalin ke direktori penerbitan. Nilai yang diizinkan adalah PreserveNewest, yang hanya menyalin item jika telah berubah, Always, yang selalu menyalin item, dan Never, yang tidak pernah menyalin item. Dari sudut performa, PreserveNewest lebih disukai karena memungkinkan build bertambah bertahap.

<ItemGroup>
  <None Update="appsettings.Development.json" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
</ItemGroup>

LinkBase

Untuk item yang berada di luar direktori proyek dan subdirektorinya, target penerbitan menggunakan metadata Link item untuk menentukan tempat menyalin item. Linkjuga menentukan cara item di luar pohon proyek ditampilkan di jendela Penjelajah Solusi Visual Studio.

Jika Link tidak ditentukan untuk item yang berada di luar kerucut proyek, defaultnya adalah %(LinkBase)\%(RecursiveDir)%(Filename)%(Extension). LinkBase memungkinkan Anda menentukan folder dasar yang masuk akal untuk item di luar kerucut proyek. Hierarki folder di bawah folder dasar dipertahankan melalui RecursiveDir. Jika LinkBase tidak ditentukan, ini dihilangkan dari jalur Link.

<ItemGroup>
  <Content Include="..\Extras\**\*.cs" LinkBase="Shared"/>
</ItemGroup>

Gambar berikut menunjukkan cara file yang disertakan melalui glob Include item sebelumnya ditampilkan di Penjelajah Solusi.

Penjelajah Solusi memperlihatkan item dengan metadata LinkBase.

Lihat juga