適用於 .NET Core 之 csproj 格式的新增項目Additions to the csproj format for .NET Core

本文件概述從 project.json 改為使用 csprojMSBuild 時,新增至專案檔的變更。This document outlines the changes that were added to the project files as part of the move from project.json to csproj and MSBuild. 如需一般專案檔語法以及參考的詳細資訊,請參閱 MSBuild 專案檔文件。For more information about general project file syntax and reference, see the MSBuild project file documentation.

隱含套件參考Implicit package references

會根據您專案檔之 <TargetFramework><TargetFrameworks> 屬性中指定的目標架構來隱含參考中繼套件。Metapackages are implicitly referenced based on the target framework(s) specified in the <TargetFramework> or <TargetFrameworks> property of your project file. 如果指定了 <TargetFramework>,則會忽略 <TargetFrameworks>,與順序無關。<TargetFrameworks> is ignored if <TargetFramework> is specified, independent of order. 如需詳細資訊,請參閱套件、中繼套件和架構For more information, see Packages, metapackages and frameworks.

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

建議Recommendations

由於會隱含參考 Microsoft.NETCore.AppNETStandard.Library 中繼套件,因此建議使用下列最佳做法:Since Microsoft.NETCore.App or NETStandard.Library metapackages are implicitly referenced, the following are our recommended best practices:

  • 以 .NET Core 或 .NET Standard 為目標時,絕不透過專案檔中的 <PackageReference> 項目明確參考 Microsoft.NETCore.AppNETStandard.Library 中繼套件。When targeting .NET Core or .NET Standard, never have an explicit reference to the Microsoft.NETCore.App or NETStandard.Library metapackages via a <PackageReference> item in your project file.
  • 如果您以 .NET Core 為目標時需要特定版本的執行階段,您應該使用專案中的 <RuntimeFrameworkVersion> 屬性 (例如 1.0.4),而不是參考中繼套件。If you need a specific version of the runtime when targeting .NET Core, you should use the <RuntimeFrameworkVersion> property in your project (for example, 1.0.4) instead of referencing the metapackage.
    • 如果您使用獨立性部署,並需要 1.0.0 LTS 執行階段的特定更新程式版本,就可能會發生此情況。This might happen if you are using self-contained deployments and you need a specific patch version of 1.0.0 LTS runtime, for example.
  • 如果您以 .NET Standard 為目標時需要特定版本的 NETStandard.Library 中繼套件,您可以使用 <NetStandardImplicitPackageVersion> 屬性並設定所需的版本。If you need a specific version of the NETStandard.Library metapackage when targeting .NET Standard, you can use the <NetStandardImplicitPackageVersion> property and set the version you need.
  • 請不要在 .NET Framework 專案中明確地新增或更新 Microsoft.NETCore.AppNETStandard.Library 中繼套件的參考。Don't explicitly add or update references to either the Microsoft.NETCore.App or NETStandard.Library metapackage in .NET Framework projects. 如果使用 .NET Standard 型 NuGet 套件時需要任何版本的 NETStandard.Library,NuGet 會自動安裝該版本。If any version of NETStandard.Library is needed when using a .NET Standard-based NuGet package, NuGet automatically installs that version.

某些套件參考的隱含版本Implicit version for some package references

<PackageReference> 的大部分使用方式都需要設定 Version 屬性來指定要使用的 NuGet 套件版本。Most usages of <PackageReference> require setting the Version attribute to specify the NuGet package version to be used. 不過,使用 .NET Core 2.1 或 2.2 並參考 Microsoft.AspNetCore.AppMicrosoft.AspNetCore.All 時,該屬性是不必要的。When using .NET Core 2.1 or 2.2 and referencing Microsoft.AspNetCore.App or Microsoft.AspNetCore.All, however, the attribute is unnecessary. .NET Core SDK 可以自動針對這些套件選取應使用的版本。The .NET Core SDK can automatically select the version of these packages that should be used.

建議Recommendation

參考 Microsoft.AspNetCore.AppMicrosoft.AspNetCore.All 套件時,請不要指定其版本。When referencing the Microsoft.AspNetCore.App or Microsoft.AspNetCore.All packages, do not specify their version. 若指定版本,SDK 可能會產生警告 NETSDK1071。If a version is specified, the SDK may produce warning NETSDK1071. 若要修正此警告,請移除套件版本,如下列範例所示:To fix this warning, remove the package version like in the following example:

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

已知問題:.NET Core 2.1 SDK 僅在專案同時使用 Microsoft.NET.Sdk.Web 時才支援此語法。Known issue: the .NET Core 2.1 SDK only supported this syntax when the project also uses Microsoft.NET.Sdk.Web. 此問題已在 .NET Core 2.2 SDK 中解決。This is resolved in the .NET Core 2.2 SDK.

這些針對 ASP.NET Core 中繼套件的參考,具有和大部分的一般 NuGet 套件些微不同的行為。These references to ASP.NET Core metapackages have a slightly different behavior from most normal NuGet packages. 使用這些中繼套件之應用程式的架構相依部署會自動利用 ASP.NET Core 共用架構的優點。Framework-dependent deployments of applications that use these metapackages automatically take advantage of the ASP.NET Core shared framework. 當您使用中繼套件時,系統不會搭配應用程式部署來自所參考之 ASP.NET Core NuGet 套件的任何資產;ASP.NET Core 共用架構會包含這些資產。When you use the metapackages, no assets from the referenced ASP.NET Core NuGet packages are deployed with the application—the ASP.NET Core shared framework contains these assets. 共用架構中的資產會針對目標平台最佳化,以改善應用程式啟動時間。The assets in the shared framework are optimized for the target platform to improve application startup time. 如需共用架構的詳細資訊,請參閱 .NET Core 發佈封裝For more information about shared framework, see .NET Core distribution packaging.

如果「已指定」某個版本,系統會將它視為 ASP.NET Core 共用架構適用於架構相依部署的「最小」版本,以及獨立式部署的「確切」版本。If a version is specified, it's treated as the minimum version of ASP.NET Core shared framework for framework-dependent deployments and as an exact version for self-contained deployments. 這可能會導致下列結果:This can have the following consequences:

  • 如果安裝在伺服器上的 ASP.NET Core 版本小於 PackageReference 上所指定的版本,.NET Core 處理序將無法啟動。If the version of ASP.NET Core installed on the server is less than the version specified on the PackageReference, the .NET Core process fails to launch. 針對中繼套件的更新通常會在於裝載環境 (例如 Azure) 中推出之前,先在 NuGet.org 上提供使用。Updates to the metapackage are often available on NuGet.org before updates have been made available in hosting environments such as Azure. 將 PackageReference 上的版本更新為 ASP.NET Core 的版本,可能會導致已部署的應用程式發生失敗。Updating the version on the PackageReference to ASP.NET Core could cause a deployed application to fail.
  • 如果應用程式是以獨立式部署的形式部署,該應用程式可能不會包含針對 .NET Core 的最新安全性更新。If the application is deployed as a self-contained deployment, the application may not contain the latest security updates to .NET Core. 沒有指定版本時,獨立式部署中的 SDK 可以自動包含最新版本的 ASP.NET Core。When a version isn't specified, the SDK can automatically include the newest version of ASP.NET Core in the self-contained deployment.

.NET Core 專案中包含預設編譯Default compilation includes in .NET Core projects

隨著改為使用最新 SDK 版本中的 csproj 格式,編譯項目的預設包含項目和排除項目以及內嵌資源都已移至 SDK 屬性檔。With the move to the csproj format in the latest SDK versions, we've moved the default includes and excludes for compile items and embedded resources to the SDK properties files. 這表示您不再需要於專案檔中指定這些項目。This means that you no longer need to specify these items in your project file.

這樣做的主要原因是為了讓專案檔更為簡潔。The main reason for doing this is to reduce the clutter in your project file. SDK 中的預設值應該涵蓋最常見的使用案例,而不需要在每個建立的專案中重複這些項目。The defaults that are present in the SDK should cover most common use cases, so there is no need to repeat them in every project that you create. 這會產生較小的專案檔,而更容易了解及視需要手動編輯。This leads to smaller project files that are much easier to understand as well as edit by hand, if needed.

下表顯示 SDK 中會同時包含及排除的元素與 Glob (英文)The following table shows which element and which globs are both included and excluded in the SDK:

元素Element 包含 GlobInclude glob 排除 GlobExclude glob 移除 GlobRemove glob
編譯Compile **/*.cs (或其他語言副檔名)**/*.cs (or other language extensions) **/*.user; **/*.*proj; **/*.sln; **/*.vssscc**/*.user; **/*.*proj; **/*.sln; **/*.vssscc N/AN/A
內嵌資源EmbeddedResource **/*.resx**/*.resx **/*.user; **/*.*proj; **/*.sln; **/*.vssscc**/*.user; **/*.*proj; **/*.sln; **/*.vssscc N/AN/A
None **/* **/*.user; **/*.*proj; **/*.sln; **/*.vssscc**/*.user; **/*.*proj; **/*.sln; **/*.vssscc **/*.cs、**/*.resx**/*.cs; **/*.resx

注意

排除 Glob 一律會排除 ./bin./obj 資料夾,其分別由 $(BaseOutputPath)$(BaseIntermediateOutputPath) MSBuild 屬性所代表。Exclude glob always excludes the ./bin and ./obj folders, which are represented by the $(BaseOutputPath) and $(BaseIntermediateOutputPath) MSBuild properties, respectively. 整體而言,所有排除都是由 $(DefaultItemExcludes) 所代表。As a whole, all excludes are represented by $(DefaultItemExcludes).

如果您的專案有 Glob,而且您嘗試使用最新的 SDK 建置專案,您會收到下列錯誤:If you have globs in your project and you try to build it using the newest SDK, you'll get the following error:

包含了重複的編譯項目。Duplicate Compile items were included. .NET SDK 預設會包含您專案目錄中的編譯項目。The .NET SDK includes Compile items from your project directory by default. 您可以從專案檔中移除這些項目;如果您想要在專案檔中明確包含這些項目,您可以將 'EnableDefaultCompileItems' 屬性設定為 'false'。You can either remove these items from your project file, or set the 'EnableDefaultCompileItems' property to 'false' if you want to explicitly include them in your project file.

若要解決此錯誤,您可以明確移除符合上表所列項目的 Compile 項目,或將 <EnableDefaultCompileItems> 屬性設定為 false,如下所示:In order to get around this error, you can either remove the explicit Compile items that match the ones listed on the previous table, or you can set the <EnableDefaultCompileItems> property to false, like this:

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

將此屬性設定為 false 會停用隱含包含項目,還原成必須在專案中指定預設 Glob 的舊版 SDK 行為。Setting this property to false will disable implicit inclusion, reverting to the behavior of previous SDKs where you had to specify the default globs in your project.

這項變更不會修改其他包含項目的主要機制。This change does not modify the main mechanics of other includes. 不過,如果您想要指定某些檔案由應用程式發行,您仍然可以使用 csproj 中已知的機制來執行這項作業 (例如 <Content> 項目)。However, if you wish to specify, for example, some files to get published with your app, you can still use the known mechanisms in csproj for that (for example, the <Content> element).

<EnableDefaultCompileItems> 只會停用 Compile GLOB,而不會影響隱含 None GLOB 這類其他 GLOB,後者也會套用至 *.cs 項目。<EnableDefaultCompileItems> only disables Compile globs but doesn't affect other globs, like the implicit None glob, which also applies to *.cs items. 因此,方案總管會繼續將 *.cs 項目顯示為包含為 None 項目之專案的一部分。Because of that, Solution Explorer will continue show *.cs items as part of the project, included as None items. 透過類似的方式,您可以將 <EnableDefaultNoneItems> 設為 False 以停用隱含 None GLOB,如下所示:In a similar way, you can set <EnableDefaultNoneItems> to false to disable the implicit None glob, like this:

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

若要停用所有隱含 GLOB,您可以將 <EnableDefaultItems> 屬性設定為 false,如下列範例所示:To disable all implicit globs, you can set the <EnableDefaultItems> property to false as in the following example:

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

如何以 MSBuild 查看專案的方式查看整個專案How to see the whole project as MSBuild sees it

雖然那些 csproj 變更可大幅簡化專案檔,在包括 SDK 和其目標之後,您可能會想要以 MSBuild 查看專案的方式查看完全展開的專案。While those csproj changes greatly simplify project files, you might want to see the fully expanded project as MSBuild sees it once the SDK and its targets are included. 使用 dotnet msbuild 命令的 /pp 切換 對專案進行前置處理,它可以在不需要實際建置專案的情況下,顯示匯入的檔案、檔案的來源,以及該檔案對組建的貢獻:Preprocess the project with the /pp switch of the dotnet msbuild command, which shows which files are imported, their sources, and their contributions to the build without actually building the project:

dotnet msbuild -pp:fullproject.xml

如果專案具有多個目標架構,系統應該會透過將它們的其中之一指定為 MSBuild 屬性,來使命令的結果專注於該目標架構:If the project has multiple target frameworks, the results of the command should be focused on only one of them by specifying it as an MSBuild property:

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

新增項目Additions

Sdk 屬性Sdk attribute

.csproj 檔案的根 <Project> 元素有一個新屬性,稱為 SdkThe root <Project> element of the .csproj file has a new attribute called Sdk. Sdk 會指定專案將使用的 SDK。Sdk specifies which SDK will be used by the project. 分層文件所述,SDK 是可建置 .NET Core 程式碼的一組 MSBuild 工作目標The SDK, as the layering document describes, is a set of MSBuild tasks and targets that can build .NET Core code. 使用.NET Core 3.0 Preview 時,隨附 .NET Core 工具的三個主要 SDK 和其他兩個 SDK:We ship three main SDKs with the .NET Core tools and an additional two SDKs when using .NET Core 3.0 Preview:

  1. 識別碼為 Microsoft.NET.Sdk 的 .NET Core SDKThe .NET Core SDK with the ID of Microsoft.NET.Sdk
  2. 識別碼為 Microsoft.NET.Sdk.Web 的 .NET Core Web SDKThe .NET Core web SDK with the ID of Microsoft.NET.Sdk.Web
  3. 識別碼為 Microsoft.NET.Sdk.Razor 的 .NET Core Razor 類別庫 SDKThe .NET Core Razor Class Library SDK with the ID of Microsoft.NET.Sdk.Razor
  4. .NET Core 的背景工作服務識別碼為 Microsoft.NET.Sdk.Worker (.NET Core 3.0 Preview)The .NET Core Worker Service with the ID of Microsoft.NET.Sdk.Worker (.NET Core 3.0 Preview)
  5. .NET Core WinForms 和 WPF 的識別碼為 Microsoft.NET.Sdk.WindowsDesktop (.NET Core 3.0 Preview)The .NET Core WinForms and WPF with the ID of Microsoft.NET.Sdk.WindowsDesktop (.NET Core 3.0 Preview)

您必須在 <Project> 項目中將 Sdk 屬性設定為上述其中一個識別碼,才能使用 .NET Core 工具並建置您的程式碼。You need to have the Sdk attribute set to one of those IDs on the <Project> element in order to use the .NET Core tools and build your code.

PackageReferencePackageReference

<PackageReference> 項目元素會在專案中指定 NuGet 相依性A <PackageReference> item element specifies a NuGet dependency in the project. Include 屬性會指定套件識別碼。The Include attribute specifies the package ID.

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

版本Version

必要的 Version 屬性會指定要還原的套件版本。The required Version attribute specifies the version of the package to restore. 該屬性採用 NuGet 版本控制配置的規則。The attribute respects the rules of the NuGet versioning scheme. 預設行為是確切的版本相符。The default behavior is an exact version match. 例如,指定 Version="1.2.3" 相當於 NuGet 標記法 [1.2.3],表示確切的套件版本 1.2.3。For example, specifying Version="1.2.3" is equivalent to NuGet notation [1.2.3] for the exact 1.2.3 version of the package.

IncludeAssets、ExcludeAssets 和 PrivateAssetsIncludeAssets, ExcludeAssets and PrivateAssets

IncludeAssets 屬性指定應取用哪些資產 (屬於由 <PackageReference> 所指定的套件)。IncludeAssets attribute specifies which assets belonging to the package specified by <PackageReference> should be consumed. 根據預設,所有套件資產均包含在內。By default, all package assets are included.

ExcludeAssets 屬性指定不應取用哪些資產 (屬於由 <PackageReference> 所指定的套件)。ExcludeAssets attribute specifies which assets belonging to the package specified by <PackageReference> should not be consumed.

PrivateAssets 屬性指定應取用哪些資產 (屬於由 <PackageReference> 所指定但未流向下一個專案的套件)。PrivateAssets attribute specifies which assets belonging to the package specified by <PackageReference> should be consumed but not flow to the next project. 根據預設,當此屬性不存在時,AnalyzersBuildContentFiles 會是私人資產。The Analyzers, Build and ContentFiles assets are private by default when this attribute is not present.

注意

PrivateAssets 相當於 project.json/xproj SuppressParent 項目。PrivateAssets is equivalent to the project.json/xproj SuppressParent element.

這些屬性可包含下列一或多個項目,若列出不只一個,則以分號 ; 字元分隔:These attributes can contain one or more of the following items, separated by the semicolon ; character if more than one is listed:

  • Compile – lib 資料夾的內容可供編譯。Compile – the contents of the lib folder are available to compile against.
  • Runtime – 會散發 runtime 資料夾的內容。Runtime – the contents of the runtime folder are distributed.
  • ContentFiles - 會使用 contentfiles 資料夾的內容。ContentFiles – the contents of the contentfiles folder are used.
  • Build – 會使用組建資料夾中的屬性/目標。Build – the props/targets in the build folder are used.
  • Native – 原生資產內容會複製到執行階段輸出資料夾。Native – the contents from native assets are copied to the output folder for runtime.
  • Analyzers – 會使用分析器。Analyzers – the analyzers are used.

另外,該屬性也可以包含︰Alternatively, the attribute can contain:

  • None – 未使用任何資產。None – none of the assets are used.
  • All – 會使用所有資產。All – all assets are used.

DotNetCliToolReferenceDotNetCliToolReference

<DotNetCliToolReference> 項目元素指定使用者想要在專案內容中還原的 CLI 工具。A <DotNetCliToolReference> item element specifies the CLI tool that the user wants to restore in the context of the project. 它會取代 project.json 中的 tools 節點。It's a replacement for the tools node in project.json.

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

版本Version

Version 指定要還原的套件版本。Version specifies the version of the package to restore. 該屬性採用 NuGet 版本控制配置的規則。The attribute respects the rules of the NuGet versioning scheme. 預設行為是確切的版本相符。The default behavior is an exact version match. 例如,指定 Version="1.2.3" 相當於 NuGet 標記法 [1.2.3],表示確切的套件版本 1.2.3。For example, specifying Version="1.2.3" is equivalent to NuGet notation [1.2.3] for the exact 1.2.3 version of the package.

RuntimeIdentifiersRuntimeIdentifiers

<RuntimeIdentifiers> 屬性元素可讓您針對專案指定以分號分隔的執行階段識別碼 (RID) 清單。The <RuntimeIdentifiers> property element lets you specify a semicolon-delimited list of Runtime Identifiers (RIDs) for the project. RID 允許發行獨立部署。RIDs enable publishing self-contained deployments.

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

RuntimeIdentifierRuntimeIdentifier

<RuntimeIdentifier> 屬性元素可讓您針對專案只指定一個執行階段識別碼 (RID)The <RuntimeIdentifier> property element allows you to specify only one Runtime Identifier (RID) for the project. RID 允許發佈獨立式部署。The RID enables publishing a self-contained deployment.

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

如果您需要發佈以供多個執行階段使用,請改用 <RuntimeIdentifiers> (複數)。Use <RuntimeIdentifiers> (plural) instead if you need to publish for multiple runtimes. 只需要單一執行階段時,<RuntimeIdentifier> 可提供更快速的組建。<RuntimeIdentifier> can provide faster builds when only a single runtime is required.

PackageTargetFallbackPackageTargetFallback

<PackageTargetFallback> 屬性元素可讓您指定一組要在還原套件時使用的相容目標。The <PackageTargetFallback> property element allows you to specify a set of compatible targets to be used when restoring packages. 其設計目的是為了讓使用 dotnet TxM (目標 x Moniker) 的套件能和未宣告 dotnet TxM 的套件一起運作。It's designed to allow packages that use the dotnet TxM (Target x Moniker) to operate with packages that don't declare a dotnet TxM. 如果您的專案使用 dotnet TxM,除非您將 <PackageTargetFallback> 新增至專案,以讓非 dotnet 平台變成能與 dotnet 相容,否則其相依的所有套件也必須要有 dotnet TxM。If your project uses the dotnet TxM, then all the packages it depends on must also have a dotnet TxM, unless you add the <PackageTargetFallback> to your project in order to allow non-dotnet platforms to be compatible with dotnet.

下列範例可為專案中的所有目標提供後援:The following example provides the fallbacks for all targets in your project:

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

下列範例只會為 netcoreapp2.1 目標指定後援︰The following example specifies the fallbacks only for the netcoreapp2.1 target:

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

NuGet 中繼資料屬性NuGet metadata properties

隨著改為使用 MSBuild,我們已經將封裝 NuGet 套件時使用的輸入中繼資料從 project.json 移動到 .csproj 檔。With the move to MSBuild, we have moved the input metadata that is used when packing a NuGet package from project.json to .csproj files. 此輸入是 MSBuild 屬性,因此必須移至 <PropertyGroup> 群組。The inputs are MSBuild properties so they have to go within a <PropertyGroup> group. 使用 dotnet pack 命令或屬於 SDK 一部分的 Pack MSBuild 目標時,會將下列的屬性清單當成封裝處理序的輸入使用。The following is the list of properties that are used as inputs to the packing process when using the dotnet pack command or the Pack MSBuild target that is part of the SDK.

IsPackableIsPackable

布林值,指定是否可封裝專案。A Boolean value that specifies whether the project can be packed. 預設值為 trueThe default value is true.

PackageVersionPackageVersion

指定所產生之套件的版本。Specifies the version that the resulting package will have. 接受所有形式的 NuGet 版本字串。Accepts all forms of NuGet version string. 預設為 $(Version) 的值,也就是專案中的屬性 VersionDefault is the value of $(Version), that is, of the property Version in the project.

PackageIdPackageId

指定所產生之套件的名稱。Specifies the name for the resulting package. 如果未指定,pack 作業會預設為使用 AssemblyName 或目錄名稱作為套件的名稱。If not specified, the pack operation will default to using the AssemblyName or directory name as the name of the package.

標題Title

套件的易記標題,通常會用於 UI 顯示,以及 nuget.org 和 Visual Studio 套件管理員中。A human-friendly title of the package, typically used in UI displays as on nuget.org and the Package Manager in Visual Studio. 如果未指定,則會改用套件識別碼。If not specified, the package ID is used instead.

作者Authors

以分號分隔的套件作者清單,與 nuget.org 上的設定檔名稱相符。這些名稱會顯示在 nuget.org 的 NuGet 組件庫中,並用來交互參照相同作者的其他套件。A semicolon-separated list of packages authors, matching the profile names on nuget.org. These are displayed in the NuGet Gallery on nuget.org and are used to cross-reference packages by the same authors.

PackageDescriptionPackageDescription

UI 顯示中的套件詳細描述。A long description of the package for UI display.

說明Description

組件的完整描述。A long description for the assembly. 如果未指定 PackageDescription,則此屬性也會用來作為套件的描述。If PackageDescription is not specified then this property is also used as the description of the package.

套件的著作權詳細資料。Copyright details for the package.

PackageRequireLicenseAcceptancePackageRequireLicenseAcceptance

布林值,指定在安裝套件時,用戶端是否必須提示取用者接受套件授權。A Boolean value that specifies whether the client must prompt the consumer to accept the package license before installing the package. 預設為 falseThe default is false.

PackageLicenseExpressionPackageLicenseExpression

SPDX 授權識別碼 (英文) 或運算式。An SPDX license identifier or expression. 例如,Apache-2.0For example, Apache-2.0.

此處有 SPDX 授權識別碼的完整清單。Here is the complete list of SPDX license identifiers. 在使用授權類型運算式時,NuGet.org 只接受 OSI 或 FSF 核准的授權。NuGet.org accepts only OSI or FSF approved licenses when using license type expression.

授權運算式的確切語法使用 ABNF,如下所述。The exact syntax of the license expressions is described below in 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)

注意

一次只能指定 PackageLicenseExpressionPackageLicenseFilePackageLicenseUrl 其中之一。Only one of PackageLicenseExpression, PackageLicenseFile and PackageLicenseUrl can be specified at a time.

PackageLicenseFilePackageLicenseFile

若您使用未獲指派 SPDX 識別碼的授權,或授權是自訂授權,這會是套件內授權檔案的路徑 (否則會優先使用 PackageLicenseExpression)Path to a license file within the package if you are using a license that hasn’t been assigned an SPDX identifier, or it is a custom license (Otherwise PackageLicenseExpression is prefered)

這會取代 PackageLicenseUrl,不能與 PackageLicenseExpression 合併,並需要 Visual Studio 15.9.4、.NET SDK 2.1.502 或 2.2.101 或更新版本。Replaces PackageLicenseUrl, can't be combined with PackageLicenseExpression and requires Visual Studio 15.9.4, .NET SDK 2.1.502 or 2.2.101, or newer.

您必須明確地將授權檔案新增到專案,以確保其封裝妥當,使用範例:You will need to ensure the license file is packed by adding it explicitly to the project, example usage:

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

PackageLicenseUrlPackageLicenseUrl

適用於套件的授權 URL。An URL to the license that is applicable to the package. (自 Visual Studio 15.9.4、.NET SDK 2.1.502 及 2.2.101 起淘汰)(deprecated since Visual Studio 15.9.4, .NET SDK 2.1.502 and 2.2.101)

PackageIconUrlPackageIconUrl

具有透明背景之 64x64 映像的 URL,該映像會用作套件在 UI 顯示中的圖示。A URL for a 64x64 image with transparent background to use as the icon for the package in UI display.

PackageReleaseNotesPackageReleaseNotes

套件的版本資訊。Release notes for the package.

PackageTagsPackageTags

以分號分隔的標記清單,用以指定套件。A semicolon-delimited list of tags that designates the package.

PackageOutputPathPackageOutputPath

決定要置放所封裝之套件的輸出路徑。Determines the output path in which the packed package will be dropped. 預設為 $(OutputPath)Default is $(OutputPath).

IncludeSymbolsIncludeSymbols

此布林值會指出在封裝專案時,套件是否應該建立額外的符號套件。This Boolean value indicates whether the package should create an additional symbols package when the project is packed. 符號套件的格式由 SymbolPackageFormat 屬性控制。The symbols package's format is controlled by the SymbolPackageFormat property.

SymbolPackageFormatSymbolPackageFormat

指定符號套件的格式。Specifies the format of the symbols package. 如果是 "symbols.nupkg",將使用包含 PDB、DLL 和其他輸出檔案的 .symbols.nupkg 副檔名建立舊版符號套件。If "symbols.nupkg", a legacy symbols package will be created with a .symbols.nupkg extension containing PDBs, DLLs, and other output files. 如果是 "snupkg",將建立一個包含可攜式 PDB 的 snupkg 符號套件。If "snupkg", a snupkg symbol package will be created containing the portable PDBs. 預設值為 "symbols.nupkg"。Default is "symbols.nupkg".

IncludeSourceIncludeSource

此布林值會指出封裝處理序是否應該建立來源套件。This Boolean value indicates whether the pack process should create a source package. 來源套件包含程式庫的原始程式碼及 PDB 檔案。The source package contains the library's source code as well as PDB files. 原始程式檔會放在所產生之套件檔案中的 src/ProjectName 目錄底下。Source files are put under the src/ProjectName directory in the resulting package file.

IsToolIsTool

指定是否要將所有輸出檔複製到 tools 資料夾,而不是 lib 資料夾。Specifies whether all output files are copied to the tools folder instead of the lib folder. 請注意,這與 DotNetCliTool 不同,該項目是藉由在 .csproj 檔案中設定 PackageType 所指定。Note that this is different from a DotNetCliTool which is specified by setting the PackageType in the .csproj file.

RepositoryUrlRepositoryUrl

指定存放庫的 URL,此存放庫是套件原始程式碼的所在位置及 (或) 正在建置的來源位置。Specifies the URL for the repository where the source code for the package resides and/or from which it's being built.

RepositoryTypeRepositoryType

指定存放庫的類型。Specifies the type of the repository. 預設值為 "git"。Default is "git".

NoPackageAnalysisNoPackageAnalysis

指定封裝不應該在建置套件之後執行套件分析。Specifies that pack should not run package analysis after building the package.

MinClientVersionMinClientVersion

指定可安裝此套件的最低 NuGet 用戶端版本,此作業是由 nuget.exe 和 Visual Studio 套件管理員強制執行。Specifies the minimum version of the NuGet client that can install this package, enforced by nuget.exe and the Visual Studio Package Manager.

IncludeBuildOutputIncludeBuildOutput

此布林值會指定是否應該將建置輸出組建封裝成 .nupkg 檔案。This Boolean values specifies whether the build output assemblies should be packed into the .nupkg file or not.

IncludeContentInPackIncludeContentInPack

此布林值會指定是否有任何類型為 Content 的項目會自動包含於所產生的套件中。This Boolean value specifies whether any items that have a type of Content will be included in the resulting package automatically. 預設為 trueThe default is true.

BuildOutputTargetFolderBuildOutputTargetFolder

指定要放置輸出組件的資料夾。Specifies the folder where to place the output assemblies. 輸出組件 (及其他輸出檔) 會複製到其相關的架構資料夾中。The output assemblies (and other output files) are copied into their respective framework folders.

ContentTargetFoldersContentTargetFolders

如果未指定 PackagePath,此屬性會指定所有內容檔案應移至的預設位置。This property specifies the default location of where all the content files should go if PackagePath is not specified for them. 預設值為 "content;contentFiles"。The default value is "content;contentFiles".

NuspecFileNuspecFile

正用於封裝之 .nuspec 檔案的相對或絕對路徑。Relative or absolute path to the .nuspec file being used for packing.

注意

如果指定 .nuspec 檔案,則會單獨使用此檔案來封裝資訊,而不會使用專案中的任何資訊。If the .nuspec file is specified, it's used exclusively for packaging information and any information in the projects is not used.

NuspecBasePathNuspecBasePath

.nuspec 檔案的基底路徑。Base path for the .nuspec file.

NuspecPropertiesNuspecProperties

以分號分隔的索引鍵=值組清單。Semicolon separated list of key=value pairs.

AssemblyInfo 屬性AssemblyInfo properties

組件屬性,通常存在於 AssemblyInfo 檔案,現在會自動從屬性產生。Assembly attributes that were typically present in an AssemblyInfo file are now automatically generated from properties.

每個屬性 (Attribute) 的屬性 (Property)Properties per attribute

每個屬性 (Attribute) 有一個屬性 (Property),控制其內容,另一個則是停用其產生,如下表所示:Each attribute has a property that control its content and another to disable its generation as shown in the following table:

屬性Attribute 屬性Property 要停用的屬性Property to disable
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

附註:Notes:

  • AssemblyVersionFileVersion 預設為採用沒有後置詞的 $(Version) 值。AssemblyVersion and FileVersion default is to take the value of $(Version) without suffix. 例如,如果 $(Version)1.2.3-beta.4,則此值會是 1.2.3For example, if $(Version) is 1.2.3-beta.4, then the value would be 1.2.3.
  • InformationalVersion 預設為 $(Version) 的值。InformationalVersion defaults to the value of $(Version).
  • 如果有屬性,則 InformationalVersion 會附加 $(SourceRevisionId)InformationalVersion has $(SourceRevisionId) appended if the property is present. 可以使用 IncludeSourceRevisionInInformationalVersion 來加以停用。It can be disabled using IncludeSourceRevisionInInformationalVersion.
  • 也會針對 NuGet 中繼資料使用 CopyrightDescription 屬性。Copyright and Description properties are also used for NuGet metadata.
  • Configuration 與所有建置程序共用,並且是透過 dotnet 命令的 --configuration 參數來設定。Configuration is shared with all the build process and set via the --configuration parameter of dotnet commands.

GenerateAssemblyInfoGenerateAssemblyInfo

布林值,啟用或停用所有 AssemblyInfo 產生。A Boolean that enable or disable all the AssemblyInfo generation. 預設值為 trueThe default value is true.

GeneratedAssemblyInfoFileGeneratedAssemblyInfoFile

產生組件資訊檔案的路徑。The path of the generated assembly info file. 預設為 $(IntermediateOutputPath) (obj) 目錄中的檔案。Default to a file in the $(IntermediateOutputPath) (obj) directory.