Edit

Breaking changes in .NET Core 2.1

  • Article

If you're migrating to version 2.1 of .NET Core, the breaking changes listed in this article may affect your app.

Core .NET libraries

Path APIs don't throw an exception for invalid characters

APIs that involve file paths no longer validate path characters or throw an ArgumentException if an invalid character is found.

Change description

In .NET Framework and .NET Core 1.0 - 2.0, the methods listed in the Affected APIs section throw an ArgumentException if the path argument contains an invalid path character. Starting in .NET Core 2.1, these methods no longer check for invalid path characters or throw an exception if an invalid character is found.

Reason for change

Aggressive validation of path characters blocks some cross-platform scenarios. This change was introduced so that .NET does not try to replicate or predict the outcome of operating system API calls. For more information, see the System.IO in .NET Core 2.1 sneak peek blog post.

Version introduced

.NET Core 2.1

If your code relied on these APIs to check for invalid characters, you can add a call to Path.GetInvalidPathChars.

Affected APIs

See also

Private fields added to built-in struct types

Private fields were added to certain struct types in reference assemblies. As a result, in C#, those struct types must always be instantiated by using the new operator or default literal.

Change description

In .NET Core 2.0 and previous versions, some provided struct types, for example, ConsoleKeyInfo, could be instantiated without using the new operator or default literal in C#. This was because the reference assemblies used by the C# compiler didn't contain the private fields for the structs. All private fields for .NET struct types are added to the reference assemblies starting in .NET Core 2.1.

For example, the following C# code compiles in .NET Core 2.0, but not in .NET Core 2.1:

ConsoleKeyInfo key;    // Struct type

if (key.ToString() == "y")
{
    Console.WriteLine("Yes!");
}

In .NET Core 2.1, the previous code results in the following compiler error: CS0165 - Use of unassigned local variable 'key'

Version introduced

2.1

Instantiate struct types by using the new operator or default literal.

For example:

ConsoleKeyInfo key = new ConsoleKeyInfo();    // Struct type.

if (key.ToString() == "y")
    Console.WriteLine("Yes!");

ConsoleKeyInfo key = default;    // Struct type.

if (key.ToString() == "y")
    Console.WriteLine("Yes!");

Category

Core .NET libraries

Affected APIs

OpenSSL versions on macOS

The .NET Core 3.0 and later runtimes on macOS now prefer OpenSSL 1.1.x versions to OpenSSL 1.0.x versions for the AesCcm, AesGcm, DSAOpenSsl, ECDiffieHellmanOpenSsl, ECDsaOpenSsl, RSAOpenSsl, and SafeEvpPKeyHandle types.

The .NET Core 2.1 runtime now supports OpenSSL 1.1.x versions, but still prefers OpenSSL 1.0.x versions.

Change description

Previously, the .NET Core runtime used OpenSSL 1.0.x versions on macOS for types that interact with OpenSSL. The most recent OpenSSL 1.0.x version, OpenSSL 1.0.2, is now out of support. To keep types that use OpenSSL on supported versions of OpenSSL, the .NET Core 3.0 and later runtimes now use newer versions of OpenSSL on macOS.

With this change, the behavior for the .NET Core runtimes on macOS is as follows:

  • The .NET Core 3.0 and later version runtimes use OpenSSL 1.1.x, if available, and fall back to OpenSSL 1.0.x only if there's no 1.1.x version available.

    For callers that use the OpenSSL interop types with custom P/Invokes, follow the guidance in the SafeEvpPKeyHandle.OpenSslVersion remarks. Your app may crash if you don't check the OpenSslVersion value.

  • The .NET Core 2.1 runtime uses OpenSSL 1.0.x, if available, and falls back to OpenSSL 1.1.x if there's no 1.0.x version available.

    The 2.1 runtime prefers the earlier version of OpenSSL because the SafeEvpPKeyHandle.OpenSslVersion property does not exist in .NET Core 2.1, so the OpenSSL version cannot be reliably determined at run time.

Version introduced

  • .NET Core 2.1.16
  • .NET Core 3.0.3
  • .NET Core 3.1.2

Category

Core .NET libraries

Affected APIs

MSBuild

Project tools now included in SDK

The .NET Core 2.1 SDK now includes common CLI tooling, and you no longer need to reference these tools from the project.

Change description

In .NET Core 2.0, projects reference external .NET tools with the <DotNetCliToolReference> project setting. In .NET Core 2.1, some of these tools are included with the .NET Core SDK, and the setting is no longer needed. If you include references to these tools in your project, you'll receive an error similar to the following: The tool 'Microsoft.EntityFrameworkCore.Tools.DotNet' is now included in the .NET Core SDK.

Tools now included in .NET Core 2.1 SDK:

<DotNetCliToolReference> value Tool
Microsoft.DotNet.Watcher.Tools dotnet-watch
Microsoft.Extensions.SecretManager.Tools dotnet-user-secrets
Microsoft.Extensions.Caching.SqlConfig.Tools dotnet-sql-cache
Microsoft.EntityFrameworkCore.Tools.DotNet dotnet-ef

Version introduced

.NET Core SDK 2.1.300

Remove the <DotNetCliToolReference> setting from your project.

Category

MSBuild

Affected APIs

N/A

See also