How To Target .NET Core 2.1

There is some pretty nifty new features making their way into .NET Core 2.1, many of which I’ll be blogging about in the near future. One of the not so nifty features is actually being able to target .NET Core 2.1. There is one or two headaches along the way that’s for sure.

Installing And Targeting .NET Core 2.1 SDK

Remember that .NET Core comes in two “parts” as it were. The “SDK” which is essentially the thing that does the “building” of your application, and the actual runtime which does the… running… of the application. The versions of these don’t always match up, but generally speaking when we are talking about .NET Core 2.1, we are talking about a specific version of the runtime. The versions might not always line up because there might be improvements to the “build” tools that don’t actually need a version bump of the runtime. This has caused a real stupid overlap of the versions as we will soon see…

Head over to the “all downloads” page and grab the latest SDK. It’s super important to download the latest SDK from this page, and not from the .NET Core homepage. The one on the homepage is the latest “stable” version that may not support 2.1 (Atleast it doesn’t at the time of writing).  The SDK also comes with the runtime that is vaguely matching (e.g. if you download the latest SDK, you’ll get the latest runtime). Because the version numbers don’t always line up, mostly be looking for the final screen that should atleast tell you you’ve installed a 2.1.0 runtime :

Once installed, from a command prompt run : dotnet –list-sdks . Which should in turn print something like :

1.0.0-preview2-003131 [C:\Program Files\dotnet\sdk]
1.0.0-preview2-1-003177 [C:\Program Files\dotnet\sdk]
1.0.0-rc4-004771 [C:\Program Files\dotnet\sdk]
1.0.0 [C:\Program Files\dotnet\sdk]
1.1.0 [C:\Program Files\dotnet\sdk]
2.0.0 [C:\Program Files\dotnet\sdk]
2.1.102 [C:\Program Files\dotnet\sdk]
2.1.105 [C:\Program Files\dotnet\sdk]
2.1.300-preview2-008533 [C:\Program Files\dotnet\sdk]

Don’t worry about earlier versions for the most part. Just make sure the last one is the one you just installed (It should be!). I just want to point out a major headache at this point. You’ll notice I have three versions of SDKs above 2.1.* And an interesting point about that is that only 2.1.300 actually supports building 2.1. If you try and build using the SDK version 2.1.105, it says it cannot build .NET Core 2.1 projects. Now I know that the versions won’t always line up… But it’s a hell of an annoyance.

Now in the root of your solution you want to “.NET Core 2.1-ify”. You want to add a global.json file to the solution folder or edit the existing one there. Inside this file, the contents should be similar to :

{
  "sdk": {
    "version": "2.1.300-preview2-008533"
  }
}

Where version is the very latest .NET Core SDK you downloaded. This actually becomes pretty important when you upgrade because you may have projects you want to use the “old” tooling. I actually already wrote a pretty indepth article on working with two different versions of an SDK side by side here. So if you want to know more about this global.json file does, head over there.

You can run dotnet –version  in your solution directory which will print out the SDK version it’s about to run. If all looks good (e.g. it’s the latest SDK version that you just installed), enter dotnet build . All going well it will build your project!

OK that’s cool, but so far we are just building a .NET Core 2.0 projects with a 2.1 SDK. So let’s change that.

Targeting Core 2.1 Runtime

Targeting the 2.1 runtime is as easy as opening up your projects .csproj file. And changing the TargetFramework tag.

<PropertyGroup>
  <TargetFramework>netcoreapp2.1</TargetFramework>
</PropertyGroup>

Head to your command prompt and run dotnet build  in your solution directory again. Everything should build fine. If instead you get :

C:\Program Files\dotnet\sdk\2.1.105\Sdks\Microsoft.NET.Sdk\build\Microsoft.NET.TargetFrameworkInference.targets(135,5): error : The current .NET SDK does not support targeting .NET Core 2.1.

Then it is *highly* likely you are building with the wrong SDK. The most likely scenario that I’ve found is that you’ve downloaded a “2.1 SDK” that doesn’t actually build 2.1 projects… As stupid as that sounds. Remember, the first SDK to actually be able to build 2.1 projects is 2.1.300-preview2-008533 . Anything earlier and it’s not gonna happen. The first part of the error actually tells you which SDK you are attempting to use, so make sure it’s the right one.

If you are a command line/notepad/VSCode kinda guy, then you should be all ready to go at this point. If you prefer using Visual Studio, read on!

Dealing With Visual Studio Messiness…

Now the interesting thing about using .NET Core 2.1 in Visual Studio is that VS kind of has it’s own way of doing things sometimes. And you’ll notice that if you open your project in Visual Studio you’ll be prompted with a message like so :

To be honest, I tried playing around with a few of the .NET Core 2.1 specific features and I couldn’t find anything that would outright break inside Visual Studio. But better safe than sorry!

When you want to update Visual Studio, you would typically go Help -> Check for Updates and pick up the update there. In this case you would be (sort of) wrong. At the time of writing Visual Studio version 15.7 is only available as a “preview” download and not as a regular update. If you are already on the latest update of the stable builds, you just get told that you’re all good and you can go away now.

Instead, inside Visual Studio go to Tools -> Get Tools and Features. You’ll be presented with a bunch of workloads that you can change in a sort of popup, instead hit the “X” up the top right of this window. On this screen you are left with, scroll right down to the bottom and select to install the “Preview” Visual Studio Version.

Unfortunately this installs an entirely new version of Visual Studio on your PC. Complete with taking up 5.65GB of your precious SSD space.

For this reason, you may want to wait a bit until these things make it into the regular stream (Or play solely with preview stuff in something like VS Code). I’m a sucker for punishment so I did install it and can confirm the annoying warning message when opening .NET Core 2.1 projects does go away.