Scott Hanselman

Draft - .NET Glossary Diagram

August 18, 2017 Comment on this post [41] Posted in DotNetCore
Sponsored By

I'm working on this slide as support for this excellent .NET Glossary. It's not done yet, but I'm curious for your thoughts. Every system has terms and concepts that are initially unfamiliar but make sense once you grok them.


Here are these concepts used in an example sentence, for context:

  • Application Framework - “Are you using the ASP.NET Core web framework for that microservice?”
  • Metapackage - “I want to install the ASP.NET Core framework; it’s a package of packages”
  • Package/NuGet - “I know there’s a NuGet package for decoding JSON.”
  • Library/Assembly - “Now, you’ll compile your source into an assembly”
  • .NET Standard – “Which version of the .NET Standard specification does your assembly target?"
    • "My Apple Watch supports .NET Standard 1.6 but my Windows 10 laptop supports 2.0 with more APIs.”
  • C#, F#, VB, etc – “Which language did you use?”
  • .NET SDK - “Did you get the developer tools?”
  • CLR/CoreCLR – “Which runtime is your app using?”
  • An implementation of .NET is a runtime along with libraries that implement a version of the .NET Standard
    • “Are you using .NET Core, .NET Framework, or Mono for this project?”
  • Platform - An operating system and some hardware (ARM, x64, etc.)
    • “Is that an ASP.NET Core app running in Docker on a Raspberry Pi?”

Constructive feedback, please. This is a draft.

Sponsor: Check out JetBrains Rider: a new cross-platform .NET IDE. Edit, refactor, test and debug ASP.NET, .NET Framework, .NET Core, Xamarin or Unity applications. Learn more and download a 30-day trial!

About Scott

Scott Hanselman is a former professor, former Chief Architect in finance, now speaker, consultant, father, diabetic, and Microsoft employee. He is a failed stand-up comic, a cornrower, and a book author.

facebook twitter subscribe
About   Newsletter
Hosting By
Hosted in an Azure App Service
August 18, 2017 1:13
While I can't offer any constructive critiques, I can say that this will be a very good teaching/learning tool, especially for visual learners like myself.
August 18, 2017 1:18
We should have CGP Grey do an explainer.
August 18, 2017 1:23
This is great. A very nice follow up, once you're done, would be: how to answer to those questions.
You know, just to be sure everything is crystal clear.
August 18, 2017 1:42
Is there a need to specify that an app written against a given .net standard version will run on every device that supports that standard? May be use your apple watch, raspberry pi analogy. Can't phrase it correctly - hope you get the gist.
August 18, 2017 1:50
Hmm, this is a good diagram. I feel like I have been drawing a crude version of this at work for explanations. Glad you included F# =).

Feedback wise:
More color contrast in the boxes might be an improvement. May be hard to see for color blind.

The items in the blue boxes, the way they are in separate boxes may confuse a user into thinking that C# does not have a any relation to CLR or the .NET SDK.
August 18, 2017 3:22
Come to think of it, it won't just run, will have to be published against each runtime.
August 18, 2017 3:53
CLR/CoreCLR – “Which runtime is your app using?”

An implementation of .NET is a runtime along with libraries that implement a version of the .NET Standard

Maybe the overlap can be visually represented? Or the CLR/CoreCLR brought down into the box below and show sub-boxes for CLR/CoreCLR, BCK etc.

August 18, 2017 4:28
I'll agree with others and say the colors need more contrast. I'd also take the language box out- the languages are kind of orthogonal to this whole thing.

CodeMonkey: See this slide, Boss- it explains what .NET Standard means.
Boss: Oh, ok great! Where do our Silverlight applications fit in?
CodeMonkey: ...
August 18, 2017 5:53
Looks good to me, though I'll second the comments on contrast (esp. between 2nd and 3rd boxes).

One thought: it may not be important enough for your goal here, but I might separate the platform layer into OS and hardware (get people to recognize they aren't in lockstep).
August 18, 2017 6:07
What's the name for the new, smaller XML project files? I refer to them as .Net SDK projects, but I don't know if that's accurate.
August 18, 2017 6:11
I love this, great visual. In thinking about this, I feel like I have seen this as a slide countless times (or something similar to it). And now there is a pseudo legend / glossary I feel like it should be interactive. I could imagine this living on the docs site, and as a user I could interact with this visual. And it would evolve over time. I could click on an area and get a flyout for example, with various details. Information or links to more docs, or examples... If I clicked on ".NET SDK" imagine a popup (or pick your favorite UX) and it would tell me immediately as a developer what it means, and provide examples. Here are some SDKs, I'd think to myself "oh, I know what they mean by this now".
August 18, 2017 7:57
I'm not sure what this is telling me overall... but the way I interpret it ( as a narrative )

There's layers

Application Framework is built on top of
Metapackage, which is built on top of (does it have to be built on top of a meta package?)
a .net runtime, with libraries that implement a version of the .NET standard (Problem: not everything is .NET standard?)
which is built on an Operating System

A MetaPackage is made up of Nuget packages? whys there a / inbetween package and nuget?
nuget packages is made up of libraries/assembly... what's with the / again??
a library consists of possibly ".NET standard", a lanaguage? some sdk? and clr/coreCLR ( now the / implies a OR condition... not quite sure the previous /s mean OR)

Hold on, a library doesn't contain C#/F#/VB, that's independent... I guess he's trying to imply it's source is written in one of those languages? seems an odd way to represent this.... actually at this level everything seems off, a library uses a language to target the other two things. actually, the sdk isn't a thing, it's a set of tools..... now I'm really not sure what this whole box is trying to say.

whys .net standard out on its own? that also has language? yeah...... really not sure what the diagram is trying to communicate? Yet I build shit with all these tools all the time, they are all things I know, but I'm not sure what useful relationship is getting communicated between these things?

August 18, 2017 10:13
Can you illustrate how original .NET incarnations fit here, for example, which question do I answer with "I used .NET v4.6.2 for this"?
August 18, 2017 10:51
I see at least 3 separate concerns here:

  • Authoring - languages, SDK, .NET Standard, Application Framework -> assembly
  • Execution - assembly -> runtimes, platform
  • Sharing - assembly -> package, metapackage

I feel it would be really helpful if the distinction was clear and it would also give an opportunity to show exactly how they relate to each other.
August 18, 2017 11:15
Scott I agree with the comments about the contrast.

Have you considered running the image through a colour blind simulator like this one? -

Vischeck is also a good tool to play with -
August 18, 2017 11:39
Scott, I think something like this is absolutely needed.

It feels like I woke up one morning and suddenly just saying I was developing a .NET application wasn't enough any more. Seemingly overnight (maybe I just wasn't paying enough attention) we all need to be a lot more specific and precise in the language we use.

Whilst this is a small price to pay for all the new options we have in front of us, a glossary is now absolutely essential.

The only suggestion I'd make is that I'm not sure the nesting feels that intuitive. At least, it doesn't match my mental model. To me it feels more like a scale than a hierarchy.

Anyway, keep up the great work.
August 18, 2017 13:22
Thanks for this very useful, visual map.

My initial reaction was to question the ".Net Standard" box - does this really sit here? Or should it be more like several boxes labelled ".Net Core", ".Net Framework (ver X.Y)", "Mono", etc...

This sort of glossary is definitely useful and very handy to have a visual "at a a glance" reminder.
August 18, 2017 15:19
Your explanation for the ".NET Standard" used the word "specification", which made a big difference. Just saying ".NET Standard" made me think of a runtime, right or wrong.
August 18, 2017 15:54
Thanks for this Scott, this is very much needed with all that is happening in .NET these days.

I tag along with the others in the "color contrast" train. There should definitely be a clearer visual separation between these boxes.

I have the same feeling as Tom about the nesting. Especially the blue section with languages, runtime and tooling. It feels a bit mixed up.

Also, .NET Standard, in my head, is something broader than what is visually represented. I don't know how the best way to put it would be, but the message should be "this is the set of APIS available to you for building this library". Right now it feels like it is somehow embedded in the library.

Again, thanks for this. Can't wait to see the final version!
August 18, 2017 16:16
Most makes sense to me , although I'm a little thrown by the apparent repetition between your 'CLR/CoreCLR' box and the 'An implementation of .Net is a runtime...' box. Is this not the same thing expressed twice?

If your intention was to list the implementations (which I think would be helpful) then I'd merge the two boxes at the 'lower' level and include Mono/Xamarin and other implementations there.

In general though a really useful diagram, great job and thanks for sharing.
August 18, 2017 17:23
Hmm not sure this works for me. The layering seems off and there seems to be a mishmash of physical and logical concepts in here. I would be tempted to lay this out explicitly from the view of a developer.

Put the languages/compilers that developers work in on top. Everything underneath (for the most part) is .Net not language specific and what things are written in is more of an implementation detail.

How are Application Frameworks differentiated from a MetaPackage or even a collection of Packages? Certainly, something like Asp.Net is delivered as a Metapackage. I wonder if you should treat the two almost as synonyms.

.Net standard in the middle kind of works. It does miss out that there are still separate frameworks and they all have extra API's unavailable to Standard or other frameworks. However, that might be hard to visualise so perhaps not worth considering here.

.Net SDK so seems to represent the development time installer, you don't need the SDK to deploy an application. I'd either drop this or make it a top-level concern with the languages/compilers and perhaps add in SKU's .Net FX, .Net Core etc...

I would either separate out each of the major runtimes (or at least CLR, Core CLR and Mono), then put those over the same big blue box as the "An implementation of blah". Or alternatively, leave as one and add the "An implementation..." text into the same box.

Then sit that over Platforms as you have already.

Hope this helps!
August 18, 2017 19:42
Scott: I hate the use of word 'platform' since it is vague. Adding to it, Platform example given in post, is confusing. I fail to understand why we are calling Operating System + hardware as a platform.

In "“Is that an ASP.NET Core app running in Docker on a Raspberry Pi?” example, Raspberry Pi is device and Raspberian is OS. So, not sure what is called here as a platform.

Hope this helps.
August 18, 2017 21:40
The term Platform is polysemous.

While most people like to think of platform as being OS + Hardware, Microsoft often refers to .NET Core, .NET Framework, etc. as platforms, for example, in this post.

I think they do this because framework can be confusing too. Generally, we think of frameworks as libraries, but .NET includes runtimes and compilers, which are more akin to as OS.

I actually just wrote a blog post discussing this very issue yesterday.
August 18, 2017 22:22
very confusing are the terms '.net core' and ' core'. The fact that ' core' can run on .net core or .net classic (if thats the correct name)
August 18, 2017 22:31
@pm100 ".net classic" is called .NET Framework.
August 18, 2017 23:38
Some of the layering confuses me.

Packages are made up of libraries makes sense.

But the inclusion of .NET Standard in Library/Assembly doesn't fit right for me. Does every library implement .NET Standard? I think of .NET Standard as of a collection of APIs, which is probably implemented with a collection of libraries. Am I misunderstanding?

And I'm really not sure how .NET SDK quite fits into that.

Perhaps I'm being confused by a mixture of "This is used to implement that" and "This makes calls into that"?
August 19, 2017 2:56
Very interesting. Just started studying computer science. I know a lot of Java and a little C# from using Unity game engine. But you've got me curious about how Java works too,msomce it's also a cross platform tyoe language. Would love to compare both.
August 19, 2017 6:10
I like the initial draft.

A few things that came to mind, is metapackage the right terminology? Maybe say composite package or package collection (ICollection<NugetPackage>)?

Related to that, how is this collection of packages different from an application framework? From the example, they seem to both be representing the core web framework.
August 19, 2017 15:05
Modules lost somwhere between assembly and .net standard
August 19, 2017 15:30
I think ".NET Standard" needs to clarified as an **API surface**, that is implemented by one or more assemblies provided by a given runtime. In the beginning it was really bad when it was called the ".NET Standard library", this gave a completely misleading designation, that this was some one for all set of mother assemblies for all. It is not. It is an agreed upon versioned API set, that any runtime compatible with needs to supply/provide.

Ha so try to squeeze that into one sentence. ".NET Standard is an **API surface** provided by a given runtime." maybe...
August 19, 2017 16:21
This is awesome !!
August 21, 2017 1:34
where's Powershell and a whole slug of other languages.
August 21, 2017 4:00
Hi Scott thanks for the knowledges, Im currently using Visual Basic.NET language, especially for windows form. Sorry for Out of topic, I want to ask if there is a away how to download special packages Visual Studio 2017 just for windows form and mobile development only? thank you.
August 21, 2017 11:27
I don't think you should nest all these subjects. This audience is confused already with all the glossary so it has to be clear whats a sub-item and what is just related. I therefore think that the previous .NET Standard images are a better representation. Those give a clear layered view of what is on top of what and what are actually grouped components.

I would like to see your image in this format:
August 21, 2017 16:48
Do not touch the explanation (example sentences); it is great!

I don't care the diagram, the explanation is the point!

Sorry for my english :)

August 22, 2017 0:51
Metapackage sounds to me as a package that contains description.
If it's a package of packages, what about Nested Package or perhaps Ordered Package?
August 22, 2017 6:48
I could not do the new Core 2.0 Identity stuff with standard2.0 ckasslib, why should I use it?
August 24, 2017 6:48
Hi Scott,

One thing I find confusing in diagrams like this is why something conceptually fundamental like a language (C#, F#, etc.) is shown on the same level as the SDK and the CLR. From my naive ASP.NET perspective I would have expected that the SDK would be a collection of optional assemblies and the CLR would be something underneath the languages. I'm not saying any of that is true, just giving my naive perspective of why I find that part of the diagram confusing.

August 25, 2017 1:06
I think we could benefit from something like this.

However I think that the assembly box and it's contents could lead to confusion IMO. I think it should be clearer that a package can contain a number of assemblies, which may or may not target netstandard versions. Also those blue boxes (Languages, SDK, CLR) should move out too.

I think Artemigos nails it by saying there are 3 separate concerns. To bring them all together in a unified hierarchy I do not think will help newcomers.
September 02, 2017 3:08
It might be helpful to include where Portable Class Libraries (PCLs) fit in this diagram, as .NET users shifting from previous versions may wonder how .NET Standard is affecting those, and whether they can still work together in one solution.

Comments are closed.

Disclaimer: The opinions expressed herein are my own personal opinions and do not represent my employer's view in any way.