.NET SDK 專案的 MSBuild 參考

  • 發行項

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

注意

此頁面建置中，不會列出 .NET SDK 的所有實用 MSBuild 屬性。 如需一般 MSBuild 屬性清單，請參閱一般 MSBuild 屬性。

組件驗證屬性

這些屬性和項目會傳遞至 ValidateAssemblies 工作。 如需組件驗證的詳細資訊，請參閱組件驗證。

本節記載下列 MSBuild 屬性：

注意

這些屬性 (還) 不是 .NET SDK 的一部分。 若要使用這些屬性，您也必須將 PackageReference 新增至 Microsoft.DotNet.ApiCompat.Task。

此外，封裝驗證屬性中記錄的下列屬性也適用於組件驗證：

ApiCompatStrictMode

當設定為 true 時，ApiCompatStrictMode 屬性會指定應該以 strict 模式執行 API 相容性檢查。

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

ApiCompatValidateAssemblies

ApiCompatValidateAssemblies 屬性會在指定的組件啟用一系列驗證。 如需詳細資訊，請參閱組件驗證。

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

Framework 屬性

本節記載下列 MSBuild 屬性：

TargetFramework

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

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

如需詳細資訊，請參閱 SDK 樣式專案中的目標 Framework。

TargetFrameworks

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

注意

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

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

如需詳細資訊，請參閱 SDK 樣式專案中的目標 Framework。

NetStandardImplicitPackageVersion

注意

這個屬性只適用於使用 netstandard1.x 的專案。 這不適用於使用 netstandard2.x 的專案。

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

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

組件屬性 (Attribute) 屬性 (Property)

GenerateAssemblyInfo

GenerateAssemblyInfo 屬性 (Property) 會控制專案的 AssemblyInfo 屬性 (Attribute) 產生。 預設值是 true。 false 可用來停用檔案的產生：

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

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

GenerateAssemblyInfo 值為 true 時，套件相關的專案屬性 (Property) 會轉換成組件屬性 (Attribute)。

如需使用專案檔產生組件屬性的詳細資訊，請參閱在專案檔中設定組件屬性。

GeneratedAssemblyInfoFile

GeneratedAssemblyInfoFile 屬性會對於產生的組件資訊檔案定義檔案的相對或絕對路徑。 預設為 $(IntermediateOutputPath) (通常是 obj) 目錄中名為 [專案名稱].AssemblyInfo.[cs|vb] 的檔案。

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

封裝屬性

描述性屬性

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

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

PackRelease

PackRelease 屬性與 PublishRelease 屬性類似，不同之處在於這會變更 dotnet pack 的預設行為 。 此屬性是在 .NET 7 中引進。

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

注意

  • 從 .NET 8 SDK 開始，PackRelease 預設為 true。 如需詳細資訊，請參閱「dotnet pack」使用版本設定。
  • 僅限 .NET 7 SDK：若要在屬於 Visual Studio 解決方案的專案中使用 PackRelease，您必須將環境變數 DOTNET_CLI_ENABLE_PACK_RELEASE_FOR_SOLUTIONS 設定為 true (或其他任何值)。 對於有許多專案的解決方案，設定此變數會增加封裝所需的時間。

套件驗證屬性

這些屬性和項目會傳遞至 ValidatePackage 工作。 如需套件驗證的詳細資訊，請參閱套件驗證概觀。

如需 ValidateAssemblies 工作的屬性資訊，請參閱組件驗證屬性。

本節記載下列 MSBuild 屬性和項目：

ApiCompatEnableRuleAttributesMustMatch

當設定為 true 時，ApiCompatEnableRuleAttributesMustMatch 屬性會啟用驗證規則，以檢查屬性是否相符。 預設值為 false。

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

ApiCompatEnableRuleCannotChangeParameterName

當設定為 true 時，ApiCompatEnableRuleCannotChangeParameterName 屬性會啟用驗證規則，以檢查參數名稱是否已在公用方法中變更。 預設值為 false。

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

ApiCompatExcludeAttributesFile

ApiCompatExcludeAttributesFile 項目指定包含要以 DocId 格式排除的屬性的檔案路徑。

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

ApiCompatGenerateSuppressionFile

ApiCompatGenerateSuppressionFile 屬性指定是否產生相容性隱藏檔案。

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

ApiCompatPermitUnnecessarySuppressions

ApiCompatPermitUnnecessarySuppressions 屬性指定是否允許隱藏檔案中不必要的隱藏。

預設值為 false。

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

ApiCompatPreserveUnnecessarySuppressions

ApiCompatPreserveUnnecessarySuppressions 屬性指定在重新產生隱藏檔案時，是否保留不必要的隱藏。 重新產生現有的隱藏檔案時，會讀取其內容、還原序列化為一組隱藏，然後儲存在清單中。 如果已修正隱藏，可能不再需要某些隱藏。 當隱藏序列化回磁碟時，您可以選擇將此屬性設定為 true 來保留所有現有的 (還原串行化) 運算式。

預設值為 false。

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

ApiCompatRespectInternals

ApiCompatRespectInternals 屬性指定除了 public API 之外，是否應檢查 internal API 相容性。

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

ApiCompatSuppressionFile

ApiCompatSuppressionFile 項目指定要讀取的一或多個隱藏檔案的路徑。 如果未指定，則會讀取隱藏檔案 <project-directory>/CompatibilitySuppressions.xml (若存在)。

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

ApiCompatSuppressionOutputFile

ApiCompatSuppressionOutputFile 屬性指定當 <ApiCompatGenerateSuppressionFile> 為 true 時，要寫入的隱藏檔案路徑。 如果未指定，則會使用第一個 ApiCompatSuppressionFile 項目。

EnablePackageValidation

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

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

EnableStrictModeForBaselineValidation

當設定為 true 時，EnableStrictModeForBaselineValidation 屬性會啟用 strict 模式以執行套件基準檢查。 預設值為 false。

EnableStrictModeForCompatibleFrameworksInPackage

當設定為 true 時，EnableStrictModeForCompatibleFrameworksInPackage 屬性會針對以目標 Framework 為基礎的元件為相容的組件啟用 strict 模式。 預設值為 false。

EnableStrictModeForCompatibleTfms

當設定為 true 時，EnableStrictModeForCompatibleTfms 屬性會針對所有相容的目標 Framework 為合約和實作組件啟用 strict 模式。 預設值為 true。

NoWarn

NoWarn 屬性指定要隱藏的診斷識別碼。

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

PackageValidationBaselineFrameworkToIgnore

PackageValidationBaselineFrameworkToIgnore 項目指定要從基準套件忽略的目標 Framework。 架構字串必須完全符合基準套件中的資料夾名稱。

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

PackageValidationBaselineName

PackageValidationBaselineName 屬性指定要驗證目前套件的基準套件名稱。 如果未指定，則會使用 PackageId 值。

PackageValidationBaselineVersion

PackageValidationBaselineVersion 屬性指定要驗證目前套件的基準套件版本。

PackageValidationReferencePath

PackageValidationReferencePath 項目指定每個 TFM 可找到參考組件的目錄路徑。

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

RoslynAssembliesPath

RoslynAssembliesPath 屬性指定目錄的路徑，其中包含您要使用的 Microsoft.CodeAnalysis 組件。 只有當您要使用比 SDK 中的編譯器版本更高的編譯器進行測試時，才需要設定此屬性。

本節記載下列 MSBuild 屬性：

AppendTargetFrameworkToOutputPath

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

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

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

AppendRuntimeIdentifierToOutputPath

AppendRuntimeIdentifierToOutputPath 屬性會控制執行階段識別碼 (RID) 是否附加至輸出路徑。 .NET SDK 會自動將目標 Framework 和執行階段識別碼 (如果有) 附加至輸出路徑。 將 AppendRuntimeIdentifierToOutputPath 設定為 false 可防止 RID 附加至輸出路徑。

例如，針對 .NET 5 應用程式和 win10-x64 的 RID，輸出路徑會使用下列設定從 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 是否會產生錯誤 NETSDK1148。 如果您不想產生錯誤，請將 ErrorOnDuplicatePublishOutputFiles 屬性設定為 false。

<PropertyGroup>
  <ErrorOnDuplicatePublishOutputFiles>false</ErrorOnDuplicatePublishOutputFiles>
</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 屬性會控制是否使用 .NET Framework 專案中的csc.exe 或 Al.exe (組件連結器) 產生附屬組件。 (.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.CompileLibraries 和 DependencyContext.CompilationOptions 屬性來擷取此資訊。

這項功能主要是由 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>

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

PublishDocumentationFile

此屬性為 true 時，如果產生專案的 XML 文件檔案，就會包含在專案的發行輸出中。 這個屬性的預設值為 true。

提示

將 GenerateDocumentationFile 設定為 true，以便在編譯時間產生 XML 文件檔案。

PublishDocumentationFiles

此屬性是數個其他屬性的啟用旗標，可控制各種 XML 文件檔案是否預設複製到發行目錄，也就是 PublishDocumentationFile 和 PublishReferencesDocumentationFiles。 如果那些屬性未設定，而此屬性已設定，則這些屬性會預設為 true。 這個屬性的預設值為 true。

PublishReferencesDocumentationFiles

此屬性為 true 時，專案的參考 XML 文件檔案會複製到發行目錄，而不只是執行階段資產，例如 DLL 檔案。 這個屬性的預設值為 true。

PublishRelease

PublishRelease 屬性預設會通知 dotnet publish 使用 Release 設定，而不是 Debug 組態。 此屬性是在 .NET 7 中引進。

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

注意

  • 從 .NET 8 SDK 開始，針對目標 .NET 為 8 或更新版本的專案，PublishRelease 預設為 true。 如需詳細資訊，請參閱「dotnet publish」使用版本設定。
  • 這個屬性不會影響 dotnet build /t:Publish 的行為，而且只有在透過 .NET CLI 發佈時才會變更組態。
  • 僅限 .NET 7 SDK：若要在屬於 Visual Studio 解決方案的專案中使用 PublishRelease，您必須將環境變數 DOTNET_CLI_ENABLE_PUBLISH_RELEASE_FOR_SOLUTIONS 設定為 true (或其他任何值)。 發行已啟用此變數的解決方案時，可執行專案的 PublishRelease 值會優先使用，並將新的預設設定傳送到解決方案中的其他任何專案。 如果解決方案包含有 PublishRelease 的不同值在其中的多個可執行檔或最上層專案，則解決方案將不會成功發佈。 對於有許多專案的解決方案，使用此設定會增加發佈所需的時間。

PublishSelfContained

PublishSelfContained 屬性會通知 dotnet publish 將應用程式發佈為獨立應用程式。 無法將引數 --self-contained 用於 dotnet publish 命令時 (例如，在解決方案層級發佈時)，此屬性非常實用。 在此情況下，您可以將 PublishSelfContained MSBuild 屬性新增至專案或 Directory.Build.Props 檔案。

此屬性是在 .NET 7 中引進。 它類似於 SelfContained 屬性，不同之處在於它專屬於 publish 動詞。 建議改用 PublishSelfContained，而不是 SelfContained。

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

RollForward

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

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

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

值 Description
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;de-DE</SatelliteResourceLanguages>
</PropertyGroup>

注意

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

  • 若要將多種語言指定為 dotnet publish 的引數，您必須在語言識別項周圍加上三組引號。 例如：

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

SelfContained

SelfContained 屬性會通知 dotnet build 和 dotnet publish 將應用程式發佈為獨立應用程式。 無法將引數 --self-contained 用於 dotnet 命令時 (例如，在解決方案層級發佈時)，此屬性非常實用。 在此情況下，您可以將 SelfContained MSBuild 屬性新增至專案或 Directory.Build.Props 檔案。

此屬性類似於 PublishSelfContained 屬性。 建議改用 PublishSelfContained，而不是 SelfContained。

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

UseAppHost

UseAppHost 屬性會控制是否為部署建立原生可執行檔。 獨立式部署需要原生可執行檔。 依預設，系統會建立架構相依可執行檔。 將 UseAppHost 屬性設定為 false，以停用可執行檔的產生。

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

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

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

屬性 值 描述
PublishTrimmed true 或 false 控制是否在發佈期間啟用修剪。
TrimMode full 或 partial 預設值為 full。 控制修剪細微性。
SuppressTrimAnalysisWarnings true 或 false 控制是否產生修剪分析警告。
EnableTrimAnalyzer true 或 false 控制是否產生修剪分析警告的子集。 即使 PublishTrimmed 設定為 false，您也可以啟用分析。
ILLinkTreatWarningsAsErrors true 或 false 控制修剪警告是否被視為錯誤。 例如，TreatWarningsAsErrors 設定為 true 時，您可能會想要將此屬性設定為 false。
TrimmerSingleWarn true 或 false 控制每個組件顯示單一警告或所有警告。
TrimmerRemoveSymbols true 或 false 控制是否從修剪的應用程式中移除所有符號。

本節記載下列 MSBuild 屬性：

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

ContinuousIntegrationBuild

屬性 ContinuousIntegrationBuild 會指出組建是否在持續整合 (CI) 伺服器上執行。 設定為 true 時，這個屬性會啟用僅套用於官方組建的設定，而不是開發人員機器上的本機組建。 例如，預存檔案路徑會針對官方組建標準化。 但在本機開發機器上，如果檔案路徑標準化，偵錯工具無法找到本機原始程式檔。

注意

目前，只有在新增特定的 SourceLink 提供者套件參考或 <SourceRoot Include="$(MyDirectory)" /> 項目時，將此屬性設定為 true 才能起作用。 如需詳細資訊，請參閱 dotnet/roslyn 問題 55860 (英文)。

您可以使用 CI 系統的變數來有條件地設定 ContinuousIntegrationBuild 屬性。 例如，Azure Pipelines 的變數名稱為 TF_BUILD：

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

對於 GitHub Actions，變數名稱為 GITHUB_ACTIONS：

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

CopyDebugSymbolFilesFromPackages

此屬性設定為 true 時，所有符號檔 (也稱為 PDB 檔案) 都會從專案中的 PackageReference 項目複製到組建輸出。 這些檔案可為例外狀況提供更多樣化的堆疊追蹤，並讓執行中應用程式的記憶體傾印和追蹤更容易瞭解。 不過，包括這些檔案會導致部署搭售方案大小增加。

這個屬性是在 .NET SDK 7.0.100 中引進，但預設不會指定。

CopyDocumentationFilesFromPackages

此屬性設定為 true 時，專案的 PackageReference 項目中所有產生的 XML 文件檔案都會複製到組建輸出。 請注意，啟用這項功能會導致部署搭售方案大小增加。

這個屬性是在 .NET SDK 7.0.100 中引進，但預設不會指定。

DisableImplicitFrameworkDefines

DisableImplicitFrameworkDefines 屬性會控制 SDK 是否為 .NET 專案的目標 Framework 和平台產生前置處理器符號。 此屬性設定為 false 或未設定 (時，即會產生預設值) 時，會產生下列項目的前置處理器符號：

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

如需目標 Framework Monikers 和這些隱含前置處理器符號的詳細資訊，請參閱目標 Framework 。

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

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

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

最後，如果您的目標 Framework 表示支援較舊的目標 Framework，則會發出這些舊基礎結構的前置處理器符號。 例如，net6.0表示支援 net5.0 等等，向下支援至 .netcoreapp1.0。 因此，針對每個目標 Framework，將定義有版本下限的 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。

注意

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

根據預設，在以 .NET Core 3.0 或更新版本為目標的新 .NET 專案中，此屬性會設定為 true。 如果設定為 false，而且未針對專案檔中的 EmbeddedResource 項目指定任何 LogicalName、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]

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

想要傳送預覽組件的程式庫作者應該將此屬性設定為 True。 如果組件需要連同預覽和非預覽 API 的混合一起傳送，請參閱下文的 GenerateRequiresPreviewFeaturesAttribute 一節。

EnableWindowsTargeting

將 EnableWindowsTargeting 屬性設定為 true 以便在非 Windows 平台上組建 Windows 應用程式 (例如，Windows Forms 或 Windows Presentation Foundation 應用程式)。 如果您未將此屬性設定為 true，您將收到組建警告 NETSDK1100。 之所以發生此錯誤，是因為目標套件和執行階段套件不會在不支援的平台上自動下載。 藉由設定此屬性，這些套件會在跨目標時下載。

注意

目前建議使用這個屬性，以允許在非 Windows 平台上進行開發。 不過，應用程式準備發行時，這應該在 Windows 上組建。 在非 Windows 平台上組建時，輸出可能與在 Windows 上組建時不同。 特別是，可執行檔不會標示為 Windows 應用程式 (這表示這一律會啟動主控台視窗)，而且不會內嵌圖示。

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

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 會在您執行測試時觸發隱含組建。 不過，只有在 TreatWarningsAsErrors 不是 true 時，才會最佳化隱含組建。 如果您將 TreatWarningsAsErrors 設定為 true，但仍想要將隱含觸發的組建最佳化，您可以將 OptimizeImplicitlyTriggeredBuild 設定為 True。 若要關閉隱含觸發組建的組建最佳化，請將 OptimizeImplicitlyTriggeredBuild 設定為 False。

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

DisableRuntimeMarshalling

DisableRuntimeMarshalling 屬性可讓您指定要停用對專案的執行階段封送處理支援。 如果此屬性設定為 true，則會將 DisableRuntimeMarshallingAttribute 新增至組件，且任何以 P/Invokes 或委派為基礎的 Interop 都會遵循停用的執行階段封送處理的規則。

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

預設項目包含屬性

本節記載下列 MSBuild 屬性：

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

DefaultItemExcludes

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

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

DefaultItemExcludesInProjectFolder

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

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

<PropertyGroup>
  <DefaultItemExcludesInProjectFolder>$(DefaultItemExcludesInProjectFolder);**/myprefix*/**</DefaultItemExcludesInProjectFolder>
</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 8，但不想讓預設的程式碼分析規則集變更，請將 AnalysisLevel 設定為 7。

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

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

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

預設值：

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

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

值 意義
latest 會使用已發佈的最新程式碼分析器。 這是預設值。
latest-<mode> 會使用已發佈的最新程式碼分析器。 <mode> 值會決定哪些規則已啟用。
preview 即使這些處於預覽狀態，也會使用最新的程式碼分析器。
preview-<mode> 即使這些處於預覽狀態，也會使用最新的程式碼分析器。 <mode> 值會決定哪些規則已啟用。
8.0 使用 .NET 第 8 版可用的規則集，即使有較新的規則也是如此。
8.0-<mode> 使用 .NET 第 8 版可用的規則集，即使有較新的規則也是如此。 <mode> 值會決定哪些規則已啟用。
8 使用 .NET 第 8 版可用的規則集，即使有較新的規則也是如此。
8-<mode> 使用 .NET 第 8 版可用的規則集，即使有較新的規則也是如此。 <mode> 值會決定哪些規則已啟用。
7.0 使用 .NET 第 7 版可用的規則集，即使有較新的規則也是如此。
7.0-<mode> 使用 .NET 第 7 版可用的規則集，即使有較新的規則也是如此。 <mode> 值會決定哪些規則已啟用。
7 使用 .NET 第 7 版可用的規則集，即使有較新的規則也是如此。
7-<mode> 使用 .NET 第 7 版可用的規則集，即使有較新的規則也是如此。 <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> 值會決定哪些規則已啟用。

注意

  • 從 .NET 6 開始，如果您將 EnforceCodeStyleInBuild 設定為 true，此屬性會影響程式碼樣式 (IDEXXXX) 規則 (以及程式碼品質規則)。
  • 如果您設定 AnalysisLevel 的複合值，則不需要指定 AnalysisMode。 不過，如果您這麼做，AnalysisLevel 優先順序高於 AnalysisMode。
  • 此屬性不會影響未參考專案 SDK 的專案中進行的程式碼分析，例如參考 Microsoft.CodeAnalysis.NetAnalyzers NuGet package 套件的舊版 .NET Framework 專案。

AnalysisLevel<Category>

此屬性與 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 SDK 提供所有「CA」程式碼品質規則。 根據預設，每個 .NET 版本中只會啟用某些規則做為組建警告 。 AnalysisMode 屬性可讓您自訂預設啟用的規則集。 您可以切換至更積極的分析模式，在其中能夠個別退出規則，也可以切換至較保守的分析模式，在其中能夠加入特定規則。 例如，如果您想要將所有規則啟用為建置警告，請將值設定為 All。

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

下表顯示可用的選項值。 這些值會依所啟用規則數目的遞增順序列出。

值 Description
None 所有規則都會停用。 您可以選擇加入 個別規則來啟用這些規則。
Default 預設模式，其中某些規則會啟用為建置警告，而某些規則會啟用為 Visual Studio IDE 建議，而其餘規則會停用。
Minimum 比 Default 模式更積極的模式。 強烈建議進行建置強制執行的某些建議會啟用為建置警告。 若要查看其中包含哪些規則，請檢查 %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.editorconfig 檔案。
Recommended 比 Minimum 模式更積極的模式，其中會將更多規則啟用為建置警告。 若要查看其中包含哪些規則，請檢查 %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.editorconfig 檔案。
All 所有規則都會啟用為建置警告*。 您可以選擇退出個別規則來停用這些規則。

* 如果將 AnalysisMode 設定為 All，或將 AnalysisLevel 設定為 latest-all，以下規則將不會啟用：CA1017、CA1045、CA1005、CA1014、CA1060、CA1021 和程式碼度量分析器規則 (CA1501、CA1502、CA1505、CA1506 和 CA1509)。 這些舊版規則可能會在未來版本中淘汰。 不過，您仍然可以使用 dotnet_diagnostic.CAxxxx.severity = <severity> 項目來個別啟用這些規則。

注意

  • 從 .NET 6 開始，如果您將 EnforceCodeStyleInBuild 設定為 true，此屬性會影響程式碼樣式 (IDEXXXX) 規則 (以及程式碼品質規則)。
  • 如果您使用 AnalysisLevel 的複合值，例如 <AnalysisLevel>8-recommended</AnalysisLevel>，則可以完全省略此屬性。 不過，如果您同時指定這兩個屬性，則 AnalysisLevel 優先於 AnalysisMode。
  • 此屬性不會影響未參考專案 SDK 的專案中進行的程式碼分析，例如參考 Microsoft.CodeAnalysis.NetAnalyzers NuGet package 套件的舊版 .NET Framework 專案。

AnalysisMode<Category>

此屬性與 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 程式碼品質分析警告也都會被視為錯誤。 若不想讓程式碼品質警告被視為錯誤，您可以在專案檔中將 CodeAnalysisTreatWarningsAsErrors MSBuild 屬性設定為 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>

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

_SkipUpgradeNetAnalyzersNuGetWarning

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

對於「6.0.0」版，.NET SDK 具有比「Microsoft.CodeAnalysis.NetAnalyzers」套件「5.0.3」版提供的分析器更新的分析器。 更新或移除此套件參考。

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

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

執行階段設定屬性

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

AutoreleasePoolSupport

AutoreleasePoolSupport 屬性會設定在支援的 macOS 平台上執行時，每個受控執行緒是否會收到隱含的 NSAutoreleasePool (英文)。 如需詳細資訊，請參閱受控執行緒的 AutoreleasePool。

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

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。

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

TieredPGO

TieredPGO 屬性控制是否啟用動態或階層式特性指引最佳化 (PGO)。 將值設定為 true 以啟用階層式 PGO。 如需詳細資訊，請參閱特性指引最佳化。

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

UseWindowsThreadPool

UseWindowsThreadPool 屬性配置執行緒集區的執行緒管理是否委派給 Windows 執行緒集區 (僅限 Windows)。 預設值為 false，在此情況下會使用 .NET 執行緒集區。 如需詳細資訊，請參閱 Windows 執行緒集區。

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

本節記載下列 MSBuild 屬性：

AssetTargetFallback

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

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

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

DisableImplicitFrameworkReferences

以 .NET Core 3.0 與更新版本為目標時，DisableImplicitFrameworkReferences 屬性會控制隱含 FrameworkReference 項目。 以 .NET Core 2.1 或 .NET Standard 2.0 和舊版為目標時，這會控制中繼套件中的套件所用的隱含 PackageReference 項目。 (中繼套件是以架構為基礎的套件，只會包含其他套件的相依性。)此屬性也會控制以 .NET Framework 為目標時的隱含參考，例如 System 和 System.Core。

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

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

DisableTransitiveFrameworkReferenceDownloads

將 DisableTransitiveFrameworkReferenceDownloads 屬性設定為 true，以避免下載專案未直接參考的額外執行階段和目標套件。

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

DisableTransitiveProjectReferences

DisableTransitiveProjectReferences 屬性會控制隱含專案參考。 將此屬性設定為 true，以停用隱含 ProjectReference 項目。 停用隱含專案參考會導致與 舊版專案系統類似的非可轉移行為。

這個屬性為 true 時，這與在相依專案的所有相依性上設定 PrivateAssets="All" 的效果類似。

如果您將此屬性設定為 true，您可以只將明確參考新增至所需的專案。

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

ManagePackageVersionsCentrally

已在 .NET 7 中引進 ManagePackageVersionsCentrally 屬性。 藉由在存放庫根目錄中的 Directory.Packages.props 檔案中將其設定為 true，您可以從一個位置管理專案中的一般相依性。 使用 Directory.Packages.props 檔案中的 PackageVersion 項目新增常用套件相依性的版本。 然後，在個別專案檔中，您可以省略參考集中管理套件的任何 PackageReference 項目提供的 Version 屬性。

範例 Directory.Packages.props 檔案：

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

個別專案檔：

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

如需詳細資訊，請參閱中央套件管理 (CPM)。

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

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

UseMauiEssentials

將 UseMauiEssentials 屬性設定為 true，以宣告相依於 MAUI Essentials 的專案或套件明確參考。 此設定可確保您的專案會提取 MAUI Essentials 的正確已知基礎結構參考。 如果您的專案參考使用 MAUI Essentials 但您未將此屬性設定為 true 的專案，可能會遇到組建警告 NETSDK1186。

<PropertyGroup>
  <UseMauiEssentials>true</UseMauiEssentials>
</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 版本，原因是 .NET SDK 5 以上皆內含 Windows 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 項目會對於指定的 friend 組件產生 InternalsVisibleToAttribute 組件屬性。

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

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

FrameworkReference

FrameworkReference 項目定義 .NET 共用架構的參考。

Include 屬性指定架構識別碼。

下列範例中的專案檔程式碼片段會參考 Microsoft.AspNetCore.App 共用架構。

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

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 指示詞。 此項目類似於可用於 Visual Basic 專案中相同用途的 Import 項目。 此屬性從 .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> 指示詞。

項目中繼資料

除了標準 MSBuild 項目屬性之外，.NET SDK 也提供下列項目中繼資料標記：

CopyToPublishDirectory

MSBuild 項目上的 CopyToPublishDirectory 中繼資料會控制項目何時複製到發行目錄。 允許的值是 PreserveNewest (只有在項目已變更時才會複製項目)、Always (一律複製項目) 和 Never (絕對不會複製項目)。 從效能的觀點來看，最好是 PreserveNewest，因為這會啟用累加建置。

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

LinkBase

對於專案目錄及其子目錄以外的項目，發佈目標會使用項目的連結中繼資料判斷項目複製到何處。 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.

另請參閱