project.json 参考

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 2026 中的自动迁移

打开包含 project.json 项目的解决方案时，Visual Studio 2026 及更高版本会自动将 project.json 项目迁移到 PackageReference。 迁移在解决方案加载时发生：

1. 在 Visual Studio 2026 或更高版本中打开包含 project.json 项目的解决方案。
2. Visual Studio 会自动检测 project.json 文件并将其迁移到 PackageReference 格式。
3. 若要检查迁移状态，请打开 “输出窗口 ”，然后选择“包管理器”中的“显示输出”。 应会看到“正在迁移 project.json 项目...”等消息后跟每个项目的“迁移成功”。 任何错误都会显示在错误列表中。
4. 原始项目文件和 project.json 文件的备份是在项目目录根目录中的文件夹中创建的 Backup 。
5. 迁移会将项目文件中的所有包依赖项转换为 PackageReference 格式。

Visual Studio 2022 中的手动迁移

对于 Visual Studio 2022 及更早版本，可以使用内置迁移程序：

1. 在 Visual Studio 中加载 project.json 项目。
2. 转到 project.json 项目的解决方案资源管理器，找到依赖项节点。
3. 右键单击并选择 Migrate project.json to 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 属性中指定逗号分隔的标记集。 下表列出了这些标记：

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

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