The Power of the global.json

As I'm sure you're all aware by now, Monday, June 27th was a special day for those of you who were anticipating the release of <inlinecode>.NET Core<inlinecode> and <inlinecode>ASP.NET Core<inlinecode>. While the "core" frameworks and runtimes are RTM, the tooling is actually still in preview. In fact, we're currently on Tools Preview 2. I wanted to focus this post entirely on one specific enhancement to Visual Studio solutions, enter the <inlinecode>global.json<inlinecode>.

Let me paint a picture for're developing an application. This application doesn't have all the source code in the world, so you take on some dependencies. Since we're not living in caves, we have packages -- this is common nomenclature and the norm for any modern software development project. One of the aforementioned dependencies is a package that you just so happen to also work on and develop for. Imagine that you find a bug or want to make an improvement to said package, what does that work-flow look like? For me, this typically involved the following steps:

  1. Open dependency project in a new instance of Visual Studio
  2. Make code change
  3. Code review
  4. Commit code
  5. Build server builds code
  6. Build goes "green" (tests passed)
  7. Build server publishes package
  8. Wander the halls playing Pokémon Go
  9. Return to original project, update package reference
  10. Continue with life

What if I told you, that headache is all but gone and you will never have to go through those agonizing steps again! Say it ain't so (queue Weezer).


The <inlinecode>global.json<inlinecode> file sits out at the solution directory-level and literally has one of the simplest <inlinecode>JSON<inlinecode> schemas you will ever see. The default templates generate the following (for the full schema):

I always immediately delete the <inlinecode>sdk<inlinecode> property. If omitted the tooling simply assumes the latest </inlinecode></inlinecode>SDK installed. Now, for all the fun! The <inlinecode>projects<inlinecode> property is an array of strings. It's defined as the following:


A list of project folders relative to this file.


These folders are search locations for resolving dependencies, where projects take precedence over packages.

Projects over Packages

Assume you're developing in a project, namely <inlinecode>IEvangelist.NetCore.App<inlinecode> and it takes a dependency on <inlinecode>IEvangelist.NetCore.ClassLib<inlinecode> and <inlinecode>IEvangelist.NetCore.Services<inlinecode>. These dependencies are packages (outside the solution) and you can use the <inlinecode>global.json/projects<inlinecode> array to your advantage. Using our imaginations, let us find a need to source-step into <inlinecode>IEvangelist.NetCore.ClassLib<inlinecode>. Let us also imagine that this project is in a neighboring folder outside our solution, perhaps the same repo, we can now use a relative path like so:>



After saving these changes to the <inlinecode>global.json<inlinecode> you'll notice Visual Studio pull this project into solution, but outside of the <inlinecode>src<inlinecode> folder. Now when you debug you can actually step into the source and treat it like any other source code you have. Project dependencies are resolved by way of their <inlinecode>project.json<inlinecode> being discovered.

Open Source for Everyone

One of the biggest advantages in my opinion is the ability to pull down source from <inlinecode>github<inlinecode> that I rely on and source-step into it. For example, I have been developing with <inlinecode>ASP.NET<inlinecode> Core since RC1, nearly eight months!! With the power of the <inlinecode>global.json<inlinecode> I can pull down source that I'm relying on in a package and fulfill my understanding of it as it executes. Simply amazing!

Further reading

For more details, these are some additional links and points of reference.

Get your project started today

Get in Touch