.NET Core 編程指南中文版 —— 6.3 CLI變更概述 -> .NET Core 的 csproj 格式的新增內容

本文檔概述了從 project.json 遷移到 csproj 和 MSBuild 後，被添加到項目文件的更改。 有關常規項目文件的語法和引用的詳細信息，請參閱 MSBuild 項目文件文檔。

隱式包引用

基於項目文件的 <TargetFramework> 或 <TargetFrameworks> 屬性中指定的目標框架對元包進行隱式引用。 如果指定了 <TargetFramework>，則忽略 <TargetFrameworks>，而與順序無關。

 <PropertyGroup>
   <TargetFramework>netcoreapp2.1</TargetFramework>
 </PropertyGroup>

 

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

建議

由於 Microsoft.NETCore.App 或 NetStandard.Library 元包是被隱式引用的，以下是建議的最佳做法：

• 面向 .NET Core 或 .NET Standard 時，絕不通過項目文件中的 <PackageReference> 項，對 Microsoft.NETCore.App 或 NetStandard.Library 元包進行顯式引用。
• 面向 .NET Core 時，如果需要特定版本的運行時，應使用項目中的 <RuntimeFrameworkVersion> 屬性（例如，1.0.4），而不是引用元包。
  • 例如，如果使用獨立部署且需要 1.0.0 LTS 運行時的特定修補程序版本，可能會發生這種情況。
• 面向 .NET Standard 時，如果需要特定版本的 NetStandard.Library 元包，可以使用 <NetStandardImplicitPackageVersion> 屬性並設置所需版本。
• 請勿在 .NET Framework 項目中顯式添加或更新對 Microsoft.NETCore.App 或 NetStandard.Library 元包的引用。 使用基於 .NET Standard 的 NuGet 包時，如果需要任意版本的 NetStandard.Library，NuGet 可自動安裝該版本。

.NET Core 項目中默認包含的編譯項

隨着遷移到最新 SDK 版本中的 csproj 格式，我們將默認的編譯項和嵌入資源的包含項和排除項移至了 SDK 屬性文件。 這意味着不需要再在項目文件中指定這些項。

執行此操作的主要目的是減少項目文件中的混雜。 SDK 中的默認設置應涵蓋最常見的用例，由此便無需在創建的每個項目中重複這些設置。 這可使項目文件更小，更易於理解和進行手動編輯（如果需要）。

下表顯示了在 SDK 中包含和排除的元素和 globs：

元素	包含 glob	排除 glob	刪除 glob
Compile	**/*.cs（或其他語言擴展名）	**/*.user; **/*.*proj; **/*.sln; **/*.vssscc	不可用
EmbeddedResource	**/*.resx	**/*.user; **/*.*proj; **/*.sln; **/*.vssscc	不可用
None	**/*	**/*.user; **/*.*proj; **/*.sln; **/*.vssscc	**/*.cs; **/*.resx

 備註

排除 glob 始終排除 ./bin 和 ./obj 文件夾，它們分別由 MSBuild 屬性 $(BaseOutputPath)和 $(BaseIntermediateOutputPath) 表示。 總體上來說，所有排除都由 $(DefaultItemExcludes)表示。

如果項目中有 glob，卻又嘗試使用最新的 SDK 生成它，則會收到以下錯誤：

包含重複的編譯項。 默認情況下，.NET SDK 包括項目目錄中的編譯項。 可從項目文件中刪除這些項，或如果想要在項目文件中顯式包括它們，則將“EnableDefaultCompileItems”屬性設爲“false”。

要解決此錯誤，可以刪除與前表中所列項匹配的顯式 Compile 項，也可以將 <EnableDefaultCompileItems> 屬性設置爲 false，如下所示：

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

將此屬性設置爲 false 將禁用隱式包含，並還原到以前 SDK 的行爲，在這種情況下，必須在項目中指定默認 glob。

此更改不會修改其他包含項的主要機制。 但是，如果要指定（例如，指定某些文件通過應用發佈），仍可以使用 csproj 中相應的已知機制來實現（例如，<Content> 元素）。

<EnableDefaultCompileItems> 僅禁用 Compile glob，但不會影響其他 glob（如隱式 Noneglob），這也適用於 *.cs 項。 因此，解決方案資源管理器繼續顯示在項目中作爲 None 項的 *.cs 項。 可按照類似的方式使用 <EnableDefaultNoneItems> 禁用隱式 None glob。

要禁用所有隱式 glob，可將 <EnableDefaultItems> 屬性設置爲 false，如以下示例所示：

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

如何像 MSBuild 一樣查看整個項目

雖然這些 csproj 更改極大地簡化了項目文件，但建議查看完全展開的項目，就像 MSBuild 查看添加了 SDK 及其目標的項目一樣。 使用 dotnet msbuild 命令的 /pp 開關預處理項目，顯示導入的文件、文件源及其在生成中的參與情況，而無需實際生成項目：

dotnet msbuild -pp:fullproject.xml

如果項目有多個目標框架，命令結果應僅側重於框架之一，具體方法爲將相應框架指定爲 MSBuild 屬性：

dotnet msbuild -p:TargetFramework=netcoreapp2.0 -pp:fullproject.xml

新增內容

Sdk 特性

.csproj 文件的根 <Project> 元素具有名爲 Sdk 的新特性。 Sdk 指定項目將使用的 SDK。 如分層文檔中所述，SDK 是一組可生成 .NET Core 代碼的 MSBuild 任務和目標。 .NET Core 工具隨附了三個主要 SDK：

1. ID 爲 Microsoft.NET.Sdk 的 .NET Core SDK
2. ID 爲 Microsoft.NET.Sdk.Web 的 .NET Core Web SDK
3. ID 爲 Microsoft.NET.Sdk.Razor 的 .NET Core Razor 類庫 SDK

需要在 <Project> 元素上將 Sdk 屬性設置爲這兩個 ID 之一，以使用 .NET Core 工具和生成代碼。

PackageReference

<PackageReference> 項元素指定項目中的 NuGet 依賴項。 Include 屬性指定包 ID。

<PackageReference Include="<package-id>" Version="" PrivateAssets="" IncludeAssets="" ExcludeAssets="" />

Version

所需的 Version 屬性指定要還原的包的版本。 此屬性遵循 NuGet 版本控制方案規則。 默認行爲是精確的版本匹配。 例如，指定 Version="1.2.3" 等效於包的 1.2.3 版本的 NuGet 表示法 [1.2.3]。

IncludeAssets、ExcludeAssets 和 PrivateAssets

IncludeAssets 屬性指定應使用 <PackageReference> 指定的包中的哪些資產。 默認情況下，包含所有包資產。

ExcludeAssets 屬性指定不應使用 <PackageReference> 指定的包中的哪些資產。

PrivateAssets 屬性指定應使用 <PackageReference> 指定的包中的哪些資產，但不得將這些資產傳遞到下一個項目。 不存在此屬性時，Analyzers、Build 和 ContentFiles 資產默認爲私有。

 備註

PrivateAssets 等效於 project.json/xproj SuppressParent 元素。

這些屬性可以包含以下一個或多個項，如果列出多個項，則用分號 ; 字符進行分隔：

• Compile - 可對 lib 文件夾內容進行編譯。
• Runtime - 分發運行時文件夾內容。
• ContentFiles - 使用 contentfiles 文件夾的內容。
• Build - 使用生成文件夾中的屬性/目標。
• Native - 將本機資產內容複製到運行時輸出文件夾。
• Analyzers - 使用分析器。

此屬性也可以包含：

• None - 不使用任何資產。
• All - 使用所有資產。

DotNetCliToolReference

<DotNetCliToolReference> 項元素指定用戶想要在項目的上下文中還原的 CLI 工具。 它替換了 project.json 中 tools 節點。

<DotNetCliToolReference Include="<package-id>" Version="" />

Version

Version 指定要還原的包的版本。 此屬性遵循 NuGet 版本控制方案規則。 默認行爲是精確的版本匹配。 例如，指定 Version="1.2.3" 等效於包的 1.2.3 版本的 NuGet 表示法 [1.2.3]。

RuntimeIdentifiers

<RuntimeIdentifiers> 屬性元素可用於指定項目的運行時標識符 (RID) 的列表（以分號分隔）。 RID 允許發佈獨立部署。

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

RuntimeIdentifier

<RuntimeIdentifier> 屬性元素可用於指定項目的唯一運行時標識符 (RID)。 RID 支持發佈獨立部署。

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

如果需要爲多個運行時發佈，請使用 <RuntimeIdentifiers>（複數）。 如果只需要單個運行時，<RuntimeIdentifier> 可以進行較快的生成。

PackageTargetFallback

<PackageTargetFallback> 屬性元素可用於指定要在還原包時使用的一組兼容目標。 旨在允許使用 dotnet TxM（Target x Moniker） 的包來操作那些未聲明 dotnet TxM 的包。 如果項目使用 dotnet TxM，那麼所依賴的所有包也必須有 dotnet TxM，除非將 <PackageTargetFallback> 添加到項目中，以允許非 dotnet 平臺與 dotnet 兼容。

以下示例展示了項目中所有目標的回退：

<PackageTargetFallback>
    $(PackageTargetFallback);portable-net45+win8+wpa81+wp8
</PackageTargetFallback >

以下示例僅指定了 netcoreapp2.1 目標的回退：

<PackageTargetFallback Condition="'$(TargetFramework)'=='netcoreapp2.1'">
    $(PackageTargetFallback);portable-net45+win8+wpa81+wp8
</PackageTargetFallback >

NugetMetadataProperties

遷移到 MSBuild 後，我們已將在打包 NuGet 包時使用的輸入元數據從 project.json 移到 .csproj 文件中。 輸入爲 MSBuild 屬性，因此它們必須轉到 <PropertyGroup> 組中。 下面列出了在使用 dotnet pack 命令或屬於 SDK 的 Pack MSBuild 目標時，用於打包進程的輸入的屬性。

IsPackable

一個指定能否打包項目的布爾值。 默認值爲 true。

PackageVersion

指定生成的包所具有的版本。 接受所有形式的 NuGet 版本字符串。 默認爲值 $(Version)，即項目中 Version 屬性的值。

PackageId

指定生成的包的名稱。 如果未指定，pack 操作將默認使用 AssemblyName 或目錄名稱作爲包的名稱。

Title

明瞭易用的包標題，通常用在 UI 顯示中，如 nuget.org 上和 Visual Studio 中包管理器上的那樣。 如果未指定，則改爲使用包 ID。

Authors

其中名稱以分號分隔的包作者列表，其中名稱與 nuget.org 上的配置文件名稱匹配。這些信息顯示在 nuget.org 上的 NuGet 庫中，並用於交叉引用同一作者的包。

PackageDescription

用於 UI 顯示的包的詳細說明。

Description

程序集的詳細說明。 如果未指定 PackageDescription，則此屬性還可用作程序包的說明。

Copyright

包的版權詳細信息。

PackageRequireLicenseAcceptance

一個布爾值，指定客戶端是否必須提示使用者接受包許可證後纔可安裝包。 默認值爲 false。

PackageLicenseExpression

SPDX 許可證標識符或表達式。 例如 Apache-2.0。

下面是 SPDX 許可證標識符的完整列表。 NuGet.org 在使用許可證類型表達式時只接受 OSI 或 FSF 批准的許可證。

許可證表達式的準確語法如下面的 ABNF 所述。

license-id            = <short form license identifier from https://spdx.org/spdx-specification-21-web-version#h.luq9dgcle9mo>

license-exception-id  = <short form license exception identifier from https://spdx.org/spdx-specification-21-web-version#h.ruv3yl8g6czd>

simple-expression = license-id / license-id”+”

compound-expression =  1*1(simple-expression /
                simple-expression "WITH" license-exception-id /
                compound-expression "AND" compound-expression /
                compound-expression "OR" compound-expression ) /                
                "(" compound-expression ")" )

license-expression =  1*1(simple-expression / compound-expression / UNLICENSED)

 備註

一次只能指定 PackageLicenseExpression、PackageLicenseFile 和 PackageLicenseUrl 中的一個。

PackageLicenseFile

如果使用的許可證沒有分配 SPDX 標識符，或者它是自定義許可證，則它是包中許可證文件的路徑（否則，優先選擇 PackageLicenseExpression）

它替換了 PackageLicenseUrl，也不能與 PackageLicenseExpression 結合使用，並且需要 Visual Studio 15.9.4、.NET SDK 2.1.502 或 2.2.101 或更高版本。

您需要確保許可證文件以顯式添加到項目中的方式被打包，示例用法如下：

<PropertyGroup>
  <PackageLicenseFile>LICENSE.txt</PackageLicenseFile>
</PropertyGroup>
<ItemGroup>
  <None Include="licenses\LICENSE.txt" Pack="true" PackagePath="$(PackageLicenseFile)"/>
</ItemGroup>

PackageLicenseUrl

適用於包的許可證的 URL。 （自 Visual Studio 15.9.4、.NET SDK 2.1.502 和 2.2.101 起已棄用）

PackageIconUrl

64x64 透明背景圖像的 URL，用作 UI 顯示中包的圖標。

PackageReleaseNotes

包的發行說明。

PackageTags

標記的分號分隔列表，這些標記用於指定包。

PackageOutputPath

確定用於已打包的包的輸出路徑。 默認值爲 $(OutputPath)。

IncludeSymbols

此布爾值指示在打包項目時，包是否應創建一個附加的符號包。 此包將具有 .symbols.nupkg 擴展名，並將 PDB 文件連同 DLL 和其他輸出文件一併複製。

IncludeSource

此布爾值指示包進程是否應創建源包。 源包中包含庫的源代碼以及 PDB 文件。 源文件置於生成的包文件中的 src/ProjectName 目錄下。

IsTool

指定是否將所有輸出文件複製到 tools 文件夾，而不是 lib 文件夾。 請注意，這不同於 DotNetCliTool，後者通過在 .csproj 文件中設置 PackageType 進行指定。

RepositoryUrl

指定存儲庫的 URL，該存儲庫是包的源代碼所駐留和/或生成的位置。

RepositoryType

指定存儲庫的類型。 默認值爲“git”。

NoPackageAnalysis

指定 pack 生成包後不運行包分析。

MinClientVersion

指定可安裝此包的最低 NuGet 客戶端版本，並由 nuget.exe 和 Visual Studio 程序包管理器強制實施。

IncludeBuildOutput

此布爾值指定是否應將生成輸出程序集打包到 .nupkg 文件中。

IncludeContentInPack

此布爾值指定是否將含有 Content 類型的任何項自動包含在生成的包中。 默認值爲 true。

BuildOutputTargetFolder

指定放置輸出程序集的文件夾。 輸出程序集（和其他輸出文件）會複製到各自的框架文件夾中。

ContentTargetFolders

此屬性指定放置所有內容文件的默認位置（如果未爲其指定 PackagePath）。 默認值爲“content;contentFiles”。

NuspecFile

用於打包的 .nuspec 文件的相對或絕對路徑。

 備註

如果指定了 .nuspec 文件，則以獨佔方式將其用於打包信息，並且不使用項目中的任何信息。

NuspecBasePath

.nuspec 文件的基路徑。

NuspecProperties

鍵=值對的分號分隔列表。

AssemblyInfoProperties

現在，AssemblyInfo 文件中通常出現的程序集特性，將自動從屬性生成。

PropertiesPerAttribute

每個特性都有一個可控制其內容的屬性，還有一個可以禁用其生成的屬性，如下表所示：

Attribute	Property	要禁用的Property
AssemblyCompanyAttribute	Company	GenerateAssemblyCompanyAttribute
AssemblyConfigurationAttribute	Configuration	GenerateAssemblyConfigurationAttribute
AssemblyCopyrightAttribute	Copyright	GenerateAssemblyCopyrightAttribute
AssemblyDescriptionAttribute	Description	GenerateAssemblyDescriptionAttribute
AssemblyFileVersionAttribute	FileVersion	GenerateAssemblyFileVersionAttribute
AssemblyInformationalVersionAttribute	InformationalVersion	GenerateAssemblyInformationalVersionAttribute
AssemblyProductAttribute	Product	GenerateAssemblyProductAttribute
AssemblyTitleAttribute	AssemblyTitle	GenerateAssemblyTitleAttribute
AssemblyVersionAttribute	AssemblyVersion	GenerateAssemblyVersionAttribute
NeutralResourcesLanguageAttribute	NeutralLanguage	GenerateNeutralResourcesLanguageAttribute

注意：

• AssemblyVersion 和 FileVersion 默認採用 $(Version) 的值而不帶後綴。 例如，如果 $(Version) 爲 1.2.3-beta.4，則值將爲 1.2.3。
• InformationalVersion 默認是 $(Version) 的值。
• 如果InformationalVersion 存在，則它會附加 $(SourceRevisionId)。 可以使用 IncludeSourceRevisionInInformationalVersion 來禁用。
• Copyright 和 Description 屬性也可用於 NuGet 元數據。
• Configuration 與所有生成過程共享，並通過 dotnet 命令的 --configuration 參數進行設置。

GenerateAssemblyInfo

一個布爾值，用於啓用或禁用所有 AssemblyInfo 生成。 默認值爲 true。

GeneratedAssemblyInfoFile

生成的程序集信息文件的路徑。 默認爲 $(IntermediateOutputPath) (obj) 目錄中的某個文件。