project.json 参考

2025-02-05

重要

此内容已弃用。项目应使用 PackageReference 格式。了解如何将 project.json 项目迁移到 PackageReference。

NuGet 3.x

project.json 文件维护项目中使用的包列表，称为包管理格式。它取代 packages.config，但反过来又被 nuGet 4.0+ PackageReference 取代。

project.lock.json 文件（如下所述）也用于采用 project.json的项目。

project.json 具有以下基本结构，其中四个顶级对象中的每个对象可以有任意数量的子对象：

{
    "dependencies": {
        "PackageID" : "{version_constraint}"
    },
    "frameworks" : {
        "TxM" : {}
    },
    "runtimes" : {
        "RID": {}
    },
    "supports" : {
        "CompatibilityProfile" : {}
    }
}

将 project.json 迁移到 PackageReference

project.json 和 PackageReference 之间的迁移非常简单。最简单的方法是使用最新的 Visual Studio 2022 Update 14 中的内置迁移程序。

在 Visual Studio 中加载 project.json 项目。
转到 project.json 项目的解决方案资源管理器，找到依赖项节点。
单击 Migrate project.json to PackageReference...！

从 project.json 迁移到 PackageReference

或者，可以使用 dotnet migrate，或者通过从 project.json 文件中获取所有内容并将其替换为等效的 packageReference 语法来手动迁移。

依赖

以以下形式列出项目的 NuGet 包依赖项：

"PackageID" : "version_constraint"

例如：

"dependencies": {
    "Microsoft.NETCore": "5.0.0",
    "System.Runtime.Serialization.Primitives": "4.0.10"
}

dependencies 部分是 NuGet 包管理器对话框向项目添加包依赖项的位置。

包 ID 对应于 nuget.org 上的包的 ID，与包管理器控制台中使用的 ID 相同：Install-Package Microsoft.NETCore。

还原包时，"5.0.0" 的版本约束意味着 >= 5.0.0。也就是说，如果 5.0.0 在服务器上不可用，但 5.0.1 是，NuGet 会安装 5.0.1 并警告你升级。否则，NuGet 会选取与约束匹配的服务器中可能的最低版本。

有关解析规则的更多详细信息，请参阅依赖项解析。

管理依赖项资产

依赖项中的哪些资产流向顶级项目，方法是在依赖项引用的 include 和 exclude 属性中指定逗号分隔的标记集。下表列出了这些标记：

Include/Exclude 标记	目标受影响的文件夹
contentFiles	内容
运行	运行时、资源和 FrameworkAssemblies
编译	自由
建	build （MSBuild 属性和目标）
本地	本地
没有	无文件夹
都	所有文件夹

使用 exclude 指定的标记优先于使用 include指定的标记。例如，include="runtime, compile" exclude="compile" 与 include="runtime"相同。

例如，若要包括依赖项的 build 和 native 文件夹，请使用以下内容：

{
  "dependencies": {
    "packageA": {
      "version": "1.0.0",
      "include": "build, native"
    }
  }
}

若要排除依赖项的 content 和 build 文件夹，请使用以下内容：

{
  "dependencies": {
    "packageA": {
      "version": "1.0.0",
      "exclude": "contentFiles, build"
    }
  }
}

框架

列出项目运行的框架，例如 net45、netcoreapp、netstandard。

"frameworks": {
    "netcore50": {}
    }

frameworks 节中仅允许单个条目。（对于使用弃用的 DNX 工具链生成的 ASP.NET 项目，project.json 文件例外，这允许多个目标。

运行时

列出应用运行的作系统和体系结构，例如 win10-arm、win8-x64、win8-x86。

"runtimes": {
    "win10-arm": { },
    "win10-arm-aot": { },
    "win10-x86": { },
    "win10-x86-aot": { },
    "win10-x64": { },
    "win10-x64-aot": { }
}

包含可在任何运行时上运行的 PCL 的包不需要指定运行时。这还必须是任何依赖项的 true，否则必须指定运行时。

支持

定义包依赖项的一组检查。可以定义希望 PCL 或应用运行的位置。定义没有限制，因为代码可能能够在其他位置运行。但指定这些检查会使 NuGet 检查列出的 TxM 上是否满足所有依赖项。此值的示例包括：net46.app、uwp.10.0.app等。

在“可移植类库目标”对话框中选择一个条目时，应自动填充此部分。

"supports": {
    "net46.app": {},
    "uwp.10.0.app": {}
}

进口

导入旨在允许使用 dotnet TxM 的包使用不声明 dotnet TxM 的包进行作。如果项目使用的是 dotnet TxM，则依赖的所有包还必须具有 dotnet TxM，除非将以下内容添加到 project.json，以允许非 dotnet 平台与 dotnet兼容：

"frameworks": {
    "dotnet": { "imports" : "portable-net45+win81" }
}

如果使用 dotnet TxM，则 PCL 项目系统会根据支持的目标添加相应的 imports 语句。

与可移植应用和 Web 项目的差异

NuGet 使用的 project.json 文件是在 ASP.NET Core 项目中找到的子集。在 ASP.NET Core project.json 中，用于项目元数据、编译信息和依赖项。在其他项目系统中使用时，这三项内容拆分为单独的文件，project.json 包含较少的信息。显著差异包括：

frameworks 部分中只能有一个框架。
该文件不能包含 DNX project.json 文件中看到的依赖项、编译选项等。由于只能有一个框架，因此输入特定于框架的依赖项没有意义。
编译由 MSBuild 处理，因此编译选项、预处理器定义等都是 MSBuild 项目文件的一部分，而不是 project.json。

在 NuGet 3+ 中，开发人员不应手动编辑 project.json，因为 Visual Studio 中的包管理器 UI 会作内容。也就是说，你当然可以编辑该文件，但必须生成项目以启动包还原或以其他方式调用还原。请参阅包还原。

project.lock.json

在还原使用 project.json的项目中的 NuGet 包的过程中，将生成 project.lock.json 文件。它保存在 NuGet 中演练包图并包括项目中所有包的版本、内容和依赖项时生成的所有信息的快照。生成系统使用此函数从生成项目时相关的全局位置选择包，而不是依赖于项目本身中的本地包文件夹。这会导致生成性能更快，因为必须仅读取 project.lock.json 而不是许多单独的 .nuspec 文件。

包还原时自动生成 project.lock.json，因此可以通过将其添加到 .gitignore 和 .tfignore 文件（请参阅包和源代码管理）来省略源代码管理。但是，如果将其包含在源代码管理中，更改历史记录会显示随时间推移解析的依赖项更改。