.NET Core - solutions, frameworks, imports, runtimes

Question

I\'m starting the process of reworking a framework set of libraries to use .NET Core. Thought I\'d wait for RC2 and keen to get stuck in.

I\'m taking the opportunity to

Answer 1

You have many questions. There is no single documentation for it, because the questions are not that simple ones ;)

global.json

• global.json build system: global.json (as project.json) do not specify a build system (other than e.g. msbuild csproj files). For now, only dotnet build is available (proxied by msbuild xproj when used in VS). This is going to change to msbuild because the complete tooling is in preview/beta and not going to release end of June. It runs over all the child folders and build the stuff. It is also the root node for looking up local project references.
• global.json sdk: That is the sdk used for the build. The new cli also supports multiple sdks, and I think this is still used for selection.

project.json

• project.json list of framework: I recommend that you read the platform standard document and there you find a list of current framework monikers. This document will also resolve many other questions you (might) have. A complete list is in the NuGet project docs, but the list again is deprecated and not that useful either. You example netcore refers is used for UWP (which runtime is also called .NET Core) while the cross-platform .NET Core uses netcoreapp which is completely missing in NuGet documentation.
• project.json import: you get here the purpose wrong. In project.json you specify the target frameworks for which implementations of your library are build (e.g. netstandard1.6 and net451). The import statement is used for dependencies you specify for the target framework and basically says: If the TFM (e.g. netstandard1.6) does not exist in a referenced library (because the NuGet was build a while ago), I also accept these imported once (e.g. the deprecated dotnet5.6 or dnxcore50). This is currently a utility to break NuGet and allow the usage of libraries which are not yet moved to the new TFMs. It does not say anything about your project but which versions of your dependencies you accept to use. That needs separate specification for each targeted frameworks because acceptance of NuGet library implementations might differ per targeted framework.
• project.json import usage: well, use what you need and remove all you do not need. You will get errors when you refer NuGets which have not been migrated yet to the new TFM. dnxcore and dotnet are save bets on .NET Core projects because they have been used before the current monikers netstandard and netcoreapp have been coined. Just do not be that bold to add e.g. net461/mscorlib based NuGet implementations to a netstandard/System.Runtime based target framework. That does not work and is a common mistake.

dependencies

• dotnet new default template: Yes, for ASP.NET and Console Apps that is always the right choice. However, this is just a simple console app (web apps are console apps as well). Use Visual Studio to create new ASP.NET Core projects or yeoman under Linux for advanced templating. dotnet new is not a full blown scaffolding system. The new template uses the netcoreapp target framework and the Microsoft.NETCore.App meta packages to import basically all available base class libraries. If you want to create a library, switch to netstandard target framework and depend on the NETStandard.Library. You can still add other dependencies. For ASP.NET core, no direct meta package is available. The guidance ends here. There is a process called trimming, where you remove these meta packages and add concrete dependencies instead. But there is not yet tooling for it.
• project.json build/platform dependencies: build dependencies are essentially tools, which are not published during build. When you know npm you know this scheme as devDependencies. platform dependencies is essentially a dependency which is not deployed along with your app but as part of the shared base installation of the .NET Core SDK. You find guidance here under the term "portable application" (that is platform) and "self-contained application" (that is it without).
• project.json meta packages / transitive dependencies: .NET Core and project.json introduce the concept of meta packages. Microsoft.NETCore.App is essentially the baseline dependency for a .NET Core command line app and NETStandard.Library for class libraries. All these packages can have code on their own and transitive dependencies for other packages. These you can also utilize then. As an example, the Microsoft.NETCore.App package refers NETStandard.Library which again refers System.Collections.Generic. So in your app which refers Microsoft.NETCore.App you can use generic collections. For ASP.NET Core the situation is different, because there the pay-as-you-go philosophy is very performance critical. For productive application you have to understand what you add. As a starter, you have to use scaffolding systems like VS or yeoman. The Microsoft.AspNetCore.Server.Kestrel (e.g. plain text) or Microsoft.AspNetCore.Mvc (for web api) transitively include most other critical ASP.NET Core dependencies.

Disclaimer: Most of the topics are above are related to tooling which is considered "preview". "preview" means "beta". There are significant changes upcoming (like switching the build system from the project.json back to msbuild, or refining the .NET standard once more).

I hope this answers most of your questions. I think answering all of them in one question is a challenge ;).