.NET SDK 專案的MSBuild參考

  • 發行項

此頁面是可用來設定 .NET 專案之MSBuild屬性和專案的參考。

注意

此頁面是進行中的工作，不會列出 .NET SDK 的所有實用MSBuild屬性。 如需常見MSBuild屬性的清單，請參閱一般MSBuild屬性。

架構屬性

本節記載下列MSBuild屬性：

TargetFramework

屬性 TargetFramework 會指定應用程式的目標架構版本。 如需有效目標架構 Monikers 的清單，請參閱 SDK 樣式專案中的目標架構。

<PropertyGroup>
  <TargetFramework>netcoreapp3.1</TargetFramework>
</PropertyGroup>

如需詳細資訊，請參閱 以 SDK 樣式專案為目標架構。

TargetFrameworks

當您想要讓應用程式以多個平臺為目標時， TargetFrameworks 請使用 屬性。 如需有效目標架構 Monikers 的清單，請參閱 SDK 樣式專案中的目標架構。

注意

如果 TargetFramework 指定 (單一) ，則會忽略這個屬性。

<PropertyGroup>
  <TargetFrameworks>netcoreapp3.1;net462</TargetFrameworks>
</PropertyGroup>

如需詳細資訊，請參閱 以 SDK 樣式專案為目標架構。

NetStandardImplicitPackageVersion

注意

此屬性僅適用于使用 netstandard1.x 的專案。 它不適用於使用 netstandard2.x 的專案。

NetStandardImplicitPackageVersion當您想要指定低於中繼套件版本的架構版本時，請使用 屬性。 下列範例中的專案檔會以 為目標 netstandard1.3 ，但使用 的 1.6.0 版本 NETStandard.Library 。

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

元件屬性屬性

GenerateAssemblyInfo

屬性 GenerateAssemblyInfo 會控制 AssemblyInfo 專案的屬性產生。 預設值是 true。 使用 false 停用檔案的產生：

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

GeneratedAssemblyInfoFile設定可控制所產生檔案的名稱。

GenerateAssemblyInfo當值為 true 時，封裝相關的專案屬性會轉換成元件屬性。 下表列出產生屬性的專案屬性。 它也會列出可用來根據每個屬性停用該產生的屬性，例如：

<PropertyGroup>
  <GenerateNeutralResourcesLanguageAttribute>false</GenerateNeutralResourcesLanguageAttribute>
</PropertyGroup>
MSBuild 屬性 組件屬性 要停用屬性產生的屬性
Company AssemblyCompanyAttribute GenerateAssemblyCompanyAttribute
Configuration AssemblyConfigurationAttribute GenerateAssemblyConfigurationAttribute
Copyright AssemblyCopyrightAttribute GenerateAssemblyCopyrightAttribute
Description AssemblyDescriptionAttribute GenerateAssemblyDescriptionAttribute
FileVersion AssemblyFileVersionAttribute GenerateAssemblyFileVersionAttribute
InformationalVersion AssemblyInformationalVersionAttribute GenerateAssemblyInformationalVersionAttribute
Product AssemblyProductAttribute GenerateAssemblyProductAttribute
AssemblyTitle AssemblyTitleAttribute GenerateAssemblyTitleAttribute
AssemblyVersion AssemblyVersionAttribute GenerateAssemblyVersionAttribute
NeutralLanguage NeutralResourcesLanguageAttribute GenerateNeutralResourcesLanguageAttribute

這些設定的相關注意事項：

  • AssemblyVersion 和 FileVersion 預設為 的值 $(Version) ，不含尾碼。 例如，如果 $(Version) 是 1.2.3-beta.4，則此值會是 1.2.3。
  • InformationalVersion 預設為 $(Version) 的值。
  • $(SourceRevisionId)如果屬性存在，則會附加至 InformationalVersion 。 您可以使用 停用此行為 IncludeSourceRevisionInInformationalVersion 。
  • 也會針對 NuGet 中繼資料使用 Copyright 和 Description 屬性。
  • Configuration預設為 Debug 的 ，會與所有MSBuild目標共用。 您可以透過 --configuration 命令選項 dotnet 加以設定，例如 dotnet pack。
  • 建立NuGet套件時，會使用某些屬性。 如需詳細資訊，請參閱 封裝屬性。

從.NET Framework移轉

.NET Framework專案範本會使用這些元件資訊屬性集建立程式碼檔案。 檔案通常位於 .\Properties\AssemblyInfo.cs 或 .\Properties\AssemblyInfo.vb。 SDK 樣式專案會根據專案設定為您產生此檔案。 您無法同時擁有這兩者。 將程式碼移植到 .NET 5 (或 .NET Core 3.1) 或更新版本時，請執行下列其中一項：

  • 在專案檔中將 設定 GenerateAssemblyInfo 為 false ，以停用包含元件資訊屬性的暫存程式碼檔案產生。 這可讓您保留 AssemblyInfo 檔案。
  • 將檔案中的 AssemblyInfo 設定移轉至專案檔，然後刪除檔案 AssemblyInfo 。

GeneratedAssemblyInfoFile

屬性 GeneratedAssemblyInfoFile 會定義所產生元件資訊檔案的相對或絕對路徑。 預設為名為 [project-name] 的檔案。AssemblyInfo。[cs|vb] 在 $(IntermediateOutputPath) (通常是 obj) 目錄中。

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

封裝屬性

您可以指定 、 PackageVersion 、 PackageIcon 、 Title 和 Description 等 PackageId 屬性，以描述從專案建立的封裝。 如需這些和其他屬性的相關資訊，請參閱 套件目標。

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

PackRelease

屬性 PackRelease 與 PublishRelease 屬性類似，不同之處在于它會變更 的預設行為 dotnet pack 。

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

本節記載下列MSBuild屬性：

AppendTargetFrameworkToOutputPath

屬性 AppendTargetFrameworkToOutputPath 會控制 目標架構 Moniker (TFM) 是否附加至 OutputPath) 所定義的輸出路徑 (。 .NET SDK 會自動附加目標架構，如果有的話，執行時間識別碼會附加至輸出路徑。 設定 AppendTargetFrameworkToOutputPath 以防止 false TFM 附加至輸出路徑。 不過，如果沒有輸出路徑中的 TFM，多個組建成品可能會彼此覆寫。

例如，針對 .NET 5 應用程式，輸出路徑會以下列設定從 bin\Debug\net5.0bin\Debug 變更為 ：

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

AppendRuntimeIdentifierToOutputPath

屬性 AppendRuntimeIdentifierToOutputPath 會控制 執行時間識別碼 (RID) 是否附加至輸出路徑。 .NET SDK 會自動附加目標架構，如果有的話，執行時間識別碼會附加至輸出路徑。 將 設定 AppendRuntimeIdentifierToOutputPath 為 false 可防止 RID 附加至輸出路徑。

例如，針對 .NET 5 應用程式和 RID 的 win10-x64 ，輸出路徑會從 bin\Debug\net5.0\win10-x64 變更為 bin\Debug\net5.0 ，並具有下列設定：

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

CopyLocalLockFileAssemblies

屬性 CopyLocalLockFileAssemblies 適用于相依于其他程式庫的外掛程式專案。 如果您將此屬性設定為 true ，則會將任何NuGet套件相依性複製到輸出目錄。 這表示您可以使用 的 dotnet build 輸出在任何電腦上執行外掛程式。

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

提示

或者，您可以使用 dotnet publish 來發佈類別庫。 如需詳細資訊，請參閱 dotnet publish。

ErrorOnDuplicatePublishOutputFiles

當 ErrorOnDuplicatePublishOutputFiles MSBuild SDK 在發行輸出中偵測到重複的檔案，但無法判斷要移除的檔案時，SDK 是否會產生錯誤 NETSDK1148。 如果您不想產生錯誤，請將 ErrorOnDuplicatePublishOutputFiles 屬性設定為 false 。

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

這個屬性是在 .NET 6 中引進的。

EnablePackageValidation

屬性 EnablePackageValidation 會在工作之後 pack 啟用封裝上的一系列驗證。 如需詳細資訊，請參閱 套件驗證。

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

這個屬性是在 .NET 6 中引進的。

GenerateRuntimeConfigDevFile

從 .NET 6 SDK 開始，編譯時期預設不會再產生[Appname].runtimesettings.dev.json檔案。 如果您仍然想要產生這個檔案，請將 GenerateRuntimeConfigDevFile 屬性設定為 true 。

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

GenerateRuntimeConfigurationFiles

屬性 GenerateRuntimeConfigurationFiles 會控制執行時間組態選項是否從 runtimeconfig.template.json 檔案複製到 [appname].runtimeconfig.json 檔案。 對於需要 runtimeconfig.json 檔案的應用程式，也就是其 OutputType 為 Exe 的應用程式，此屬性預設為 true 。

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

GenerateSatelliteAssembliesForCore

屬性 GenerateSatelliteAssembliesForCore 會控制是否使用csc.exe或Al.exe (元件連結器在.NET Framework專案中產生附屬元件) 。 (.NET Core 和 .NET 5+ 專案一律會使用csc.exe來產生附屬元件。) 針對.NET Framework專案，預設會al.exe建立附屬元件。 藉由將 GenerateSatelliteAssembliesForCore 屬性設定為 true ，附屬元件會改為由 csc.exe 建立。 在下列情況下，使用 csc.exe 可能會有好處：

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

IsPublishable

屬性 IsPublishable 可讓 Publish 目標執行。 此屬性只會影響使用 .*proj 檔案和 Publish 目標的進程，例如 dotnet publish 命令。 它不會影響Visual Studio中的發佈，這會使用 PublishOnly 目標。 預設值是 true。

如果您在方案檔上執行 dotnet publish ，這個屬性會很有用，因為它允許自動選取應該發佈的專案。

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

PreserveCompilationCoNtext

屬性 PreserveCompilationContext 可讓建置或已發佈的應用程式使用在建置時間所使用的相同設定，在執行時間編譯更多程式碼。 在建置階段參考的元件將會複製到輸出目錄的 ref 子目錄中。 參考元件的名稱會儲存在應用程式的 .deps.json 檔案中，以及傳遞至編譯器的選項。 您可以使用 和 DependencyContext.CompilationOptions 屬性來擷 DependencyContext.CompileLibraries 取此資訊。

此功能大部分都是由 ASP.NET Core MVC 和 Razor 頁面在內部使用，以支援 Razor 檔案的執行時間編譯。

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

PreserveCompilationReferences

屬性 PreserveCompilationReferences 類似于 PreserveCompilationCoNtext 屬性，不同之處在于它只會將參考的元件複製到發行目錄，而不是 .deps.json 檔案。

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

如需詳細資訊，請參閱 Razor SDK 屬性。

ProduceReferenceAssemblyInOutDir

在 .NET 5 和舊版中，參考元件一律會寫入 OutDir 目錄。 在 .NET 6 和更新版本中，您可以使用 ProduceReferenceAssemblyInOutDir 屬性來控制參考元件是否寫入 OutDir 目錄。 預設值為 false ，而且參考元件只會寫入 IntermediateOutputPath 目錄。 將 值設定為 true ，以將參考元件 OutDir 寫入目錄。

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

如需詳細資訊，請參閱 將參考元件寫入中繼輸出。

PublishRelease

屬性 PublishRelease 會 dotnet publish 通知利用組 Release 態，而不是組 Debug 態。 建議您將這個屬性新增至 Directory.Build.props 檔案，而不是專案檔，以便提早評估該屬性，以便傳播組態變更。

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

注意

這個屬性不會影響 的行為 dotnet build /t:Publish 。

RollForward

屬性 RollForward 可控制當有多個執行時間版本可用時，應用程式如何選擇執行時間。 這個值會輸出至 .runtimeconfig.json 做為 rollForward 設定。

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

設定 RollForward 為下列其中一個值：

值 描述
Minor 如果未指定，則為預設值。
如果遺漏要求的次要版本，請向前復原至最低較高的次要版本。 如果要求的次要版本存在，則會使用原則 LatestPatch 。
Major 如果缺少要求的主要版本，請向前復原至下一個可用的較高主要版本，以及最低次要版本。 如果要求的主要版本存在，則會使用原則 Minor 。
LatestPatch 向前復原至最高修補程式版本。 此值會停用次要版本向前復原。
LatestMinor 向前復原至最高次要版本，即使要求次要版本存在也一樣。
LatestMajor 向前復原至最高主要和最高次要版本，即使要求的主要版本存在也一樣。
Disable 不要向前復原，只系結至指定的版本。 不建議將此原則用於一般用途，因為它會停用向前復原至最新修補程式的功能。 只有測試時才建議使用這個值。

如需詳細資訊，請參閱 控制向前復原行為。

RuntimeFrameworkVersion

屬性 RuntimeFrameworkVersion 會指定發行時要使用的執行時間版本。 指定執行階段版本：

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

發佈架構相依應用程式時，此值會指定所需的 最低 版本。 發佈獨立應用程式時，此值會指定所需的 確切 版本。

RuntimeIdentifier

屬性 RuntimeIdentifier 可讓您為專案指定單一 執行時間識別碼 (RID) 。 RID 允許發佈獨立式部署。

<PropertyGroup>
  <RuntimeIdentifier>ubuntu.16.04-x64</RuntimeIdentifier>
</PropertyGroup>

RuntimeIdentifiers

屬性 RuntimeIdentifiers 可讓您為專案指定以分號分隔的執行時間識別碼清單 ， (RID) 。 如果您需要針對多個執行時間發佈，請使用此屬性。 RuntimeIdentifiers 會在還原時使用 ，以確保正確的資產位於圖表中。

提示

RuntimeIdentifier 當只需要單一執行時間時， (單一) 可以提供更快速的組建。

<PropertyGroup>
  <RuntimeIdentifiers>win10-x64;osx.10.11-x64;ubuntu.16.04-x64</RuntimeIdentifiers>
</PropertyGroup>

SatelliteResourceLanguages

屬性 SatelliteResourceLanguages 可讓您指定要在建置和發佈期間保留附屬資源元件的語言。 許多NuGet套件都包含主要套件中的當地語系化資源附屬元件。 對於參考這些NuGet套件而不需要當地語系化資源的專案，當地語系化的元件可能會不必要地擴大組建和發佈輸出大小。 藉由將 SatelliteResourceLanguages 屬性新增至專案檔，您指定的語言只有當地語系化的元件會包含在建置和發佈輸出中。 例如，在下列專案檔中，只會保留英文 (美國) 資源附屬元件。

<PropertyGroup>
  <SatelliteResourceLanguages>en-US</SatelliteResourceLanguages>
</PropertyGroup>

注意

您必須在專案中指定此屬性，以參考具有當地語系化資源附屬元件的NuGet套件。

UseAppHost

屬性 UseAppHost 可控制是否為部署建立原生可執行檔。 獨立部署需要原生可執行檔。

在 .NET Core 3.0 和更新版本中，預設會建立架構相依可執行檔。 將 UseAppHost 屬性設定為 false ，以停用可執行檔的產生。

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

如需部署的詳細資訊，請參閱 .NET 應用程式部署。

有許多MSBuild屬性可用來微調修剪，這是一項功能，可從獨立式部署修剪未使用的程式碼。 修剪選項會詳細討論這些 選項。 下表提供快速參考。

屬性 值 描述
PublishTrimmed true 或 false 控制是否在發佈期間啟用修剪。
TrimMode link 或 copyused 控制修剪細微性。 這個屬性可以全域設定專案，或在元件層級設定為中繼資料。
SuppressTrimAnalysisWarnings true 或 false 控制是否產生修剪分析警告。
EnableTrimAnalyzer true 或 false 控制是否產生修剪分析警告的子集。 即使 PublishTrimmed 設定為 false ，您也可以啟用分析。
ILLinkWarningLevel 5-9999、、 preview 或 latest 控制修剪分析警告的版本。
ILLinkTreatWarningsAsErrors true 或 false 控制修剪警告是否視為錯誤。 例如，當 設定為 時 TreatWarningsAsErrors ，您可能會想要將這個屬性 false 設定為 true 。
TrimmerSingleWarn true 或 false 控制每個元件是否顯示單一警告或所有警告。
TrimmerRemoveSymbols true 或 false 控制是否從修剪的應用程式中移除所有符號。

本節記載了下列MSBuild屬性：

C# 編譯器選項，例如 LangVersion 和 Nullable ，也可以指定為專案檔中的MSBuild屬性。 如需詳細資訊，請參閱 C# 編譯器選項。

DisableImplicitFrameworkDefines

屬性 DisableImplicitFrameworkDefines 可控制 SDK 是否為 .NET 專案的目標架構和平臺產生預處理器符號。 當此屬性設定為 false 或 未設定 (這是產生預處理器符號的預設值) 預處理器符號時：

  • 沒有版本 (NETFRAMEWORK 、、 NETSTANDARD) NET 的架構
  • 具有版本 (NET48 、 NETSTANDARD2_0 、 NET6_0) 的架構
  • 具有版本下限的架構 (NET48_OR_GREATER 、 NETSTANDARD2_0_OR_GREATER) NET6_0_OR_GREATER

如需目標 Framework Moniker 和這些隱含預處理器符號的詳細資訊，請參閱 目標架構。

此外，如果您在專案中指定作業系統特定的目標架構，例如 net6.0-android () ，就會產生下列預處理器符號：

  • 沒有版本的平臺 (ANDROID 、 IOS) WINDOWS
  • 具有版本 (IOS15_1) 的平臺
  • 版本下限 () IOS15_1_OR_GREATER 的平臺

如需作業系統特定目標 Framework Moniker 的詳細資訊，請參閱 OS 特定的TFM。

最後，如果您的目標 Framework 表示支援較舊的目標架構，則會發出這些舊架構的預處理器符號。 例如， net6.0表示支援 net5.0 等等，一路回到 .netcoreapp1.0 。 因此，針對每個目標架構，將會定義 版本下限符號的 Framework 。

DocumentationFile

屬性 DocumentationFile 可讓您指定 XML 檔案的檔案名，其中包含程式庫的檔。 若要讓IntelliSense使用您的檔正確運作，檔案名必須與元件名稱相同，而且必須位於與元件相同的目錄中。 如果您未指定此屬性，但將 GenerateDocumentationFile 設定為 true ，檔檔的名稱預設為元件的名稱，但副檔名 為.xml 。 基於這個理由，通常比較容易省略此屬性，並改用 GenerateDocumentationFile 屬性 。

如果您指定這個屬性，但將 GenerateDocumentationFile 設定為 false ，編譯器 就不會 產生檔檔。 如果您指定這個屬性並省略 GenerateDocumentationFile 屬性，編譯器 就會 產生檔檔。

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

EmbeddedResourceUseDependentUponConvention

屬性 EmbeddedResourceUseDependentUponConvention 會定義是否從與資源檔共置的來源檔案中的類型資訊產生資源資訊清單檔案名。 例如，如果 Form1.resx 位於 與 Form1.cs相同的資料夾中，而且 EmbeddedResourceUseDependentUponConvention 設定為 true ，則產生的 .resources 檔案會從 Form1.cs中定義的第一個類型取得其名稱。 例如，如果 MyNamespace.Form1 是 Form1.cs中定義的第一個類型，則產生的檔案名為 MyNamespace.Form1.resources。

注意

如果 LogicalName 為 EmbeddedResource 專案指定了 、 ManifestResourceName 或 DependentUpon 中繼資料，該資源檔的產生的資訊清單檔名稱會改為以該中繼資料為基礎。

根據預設，在新的 .NET 專案中，此屬性會設定為 true 。 如果設定為 false ，且未 LogicalName 針對 EmbeddedResource 專案檔中的專案指定任何 、 ManifestResourceName 或 DependentUpon 中繼資料，則資源資訊清單檔名稱是以專案的根命名空間和.resx檔案的相對檔案路徑為基礎。 如需詳細資訊，請參閱 如何命名資源資訊清單檔。

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

EnablePreviewFeatures

屬性 EnablePreviewFeatures 會定義專案是否相依于使用 RequiresPreviewFeaturesAttribute 屬性裝飾的任何 API 或元件。 這個屬性用來表示 API 或元件會使用您正在使用之 SDK 版本的 預覽 功能。 不支援預覽功能，未來版本可能會移除。 若要啟用預覽功能的使用，請將 屬性設定為 True 。

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

當專案包含此屬性設定為 True 時，會將下列元件層級屬性新增至 AssemblyInfo.cs 檔案：

[assembly: RequiresPreviewFeatures]

分析器會在未設定 True 為 的專案 EnablePreviewFeatures 相依性上出現這個屬性時發出警告。

想要寄送預覽元件的程式庫作者應該將此屬性設定為 True 。 如果元件需要隨附預覽和非預覽 API 的混合，請參閱下方的 GenerateRequiresPreviewFeaturesAttribute 一節。

GenerateDocumentationFile

屬性 GenerateDocumentationFile 可控制編譯器是否為程式庫產生 XML 檔檔。 如果您將此屬性設定為 true ，而且未透過 DocumentationFile 屬性指定檔案名，則產生的 XML 檔案會放在與元件相同的輸出目錄中，而且具有相同的檔案名 (，但副檔名為 .xml) 。

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

如需從程式碼批註產生檔的詳細資訊，請參閱XML 檔批註 (C#) 、使用 XML (Visual Basic) 記錄程式碼，或使用XML (F#) 記錄程式碼。

GenerateRequiresPreviewFeaturesAttribute

屬性 GenerateRequiresPreviewFeaturesAttribute 與 EnablePreviewFeatures 屬性緊密相關。 如果您的程式庫使用預覽功能，但您不想讓整個元件以 屬性標示 RequiresPreviewFeaturesAttribute ，這需要任何取用者 才能啟用預覽功能，請將此屬性設定為 False 。

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

重要

如果您將 GenerateRequiresPreviewFeaturesAttribute 屬性設定為 False ，則必須確定使用 裝飾依賴預覽功能 RequiresPreviewFeaturesAttribute 的所有公用 API。

OptimizeImplicitlyTriggeredBuild

若要加快建置時間，Visual Studio略過程式碼分析所隱含觸發的組建，包括可為 Null 的分析。 例如，Visual Studio會在您執行測試時觸發隱含組建。 不過，只有在 不是 true 時 TreatWarningsAsErrors ，才會優化隱含組建。 如果您已 TreatWarningsAsErrors 設定為 true ，但仍想要將隱含觸發的組建優化，您可以將 設定 OptimizeImplicitlyTriggeredBuild 為 True 。 若要關閉隱含觸發組建的組建優化，請將 設定 OptimizeImplicitlyTriggeredBuild 為 False 。

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

預設專案包含屬性

本節記載了下列MSBuild屬性：

如需詳細資訊，請參閱 預設包含和排除。

DefaultItemExcludes

DefaultItemExcludes使用 屬性來定義應該從 include、exclude 和 remove glob 中排除的檔案和資料夾的 Glob 模式。 根據預設，. /bin 和 ./obj 資料夾會從 glob 模式中排除。

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

DefaultExcludesInProjectFolder

DefaultExcludesInProjectFolder使用 屬性來定義專案資料夾中應該從 include、exclude 和 remove glob 中排除的檔案和資料夾的 Glob 模式。 根據預設，以句號開頭的資料夾 (.) ，例如 .git 和 .vs，會從 glob 模式中排除。

此屬性與 屬性非常類似 DefaultItemExcludes ，不同之處在于它只會考慮專案資料夾中的檔案和資料夾。 當 Glob 模式不小心比對專案資料夾外部的專案與相對路徑時，請使用 DefaultExcludesInProjectFolder 屬性，而不是 DefaultItemExcludes 屬性。

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

EnableDefaultItems

屬性 EnableDefaultItems 會控制編譯專案、內嵌的資源專案和 None 專案是否隱含包含在專案中。 預設值是 true。 將 EnableDefaultItems 屬性設定為 false ，以停用所有隱含檔案包含。

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

EnableDefaultCompileItems

屬性 EnableDefaultCompileItems 可控制編譯專案是否隱含包含在專案中。 預設值是 true。 將 EnableDefaultCompileItems 屬性設定為 false ，以停用 *.cs 和其他語言副檔名檔案的隱含包含。

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

EnableDefaultEmbeddedResourceItems

屬性 EnableDefaultEmbeddedResourceItems 可控制內嵌資源專案是否隱含地包含在專案中。 預設值是 true。 將 EnableDefaultEmbeddedResourceItems 屬性設定為 false ，以停用內嵌資源檔的隱含包含。

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

EnableDefaultNoneItems

屬性 EnableDefaultNoneItems 會控制專案 (建置程式中沒有任何角色的專案) 是否 None 隱含包含在專案中。 預設值是 true。 將 EnableDefaultNoneItems 屬性設定為 false ，以停用專案的隱含包含 None 。

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

程式碼分析屬性

本節記載了下列MSBuild屬性：

AnalysisLevel

屬性 AnalysisLevel 可讓您指定要根據 .NET 版本執行的一組程式碼分析器。 從 .NET 5 開始，每個 .NET 版本都有一組程式碼分析規則。 在該集合中，預設為該版本啟用的規則將會分析您的程式碼。 例如，如果您升級至 .NET 6，但不想讓預設的程式碼分析規則集變更，請將 設定 AnalysisLevel 為 5 。

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

或者，從 .NET 6 開始，您可以指定這個屬性的複合值，同時指定如何積極啟用規則。 複合值的格式 <version>-<mode> 為 ，其中 <mode> 值是 AnalysisMode 值的其中一個。 下列範例使用程式碼分析器的預覽版本，並啟用建議的規則集。

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

注意

如果您將 設定 AnalysisLevel 為 5-<mode> 或 5.0-<mode> ，然後安裝 .NET 6 SDK 並重新編譯專案，您可能會看到非預期的新組建警告。 如需詳細資訊，請參閱 dotnet/roslyn-analyzers#5679。

預設值：

  • 如果您的專案是以 .NET 5 或更新版本為目標，或如果您已新增 AnalysisMode 屬性，則預設值為 latest 。
  • 否則，除非您明確地將此屬性新增至專案檔，否則會省略此屬性。

下表顯示您可以指定的值。

值 意義
latest 會使用已發行的最新程式碼分析器。 此為預設值。
latest-<mode> 會使用已發行的最新程式碼分析器。 值 <mode> 會決定哪些規則已啟用。
preview 使用最新的程式碼分析器，即使它們處於預覽狀態也一樣。
preview-<mode> 使用最新的程式碼分析器，即使它們處於預覽狀態也一樣。 值 <mode> 會決定哪些規則已啟用。
6.0 會使用適用于 .NET 6 版本的規則集，即使有較新的規則可用也一樣。
6.0-<mode> 會使用適用于 .NET 6 版本的規則集，即使有較新的規則可用也一樣。 值 <mode> 會決定哪些規則已啟用。
6 會使用適用于 .NET 6 版本的規則集，即使有較新的規則可用也一樣。
6-<mode> 會使用適用于 .NET 6 版本的規則集，即使有較新的規則可用也一樣。 值 <mode> 會決定哪些規則已啟用。
5.0 使用 .NET 5 版本可用的規則集，即使有較新的規則也一樣。
5.0-<mode> 使用 .NET 5 版本可用的規則集，即使有較新的規則也一樣。 值 <mode> 會決定哪些規則已啟用。
5 使用 .NET 5 版本可用的規則集，即使有較新的規則也一樣。
5-<mode> 使用 .NET 5 版本可用的規則集，即使有較新的規則也一樣。 值 <mode> 會決定哪些規則已啟用。

注意

AnalysisLevel < 類別>

在 .NET 6 中引進，此屬性與 AnalysisLevel相同，不同之處在于它只適用于特定 類別的程式碼分析規則。 此屬性可讓您針對特定類別使用不同的程式碼分析器版本，或啟用或停用其他規則類別的不同層級的規則。 如果您省略特定類別規則的這個屬性，它會預設為 AnalysisLevel 值。 可用的值與 AnalysisLevel的值相同。

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

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

下表列出每個規則類別目錄的屬性名稱。

屬性名稱 規則類別
<AnalysisLevelDesign> 設計規則
<AnalysisLevelDocumentation> 文件規則
<AnalysisLevelGlobalization> 全球化規則
<AnalysisLevelInteroperability> 可攜性與互通性規則
<AnalysisLevelMaintainability> 維護性規則
<AnalysisLevelNaming> 命名規則
<AnalysisLevelPerformance> 效能規則
<AnalysisLevelSingleFile> 單一檔案應用程式規則
<AnalysisLevelReliability> 可靠性規則
<AnalysisLevelSecurity> 安全性規則
<AnalysisLevelStyle> 程式碼樣式 (IDEXXXX) 規則
<AnalysisLevelUsage> 使用規則

AnalysisMode

從 .NET 5 開始，.NET SDK 隨附所有 「CA」 程式碼品質規則。 根據預設，每個 .NET 版本中只有 某些規則會啟用 為組建警告。 屬性 AnalysisMode 可讓您自訂預設啟用的規則集。 您可以切換至較積極的分析模式，其中您可以個別退出宣告規則，或加入宣告特定規則的較保守分析模式。 例如，如果您想要啟用所有規則作為建置警告，請將值設定為 All 。

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

下表顯示 .NET 5 和 .NET 6 中的可用選項值。 它們會依其啟用的規則數目遞增順序列出。

.NET 6+ 值 .NET 5 值 意義
None AllDisabledByDefault 所有規則都會停用。 您可以選擇 性地加入 個別規則來加以啟用。
Default Default 預設模式，其中某些規則會啟用為建置警告，某些規則會啟用為Visual Studio IDE 建議，而其餘規則則會停用。
Minimum N/A 比 Default 模式更積極模式。 強烈建議進行建置強制執行的某些建議會啟用為建置警告。
Recommended N/A 比 Minimum 模式更積極模式，其中會啟用更多規則作為建置警告。
All AllEnabledByDefault 所有規則都會啟用為建置警告。 您可以選擇 退出 個別規則來停用這些規則。

注意

  • 在 .NET 5 中，此屬性只會影響 程式碼品質 (CAXXXX) 規則。 從 .NET 6 開始，如果您將 EnforceCodeStyleInBuild 設定為 true ，此屬性也會影響 程式碼樣式 (IDEXXXX) 規則 。
  • 例如，如果您使用 AnalysisLevel的複合值， <AnalysisLevel>5-recommended</AnalysisLevel> 則可以完全省略這個屬性。 不過，如果您同時指定這兩個屬性， AnalysisLevel 優先順序高於 AnalysisMode 。
  • 如果 AnalysisMode 設定為 AllEnabledByDefault 且 AnalysisLevel 設定為 5 或 5.0 ，然後安裝 .NET 6 SDK 並重新編譯專案，您可能會看到未預期的新組建警告。 如需詳細資訊，請參閱 dotnet/roslyn-analyzers#5679。
  • 此屬性不會影響未參考專案 SDK 之專案中的程式代碼分析，例如，參考 Microsoft.CodeAnalysis.NetAnalyzers NuGet 套件的舊版.NET Framework專案。

AnalysisMode < 類別>

在 .NET 6 中引進，此屬性與 AnalysisMode相同，不同之處在于它只適用于特定 類別的程式碼分析規則。 此屬性可讓您在其他規則類別的不同層級啟用或停用規則。 如果您省略特定規則類別的這個屬性，它會預設為 AnalysisMode 值。 可用的值與 AnalysisMode的值相同。

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

下表列出每個規則類別目錄的屬性名稱。

屬性名稱 規則類別
<AnalysisModeDesign> 設計規則
<AnalysisModeDocumentation> 文件規則
<AnalysisModeGlobalization> 全球化規則
<AnalysisModeInteroperability> 可攜性與互通性規則
<AnalysisModeMaintainability> 維護性規則
<AnalysisModeNaming> 命名規則
<AnalysisModePerformance> 效能規則
<AnalysisModeSingleFile> 單一檔案應用程式規則
<AnalysisModeReliability> 可靠性規則
<AnalysisModeSecurity> 安全性規則
<AnalysisModeStyle> 程式碼樣式 (IDEXXXX) 規則
<AnalysisModeUsage> 使用規則

CodeAnalysisTreatWarningsAsErrors

屬性 CodeAnalysisTreatWarningsAsErrors 可讓您設定是否應該將程式碼品質分析警告 (CAxxxx) 視為警告並中斷組建。 如果您在建置專案時使用 -warnaserror 旗標，也會將 .NET 程式碼品質分析 警告視為錯誤。 如果您不想將程式碼品質分析警告視為錯誤，您可以將專案檔中的 MSBuild 屬性設定 CodeAnalysisTreatWarningsAsErrors 為 false 。

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

EnableNETAnalyzers

預設會針對以 .NET 5 或更新版本為目標的專案啟用.NET 程式碼品質分析。 如果您要使用 .NET 5+ SDK 進行開發，您可以將 屬性設定 EnableNETAnalyzers 為 true ，為以舊版 .NET 為目標的 SDK 樣式專案啟用 .NET 程式碼分析。 若要停用任何專案中的程式碼分析，請將此屬性設定為 false 。

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

注意

此屬性特別適用于 .NET 5+ SDK 中的內建分析器。 當您安裝NuGet程式碼分析套件時，不應該使用它。

EnforceCodeStyleInBuild

根據預設，針對所有 .NET 專案建置時，會停用.NET 程式碼樣式分析。 您可以將 屬性設定 EnforceCodeStyleInBuild 為 true ，以啟用 .NET 專案的程式碼樣式分析。

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

所有 設定 為警告或錯誤的程式碼樣式規則都會在建置和報告違規時執行。

注意

如果您安裝 .NET 6 (或 Visual Studio 2022，其中包含 .NET 6) ，但想要使用 Visual Studio 2019 建置專案，如果您已 EnforceCodeStyleInBuild 將 屬性設定為 true ，您可能會看到新的CS8032警告。 若要解決警告，您可以藉由新增global.json 專案來指定 .NET SDK 版本，以使用 (5.0.404) 建置專案。

_SkipUpgradeNetAnalyzersNuGetWarning

_SkipUpgradeNetAnalyzersNuGetWarning相較于最新 .NET SDK 中的程式碼分析器，屬性可讓您設定是否從NuGet套件使用程式碼分析器收到警告。 警告看起來類似：

.NET SDK 具有比 'Microsoft.CodeAnalysis.NetAnalyzers' 套件版本 '5.0.3' 版本 '6.0.0' 的新分析器。 更新或移除此套件參考。

若要移除此警告，並繼續使用NuGet套件中的程式碼分析器版本，請在專案檔中設定 _SkipUpgradeNetAnalyzersNuGetWarning 為 true 。

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

執行時間組態屬性

您可以在應用程式的專案檔中指定MSBuild屬性，以設定一些執行時間行為。 如需設定執行時間行為之其他方式的資訊，請參閱執行時間組 態設定。

ConcurrentGarbageCollection

屬性 ConcurrentGarbageCollection 會設定是否啟用 背景 (並行) 垃圾收集 。 將 值設定為 false 以停用背景垃圾收集。 如需詳細資訊，請參閱 背景 GC。

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

InvariantGlobalization

屬性 InvariantGlobalization 會設定應用程式是否以 全球化非變異 模式執行，這表示它無法存取特定文化特性的資料。 將 值設定為 ， true 以在全球化非變異模式中執行。 如需詳細資訊，請參閱 非變異模式。

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

PredefinedCulturesOnly

在 .NET 6 和更新版本中，屬性會 PredefinedCulturesOnly 設定應用程式是否可以在啟用 全球化非變異模式 時建立非變異文化特性的文化特性。 預設值為 true。 將 值設定為 false ，以允許在全球化非變異模式中建立任何新的文化特性。

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

如需詳細資訊，請參閱 全球化非變異模式中的文化特性建立和案例對應。

RetainVMGarbageCollection

屬性 RetainVMGarbageCollection 會設定垃圾收集行程，以將已刪除的記憶體區段放在待命清單上，以供日後使用或釋放。 將 值設定為 true ，告知垃圾收集行程將區段放在待命清單中。 如需詳細資訊，請參閱 保留 VM。

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

ServerGarbageCollection

屬性 ServerGarbageCollection 會設定應用程式是否使用 工作站垃圾收集或伺服器垃圾收集。 將 值設定為 true 以使用伺服器垃圾收集。 如需詳細資訊，請參閱 工作站與伺服器。

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

ThreadPoolMaxThreads

屬性 ThreadPoolMaxThreads 會設定背景工作執行緒集區的最大執行緒數目。 如需詳細資訊，請參閱 執行緒上限。

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

ThreadPoolMinThreads

屬性 ThreadPoolMinThreads 會設定背景工作執行緒集區的執行緒數目下限。 如需詳細資訊，請參閱 最小線程。

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

TieredCompilation

屬性 TieredCompilation 會設定 Just-In-Time (JIT) 編譯器是否使用 階層式編譯。 將 值設定為 false ，以停用階層式編譯。 如需詳細資訊，請參閱 階層式編譯。

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

TieredCompilationQuickJit

屬性 TieredCompilationQuickJit 會設定 JIT 編譯程式是否使用快速 JIT。 將 值設定為 false ，以停用快速 JIT。 如需詳細資訊，請參閱 快速 JIT。

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

TieredCompilationQuickJitForLoops

屬性 TieredCompilationQuickJitForLoops 會設定 JIT 編譯程式是否在包含迴圈的方法上使用快速 JIT。 將 值設定為 ， true 以在包含迴圈的方法上啟用快速 JIT。 如需詳細資訊，請參閱 快速 JIT for 迴圈。

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

參考屬性

本節記載下列MSBuild屬性：

AssetTargetFallback

屬性 AssetTargetFallback 可讓您為專案參考和NuGet套件指定其他相容的架構版本。 例如，如果您使用 指定套件相依性 PackageReference ，但該套件不包含與專案 TargetFramework 相容的資產，則 AssetTargetFallback 屬性會開始運作。 參考套件的相容性會使用 中指定的 AssetTargetFallback 每個目標架構來重新檢查。 這個屬性會取代已被取代的屬性 PackageTargetFallback 。

您可以將 屬性設定 AssetTargetFallback 為一或多個 目標架構版本。

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

DisableImplicitFrameworkReferences

當以 .NET Core 3.0 和更新版本為目標時，屬性 DisableImplicitFrameworkReferences 會控制隱含 FrameworkReference 專案。 以 .NET Core 2.1 或 .NET Standard 2.0 和舊版為目標時，它會控制中繼套件中的套件隱含 PackageReference 專案。 (中繼套件是以架構為基礎的套件，僅包含其他 packages 的相依性。) 此屬性也會控制以 .NET Framework 為目標時的隱含參考 SystemSystem.Core 。

將此屬性設定為 true ，以停用隱含 FrameworkReference 或 PackageReference 專案。 如果您將此屬性設定為 true ，您可以只新增您所需的架構或套件的明確參考。

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

還原參考的套件會安裝其所有直接相依性，以及這些相依性的所有相依性。 您可以藉由指定 和 RestoreIgnoreFailedSources 之類的 RestorePackagesPath 屬性來自訂套件還原。 如需這些和其他屬性的詳細資訊，請參閱 還原目標。

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

ValidateExecutableReferencesMatchSelfContained

ValidateExecutableReferencesMatchSelfContained屬性可用來停用與可執行專案參考相關的錯誤。 如果 .NET 偵測到獨立可執行檔專案參考架構相依可執行檔專案，反之亦然，則會分別產生錯誤 NETSDK1150 和 NETSDK1151。 若要避免在刻意參考時發生這些錯誤，請將 ValidateExecutableReferencesMatchSelfContained 屬性設定為 false 。

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

WindowsSdkPackageVersion

WindowsSdkPackageVersion屬性可用來覆寫Windows SDK 目標套件的版本。 這個屬性是在 .NET 5 中引進的，並取代此用途的專案 FrameworkReference 用法。

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

注意

我們不建議覆寫 Windows SDK 版本，因為Windows SDK 目標套件隨附于 .NET 5+ SDK。 相反地，若要參考最新的 Windows SDK 套件，請更新您的 .NET SDK 版本。 這個屬性應該只在罕見的情況下使用，例如使用預覽套件，或需要覆寫 C#/WinRT 版本。

下列屬性用於使用 dotnet run 命令啟動應用程式：

RunArguments

屬性 RunArguments 會定義在應用程式執行時傳遞至應用程式的引數。

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

提示

您可以使用 的 選項，指定要傳遞至應用程式-- 的其他引數。 dotnet run

RunWorkingDirectory

屬性 RunWorkingDirectory 會定義要啟動應用程式進程的工作目錄。 它可以是絕對路徑或相對於專案目錄的路徑。 如果您未指定目錄， OutDir 則會當做工作目錄使用。

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

本節記載下列MSBuild屬性：

EnableComHosting

屬性 EnableComHosting 表示元件提供 COM 伺服器。 EnableComHosting將 設定為 true 也表示EnableDynamicLoading為 true 。

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

如需詳細資訊，請參閱 將 .NET 元件公開至 COM。

EnableDynamicLoading

屬性 EnableDynamicLoading 表示元件是動態載入的元件。 元件可以是 COM 程式庫 或非 COM 程式庫，可從 原生主機使用 或 作為外掛程式使用。 將此屬性設定為 true 具有下列效果：

  • 會產生 .runtimeconfig.json 檔案。
  • RollForward 設定為 LatestMinor 。
  • NuGet參考會複製到本機。
<PropertyGroup>
  <EnableDynamicLoading>true</EnableDynamicLoading>
</PropertyGroup>

產生的檔案屬性

下列屬性涉及所產生檔案中的程式碼：

DisableImplicitNamespaceImports

DisableImplicitNamespaceImports屬性可用來停用以 .NET 6 或更新版本為目標之Visual Basic專案中的隱含命名空間匯入。 隱含命名空間是全域匯入Visual Basic專案中的預設命名空間。 將此屬性設定為 true ，以停用隱含命名空間匯入。

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

ImplicitUsings

ImplicitUsings屬性可用來在以 .NET 6 或更新版本和 C# 10 或更新版本為目標的 C# 專案中啟用和停用隱含 global using 指示詞。 啟用此功能時，.NET SDK 會根據專案 SDK 的類型，新增 global using 一組預設命名空間的指示詞。 將這個屬性設定為 true 或 enable ，以啟用隱含 global using 指示詞。 若要停用隱含 global using 指示詞，請移除 屬性，或將其設定為 false 或 disable 。

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

注意

以 .NET 6 或更新版本為目標之新 C# 專案的範本預設會 ImplicitUsings 設定為 enable 。

若要定義明確的 global using 指示詞，請新增 Using 專案。

項目

MSBuild專案是建置系統的輸入。 專案會根據其類型指定，也就是專案名稱。 例如， Compile 和 Reference 是兩 個常見的專案類型。 .NET SDK 提供下列其他專案類型：

您可以在這些專案上使用任何標準 專案屬性，例如 Include 和 Update 。 使用 Include 來新增專案，並使用 Update 來修改現有的專案。 例如， Update 通常用來修改 .NET SDK 隱含新增的專案。

AssemblyMetadata

專案 AssemblyMetadata 會指定索引鍵/值組 AssemblyMetadataAttribute 元件屬性。 中繼資料 Include 會變成索引鍵，而 Value 中繼資料會變成值。

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

InternalsVisibleTo

專案 InternalsVisibleTo 會產生 InternalsVisibleToAttribute 指定之 friend 元件的元件屬性。

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

如果 friend 元件已簽署，您可以指定選擇性 Key 中繼資料來指定其完整公開金鑰。 如果您未指定 Key 中繼資料，而且 $(PublicKey) 可以使用 ，則會使用該金鑰。 否則，不會將公開金鑰新增至 屬性。

PackageReference

專案 PackageReference 會定義NuGet套件的參考。

Include 屬性會指定套件識別碼。 屬性 Version 會指定版本或版本範圍。 如需如何指定最低版本、最大版本、範圍或完全相符專案的詳細資訊，請參閱 版本範圍。

下列範例中的專案檔程式碼片段會參考 System.Runtime 套件。

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

您也可以使用 之類的中繼資料 PrivateAssets來控制相依性資產。

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

如需詳細資訊，請參閱 專案檔中的套件參考。

TrimmerRootAssembly

專案 TrimmerRootAssembly 可讓您排除元件進行 修剪。 修剪是從封裝的應用程式移除未使用的執行時間部分的程式。 在某些情況下，修剪可能會不正確地移除必要的參考。

下列 XML 會 System.Security 排除元件進行修剪。

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

如需詳細資訊，請參閱 修剪選項。

使用

專案 Using 可讓您在 C# 專案中 全域包含命名空間 ，因此您不需要在來源檔案頂端新增 using 命名空間的 指示詞。 此專案類似于 Import 可用於Visual Basic專案中相同用途的專案。 此屬性可從 .NET 6 開始取得。

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

您也可以使用 Using 專案來定義全域 using <alias> 和 using static <type> 指示詞。

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

例如：

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

如需別名 using 指示詞和 using static <type> 指示詞的詳細資訊，請參閱 using 指示詞。

項目中繼資料

除了標準MSBuild專案屬性之外，.NET SDK 還提供下列專案元資料標記：

CopyToPublishDirectory

當 CopyToPublishDirectory 專案複製到發行目錄時，MSBuild專案上的中繼資料會控制。 允許的值是 PreserveNewest ，只有在專案已變更時，才會複製專案， Always 一律複製專案，而且 Never 永遠不會複製專案。 從效能的觀點來看， PreserveNewest 最好是因為它會啟用累加建置。

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

LinkBase

對於專案目錄及其子目錄以外的專案，發佈目標會使用專案的 Link 中繼資料 來判斷專案複製到何處。 Link也會決定專案樹狀結構外部的專案如何顯示在Visual Studio的方案總管視窗中。

如果未 Link 為專案圓錐以外的專案指定，則預設為 %(LinkBase)\%(RecursiveDir)%(Filename)%(Extension) 。 LinkBase 可讓您為專案圓錐以外的專案指定合理的基底資料夾。 基底資料夾下的資料夾階層會透過 RecursiveDir 保留。 如果未 LinkBase 指定，則會從 Link 路徑中省略它。

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

下圖顯示透過上一個專案 Include glob 包含的檔案如何在 方案總管 中顯示。

Solution Explorer showing item with LinkBase metadata.

另請參閱