.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 get up close and personal with the build system, configs, code everything from scratch to get a deeper understanding and have no unnecessary baggage that I don't want/need. However, the lack of documentation makes this quite difficult.. so I wanted to ask here, where no doubt clever .NET Core folks are hiding ;)

I know this question is long and has lots of sub-questions. But it could be answered I feel by a single link to documentation, or a few succint lines from someone in the know. Thanks for bearing with me, and I hope that this might become a useful answer resource for others in the same boat, trying to understand a good approach for .NET Core.

---

First, global.json. I want multiple projects and components in the same 'solution'. Through another SO question I found this hidden link: http://dotnet.github.io/docs/project-model/global-json-reference.html - but there seems to be no VS tooling for setting up or using this from scratch.

1) global.json questions

A) What build system do these docs refer to? dotnet build? (The help for that says it just builds a project - if it does 'solutions' - if that's still the name - does it just run dotnet build over all child folders?).

B) Many examples around have an "sdk" property - but EF Core doesn't have it, and the new "single-sentence-style" docs don't refer to it. The official RC2 migration guide for ASP.NET Core has it Is it still around or not? If so, why is it needed? What uses it? What are the options for it?

---

Next up, to project.json and frameworks. I want to understand the options here for frameworks. Is there a list? Official guidance? dotnet new uses netcoreapp1.0; "official docs" use an example of dnxcore50 and this GH discussion from last month also raises the question of netcore1.0 as a possibility for frameworks (vs apps).

Furthermore, imports. Am quite baffled on the naming - the docs talk about this being a list of other frameworks that the project is compatible with..

2) project.json framework questions -

A) Where can I find an up-to-date or maintained list or set of advice around the framework options?

B) If my understanding of the purpose of import is correct, why is it named so? If not, what exactly does it import?

C) Why is there an import property for every framework property? If it's to indicate the whole project is compatible with another framework, that would seem to be best placed at the top level of project.json, no?

D) How should I decide which import options should I use? dotnet new has just dnxcore50 - which packages is that to satisfy? This guy suggests dotnet5.6, dnxcore50 and portable-net45+win8!

---

Finally, I'm building class libraries, test projects, console utils. So..

3) references and packages

A) Do I always want Microsoft.NETCore.App as per dotnet new? Are there other baseline options? Guidance on choosing? A list?

B) The docs don't mention anything about the type option (build, platform). Is there any guidance available on these?

C) Some of my projects will use ASP.NET. Where's the best place to find the correct packages to reference? There seem to be a million versions and packages on NuGet. This tutorial just talks about referencing Microsoft.AspNetCore.Server.Kestrel - and the only ASP.NETty thing that refs is Microsoft.AspNetCore.Hosting. Does that mean that one package is most of ASP.NET?

Arneson

I find it very messy as well. – Ion

Great job on these questions. I understand that Microsoft was already pressured to just get RC2 out as fast as they could and that documentation could be tended over time, but so far it doesn't look like the documentation is responsive to the questions people actually have. Since it's both not supposed to change any more unless absolutely necessary and about to ship within the month, I hope they start filling out the documentation soon. – Cenotaph

A quick note, don't read this as a moan - this is just stuff I want to know and seems fairly "baseline" to understand. I'd love to compile the answers and write up a ".NET Core from the ground up" blog post perhaps. Each line of each .json file explained for example, what it means, why it's needed. – Arneson

It would take a lifetime to answer all your questions, so I rather leave a comment to ask you to wait till the tooling (currently in Preview 1) becomes RTM (months away). Definitely the core runtime (.NET Core) will be RTM by the end of this month (June), but Microsoft has made another series of changes on the tooling part (moving from .json attempts back to MSBuild), so even if someone spends the time giving you some answers, they would be obsolete soon (like the documentation you refer to). I jumped on the boat some time after RC1, and I am already tired. – Standby

You should ask one question per question. – Selfhypnosis

@LexLi 35 mins it took. But I agree with you and also with svick ;) – Assess

It's not reasonable to expect people to wait. The point of releasing betas and RCs (as opposed to ad-hoc builds from GitHub) is for people to actually try this stuff out and start using it. We need the information now in order to do that. Currently the sprawl of frameworks and libraries is a confusing mess and the tooling won't change that. – Antoniaantonie

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 ;).

Assess

Tyvm, appreciated the in-depth reply! Will run through over a coffee soon :) – Arneson

This is a great collection of advice, thank you. If I may push my luck, I'm trying to reference my library from a new console app. Library using netstandard1.6, app using netcoreapp1.0. But dotnet restore says Project MYLIB is not compatible with netcoreapp1.0 (.NETCoreApp,Version=v1.0). Project MYLIB supports: netstandard1.6 (.NETStandard,Version=v1.6). But platform std doc says netcoreapp1.0 maps to netstandard1.6. Should I be adding an import on the app, or changing the lib? (& why is that necessary?). – Arneson

Well, I solved it I think, but ugghh!.. why does netstandard1.5 work but not netstandard1.6? If the ".NET Platform Standard" doc says it should work! – Arneson

And when I try to run, Expect required library hostpolicy.dll to be present in MYAPP\bin\Debug\netcoreapp1.0. I'll do some more googling I guess :'( – Arneson

Use netstandard1.5. I guess the platform spec document is also not 100% accurate. netstandard1.6 will align with .NET Framework 4.6.3 ... which is not out till earlilest November. So I would bet, that this was more a planning document at the time of writing. – Assess