Dot Net Core 1.0.1 & Semantic Versioning

What does it mean for you?

Dot Net Core 1.0.1 & Semantic Versioning

What does it mean for you?

This past week marked the first official patch update since .NET Core’s initial release. Naturally, the version number we have jumped up to is 1.0.1. If you spent any time with the beta’s and rc1-8, let me forewarn you now: DO NOT go open project.json and edit every single reference up to 1.0.1.

Firstly, in a basic Hello World or a Console App, the declaration the .NET Core version has changed very slightly.

"frameworks": {
  "netcoreapp1.0": {
    "dependencies": {
      "Microsoft.NETCore.App": {
        "version": "1.0.1"

For a while now (let’s say since the release of 1.0.0) we have known that Microsoft plans on using Semantic Versioning in order to simplify and further adopt some software best practices into their own package. See Microsoft’s explanation above or visit to learn more about it.

In short, the idea of Semantic Versioning is all packages are versioned as follows: major.minor.patch. In the case of .NET Core, this was a patch update (mainly to patch a vulnerability in System.Mvc). You can see the issue and advisory on GitHub and affected packages.

It is extremely recommended to update the necessary packages and runtime, as there are a few other minor updates including fixing some Linux 4.6 segfaults. Beyond that, the most release notes seem to belong to EF Core which has several packages updated to version 1.0.1.

One important thing to know and understand, however: you are in no way REQUIRED to upgrade. The actual idea behind the power of semantic versioning is that these patch upgrades (any update in the 1.0.x portion) should contain ZERO breaking changes. In fact, if you have a working application that 1.0.1 breaks, then you should absolutely submit an issue on GitHub as this should not be the case.

This is where things get interesting. Remember when I said “do not edit every single reference in project.json to 1.0.1”? Well, apparently Semantic Versioning has its pros and cons (see that link for Microsoft’s explanation).

Interestingly (and awesome-ly) you are also perfectly capable of running .NET 1.0.0 and 1.0.1 side by side.


You can see installing 1.0.1 does not wipe out 1.0.0, but my “active” runtime has been updated, visible from running dotnet --info in my command line. So in reality here, we have an update to the runtime and the SDK–which, note, is still in preview.

Seems simple enough, right? Here comes the confusion.

If you are in your command line after upgrading to 1.0.1 with tooling 1.0.0-preview2-003131, you can scaffold a web app using dotnet new -t web

Your process should look something like this:

Command Line Web Browser
Core 1.0.1 WebApp ASP.NET Core Debug
Or in order for your cmd line arguments: mkdir NewDotNet101 then
cd NewDotNew101 dotnet new -t web
You now should see the full directory structure as shown above. Almost ready to run.
dotnet restore (this may take a few minutes) dotnet run then will run the app by default on Port 5000

So let’s take a look at the full project.json file (shortened for readability) that we see now. Ironically, this is also exactly where the confusion comes in. After seeing the full platform version change to "version": "1.0.1", as you begin to scroll you may happen upon some confusion.

While the full framework and runtime has received a patch upgrade, as we read through the packages below you can see that NOT EVERY PACKAGE has been upgraded to 1.0.1. In fact, only a small subset of all the .NET Core & ASP.NET Core libraries have updated to 1.0.1.

  "userSecretsId": "aspnet-WebApplication-0799fe3e-6eaf-4c5f-b40e-7c6bfd5dfa9a",

  "dependencies": {
    "Microsoft.NETCore.App": {
      "version": "1.0.1",
      "type": "platform"
    "Microsoft.AspNetCore.Authentication.Cookies": "1.0.0",
    "Microsoft.AspNetCore.Diagnostics": "1.0.0",
    "Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore": "1.0.0",
    "Microsoft.AspNetCore.Identity.EntityFrameworkCore": "1.0.0",
    "Microsoft.AspNetCore.Mvc": "1.0.1",
    "Microsoft.AspNetCore.Razor.Tools": {
      "version": "1.0.0-preview2-final",
      "type": "build"
    "Microsoft.AspNetCore.Routing": "1.0.1",
    "Microsoft.AspNetCore.Server.IISIntegration": "1.0.0",
    "Microsoft.AspNetCore.Server.Kestrel": "1.0.1",
    "Microsoft.AspNetCore.StaticFiles": "1.0.0",
    "Microsoft.EntityFrameworkCore.Sqlite": "1.0.1",
    "Microsoft.EntityFrameworkCore.Tools": {
      "version": "1.0.0-preview2-final",
      "type": "build"

Now, honestly, I initially read/saw this and I basically just said “OK”. These days, with the trends in web dev, plus being somewhat accustomed to npm package versioning, NuGet, etc–it really didn’t sound all that crazy to me. Thankfully for us developers, there are people looking out for and advocating for developers and developer productivity. In this case, I’m referring to Scott Hanselman (@shanselman on Twitter) from the Microsoft ASP.NET team.

In the September 13th ASP.NET Community Standup, Scott makes the argument that we as developers need this type of upgrade automated or at least an ability to just type/hit a button and “Upgrade to LTS” or “Upgrade to FTS” or “Upgrade to Latest” (bleeding edge). In short, Scott makes 3 quick & simple points that landed me squarely on his side of the fence.

Scott argues that this style of manually upgrading (e.g., editing .json files extremely carefully) is completely untenable. Specifically, he feels that it is something that must be figured out because currently the process is:

  1. Manual
  2. Complicated
  3. Problematic for humans

Regardless of my finding this particular upgrade fairly painless, I absolutely see his point and understand exactly how quickly version numbers will begin to climb out of hand becomining impossible to keep track or remember which patch what package should be on.

I don’t think I can point to anyone who has solved this problem in any sort of decent manner. Scott also mentions how this is a real non-trivial issue. If you have any experience in the Node ecosystem, you can understand how problematic this can get, and just how quickly.

It will be very interesting to see what the Microsoft .NET Core team comes up with. On the same standup, Eilon Lipton and Glenn Condron accompany Scott & Jon Galloway whilst Damian Edwards is on vacation (though he does appear to still be watching the Community Standups ;)).

Eilon actually mentions a tool they had attempted to write to do exactly what Scott was alluding to in terms of an upgrade tool or an automated way to update all the necessary packages without any manual process. Unfortunately for us, as of now that is still being worked on, so manual updates it is!

I have closely followed .NET Core’s progress and began learning way back in rc4 and 5. I chose to leave it alone for a while, waiting for final release. Now, we are here, and we are ready. I absolutely love most everything that’s been done with the framework in terms of design decisions and am extremely excited to begin building and using in production.

Side note: Call to action for any and all Open Source contributors out there.

Especially if you are a user of log4net or would like to see it on .NET Core:

The Apache Software Foundation needs HELP. Apache log4net is a very robust logging framework that was born out of log4j and is extremely powerful. I, myself, have used it as my logging solution in several projects and continue to do so in some ASP.NET 4.5 & 4.6 solutions. Apache has issued a public call for arms from the community, especially those of us who still use log4net as their preferred framework.

Check out Apache’s blog post @… and feel free to get your hands dirty! They are asking for help and will take it any way they can.

Feel free to check their JIRA @ and

Dev mailing list @

Wrapping Up

Totally unrelated, but: Angular 2 has also released its “final” version! Timing couldn’t be better and we are heavily invested in these new technologies in terms of education & man-hours–I am giddy with excitement.

Aside from that, all I can do is hope that semver doesn’t turn into a developer nightmare (instead of npm package hell or nuget hell). Hopefully, some of the .NET tooling will also become significantly better as it is moved up out of beta. As much as a complete paradigm shift that the Core frameworks and open source are for Microsoft, I do not think they are getting out of the business of prescription and spreading “best practices.”

So fear not–we’re just barely getting past the bleeding edge here. :)

Categories: .NET Core
Tags: .net core, semver

Looking for something specific? Search.

comments powered by Disqus