dotnet · gewarren · Jul 31, 2020 · Jul 30, 2020 · Jul 30, 2020 · Jul 31, 2020
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
diff --git a/...ore-changes/serialization/5.0/binaryformatter-deserialize-rewraps-exceptions.md b/...ore-changes/serialization/5.0/binaryformatter-deserialize-rewraps-exceptions.md
@@ -0,0 +1,58 @@
+### BinaryFormatter.Deserialize rewraps some exceptions in SerializationException
+
+The <xref:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter.Deserialize%2A?displayProperty=nameWithType> method now rewraps some exception objects inside a <xref:System.Runtime.Serialization.SerializationException> before propagating the exception back to the caller.
+
+#### Change description
+
+Previously, the <xref:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter.Deserialize%2A?displayProperty=nameWithType> method allowed some arbitrary exceptions, such as <xref:System.ArgumentNullException>, to propagate up the stack to its callers.
+
+In .NET 5.0 and later, the <xref:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter.Deserialize%2A?displayProperty=nameWithType> method more aggressively catches exceptions that occur due to invalid deserialization operations and wraps them in a <xref:System.Runtime.Serialization.SerializationException>.
+
+#### 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 <xref:System.Runtime.Serialization.SerializationException>, 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
+
+- <xref:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter.Deserialize%2A?displayProperty=fullName>
+
+<!--
+
+#### Affected APIs
+
+- `Overload:System.Runtime.Serialization.Formatters.Binary.BinaryFormatter.Deserialize`
+
+-->