Explanation of the projects section in Global.json in ASP.NET 5

Question

I noticed that when creating a new ASP.NET 5 project there is a src directory which completely makes sense to me since I have always put all of my solution's code in a directory called source.

I noticed there is a file called global.json which by default has the following content in it:

{
  "projects": [ "src", "test" ],
  "sdk": {
    "version": "1.0.0-rc1-update1"
  }
}

I found the following in the ASP.NET 5 documentation: The projects property designates which folders contain source code for the solution. By default the project structure places source files in a src folder, allowing build artifacts to be placed in a sibling folder, making it easier to exclude such things from source control.

However, here is the project structure that I have in mind (It is basically going to be 2 large projects that I want under the same solution):

MySolution
    MySolutionProject1Src
        client
            p1.WebAPI
        business
            p1.Business
            p1.Model
        data
            p1.Repository
        test
            p1.BusinessTests
            p1.WebAPITests


    MySolutionProject2Src
        client
            p2.Web
        business
            p2.Business
            p2.Model
        data
            p2.Repository
        test
            p2.BusinessTests

So would I update global.json to be the following? (one for each parent directory):

{
  "projects": [ "MySolutionProject1Src", "MySolutionProject2Src" ],
  "sdk": {
    "version": "1.0.0-rc1-update1"
  }
}

or should it be something more like this (one for every single sub-directory):

{
  "projects": [ "MySolutionProject1Src/client", "MySolutionProject1Src/business", "MySolutionProject1Src/data" "MySolutionProject1Src/test", "MySolutionProject2Src/client", "MySolutionProject2Src/business", "MySolutionProject2Src/data" "MySolutionProject2Src/test" ],
  "sdk": {
    "version": "1.0.0-rc1-update1"
  }
}

Or should I simply just leave it as "src" and put everything as sub folders under src..

I am assuming I can create whatever solution structure I want, but my concern is the rules to follow when updating the global.json projects section to match it. Based on the documentation it says an artifacts folder will be created for each path specified in global.json. So I am wondering if I want an artifacts folder for every single project in the solution or just one big one on the outside.

Answer 1

First of all I would forward you to the part of documentation, which describes global.json.

{
  "projects": [ "src", "test" ],
  "sdk": {
        "version": "1.0.0-beta5",
        "runtime": "clr",
        "architecture": "x86"
  }
}

The version (and optionally runtime and architecture) are important because your computer have multiple versions of dnx.exe. You can examine %USERPROFILE%\.dnx\runtimes directory to see all the installed runtimes. The "sdk" part of global.json defines the version of dnx.exe from one of the runtimes which you installed.

It's important to understand about "projects" part of global.json that it will be scanned all sibling folders on any level under every from the directory. Every project.json, which will be found, will be interpreted as the project of the solution.

You can for example download some part of ASP.NET and place it in the new subfolder of your solution hierarchy. For example you can download RC1 source of Entity Framework 7 (the file) any extract the zip-file in new ef folder inside of src folder of your project. You will see that, short time after reopening of the solution, the list of your project will be longer and longer and all Entity Framework 7 components will be included in your solution. In the same way you can extract the downloaded sources in separate directory C:\aspnet\EF7 and to use

{
  "projects": [ "src", "c:/aspnet/EF7" ],
  "sdk": {
    "version": "1.0.0-rc1-update1"
  }
}

You will have the same effects. If you later decide to remove debugging the sources of Entity Framework 7 then you should just exclude "c:/aspnet/EF7" from global.json and then remove in Visual Studio previously added projects by selection in Solution View and click Del key.

I think that it should clear the possibilities which you have in the folder structures.

One more very important optional file, which could exist in the solution hierarchy, is NuGet.config file. It defines NuGet feed, where the packages will be loaded. The problem is that there are many NuGet repositories (see the answer), which have different preliminary versions of ASP.NET 5 components. If you use the exact dependencies like

"EntityFramework.MicrosoftSqlServer": "7.0.0-rc1-final"

then one need just have the explicit version in the NuGet repository. The problem is that sometimes one uses the dependency like

"EntityFramework.MicrosoftSqlServer": "7.0.0-*"

to load the latest build of the package. If you would use wrong NuGet feed then you can get early RC2 builds, which are incompatible with other RC1 packages (at least because of renaming of many components between beta versions). To be sure that your solution (all your projects) uses RC1 you can place the following NuGet.config in your solution folder (on top of all projects) for example the following content

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageRestore>
    <clear /> <!-- ensure only the sources defined below are used -->
    <add key="automatic" value="False" />
  </packageRestore>
  <packageSources>
    <add key="AspNetVNext" value="https://www.myget.org/F/aspnetmaster/api/v3/index.json" />
    <add key="NuGet" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
  <activePackageSource>
    <add key="AspNetVNext" value="true"  />
    <add key="NuGet" value="true"  />
  </activePackageSource>
</configuration>

See the documentation. I recommend you to open command line in some project folder and to execute

dnu feeds list

command. It will shows that all the NuGet.config from the current and the parent folders and the global file %appdata%\NuGet\NuGet.Config will be combined. NuGet will be search for packages in on all active repositories. It will be https://api.nuget.org/v3/index.json and https://www.myget.org/F/aspnetmaster/api/v3/index.json in the above case.

Possible conflicts could be if multiple NuGet.config exist, points different NuGet feeds or enable/disable some feeds. The command dnu feeds list helps here. You should always scan for all NuGet.config files in your project hierarchy to prevent/resolve the conflicts. The resolution of many conflicts consist mostly in usage of correct feeds or the usage of explicit versions for resolution of packages.

I recommend you to read the article, which describes NuGet Configuration Inheritance.

I hope that you could decide which structure would be better for your existing environment. I would you recommend to hold the standard structure

solution
    src
        project
        folderWithProjects

and to place global.json and NuGet.config in the solution directory. The default place for the test-projects: separate from the main projects:

solution
    src
        project
        folderWithProjects
    test
        testproject1
        testproject2

(you can examine the structure of Entity Framework 7 on GitHub or MVC6 here). You can follow the structure or to choose another location and to modify "projects" part of the global.json.

UPDATED: Microsoft made a lot of changes between RC1 and RC2. Dnx.exe will be not more used in ASP.NET Core. One should use dotnet.exe instead. The description of new/modified global.json and project.json are not yet full documented. You can see the preliminary version of the documentation here. The links on the old documentation (under https://docs.asp.net/en/latest/dnx) are now broken.