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

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 7 to 3.0 Preview 8 of .NET Core, ASP.NET Core, or EF Core, review the following topics for breaking changes that may affect your app:

CoreFx

Change in semantics of (string)null in Utf8JsonWriter

In .NET Core 3.0 Preview 7, the null string is treated as the empty string in Utf8JsonWriter. Starting with .NET Core 3.0 Preview 8, the null string throws an exception when used as a property name, and it emits the JSON null token when used as a value.

Change description

In .NET Core 3.0 Preview 7, the null string was treated as "" both when writing property names and when writing values.

Starting with .NET Core 3.0 Preview 8, a null property name throws an ArgumentNullException, and a null value is treated as a call to Utf8JsonWriter.WriteNull or Utf8JsonWriter.WriteNullValue().

Consider the following code:

string propertyName1 = null;
string propertyValue1 = null;
string propertyName2 = "prop2";
string propertyValue2 = null;
string simpleValue1 = null;

using (Utf8JsonWriter writer = new Utf8JsonWriter(stream))
{
    writer.WriteStartArray();

    writer.WriteStartObject();
    writer.WriteString(propertyName1, propertyValue1);
    writer.WriteString(propertyName2, propertyValue2);
    writer.WriteEndObject();

    writer.WriteStringValue(simpleValue1);

    writer.WriteEndArray();
}

If run with .NET Core 3.0 Preview 7, the writer produces the following output:

[{"":"","prop2":""},""]

Starting with .NET Core 3.0 Preview 8, the call to writer.WriteString(propertyName1, propertyValue1) throws an ArgumentNullException. If propertyName1 = null is replaced with propertyName1 = string.Empty, the output would now be:

[{"":null,"prop2":null},null]

This change was made to better align with caller expectations for null values.

Version introduced

3.0 Preview 8

When writing property names and values with the Utf8JsonWriter class:

  • Ensure non-null strings are used as property names.

  • If the previous behavior is desired, use a null coalescing invocation; for example, writer.WriteString(propertyName1 ?? "", propertyValue1).

  • If writing a null literal for a null string value is not desirable, use a null coalescing invocation; for example, writer.WriteString(propertyName2, propertyValue2 ?? "").

Category

CoreFx

Affected APIs

JsonEncodedText.Encode methods have an additional JavaScriptEncoder argument

Starting with .NET Core 3.0 Preview 8, the JsonEncodedText.Encode methods contain an optional JavaScriptEncoder argument.

Change description

.NET Core 3.0 includes a new type, xref:System.Text.Json.JsonEncodedText.Encode%2A?displayProperty=nameWithType>. Starting with .NET Core 3.0 Preview 8, the signature of all JsonEncodedText.Encode method overloads has changed to include an optional JavaScriptEncoder parameter. This change was made to allow for a different or custom encoder.

The signature of the Encode methods in .NET Core 3.0 Preview 7 is:

namespace System.Text.Json
{
    public readonly struct JsonEncodedText
    {
        public static JsonEncodedText Encode(ReadOnlySpan<byte> utf8Value);
        public static JsonEncodedText Encode(ReadOnlySpan<char> value);
        public static JsonEncodedText Encode(string value);
    }
}

The signature of the same Encode methods in .NET Core 3.0 Preview 8 and later versions is:

namespace System.Text.Json
{
    public readonly struct JsonEncodedText
    {
        public static JsonEncodedText Encode(ReadOnlySpan<byte> utf8Value, JavaScriptEncoder encoder = null);
        public static JsonEncodedText Encode(ReadOnlySpan<char> value, JavaScriptEncoder encoder = null);
        public static JsonEncodedText Encode(string value, JavaScriptEncoder encoder = null);
    }
}

Version introduced

.NET Core 3.0 Preview 8

This is a binary breaking change only; a recompile against .NET Core 3.0 Preview 8 or a later version will fix any runtime issues.

Category

CoreFx

Affected APIs

JsonEncodedText.Encode(ReadOnlySpan<Byte>, JavaScriptEncoder) JsonEncodedText.Encode(ReadOnlySpan<Char>, JavaScriptEncoder) JsonEncodedText.Encode(String, JavaScriptEncoder)

JsonFactoryConverter.CreateConverter signature changed

To facilitate the composition of JsonConverterFactory classes, the CreateConverter method has been made public and given a second argument of type JsonSerializerOptions.

Change description

The signature of the CreateConverter method in .NET Core prior to version 3.0 Preview 8 was:

namespace System.Text.Json.Serialization
{
    public abstract class JsonConverterFactory : JsonConverter
    {
        protected abstract JsonConverter CreateConverter(Type typeToConvert);
    }
}

In .NET Core 3.0 Preview 8 and later versions, it is:

namespace System.Text.Json.Serialization
{
    public abstract class JsonConverterFactory : JsonConverter
    {
        public abstract JsonConverter CreateConverter(Type typeToConvert, JsonSerializerOptions options);
    }
}

Before this change, it was difficult to compose sealed factory converters, since there was no easy way to get the JsonConverter<T> from it. Making the factory method public and also passing the current JsonSerializerOptions allow for much more flexible composition.

Version introduced

3.0 Preview 8

Derived classes need to be updated and recompiled.

Affected APIs

JsonConverterFactory.CreateConverter(Type, JsonSerializerOptions).

Cryptography

EnvelopedCms defaults to AES-256 encryption

The default symmetric encryption algorithm used by EnvelopedCms has changed from TripleDES to AES-256.

Change description

In .NET Core Preview 7 and earlier versions, when EnvelopedCms is used to encrypt data without specifying a symmetric encryption algorithm via a constructor overload, the data was encrypted with the TripleDES/3DES/3DEA/DES3-EDE algorithm.

Starting with .NET Core 3.0 Preview 8 (via version 4.6.0 of the System.Security.Cryptography.Pkcs NuGet package), the default algorithm has been changed to AES-256 for algorithm modernization and to improve the security of default options. If a message recipient certificate has a (non-EC) Diffie-Hellman public key, the encryption operation may fail with a CryptographicException due to limitations in the underlying platform.

In the following sample code, the data is encrypted with TripleDES if running on .NET Core 3.0 Preview 7 or earlier. If running on .NET Core 3.0 Preview 8 or later, it is encrypted with AES-256.

EnvelopedCms cms = new EnvelopedCms(content);
cms.Encrypt(recipient);
return cms.Encode();

Version introduced

3.0 Preview 8

If you are negatively impacted by the change, you can restore TripleDES encryption by explicitly specifying the encryption algorithm identifier in an EnvelopedCms constructor that includes a parameter of type AlgorithmIdentifier, such as:

Oid tripleDesOid = new Oid("1.2.840.113549.3.7", null);
AlgorithmIdentifier tripleDesIdentifier = new AlgorithmIdentifier(tripleDesOid);
EnvelopedCms cms = new EnvelopedCms(content, tripleDesIdentifier);

cms.Encrypt(recipient);
return cms.Encode()l

Category

Cryptography

Affected APIs

Visual Basic

Microsoft.VisualBasic.Constants.vbNewLine is obsolete

The Microsoft.VisualBasic.Constants.vbNewLine constant is marked Obsolete starting with .NET Core 3.0 Preview 8.

Version introduced

3.0 Preview 8

Change description

Starting with .NET Core 3.0 Preview 8, the Obsolete attribute has been applied to the Microsoft.VisualBasic.Constants.vbNewLine constant. Use of the constant produces a compiler warning. In previous releases of both .NET Core and .NET Framework, it was not marked as obsolete.

This change was made to support Visual Basic as a language for multi-platform development. The vbNewLine constant is equivalent to \r\n, the newline character sequence on Windows. On Unix-based systems, the newline character is \n.

The Obsolete attribute message for vbNewLine includes the following recommendation:

For a carriage return and line feed, use vbCrLf. For the current platform's newline, use Environment.NewLine.

Category

Visual Basic

Affected APIs

Entity Framework Core

Entity Framework Core breaking changes on GitHub