What is Project.json in ASP.NET 5

With the release of ASP.NET 5 ASP.NET Core 1.0 (new version of ASP.NET), things are changing quite a lot with the way we code, organize dependencies, manage runtimes and many other things. Today, we will be looking at one of the most exciting change that Microsoft made which is introduction of “Project.json” file in ASP.NET 5 ASP.NET Core 1.0. This new file the way to define your dependencies, managing your runtime frameworks, compilation settings, adding scripts to execute at different events (Prebuild, Postbuild etc.) 

Project.json in ASP.NET 5

Let’s first create a new ASP.NET empty project using Visual Studio 2015. If you don’t have visual studio 2015, then you can download the community version from here. So let’s create a new project File -> New Project -> Select ASP.NET Web application.

Enter Project name and location and Hit Ok. In the next dialog box, select ASP.NET Preview template Empty template and hit Ok.

And now, take a look at your solution explorer. You will find Project.json present there. By the way, web.config is gone now. There is now easier way to manage configurations.

Let’s double click the file and see what’s inside. You will find that this file is divided in various sections like dependencies, framework, commands etc…

Since at the time creating project, we selected empty template. But if we select web application, then your project.json file will look like below.

In case of empty template, there are only 2 entries in project.json file for dependency section where in case of web application there are many entries in dependency section. Dependency section will have list of all the dependency on which your application/project is dependent. I will explain this section in detail in later part of this post.

There is one more section “Scripts” which is not available in empty template “Project.json” file. And that makes sense. As with empty template, there is nothing present in your solution explorer but with web application project, you get a running website and that’s why this section is present. Using this section, you can execute various scripts at different stage of your building process of your project.

Closer look at Project.json section

First two lines of project.json define webroot and version.  The webroot specifies the folder that should act as the root of the web site, which by convention defaults to the wwwroot folder.  This is also a new feature introduced with ASP.NET 5 ASP.NET Core 1.0.  If you take a look at solution explorer, you will find “wwwroot” present. I will cover this in another post, but for now remember it is for keeping your static content like images, js and css files. And the version property specifies the current version of the project.

[UPDATE: This is changed in ASP.NET 5 RC 1 release. Read more here]

Now, let’s take a look at various section of this file in detail.

Dependencies

This section lists all the dependencies of your application. Dependencies are defined with name and their version. And if you wish to include any nuget package or class library then this is the place to do. And intellisense feature is ice on the cake. As you start typing name of nuget package, you will see that Nuget package manager is getting all the information for you.

Once you select the package you need, intellisense will assist you for the version as well. It indicates the latest version and all other previous version. And if you select (“”) empty quotes then you are always referencing the latest version.

Once you include your dependency and save the file, the solution explorer will restore the dependency for you and add the reference. So your dependencies are always in sync with solution explorer when you add/remove in project.json, solution explorer will also update the references accordingly.

And it’s both ways. Which means adding a nuget package via nuget package manager will also update project.json file. Just give it a try.

Commands

This section allows you to define commands for your project, which later on you can execute using dnx (.NET Execution Environment) or Visual studio command window (Ctrl+Alt+A). There are various commands which can be included like self hosting on windows or on linux server. Following snippets when executed using .dnx will self host the project on windows.

"commands": {
    "web": "Microsoft.AspNet.Hosting --config hosting.ini"
  },

[UPDATE: This is changed in ASP.NET 5 RC 1 release. Read more here]

We can run the web command from a command prompt using dnx: dnx web. This will host your application and the settings will be picked up from hosting.ini file present in your solution explorer.

Likewise, we can use “kestrel” command to host it on linux machine. “ef” command for entity framework migration. Any NuGet package can include commands and you can also create your own and command name could be anything.

"commands": {
    "web": "Microsoft.AspNet.Hosting --config hosting.ini",
     "kestrel": "Microsoft.AspNet.Hosting --config hosting.ini",
     "gen": "Microsoft.Framework.CodeGeneration",
     "ef": "EntityFramework.Commands"
  },

Frameworks

ASP.NET 5 can target multiple frameworks, which allows the deployment into different hosting environment. Along with the main framework, there is also .NET core framework. .NET Core is a small version of the .NET framework that is optimized for web apps and supports Linux and Mac environments. Project.json has following code for framework section. “dnx451” indicates .NET 4.5.1 or Full CLR where “dnxcore50” means .NET core 5.

"frameworks": {
    "dnx451": { },
    "dnxcore50": {  }
  },

This defines your targeted framework and their dependencies. We have already seen dependency section and those dependencies are applicable for both the frameworks. You can have different dependencies for each framework. For example, here we have defined dependency only for dnxcore50 framework.

"frameworks": {
    "dnx451": { },
    "dnxcore50": {
      "dependencies": {
        "EntityFramework.Core": "7.0.0-beta8"
      }
    }
  }

And solution explorer will also confirm this.

Defining multiple frameworks will ensure reusability of your code. When your application is built, complier will ensure that it runs against all the defined frameworks. That means single code base can be used for application which is hosted on windows and as well as on Linux/Mac. However, there are certain limitations of .NET Core 5 like reflection is not available with .NET Core. And while writing the code, you can target the framework.

#if DNX451
#endif

#if DNXCORE50
#endif

Visual studio intellisense also tells you whether the requested option is available with framework or not. It clearly displays a warning sign, if the option is not available against the framework.

publishExclude

This section indicates the folders and files needs to be excluded while publishing the website. You can see that folders like node_modules, bower_components are excluded as they are not required while publishing the website.

"publishExclude": [
    "node_modules",
    "bower_components",
    "**.xproj",
    "**.user",
    "**.vspscc"
  ],

exclude

This section is similar to publishExclude, the only difference is that it indicates files and folders should be excluded while building the application.

"exclude": [
    "wwwroot",
    "node_modules",
    "bower_components"
  ],

Scripts

The scripts section is used to specify build automation scripts. Following code defines commands needs to be run before publishing a website. You can also include “prebuild”, “postbuild”.

"scripts": {
    "prepublish": [ "npm install", "bower install", "gulp clean", "gulp min" ]
  }

UPADTE: Following changes are made in ASP.NET Core 1.0 RC 2 release. BTW ASP.NET 5 is now ASP.NET Core 1.0 and read What’s new in ASP.NET Core 1.0 RC 2 Release.

• Project.json now allows to set compiler in compilerOption section. So when dotnet compile command is executed, it will look in Project.json file.
• You can also set gcMode (Garbage Collection Mode) in Project.json file under runTimeOptions section.
• commands section is gone.
• dnx46 now becomes net46

That’s all folks. Keep visiting this blog and share this in your network. Please put your thoughts and feedback in comments section.

PS: If you found this content valuable and want to return the favour, then