*This document is now out of date. See https://docs.microsoft.com/dotnet/articles/core/tools/project-json

Schema

http://json.schemastore.org/project

Dependencies

Dependencies section lists all the dependencies of your application. These are defined by name and version, the runtime loaders will determine what should be loaded. NuGet package, source code, etc.

{
  "dependencies": {
    "Microsoft.AspNet.ConfigurationModel": "0.1-alpha-*",
    "SomeProject": ""
  }
}

More features to come here with different types of dependencies and it will likely look like this:

{
  "dependencies": {
    "Microsoft.AspNet.ConfigurationModel": { "version": "0.1-alpha-*", "options": "private" },
    "FakeToolingPackage" : {"version": "0.1", "options": "dev"},
    "SomeProject": ""
  }
}

You'll be able to have different types of references: - Private - Don't expose this dependency to intellisense or compilation transitively. - Bago (Build and go away) - After compiling this reference will be compiled into the target project

Detailed information on how dependency versions are chosen is available here.

Configurations

Configurations are named groups of compilation settings. There are 2 defaults built into the runtime, Debug and Release. You can override these (or add more) by adding to the configurations section in the project.json.

{
  "configurations": {
    "Debug": {
      "compilationOptions": {
        "define": ["DEBUG", "TRACE"]
      }
    },
    "Release": {
      "compilationOptions": {
        "define": ["RELEASE", "TRACE"],
        "optimize": true
      }
    }
  }
}

Frameworks

Target frameworks that will be built, and dependencies that are specific to the configuration. This snippet will build for Desktop (dnx451) or Core CLR (dnxcore50). Core CLR has many extra dependencies as the packages that make up the BCL need to be referenced.

{
  "frameworks": {
    "dnx451": {},
    "dnxcore50": {
      "dependencies": {
        "System.Collections": "4.0.0.0",
        "System.Collections.Concurrent": "4.0.0.0",
        "System.ComponentModel": "4.0.0.0",
        "System.Linq": "4.0.0.0",
        "System.Reflection": "4.0.10.0",
        "System.Runtime": "4.0.20.0",
        "System.Runtime.InteropServices": "4.0.10.0",
        "System.Threading": "4.0.0.0",
        "System.Threading.Tasks": "4.0.0.0"
      }
    }
  }
}

Sources

The sources section defines what files should be included and compiled.

{
    "compile": "*.cs",
    "exclude": "buggy/**/*.cs",
    "publishExclude": "something/**/*.*",
    "resource": "embed/**/*.*"
}

This also supports an array of sources:

{
    "compile": ["*.cs"],
    "exclude": ["buggy/**/*.cs", "foo/**/*.*"],
    "publishExclude": ["something/**/*.*"],
    "resource": ["embed/**/*.*"]
}

List of supported properties for sources:

name default value remark
compile
compileExclude
compileFiles Wildcard is not allowed
compileBuiltIn **/*.cs Concatenated to compile
code **/*.cs Deprecated, replaced by compile
content **/*
contentExclude
contentFiles Wildcard is not allowed
files **/* Deprecated, replaced by content
preprocess compiler/preprocess/**/*.cs
preprocessExclude
preprocessFiles Wildcard is not allowed
resource compiler/preprocess/resources/**/*
resourceExclude
resourceFiles Wildecard is not allowed
resources compiler/preprocess/resources/**/* Deprecated, replaced by content
shared compiler/shared/**/*.cs
sharedExclude
sharedFiles Wildecard is not allowed
publishExclude bin/**;obj/**;**/.*/**
exclude
excludeBuiltIn bin/**;obj/**;*.kproj

Rules

The sequence of searching one type of files are (take compile files as example):

  1. Using including patterns (compile and compileBuiltIn), excluding patterns (compileExclude, exclude, excludeBuiltIn) to glob the files using Microsoft.Framework.FileSystemGlobbing.
  2. Excluding other types of files (for compile, shared and preprocess files are excluded).
  3. Adding individually specified files (compileFiles)

Here's the overall rules

CompileList =
  +Glob( +compile +compileBuiltIn -compileExclude -exclude -excludeBuiltIn) 
  -SharedList
  -PreprocessList
  +Literal( +compileFiles )

PreprocessList =
  +Glob( +preprocess -preprocessExclude -exclude -excludeBuiltIn) 
  +Literal( +preprocessFiles )

SharedList =
  +Glob( +shared -sharedExclude -exclude -excludeBuiltIn) 
  +Literal( +sharedFiles )

ResourceList =
  +Glob( +resource -resourceExclude -exclude -excludeBuiltIn) 
  +Literal( +resourceFiles )

ContentList =
  +Glob( +content -contentExclude -exclude -excludeBuiltIn) 
  -CompileList
  -PreprocessList
  -SharedList
  -ResourcesList
  +Literal( +contentFiles )

PublishExcludeList =
  +Glob ( +publishExclude )

WebRoot

Specifying the webroot property in the project.json file specifies the web server root (aka public folder). In visual studio, this folder will be used to root IIS. Static files should be put in here.

{
    "webroot": "wwwroot"
}

Shared files

Allows you to share code with dependent projects. To share code, like shared assembly info, you would create a common project with the shared code files referenced in the shared section. After that any project that references your common project will have the files compiled into it as if it was source in their project.

{
    "shared": "*.cs"
}

Compilation options

Compilation options that can be passed through to Roslyn. The language version can be set here.

{
    "compilationOptions": {
        "define": ["SOMETHING"],
        "allowUnsafe": true,
        "warningsAsErrors" : true,
        "languageVersion": "experimental"
    }
}

Commands

When running dnx.exe you can pass the name of a command to execute it. In this snippet you could run "dnx . web" to self host the app on Windows or "dnx . kestrel" to run your app on OS X/Linux.

{
  "commands": {
    "web": "Microsoft.AspNet.Hosting server.name=Microsoft.AspNet.Server.WebListener server.urls=http://localhost:5001",
    "kestrel" : "Microsoft.AspNet.Hosting --server Kestrel --server.urls http://localhost:5004"
  }
}

Scripts

Events that you can hook to run scripts for kpm actions:

{
  "scripts": {
    "prebuild": "echo before building",
    "postbuild": "echo after building",
    "prepack": "echo before packing",
    "postpack": "echo after packing",
    "prerestore": "echo before restoring packages",
    "postrestore": "echo after restoring packages"
  }
}

There are variables available:

%project:Directory% - The project directory
%project:Name% - The project name
%project:Version% - The project version

Metadata

Metadata about your project. 

{
  "version": "0.1-alpha",
  "authors": ["John Doe"],
  "description": "A wonderful library that does nice stuff"
}

Bin syntax (wrapping a dll)

You can create an project that, instead of compiling, references an already compiled dll and generates a package containing that dll. To do this you use syntax like this:

{
"frameworks" : {
  "dnx451" : {
      "bin" : { "assembly":"<path to dll>", "pdb" :"<path to pdb if needed>" }
   }
}
}

It is this feature that kpm wrap leverages when wrapping csproj files.

Example project.json from one of the EF projects

{
  "version": "0.1-alpha-*",
  "compilationOptions": {
    "warningsAsErrors": true
  },
  "dependencies": {
    "Microsoft.Bcl.Immutable": "1.1.18-beta-*",
    "Microsoft.AspNet.ConfigurationModel": "0.1-alpha-*",
    "Microsoft.AspNet.DependencyInjection": "0.1-alpha-*",
    "Microsoft.AspNet.Logging": "0.1-alpha-*",
    "System.Data.Common": "0.1-alpha-*"
  },
  "code": ["**/*.cs", "/Shared/*.cs"],
  "frameworks": {
    "dnx451": {
      "frameworkAssemblies": {
        "System.Runtime": "",
        "System.Collections": ""
      }
    },
    "dnxcore50": {
      "dependencies": {
        "System.Collections": "4.0.0.0",
        "System.Collections.Concurrent": "4.0.0.0",
        "System.ComponentModel": "4.0.0.0",
        "System.Console": "4.0.0.0",
        "System.Diagnostics.Contracts": "4.0.0.0",
        "System.Diagnostics.Debug": "4.0.10.0",
        "System.Globalization": "4.0.10.0",
        "System.Linq": "4.0.0.0",
        "System.Linq.Expressions": "4.0.0.0",
        "System.Linq.Queryable": "4.0.0.0",
        "System.Reflection": "4.0.10.0",
        "System.Reflection.Extensions": "4.0.0.0",
        "System.Resources.ResourceManager": "4.0.0.0",
        "System.Runtime": "4.0.20.0",
        "System.Runtime.Extensions": "4.0.10.0",
        "System.Threading": "4.0.0.0",
        "System.Threading.Tasks": "4.0.10.0"
      }
    }
  }
}