Breaking changes for migration from Version 3.0 Preview 8 to 3.0 Preview 9

Important

This article is under construction. This is not a complete list of .NET Core breaking changes. For more information on .NET Core breaking changes, you can examine individual breaking changes issues in the dotnet/docs repository on GitHub.

If you are migrating from 3.0 Preview 8 to 3.0 Preview 9 of .NET Core, ASP.NET Core, or EF Core, review the following topics for breaking changes that may affect your app:

CoreFx

Json serializer exception type changed from JsonException to NotSupportedException

In .NET Core 3.0 Preview 6 through 8, the serializer would throw a JsonException when it encountered an unsupported derived collection type. Starting in .NET Core 3.0 Preview 9, the serializer throws a NotSupportedException instead.

Change description

In .NET Core 3.0 Preview 6 through Preview 8, the serializer would throw a JsonException when it encountered an unsupported derived collection type. An unsupported derived collection type is any collection type that isn't assignable to one of the following types:

Starting with .NET Core 3.0 Preview 9, the serializer throws a NotSupportedException When encountering an unsupported collection type. The new exception type better reflects why the deserialization operation is failing.

Version introduced

3.0 Preview 9

If you're catching JsonException when deserializing, you might want to consider also catching NotSupportedException.

Category

CoreFx

Affected APIs

Cryptography

Better argument validation in the Pkcs8PrivateKeyInfo constructor

Starting with .NET Core 3.0 Preview 9, the Pkcs8PrivateKeyInfo constructor validates the algorithmParameters parameter as a single BER-encoded value.

Change description

Before .NET Core 3.0 Preview 9, the Pkcs8PrivateKeyInfo constructor did not validate the algorithmParameters argument. When this argument represented an invalid value, the constructor would succeed, but a call to any of the Encode(), TryEncode, Encrypt, or TryEncrypt methods would throw either an ArgumentException for an argument they did not accept (preEncodedValue) or a CryptographicException.

If run with .NET Core 3.0 before Preview 9, the following code throws an exception only when the Encode() method is called:

byte[] algorithmParameters = { 0x05, 0x00, 0x05, 0x00 };

var info = new Pkcs8PrivateKeyInfo(algorithmId, algorithmParameters, privateKey);
// This line throws an ArgumentException for `preEncodedValue`:
byte[] encoded = info.Encode();

Starting with .NET Core 3.0 Preview 9, the argument is validated in the constructor, and an invalid value results in the method throwing a CryptographicException. This change moves the exception closer to the source of the data error. For example:

byte[] algorithmParameters = { 0x05, 0x00, 0x05, 0x00 };

// This line throws a CryptographicException
var info = new Pkcs8PrivateKeyInfo(algorithmId, algorithmParameters, privateKey);

Version introduced

3.0 Preview 9

Ensure that only valid algorithmParameters values are provided, or that calls to the Pkcs8PrivateKeyInfo constructor test for both ArgumentException and CryptographicException if exception handling is desired.

Category

Cryptography

Affected APIs