.net SDK 專案的 MSBuild 參考

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

注意

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

架構屬性

本節記載下列 MSBuild 屬性:

TargetFramework

TargetFramework屬性會指定應用程式的目標 framework 版本。 如需有效的目標 framework 名字標記清單,請參閱 SDK 樣式專案中的目標framework。

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

如需詳細資訊,請參閱 SDK 樣式專案中的目標 framework

TargetFrameworks

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

注意

如果 TargetFramework 指定了 (單數) ,就會忽略這個屬性。

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

如需詳細資訊,請參閱 SDK 樣式專案中的目標 framework

NetStandardImplicitPackageVersion

注意

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

NetStandardImplicitPackageVersion當您想要指定的 framework 版本低於中繼套件版本時,請使用屬性。 下列範例中的專案檔會以 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 中繼資料使用 CopyrightDescription 屬性。
  • 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屬性會定義所產生之元件資訊檔案的相對或絕對路徑。 預設為名為 [專案名稱] 的檔案。AssemblyInfo.[cs | vb]$(IntermediateOutputPath) (通常是 Obj) 目錄。

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

封裝屬性

您可以指定屬性,例如 PackageIdPackageVersionPackageIconTitle 和, Description 以描述從專案建立的封裝。 如需這些屬性和其他屬性的詳細資訊,請參閱 套件目標

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

本節記載下列 MSBuild 屬性:

AppendTargetFrameworkToOutputPath

AppendTargetFrameworkToOutputPath屬性控制是否要將目標 framework 標記 (TFM) 附加至OutputPath) 所定義的輸出路徑 (。 .NET SDK 會自動將目標 framework (如果有的話)附加至輸出路徑的執行時間識別碼。 設定 AppendTargetFrameworkToOutputPathfalse 防止將 TFM 附加至輸出路徑。 但是,如果沒有 TFM 在輸出路徑中,多個組建成品可能會互相覆寫。

例如,針對 .NET 5.0 應用程式,輸出路徑會從變更 bin\Debug\net5.0 為, bin\Debug 並具有下列設定:

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

AppendRuntimeIdentifierToOutputPath

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

例如,針對 .NET 5.0 應用程式和的 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 是否會產生錯誤 NETSDK1148。 ErrorOnDuplicatePublishOutputFiles false 如果您不想產生錯誤,請將屬性設定為。

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

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

GenerateRuntimeConfigurationFiles

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

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

IsPublishable

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

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

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

PreserveCompilationCoNtext

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

這項功能大多是由 ASP.NET Core MVC 和 Razor pages 在內部使用,以支援 Razor 檔案的執行時間編譯。

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

PreserveCompilationReferences

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

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

如需詳細資訊,請參閱 RAZOR SDK 屬性

向前復原

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>

發行與 framework 相依的應用程式時,這個值會指定所需的 最低 版本。 發行獨立應用程式時,這個值會指定所需的 確切 版本。

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 屬性加入至專案檔,組建和發行輸出中只會包含您所指定語言的當地語系化元件。 例如,在下列專案檔中,只會保留英文 (US) 資源附屬元件。

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

注意

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

UseAppHost

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

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

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

如需部署的詳細資訊,請參閱 .net 應用程式部署

本節記載下列 MSBuild 屬性:

c # 編譯器選項也可以指定為專案檔中的 MSBuild 屬性。 如需詳細資訊,請參閱 c # 編譯器選項

EmbeddedResourceUseDependentUponConvention

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

注意

如果 LogicalNameManifestResourceName DependentUpon 專案指定、或中繼資料 EmbeddedResource ,則會改為以該中繼資料為基礎,產生該資源檔的資訊清單檔案名。

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

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

EnablePreviewFeatures

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

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

當專案將這個屬性設定為時 True ,會將下列元件層級屬性加入至 AssemblyInfo .cs 檔案:

[assembly: RequiresPreviewFeatures]

如果專案的相依性 EnablePreviewFeatures 不是設定為,則分析器會發出警告 True

想要寄送預覽元件的程式庫作者,應該將此屬性設定為 True 。 如果元件需要以混合的預覽和非預覽 Api 來送出,請參閱下面的 GenerateRequiresPreviewFeaturesAttribute 一節。

GenerateRequiresPreviewFeaturesAttribute

GenerateRequiresPreviewFeaturesAttribute屬性與EnablePreviewFeatures屬性密切相關。 如果您的程式庫使用預覽功能,但您不想要使用屬性標記整個元件 RequiresPreviewFeaturesAttribute ,這會要求任何取用者 啟用預覽功能,請將此屬性設定為 False

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

重要

如果您將 GenerateRequiresPreviewFeaturesAttribute 屬性設定為 False ,您必須確定所有依賴預覽功能的公用 api 都必須加以裝飾 RequiresPreviewFeaturesAttribute

OptimizeImplicitlyTriggeredBuild

為了加速組建時間,Visual Studio 略過程式碼分析(包含可為 null 的分析)隱含觸發的組建。 例如,當您執行測試時,Visual Studio 會觸發隱含的組建。 不過,隱含組建只有在不是時才會優化 TreatWarningsAsErrors true 。 如果您已 TreatWarningsAsErrors 將設定為, true 但仍想要將隱含觸發的組建優化,則可以將設定 OptimizeImplicitlyTriggeredBuildTrue 。 若要關閉隱含觸發之組建的組建優化,請將設定 OptimizeImplicitlyTriggeredBuildFalse

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

預設專案包含屬性

本節記載下列 MSBuild 屬性:

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

DefaultItemExcludes

DefaultItemExcludes 可以使用屬性來定義應從包含、排除和移除 glob 中排除之檔案和資料夾的 glob 模式。 根據預設, /bin./obj 資料夾會從 glob 模式中排除。

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

DefaultExcludesInProjectFolder

DefaultExcludesInProjectFolder 可以使用屬性來定義專案資料夾中檔案和資料夾的 glob 模式,這些檔案和資料夾應從 include、exclude 和 remove glob 中排除。 根據預設,以句點開頭的資料夾 (.) (例如, git..)會從 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,但不想要變更預設的程式碼分析規則集,請將設定 AnalysisLevel5

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

(選擇性)從 .NET 6 開始,您可以指定這個屬性的複合值,此屬性也會指定啟用規則的積極程度。 複合值採用格式 <level>-<mode> ,其中的 <mode> 值是其中一個 AnalysisMode 值。 下列範例會使用 preview 版的程式碼分析器,並啟用建議的規則集。

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

預設值:

  • 如果您的專案是以 .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> 值會決定啟用的規則。

注意

  • 在 .NET 5 和較早的版本中,此屬性只會影響 程式碼品質 (CAXXXX) 規則。 從 .NET 6 開始,如果您將 EnforceCodeStyleInBuild 設定為 true ,這個屬性也會影響 程式碼樣式 (IDEXXXX) 規則
  • 如果您設定的複合值 AnalysisLevel ,就不需要指定 AnalysisMode。 但是,如果您這麼做,優先 AnalysisLevelAnalysisMode
  • 在未參考專案 SDK的專案中,這個屬性不會影響程式碼分析,例如,參考 CodeAnalysis NetAnalyzers NuGet 封裝的舊版 .NET Framework 專案。

AnalysisLevel<Category>

在 .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.0 開始,.NET SDK 隨附所有「CA」程式 代碼品質規則。 依預設,只 會啟用部分規則 做為組建警告。 AnalysisMode屬性可讓您自訂預設啟用的規則集。 您可以切換至更積極的 (退出) 分析模式或更保守的 (加入) 分析模式。 例如,如果您想要預設啟用所有規則作為組建警告,請將值設為 AllAllEnabledByDefault

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

下表顯示可用的選項。 它們會以其所啟用的規則數目遞增順序列出。

意義 對應的已取代值
None 預設會停用所有規則。 您可以選擇性地 加入宣告 個別規則來啟用它們。 AllDisabledByDefault
Default 預設模式,其中某些規則會啟用為組建警告,某些規則會啟用為 Visual Studio IDE 建議,並停用其餘部分。
Minimum 比模式更積極的模式 Default 。 針對組建強制執行強烈建議的某些建議會啟用為組建警告。
Recommended 比模式更積極的模式 Minimum ,其中會啟用更多規則作為組建警告。
All 預設會啟用所有規則作為組建警告。 您可以選擇性地 退出宣告 個別規則來停用它們。 AllEnabledByDefault

注意

  • 在 .NET 5 中,這個屬性只會影響 程式碼品質 (CAXXXX) 規則。 從 .NET 6 開始,如果您將 EnforceCodeStyleInBuild 設定為 true ,這個屬性也會影響 程式碼樣式 (IDEXXXX) 規則
  • 例如,如果您使用 AnalysisLevel的複合值, <AnalysisLevel>5-recommended</AnalysisLevel> 就可以完全省略這個屬性。 但是,如果您同時指定這兩個屬性,就 AnalysisLevel 會優先使用 AnalysisMode
  • 在未參考專案 SDK的專案中,這個屬性不會影響程式碼分析,例如,參考 CodeAnalysis NetAnalyzers NuGet 封裝的舊版 .NET Framework 專案。

AnalysisMode<Category>

在 .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 程式碼品質分析 警告視為錯誤。 如果您不想將程式碼品質分析警告視為錯誤,您可以 CodeAnalysisTreatWarningsAsErrors 在專案檔中將 MSBuild 屬性設定為 false

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

EnableNETAnalyzers

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

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

注意

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

EnforceCodeStyleInBuild

注意

這項功能目前為實驗性,而且在 .NET 5 和 .NET 6 版本之間可能會變更。

根據預設, .net 程式碼樣式分析會在所有 .net 專案的組建上停用。 您可以藉由將屬性設定為,啟用 .NET 專案的程式碼樣式分析 EnforceCodeStyleInBuild true

<PropertyGroup>
  <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
</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 及時 (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 屬性會進入 play。 參考封裝的相容性是使用中所指定的每一個目標架構來間隔 AssetTargetFallback 。 這個屬性會取代已被取代的屬性 PackageTargetFallback

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

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

DisableImplicitFrameworkReferences

DisableImplicitFrameworkReferences FrameworkReference .net Core 3.0 和更新版本為目標時,屬性會控制隱含專案。 以 .NET Core 2.1 或 .NET Standard 2.0 和更早版本為目標時,它會在中繼套件中控制封裝的隱含 PackageReference 專案。 (中繼套件是以架構為基礎的封裝,其中只包含其他封裝的相依性。 ) 此屬性也會控制以 System .NET Framework 為 System.Core 目標時的隱含參考,例如和。

將這個屬性設定為, true 以停用隱含 FrameworkReferencePackageReference 專案。 如果您將此屬性設定為 true ,您可以只將明確參考新增至所需的架構或封裝。

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

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

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

ValidateExecutableReferencesMatchSelfContained

ValidateExecutableReferencesMatchSelfContained屬性可用來停用與可執行檔專案參考相關的錯誤。 如果 .NET 偵測到獨立可執行檔專案參考與 framework 相依的可執行檔專案,反之亦然,則會分別產生錯誤 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 伺服器。 將設定 EnableComHostingtrue 也表示 EnableDynamicLoadingtrue

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

如需詳細資訊,請參閱 將 .net 元件公開至 COM

EnableDynamicLoading

EnableDynamicLoading屬性工作表示元件是動態載入的元件。 元件可以是 COM 連結 或可 從原生主機使用 或當做 外掛程式使用的非 com 程式庫。 將這個屬性設定為 true 具有下列效果:

  • 會產生 >.runtimeconfig.json 檔案。
  • 向前復原 設定為 LatestMinor
  • NuGet 的參考會在本機複製。
<PropertyGroup>
  <EnableDynamicLoading>true</EnableDynamicLoading>
</PropertyGroup>

產生的檔案屬性

下列屬性會考慮產生的檔案中的程式碼:

DisableImplicitNamespaceImports

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

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

ImplicitUsings

ImplicitUsings屬性可用來啟用和停用以 global using .net 6 或更新版本為目標的 c # 專案中的隱含指示詞,以及 c # 10.0 或更新版本。 啟用此功能時,.NET SDK 會 global using 根據專案 SDK 的類型,加入一組預設命名空間的指示詞。 將這個屬性設定為 trueenable ,以啟用隱含指示詞 global using 。 若要停用隱含指示詞 global using ,請移除屬性,或將它設定為 falsedisable

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

注意

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

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

項目

MSBuild 專案是組建系統的輸入。 專案是根據其類型(也就是元素名稱)來指定。 例如, CompileReference 是兩個 常見的專案類型。 .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.object 套件。

<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

CopyToPublishDirectoryMSBuild 專案的中繼資料會控制將專案複製到發佈目錄的時間。 允許的值為 PreserveNewest ,只有在已變更時才會複製專案, Always 這一律會複製專案,而且 Never 永遠不會複製專案。 從效能的觀點來看,最好 PreserveNewest 是因為它會啟用增量組建。

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

連結

針對專案目錄及其子目錄以外的專案,發行目標會使用專案的 連結中繼資料 來決定要將專案複製到何處。 Link也會決定專案樹狀結構外的專案如何顯示在 Visual Studio 的方案總管視窗中。

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

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

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

方案總管顯示具有程式庫中繼資料的專案。

另請參閱