We’re excited to announce the release of .NET Core 2.1. It includes improvements to performance, to the runtime and tools. It also includes a new way to deploy tools as NuGet packages. We’ve added a new primitive type called Span<T> that operates on data without allocations. There are many other new APIs, focused on cryptography, compression, and Windows compatibility. It is the first release to support Alpine Linux and ARM32 chips. You can start updating existing projects to target .NET Core 2.1 today. The release is compatible with .NET Core 2.0, making updating easy.

ASP.NET Core 2.1 and Entity Framework Core 2.1 are also releasing today.

You can download and get started with .NET Core 2.1, on Windows, macOS, and Linux:

.NET Core 2.1 is supported by Visual Studio 15.7, Visual Studio for Mac and Visual Studio Code.

Docker images are available at microsoft/dotnet for .NET Core and ASP.NET Core.

The Build 2018 conference was earlier this month. We had several in-depth presentations on .NET Core. Check out Build 2018 sessions for .NETon Channel9.

You can see complete details of the release in the .NET Core 2.1 release notes. Related instructions, known issues, and workarounds are included in the releases notes. Please report any issues you find in the comments or at dotnet/core #1614

Thanks for everyone that contributed to .NET Core 2.1. You’ve helped make .NET Core a better product!

Long-term Support

.NET Core 2.1 will be a long-term support (LTS) release. This means that it is supported for three years. We recommend that you make .NET Core 2.1 your new standard for .NET Core development.

We intend to ship a small number of significant updates in the next 2-3 months and then officially call .NET Core 2.1 an LTS release. After that, updates will be targeted on security, reliability, and adding platform support (for example, Ubuntu 18.10). We recommend that you start adopting .NET Core 2.1 now. For applications in active development, there is no reason to hold off deploying .NET Core 2.1 into production. For applications that will not be actively developed after deployment, we recommend waiting to deploy until .NET Core 2.1 has been declared as LTS.

There are a few reasons to move to .NET Core 2.1:

  • Long-term support.
  • Superior performance and quality.
  • New platform support, such as: Ubuntu 18.04, Alpine, ARM32.
  • Much easier to manage .NET Core and ASP.NET Core versions in project files and with self-contained application publishing.

We had many requests to make .NET Core 2.0 an LTS release. In fact, that was our original plan. We opted to wait until we had resolved various challenges managing platform dependencies (the last point above). Platform dependency management was a significant problem with .NET Core 1.0 and has gotten progressively better with each release. For example, you will notice that the ASP.NET Core package references no longer include a version number with .NET Core 2.1.

Platform Support

.NET Core 2.1 is supported on the following operating systems:

  • Windows Client: 7, 8.1, 10 (1607+)
  • Windows Server: 2008 R2 SP1+
  • macOS: 10.12+
  • RHEL: 6+
  • Fedora: 26+
  • Ubuntu: 14.04+
  • Debian: 8+
  • SLES: 12+
  • openSUSE: 42.3+
  • Alpine: 3.7+

Note: The runtime ID for Alpine was previously alpine-3.6. There is now a more generic runtime ID for Alpine and similar distros, called linux-musl, to support any Linux distro that uses musl libc. All of the other runtime IDs assume glibc.

Chip support follows:

  • x64 on Windows, macOS, and Linux
  • x86 on Windows
  • ARM32 on Linux (Ubuntu 18.04+, Debian 9+)

Note: .NET Core 2.1 is supported on Raspberry Pi 2+. It isn’t supported on the Pi Zero or other devices that use an ARMv6 chip. .NET Core requires ARMv7 or ARMv8 chips, like the ARM Cortex-A53.

If you are new to Raspberry Pi, I suggest the awesome Pi resources at AdaFruit. You can buy a Pi there, too.

Major thanks to Samsung and Qualcomm for investing heavily on .NET Core ARM32 and ARM64 implementations. Please thank them, too! These contributions speak to the value of open-source.

.NET Core Tools

.NET Core now has a new deployment and extensibility mechanism for tools. This new experience is very similar to and was inspired by NPM global tools. You can create your own global tools by looking at the dotnetsay tools sample.

You can try the new tools experience with the dotnetsay tool with the following commands:

dotnet tool install -g dotnetsay
dotnetsay

.NET Core tools are .NET Core console apps that are packaged and acquired as NuGet packages. By default, these tools are framework-dependent applications and include all of their NuGet dependencies. This means that .NET Core tools run on all .NET Core supported operating system and chip architecture by default, with one set of binaries. By default, the dotnet tool install command looks for tools on NuGet.org. You can use your own NuGet feeds instead.

At present, .NET Core Tools only support global install and require the -g argument to be installed. We’re working on various forms of local install, too, and plan to deliver that in a subsequent release.

We expect a whole new ecosystem of tools to establish itself for .NET. @natemcmaster maintains a list of dotnet tools. You might also check out his dotnet-serve tool.

The following existing DotNetCliReferenceTool tools have been converted to in-box tools.

  • dotnet watch
  • dotnet dev-certs
  • dotnet user-secrets
  • dotnet sql-cache
  • dotnet ef

Remove project references to these tools when you upgrade to .NET Core 2.1.

Build Performance Improvements

Improving the performance of the .NET Core build was perhaps the biggest focus of the release. It is greatly improved in .NET Core 2.1, particularly for incremental builds. These improvements apply to both dotnet build on the command line and to builds in Visual Studio.

The following image shows the improvements that we’ve made, compared to .NET Core 2.0. We focused on large projects, as you can see from the image.

.NET Core 2.1 Incremental Build-time performance improvements

.NET Core 2.1 Incremental Build-time performance improvements

Note: 2.1 in the image refers to the 2.1.300 SDK version.

Note: These benchmarks were produced from projects at mikeharder/dotnet-cli-perf.

We added long-running servers to the .NET Core SDK to improve the performance of common development operations. The servers are additional processes that run for longer than a single dotnet build invocation. Some of these are ports from the .NET Framework and others are new.

The following SDK build servers have been added:

  • VBCSCompiler
  • MSBuild worker processes
  • Razor server

The primary benefit of these servers is that they skip the need to JIT compile large blocks of code on every dotnet build invocation. They auto-terminate after a period of time. See release notes for more information on finer control of these build servers.

Runtime Performance Improvements

See Performance Improvements in .NET Core 2.1 for an in-depth exploration of all the performance improvements in the release.

Networking Performance Improvements

We built a new from-the-ground-up HttpClientHandler called SocketsHttpHandler to improve networking performance. It’s a C# implementation of HttpClient based on .NET sockets and Span<T>.

SocketsHttpHandler is now the default implementation for HttpClient. The biggest win of SocketsHttpHandler is performance. It is a lot faster than the existing implementation. It also eliminates platform-specific dependencies and enables consistent behavior across operating systems.

See the .NET Core 2.1 release notes for instructions on how to enable the older networking stack.

Span<T>, Memory<T>, and friends

We are entering a new era of memory-efficient and high-performance computing with .NET, with the introduction of Span<T> and related types. Today, if you want to pass the first 1000 elements of a 10,000 element array, you need to make a copy of those 1000 elements and pass that copy to your caller. That operation is expensive in both time and space. The new Span<T> type enables you to provide a virtual view of that array without the time or space cost. Span<T> is a struct, which means that you can enable complex pipelines of parsing or other computation without allocating. We are using this new type extensively in corefx for this reason.

Jared Parsons gives a great introduction in his Channel 9 video C# 7.2: Understanding Span. Stephen Toub goes into even more detail in C# – All About Span: Exploring a New .NET Mainstay.

In the most simple use case, you can cast an array to a Span<T>, as follows.

var arr = new byte[10];
Span<byte> bytes = arr; // Implicit cast from T[] to Span<T>
view rawspan.cs hosted with ❤ by GitHub

You can Slice a Span<T>, as follows.

// generating data for the example
int[] ints = new int[100];
for (var i = 0; i < ints.Length; i++)
{
ints[i] = i;
}
// creating span of array
Span<int> spanInts = ints;
// slicing the span, which creates another (subset) span
Span<int> slicedInts = spanInts.Slice(start: 42, length: 2);
// printing composition of the array and two spans
Console.WriteLine($”ints length: {ints.Length});
Console.WriteLine($”spanInts length: {spanInts.Length});
Console.WriteLine($”slicedInts length: {slicedInts.Length});
Console.WriteLine(slicedInts contents);
for (var i = 0; i < slicedInts.Length; i++)
{
Console.WriteLine(slicedInts[i]);
}
// performing tests to validate the span has the expected contents
if (slicedInts[0] != 42) Console.WriteLine(error);
if (slicedInts[1] != 43) Console.WriteLine(error);
slicedInts[0] = 21300;
if (slicedInts[0] != ints[42]) Console.WriteLine(error);
// printing composition of subset span
Console.WriteLine(slicedInts contents);
for (var i = 0; i < slicedInts.Length; i++)
{
Console.WriteLine(slicedInts[i]);
}
view rawspan-slice.cs hosted with ❤ by GitHub

This code produces the following output:

ints length: 100
spanInts length: 100
slicedInts length: 2
slicedInts contents
42
43
slicedInts contents
21300
43

Brotli Compression

Brotli is a general-purpose lossless compression algorithm that compresses data comparable to the best currently available general-purpose compression methods. It is similar in speed to deflate but offers more dense compression. The specification of the Brotli Compressed Data Format is defined in RFC 7932. The Brotli encoding is supported by most web browsers, major web servers, and some CDNs (Content Delivery Networks). The .NET Core Brotli implementation is based around the c code provided by Google at google/brotli. Thanks, Google!

Brotli support has been added to .NET Core 2.1. Operations may be completed using either the stream-based BrotliStream or the high-performance span-based BrotliEncoder/BrotliDecoder classes. You can see it used in the following example.

using System;
using System.IO;
using System.IO.Compression;
using System.Net.Http;
using System.Threading.Tasks;
using static System.Console;
namespace BrotliApp
{
class Program
{
static readonly string s_URL = https://raw.githubusercontent.com/dotnet/core/master/README.md;
static async Task Main(string[] args)
{
var client = new HttpClient();
var response = await client.GetAsync(s_URL,HttpCompletionOption.ResponseHeadersRead);
var stream = await response.Content.ReadAsStreamAsync();
WriteLine($”Request URL: {s_URL});
WriteLine($”Initial content length: {response.Content.Headers.ContentLength});
var compressedStream = CompressWithBrotli(stream);
WriteLine($”Compressed content length: {compressedStream.Length});
var decompressedStream = DecompressWithBrotli(compressedStream);
WriteLine($”Decompressed content length: {decompressedStream.Length});
WriteLine($”Compression ratio: {100 (Decimal.Divide(compressedStream.Length, response.Content.Headers.ContentLength.Value)*100):N1}%);
WriteLine(First 10 lines of decompressed content);
WriteLine();
var reader = new StreamReader(decompressedStream);
for (var i = 0; i < 10; i++)
{
WriteLine(reader.ReadLine());
}
}
public static Stream CompressWithBrotli(Stream toCompress)
{
MemoryStream compressedStream = new MemoryStream();
using (BrotliStream compressionStream = new BrotliStream(compressedStream, CompressionMode.Compress, leaveOpen: true))
{
toCompress.CopyTo(compressionStream);
}
compressedStream.Position = 0;
return compressedStream;
}
public static Stream DecompressWithBrotli(Stream toDecompress)
{
MemoryStream decompressedStream = new MemoryStream();
using (BrotliStream decompressionStream = new BrotliStream(toDecompress, CompressionMode.Decompress, leaveOpen: true))
{
decompressionStream.CopyTo(decompressedStream);
}
decompressedStream.Position = 0;
return decompressedStream;
}
}
}
view rawbrotli-app.cs hosted with ❤ by GitHub

This code produces the following output:

Request URL: https://raw.githubusercontent.com/dotnet/core/master/README.md
Initial content length: 2244
Compressed content length: 727
Decompressed content length: 2244
Compression ratio: 67.6%
First 10 lines of decompressed content

# .NET Core Home
The dotnet/core repository is a good starting point for .NET Core.
The latest major release is [.NET Core 2.1](release-notes/2.1/2.1.0.md). The latest patch updates are listed in [.NET Core release notes](release-notes/README.md)
## Download the latest .NET Core SDK
* [.NET Core 2.1 SDK](release-notes/download-archives/2.1.0-download.md)

New Cryptography APIs

The following enhancements have been made to .NET Core cryptography APIs:

  • New SignedCms APIs — System.Security.Cryptography.Pkcs.SignedCms is now available in the System.Security.Cryptography.Pkcspackage. The .NET Core implementation is available to all .NET Core platforms and has parity with the class from .NET Framework. See: dotnet/corefx #14197.
  • New X509Certificate.GetCertHash overload for SHA-2 — New overloads for X509Certificate.GetCertHash and X509Certificate.GetCertHashString accept a hash algorithm identifier to enable callers to get certificate thumbprint values using algorithms other than SHA-1. dotnet/corefx #16493.
  • New Span<T>-based cryptography APIs — Span-based APIs are available for hashing, HMAC, (cryptographic) random number generation, asymmetric signature generation, asymmetric signature processing, and RSA encryption.
  • Rfc2898DeriveBytes performance improvements — The implementation of Rfc2898DeriveBytes (PBKDF2) is about 15% faster, based on using Span<T>-based. Users who benchmarked an iteration count for an amount of server time may want to update iteration count accordingly.
  • Added CryptographicOperations class — CryptographicOperations.FixedTimeEquals takes a fixed amount of time to return for any two inputs of the same length, making it suitable for use in cryptographic verification to avoid contributing to timing side-channel information. CryptographicOperations.ZeroMemory is a memory clearing routine that cannot be optimized away via a write-without-subsequent-read optimization.
  • Added static RandomNumberGenerator.Fill — The static RandomNumberGenerator.Fill will fill a Span with random values using the system-preferred CSPRNG, and does not require the caller to manage the lifetime of an IDisposable resource.
  • Added support for RFC 3161 cryptographic timestamps — New API to request, read, validate, and create TimestampToken values as defined by RFC 3161.
  • Add Unix EnvelopedCms — The EnvelopedCms class has been added for Linux and macOS.
  • Added ECDiffieHellman — Elliptic-Curve Diffie-Hellman (ECDH) is now available on .NET Core via the ECDiffieHellman class family with the same surface area as .NET Framework 4.7.
  • Added RSA-OAEP-SHA2 and RSA-PSS to Unix platforms — Starting with .NET Core 2.1 the instance provided by RSA.Create() can always encrypt or decrypt with OAEP using a SHA-2 digest, as well as generate or validate signatures using RSA-PSS

Windows Compatibility Pack

When you port existing code from the .NET Framework to .NET Core, you can use the Windows Compatibility Pack. It provides access to an additional 20,000 APIs, compared to what is available in .NET Core. This includes System.Drawing, EventLog, WMI, Performance Counters, and Windows Services. See Announcing the Windows Compatibility Pack for .NET Core for more information.

The following example demonstrates accessing the Windows registry with APIs provided by the Windows Compatibility Pack.

private static string GetLoggingPath()
{
// Verify the code is running on Windows.
if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
{
using (var key = Registry.CurrentUser.OpenSubKey(@”Software\Fabrikam\AssetManagement))
{
if (key?.GetValue(LoggingDirectoryPath) is string configuredPath)
return configuredPath;
}
}
// This is either not running on Windows or no logging path was configured,
// so just use the path for non-roaming user-specific data files.
var appDataPath = Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData);
return Path.Combine(appDataPath, Fabrikam, AssetManagement, Logging);
}

Tiered Compilation

We’ve added a preview of a new and exciting capability to the runtime called tiered compilation. It’s a way for the runtime to more adaptively use the Just-In-Time (JIT) compiler to get better performance.

The basic challenge for JIT compilers is that compilation time is part of the application’s execution time. Producing better code usually means spending more time optimizing it. But if a given piece of code only executes once or just a few times, the compiler might spend more time optimizing it than the application would spend just running an unoptimized version.

With tiered compilation, the compiler first generates code as quickly as possible, with only minimal optimizations (first tier). Then, when it detects that certain methods are executed a lot, it produces a more optimized version of those methods (second tier) that are then used instead. The second tier compilation is performed in parallel, which removes the tension between fast compile speeds and producing optimal code. This model can be more generically called Adaptive optimization.

Tiered compilation is also beneficial for long-running applications, such as web servers. We’ll go into more detail in follow-on posts, but the short version is that the JIT can produce much better code than is in the pre-compiled assemblies we ship for .NET Core itself. This is mostly due to the fragile binary interface problem. With tiered compilation, the JIT can use the pre-compiled code it finds for .NET Core and then JIT-compile better code for methods that get called a lot. We’ve seen this scenario having a large impact for the tests in our performance lab.

You can test tiered compilation with by setting an environment variable:

COMPlus_TieredCompilation="1"

You can enable tiered compilation for an application by setting the TieredCompilation property, as you can see done in this project.

SourceLink

SourceLink is a system that enables a source debugging experiences for binaries that you either distribute or consume. It requires producers of SourceLink information and debuggers that support it. The Visual Studio debugger already supports SourceLink, starting with Visual Studio 2017 15.3. We have added support for generating SourceLink information in symbols, binaries, and NuGet packages in the .NET Core 2.1 RC SDK.

You can start producing SourceLink information by following the example at dotnet/sourcelink. You can see how it is enable in this project.

Our goal for the project is to enable anyone building NuGet libraries to provide source debugging for their users with almost no effort. There are a few steps left to enable the full experience, but you can get started now.

The following screenshot demonstrates debugging a NuGet package referenced by an application, with source automatically downloaded from GitHub and used by Visual Studio 2017.

sourcelink-example

Self-contained application publishing

dotnet publish now publishes self-contained applications with a serviced runtime version. When you publish a self-contained application with the new SDK, your application will include the latest serviced runtime version known by that SDK. When you upgrade to the latest SDK, you’ll publish with the latest .NET Core runtime version. This applies for .NET Core 1.0 runtimes and later.

Self-contained publishing relies on runtime versions on NuGet.org. You do not need to have the serviced runtime on your machine.

Using the .NET Core 2.0 SDK, self-contained applications are published with .NET Core 2.0.0 Runtime unless a different version is specified via the RuntimeFrameworkVersion property. With this new behavior, you’ll no longer need to set this property to select a higher runtime version for self-contained application. The easiest approach going forward is to always install and publish with the latest SDK.

Docker

Docker images for .NET Core 2.1 are available at microsoft/dotnet on Docker Hub. We’ve made a few changes relative to .NET Core 2.0. We have consolidating the set of Docker Hub repositories that we use for .NET Core and ASP.NET Core. We will use microsoft/dotnet as the only repository that we publish to for .NET Core 2.1 and later releases.

We added a set of environment variables to .NET Core images to make it easier to host ASP.NET Core sites at any .NET Core image layer and to enable dotnet watch in SDK container images without additional configuration.

.NET Core Docker Samples have been moved to the dotnet/dotnet-docker repo. The samples have been updated for .NET Core 2.1. New samples have been added, including Hosting ASP.NET Core Images with Docker over HTTPS.

For more information, see .NET Core 2.1 Docker Image Updates.

.NET Core 2.1 and Compatibility

.NET Core 2.1 is a highly compatible release. .NET Core 2.0 applications will run on .NET Core 2.1 in absence of .NET Core 2.0 being installed. This roll-forward behavior only applies to minor releases. .NET Core 1.1 will not roll-forward to 2.0, nor will .NET Core 2.0 roll-forward to 3.0.

See the .NET Core 2.1 release notes for instructions on how to disable minor-version roll-forward.

If you built .NET Core 2.1 applications or tools with .NET Core 2.1 preview releases, they must be rebuilt with the final .NET Core 2.1 release. Preview releases do not roll-forward to final releases.

Early Snap Installer Support

We have been working on bringing .NET Core to Snap and are ready to hear what you think. Snaps, along with a few other technologies, are an emerging application installation and sandboxing technology that we think is intriguing. The Snap install works well on Debian-based systems and other distros such as Fedora are having challenges that we’re working to run down. The following steps can be used if you would like to give this a try.

.NET Core 2.1 Runtime and SDK snaps are available:

  • sudo snap install dotnet-sdk --candidate --classic
  • sudo snap install dotnet-runtime-21 --candidate

Watch for future posts delving into what Snaps are about. In the meantime, we would love to hear your feedback.

Closing

.NET Core 2.1 is a big step forward for the platform. We’ve significantly improved performance, added many APIs, and added a new way of deploying tools. We’ve also added support for new Linux distros and ARM32, another CPU type. This release expands the places you can use .NET Core and makes it much more efficient everywhere.

We expect .NET Core 2.1 to be available in Azure App Service later this week.

You can see the progress we made with the .NET Core 2.1 interim releases: RC1Preview 2Preview 1. Thanks again to everyone who contributed to the release. It helps a lot.