diff --git a/docs/core/compatibility/2.2-3.0.md b/docs/core/compatibility/2.2-3.0.md index 10557902931cb..fd54929510c36 100644 --- a/docs/core/compatibility/2.2-3.0.md +++ b/docs/core/compatibility/2.2-3.0.md @@ -274,7 +274,6 @@ If you're migrating from version 2.2 to version 3.0 of .NET Core, ASP.NET Core, - [InvalidAsynchronousStateException moved to another assembly](#invalidasynchronousstateexception-moved-to-another-assembly) - [Replacing ill-formed UTF-8 byte sequences follows Unicode guidelines](#replacing-ill-formed-utf-8-byte-sequences-follows-unicode-guidelines) - [TypeDescriptionProviderAttribute moved to another assembly](#typedescriptionproviderattribute-moved-to-another-assembly) -- [JSON serializer exception type changed from JsonException to NotSupportedException](#json-serializer-exception-type-changed-from-jsonexception-to-notsupportedexception) - [Change in semantics of (string)null in Utf8JsonWriter](#change-in-semantics-of-stringnull-in-utf8jsonwriter) - [JsonEncodedText.Encode methods have an additional JavaScriptEncoder argument](#jsonencodedtextencode-methods-have-an-additional-javascriptencoder-argument) - [JsonFactoryConverter.CreateConverter signature changed](#jsonfactoryconvertercreateconverter-signature-changed) @@ -314,10 +313,6 @@ If you're migrating from version 2.2 to version 3.0 of .NET Core, ASP.NET Core, *** -[!INCLUDE[JSON serializer exception type changed from JsonException to NotSupportedException](~/includes/core-changes/corefx/3.0/serializer-throws-notsupportedexception.md)] - -*** - [!INCLUDE[JsonEncodedText.Encode methods have an additional JavaScriptEncoder argument](~/includes/core-changes/corefx/3.0/jsonencodedtext-encode-has-additional-argument.md)] *** diff --git a/docs/core/compatibility/2.2-3.1.md b/docs/core/compatibility/2.2-3.1.md index 45334e940f1e5..95850de28a2a5 100644 --- a/docs/core/compatibility/2.2-3.1.md +++ b/docs/core/compatibility/2.2-3.1.md @@ -277,7 +277,6 @@ If you're migrating from version 2.2 to version 3.1 of .NET Core, ASP.NET Core, - [InvalidAsynchronousStateException moved to another assembly](#invalidasynchronousstateexception-moved-to-another-assembly) - [Replacing ill-formed UTF-8 byte sequences follows Unicode guidelines](#replacing-ill-formed-utf-8-byte-sequences-follows-unicode-guidelines) - [TypeDescriptionProviderAttribute moved to another assembly](#typedescriptionproviderattribute-moved-to-another-assembly) -- [JSON serializer exception type changed from JsonException to NotSupportedException](#json-serializer-exception-type-changed-from-jsonexception-to-notsupportedexception) - [Change in semantics of (string)null in Utf8JsonWriter](#change-in-semantics-of-stringnull-in-utf8jsonwriter) - [JsonEncodedText.Encode methods have an additional JavaScriptEncoder argument](#jsonencodedtextencode-methods-have-an-additional-javascriptencoder-argument) - [JsonFactoryConverter.CreateConverter signature changed](#jsonfactoryconvertercreateconverter-signature-changed) @@ -313,10 +312,6 @@ If you're migrating from version 2.2 to version 3.1 of .NET Core, ASP.NET Core, *** -[!INCLUDE[JSON serializer exception type changed from JsonException to NotSupportedException](~/includes/core-changes/corefx/3.0/serializer-throws-notsupportedexception.md)] - -*** - [!INCLUDE[Change in semantics of `(string)null` in Utf8JsonWriter](~/includes/core-changes/corefx/3.0/change-in-null-in-utf8jsonwriter.md)] *** diff --git a/docs/core/compatibility/3.1-5.0.md b/docs/core/compatibility/3.1-5.0.md index 9f0d38628ae55..f01785b23da6a 100644 --- a/docs/core/compatibility/3.1-5.0.md +++ b/docs/core/compatibility/3.1-5.0.md @@ -174,6 +174,14 @@ If you're migrating from version 3.1 of .NET Core, ASP.NET Core, or EF Core to v *** +## Serialization + +- [BinaryFormatter.Deserialize rewraps some exceptions in SerializationException](#binaryformatterdeserialize-rewraps-some-exceptions-in-serializationexception) + +[!INCLUDE [binaryformatter-deserialize-rewraps-exceptions](../../../includes/core-changes/serialization/5.0/binaryformatter-deserialize-rewraps-exceptions.md)] + +*** + ## Windows Forms - [Removed status bar controls](#removed-status-bar-controls) diff --git a/docs/core/compatibility/corefx.md b/docs/core/compatibility/corefx.md index 1d80006bc07f6..39334e295953d 100644 --- a/docs/core/compatibility/corefx.md +++ b/docs/core/compatibility/corefx.md @@ -25,7 +25,6 @@ The following breaking changes are documented on this page: | [Replacing ill-formed UTF-8 byte sequences follows Unicode guidelines](#replacing-ill-formed-utf-8-byte-sequences-follows-unicode-guidelines) | 3.0 | | [TypeDescriptionProviderAttribute moved to another assembly](#typedescriptionproviderattribute-moved-to-another-assembly) | 3.0 | | [ZipArchiveEntry no longer handles archives with inconsistent entry sizes](#ziparchiveentry-no-longer-handles-archives-with-inconsistent-entry-sizes) | 3.0 | -| [JSON serializer exception type changed from JsonException to NotSupportedException](#json-serializer-exception-type-changed-from-jsonexception-to-notsupportedexception) | 3.0 | | [Change in semantics of (string)null in Utf8JsonWriter](#change-in-semantics-of-stringnull-in-utf8jsonwriter) | 3.0 | | [JsonEncodedText.Encode methods have an additional JavaScriptEncoder argument](#jsonencodedtextencode-methods-have-an-additional-javascriptencoder-argument) | 3.0 | | [JsonFactoryConverter.CreateConverter signature changed](#jsonfactoryconvertercreateconverter-signature-changed) | 3.0 | @@ -99,10 +98,6 @@ The following breaking changes are documented on this page: *** -[!INCLUDE[JSON serializer exception type changed from JsonException to NotSupportedException](~/includes/core-changes/corefx/3.0/serializer-throws-notsupportedexception.md)] - -*** - [!INCLUDE[Change in semantics of (string)null in Utf8JsonWriter](~/includes/core-changes/corefx/3.0/change-in-null-in-utf8jsonwriter.md)] *** diff --git a/docs/core/compatibility/serialization.md b/docs/core/compatibility/serialization.md new file mode 100644 index 0000000000000..a57ffb0a49bb9 --- /dev/null +++ b/docs/core/compatibility/serialization.md @@ -0,0 +1,18 @@ +--- +title: Serialization breaking changes +description: Lists the breaking changes in the serialization category in .NET Core and .NET 5.0 and later. +ms.date: 07/30/2020 +--- +# Serialization breaking changes + +The following breaking changes are documented on this page: + +| Breaking change | Introduced version | +| - | - | +| [BinaryFormatter.Deserialize rewraps some exceptions in SerializationException](#binaryformatterdeserialize-rewraps-some-exceptions-in-serializationexception) | 5.0 | + +## .NET Core 5.0 + +[!INCLUDE [binaryformatter-deserialize-rewraps-exceptions](../../../includes/core-changes/serialization/5.0/binaryformatter-deserialize-rewraps-exceptions.md)] + +*** diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 697f7c494c723..d347358947494 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -44,6 +44,8 @@ href: msbuild.md - name: Networking href: networking.md + - name: Serialization + href: serialization.md - name: Visual Basic href: visualbasic.md - name: Windows Forms diff --git a/includes/core-changes/categoryselector.md b/includes/core-changes/categoryselector.md index 199f12a1c060b..100287b46a4b1 100644 --- a/includes/core-changes/categoryselector.md +++ b/includes/core-changes/categoryselector.md @@ -7,5 +7,6 @@ > - [Globalization](~/docs/core/compatibility/globalization.md) > - [Interop](~/docs/core/compatibility/interop.md) > - [Networking](~/docs/core/compatibility/networking.md) +> - [Serialization](~/docs/core/compatibility/serialization.md) > - [Visual Basic](~/docs/core/compatibility/visualbasic.md) > - [Windows Forms](~/docs/core/compatibility/winforms.md) diff --git a/includes/core-changes/corefx/3.0/serializer-throws-notsupportedexception.md b/includes/core-changes/corefx/3.0/serializer-throws-notsupportedexception.md deleted file mode 100644 index 3e90935e19c24..0000000000000 --- a/includes/core-changes/corefx/3.0/serializer-throws-notsupportedexception.md +++ /dev/null @@ -1,42 +0,0 @@ -### Json serializer exception type changed from `JsonException` to `NotSupportedException` - -In .NET Core 3.0 Preview 6 through 8, the serializer would throw a when it encountered an unsupported derived collection type. Starting in .NET Core 3.0 Preview 9, the serializer throws a instead. - -#### Change description - -In .NET Core 3.0 Preview 6 through Preview 8, the serializer would throw a 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: - -- -- -- -- -- -- [IDictionary\](xref:System.Collections.Generic.IDictionary%602) - -Starting with .NET Core 3.0 Preview 9, the serializer throws a When encountering an unsupported collection type. The new exception type better reflects why the deserialization operation is failing. - -#### Version introduced - -3.0 Preview 9 - -#### Recommended action - -If you're catching when deserializing, you might want to consider also catching . - -#### Category - -Core .NET libraries - -#### Affected APIs - -- -- - - diff --git a/includes/core-changes/serialization/5.0/binaryformatter-deserialize-rewraps-exceptions.md b/includes/core-changes/serialization/5.0/binaryformatter-deserialize-rewraps-exceptions.md new file mode 100644 index 0000000000000..5aeec29aa504c --- /dev/null +++ b/includes/core-changes/serialization/5.0/binaryformatter-deserialize-rewraps-exceptions.md @@ -0,0 +1,58 @@ +### BinaryFormatter.Deserialize rewraps some exceptions in SerializationException + +The method now rewraps some exception objects inside a before propagating the exception back to the caller. + +#### Change description + +Previously, the method allowed some arbitrary exceptions, such as , to propagate up the stack to its callers. + +In .NET 5.0 and later, the method more aggressively catches exceptions that occur due to invalid deserialization operations and wraps them in a . + +#### Version introduced + +5.0 Preview 1 + +#### Recommended action + +In most cases, you don't need to take any action. However, if your call site depends on a particular exception being thrown, you can unwrap the exception from the outer , as shown in the following example. + +```csharp +Stream inputStream = GetInputStream(); +var formatter = new BinaryFormatter(); + +try +{ + object deserialized = formatter.Deserialize(inputStream); +} +catch (MyException myEx) +{ + // Handle 'myEx' here in case it was thrown directly. +} +catch (SerializationException serEx) +{ + if (serEx.InnerException is MyException myEx) + { + // Handle 'myEx' here in case it was wrapped in SerializationException. + } + else + { + throw; + } +} +``` + +#### Category + +Serialization + +#### Affected APIs + +- + +