project.json reference

Article
10/11/2022

Important

This content is deprecated. Projects should use either the packages.config or PackageReference formats.

NuGet 3.x+

The project.json file maintains a list of packages used in a project, known as a package management format. It supersedes packages.config but is in turn superseded by PackageReference with NuGet 4.0+.

The project.lock.json file (described below) is also used in projects employing project.json.

project.json has the following basic structure, where each of the four top-level objects can have any number of child objects:

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

Dependencies

Lists the NuGet package dependencies of your project in the following form:

"PackageID" : "version_constraint"

For example:

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

The dependencies section is where the NuGet Package Manager dialog adds package dependencies to your project.

The Package id corresponds to the id of the package on nuget.org , the same as the id used in the package manager console: Install-Package Microsoft.NETCore.

When restoring packages, the version constraint of "5.0.0" implies >= 5.0.0. That is, if 5.0.0 is not available on the server but 5.0.1 is, NuGet installs 5.0.1 and warns you about the upgrade. NuGet otherwise picks the lowest possible version on the server matching the constraint.

See Dependency resolution for more details on resolution rules.

Managing dependency assets

Which assets from dependencies flow into the top-level project is controlled by specifying a comma-delimited set of tags in the include and exclude properties of the dependency reference. The tags are listed the table below:

Include/Exclude tag	Affected folders of the target
contentFiles	Content
runtime	Runtime, Resources, and FrameworkAssemblies
compile	lib
build	build (MSBuild props and targets)
native	native
none	No folders
all	All folders

Tags specified with exclude take precedence over those specified with include. For example, include="runtime, compile" exclude="compile" is the same as include="runtime".

For example, to include the build and native folders of a dependency, use the following:

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

To exclude the content and build folders of a dependency, use the following:

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

Frameworks

Lists the frameworks that the project runs on, such as net45, netcoreapp, netstandard.

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

Only a single entry is allowed in the frameworks section. (An exception is project.json files for ASP.NET projects that are build with deprecated DNX tool chain, which allows for multiple targets.)

Runtimes

Lists the operating systems and architectures that your app runs on, such as win10-arm, win8-x64, win8-x86.

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

A package containing a PCL that can run on any runtime doesn't need to specify a runtime. This must also be true of any dependencies, otherwise you must specify runtimes.

Supports

Defines a set of checks for package dependencies. You can define where you expect the PCL or app to run. The definitions are not restrictive, as your code may be able to run elsewhere. But specifying these checks makes NuGet check that all dependencies are satisfied on the listed TxMs. Examples of the values for this are: net46.app, uwp.10.0.app, etc.

This section should be populated automatically when you select an entry in the Portable Class Library targets dialog.

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

Imports

Imports are designed to allow packages that use the dotnet TxM to operate with packages that don't declare a dotnet TxM. If your project is using the dotnet TxM then all the packages you depend on must also have a dotnet TxM, unless you add the following to your project.json to allow non dotnet platforms to be compatible with dotnet:

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

If you are using the dotnet TxM then the PCL project system adds the appropriate imports statement based on the supported targets.

Differences from portable apps and web projects

The project.json file used by NuGet is a subset of that found in ASP.NET Core projects. In ASP.NET Core project.json is used for project metadata, compilation information, and dependencies. When used in other project systems, those three things are split into separate files and project.json contains less information. Notable differences include:

There can only be one framework in the frameworks section.
The file cannot contain dependencies, compilation options, etc. that you see in DNX project.json files. Given that there can only be a single framework it doesn't make sense to enter framework-specific dependencies.
Compilation is handled by MSBuild so compilation options, preprocessor defines, etc. are all part of the MSBuild project file and not project.json.

In NuGet 3+, developers are not expected to manually edit the project.json, as the Package Manager UI in Visual Studio manipulates the content. That said, you can certainly edit the file, but you must build the project to start a package restore or invoke restore in another way. See Package restore.

project.lock.json

The project.lock.json file is generated in the process of restoring the NuGet packages in projects that use project.json. It holds a snapshot of all the information that is generated as NuGet walks the graph of packages and includes the version, contents, and dependencies of all the packages in your project. The build system uses this to choose packages from a global location that are relevant when building the project instead of depending on a local packages folder in the project itself. This results in faster build performance because it's necessary to read only project.lock.json instead of many separate .nuspec files.

project.lock.json is automatically generated on package restore, so it can be omitted from source control by adding it to .gitignore and .tfignore files (see Packages and source control. However, if you include it in source control, the change history shows changes in dependencies resolved over time.

Share via