BinaryFormatter Migration Guide

docs/fundamentals/toc.yml

@@ -861,6 +861,30 @@ items:
                     href: ../standard/serialization/xml-schema-definition-tool-xsd-exe.md
           - name: Binary serialization
             items:
+              - name: BinaryFormatter migration guide
+                items:
+                  - name: Overview
+                    href: ../standard/serialization/binaryformatter-migration-guide/overview.md
+                  - name: Choose a serializer
+                    href: ../standard/serialization/binaryformatter-migration-guide/choose-a-serializer.md
+                  - name: Migration to DataContractSerializer
+                    href: ../standard/serialization/binaryformatter-migration-guide/migration-to-data-contract-serializer.md
+                  - name: Migration to System.Text.Json
+                    href: ../standard/serialization/binaryformatter-migration-guide/migration-to-system-text-json.md
+                  - name: Migration to MessagePack
+                    href: ../standard/serialization/binaryformatter-migration-guide/migration-to-message-pack.md
+                  - name: Migration to protobuf-net
+                    href: ../standard/serialization/binaryformatter-migration-guide/migration-to-protobuf-net.md
+                  - name: Read NRBF payloads
+                    href: ../standard/serialization/binaryformatter-migration-guide/read-nrbf-payloads.md
+                  - name: Compatibility package
+                    href: ../standard/serialization/binaryformatter-migration-guide/compatibility-package.md
+                  - name: BinaryFormatter functionality reference
+                    href: ../standard/serialization/binaryformatter-migration-guide/functionality-reference.md
+                  - name: WinForms Migration Guide
+                    href: ../standard/serialization/binaryformatter-migration-guide/winforms-migration-guide.md
+                  - name: WinForms/WPF Clipboard and Drag/Drop Guidance
+                    href: ../standard/serialization/binaryformatter-migration-guide/winforms-wpf-ole-guidance.md
               - name: BinaryFormatter security guide
                 href: ../standard/serialization/binaryformatter-security-guide.md
               - name: BinaryFormatter event source

docs/standard/serialization/binaryformatter-migration-guide/choose-a-serializer.md

@@ -0,0 +1,33 @@
+---
+title: "BinaryFormatter Migration Guide: Choose a serializer"
+description: "Compare the capabilities and trade-offs of serializers to choose a replacement for BinaryFormatter."
+ms.date: 5/31/2024
+no-loc: [BinaryFormatter, Serialization]
+helpviewer_keywords:
+  - "BinaryFormatter"
+  - "serializing objects"
+  - "serialization"
+  - "objects, serializing"
+---
+
+# Choose a serializer
+
+Choosing a serializer format boils down to two questions:
+
+- Is compact binary representation important for your scenario? If so, you need to switch to a different binary serializer. .NET open-source ecosystem provides many great binary serializers and we recommend two of them: [MessagePack](./migration-to-message-pack.md) and [protobuf-net](./migration-to-protobuf-net.md). If compact binary representation is not a must have, you can consider using JSON and XML serialization. For XML, we recommend [DataContractSerializer](./migration-to-data-contract-serializer.md) and for JSON the [System.Text.Json](./migration-to-system-text-json.md).
+- Can you modify the types that are being serialized by annotating them with attributes, adding new constructors, making the types public and changing fields to properties? If not, using the modern serializers might require more work (like implementing custom converters or resolvers).
+
+| Feature                                        | BinaryFormatter | DataContractSerializer | System.Text.Json        | MessagePack              | protobuf-net                      |
+|------------------------------------------------|-----------------|------------------------|-------------------------|--------------------------|-----------------------------------|
+| Compact binary representation                  | ✔️              | ❌                      | ❌                      |  ✔️                       |  ✔️                               |
+| Human readable                                 | ❌️              | ✔️                      | ✔️                      |  ❌️                       |  ❌️                               |
+| Performance                                    | ❌️              | ❌                      | ✔️                      |  ✔️                       |  ✔️                               |
+| `[Serializable]` support                       | ✔️              | ✔️                      | ❌                      |  ❌                       |  ❌                               |
+| Serializing public types                       | ✔️              | ✔️                      | ✔️                      |  ✔️                       |  ✔️                               |
+| Serializing non-public types                   | ✔️              | ✔️                      | ✔️                      |  ✔️ (resolver required)   |  ✔️                               |
+| Serializing fields                             | ✔️              | ✔️                      | ✔️ (opt in)             |  ✔️ (attribute required)  |  ✔️ (attribute required)          |
+| Serializing non-public fields                  | ✔️              | ✔️                      | ✔️ (resolver required)  |  ✔️ (resolver required)   |  ✔️ (attribute required)          |
+| Serializing properties                         | ✔️<sup>*</sup>  | ✔️                      | ✔️                      |  ✔️ (attribute required)  |  ✔️ (attribute required)          |
+| Deserializing readonly members                 | ✔️              | ✔️                      | ✔️ (attribute required) |  ✔️                       |  ✔️ (parameterless ctor required) |
+| Polymorphic type hierarchy                     | ✔️              | ✔️                      | ✔️ (attribute required) |  ✔️ (attribute required)  |  ✔️ (attribute required)          |
+| AOT support                                    | ❌️              | ❌                      | ✔️                      |  ✔️                       |  ❌ (planned)                     |

docs/standard/serialization/binaryformatter-migration-guide/compatibility-package.md

@@ -0,0 +1,32 @@
+---
+title: "BinaryFormatter Migration Guide: Compatibility Package"
+description: "Using the BinaryFormatter compatibility package."
+ms.date: 5/31/2024
+no-loc: [BinaryFormatter, Serialization]
+helpviewer_keywords:
+  - "BinaryFormatter"
+  - "serializing objects"
+  - "serialization"
+  - "objects, serializing"
+---
+
+# Using the compatibility package
+
+> [!WARNING]
+> The compatibility package is unsafe and not recommended.
+
+.NET 9+ users who can't migrate away from `BinaryFormatter` can install the [System.Runtime.Serialization.Formatters](https://www.nuget.org/packages/System.Runtime.Serialization.Formatters) NuGet package and set the `System.Runtime.Serialization.EnableUnsafeBinaryFormatterSerialization` AppContext switch to `true`.
+
+```xml
+<PropertyGroup>
+  <TargetFramework>net9.0</TargetFramework>
+  <EnableUnsafeBinaryFormatterSerialization>true</EnableUnsafeBinaryFormatterSerialization>
+</PropertyGroup>
+
+<ItemGroup>
+  <PackageReference Include="System.Runtime.Serialization.Formatters" Version="9.0.0-*" />
+</ItemGroup>
+```
+
+> [!WARNING]
+> The compatibility package is unsafe and not recommended.

docs/standard/serialization/binaryformatter-migration-guide/functionality-reference.md

@@ -0,0 +1,88 @@
+---
+title: "BinaryFormatter Migration Guide: Functionality Reference"
+description: "A reference for BinaryFormatter's functionality that may need to be considered during migrations."
+ms.date: 5/31/2024
+no-loc: [BinaryFormatter, Serialization, WinForms]
+dev_langs:
+  - CSharp
+helpviewer_keywords:
+  - "BinaryFormatter"
+  - "serializing objects"
+  - "serialization"
+  - "objects, serializing"
+---
+
+# BinaryFormatter functionality reference
+
+The `BinaryFormatter` was first introduced with the initial release of the .NET Framework in 2002. To understand how to replace usage of BinaryFormatter, it helps to know how BinaryFormatter works.
+
+`BinaryFormatter` can serialize any instance of any type that's annotated with `[Serializable]` or implements the `ISerializable` interface.
+
+## Member names
+
+In most common scenario, the type is annotated with `[Serializable]` and the serializer uses reflection to serialize **all fields** (both public and non-public) except those that are annotated with `[NonSerialized]`.
+For C# auto properties (`{ get; set; }`), the properties are backed by fields generated by the C# compiler, so the names of the serialized fields are compiler generated (and not very human friendly).
+
+A C# decompiler (such as [https://sharplab.io/](https://sharplab.io/) or [ILSpy](https://github.com/icsharpcode/ILSpy)) can demonstrate how C# auto properties are presented to the runtime.
+
+```csharp
+[Serializable]
+internal class PropertySample
+{
+    public string Name { get; set; }
+}
+```
+
+The previous class is translated by the C# compiler to:
+
+```csharp
+[Serializable]
+internal class PropertySample
+{
+    private string <Name>k__BackingField;
+
+    public string Name
+    {
+        get
+        {
+            return <Name>k__BackingField;
+        }
+        set
+        {
+            <Name>k__BackingField = value;
+        }
+    }
+}
+```
+
+In this case, `<Name>k__BackingField` is **the name of the member that `BinaryFormatter` uses in the serialized payload**. It's not possible to use `nameof` or any other C# operator to get this name.
+
+The [ISerializable](/dotnet/api/system.runtime.serialization.iserializable) interface comes with [GetObjectData(SerializationInfo info, StreamingContext context)](/dotnet/api/system.runtime.serialization.iserializable.getobjectdata) method that allows the users to control the names, by using one of the [SerializationInfo.AddValue](/dotnet/api/system.runtime.serialization.serializationinfo.addvalue) methods.
+
+```csharp
+// Note lack of any special attribute.
+public void GetObjectData(SerializationInfo info, StreamingContext context)
+{
+    info.AddValue("Name", this.Name);
+}
+```
+
+If such customization has been applied, the information needs to be provided during deserialization as well. That's possible by using the **serialization constructor**, where all values are read from `SerializationInfo` with one of the `Get` methods it provides.
+
+```csharp
+private PropertySample(SerializationInfo info, StreamingContext context)
+{
+    this.Name = info.GetString("Name");
+}
+```
+
+> [!NOTE]
+> The `nameof` operator was purposely not used here, as the payload can be persisted and the property can get renamed at a later time. So even if it gets renamed (say to `FirstName` because you decide to also introduce a `LastName` property), to remain backward compatible, the serialization should still use the old name that could have been persisted somewhere.
+
+## Serialization binder
+
+It's recommended to use [SerializationBinder](/dotnet/api/system.runtime.serialization.serializationbinder) to control class loading and mandate what class to load. That minimizes security vulnerabilities (so only allowed types get loaded, even if the attacker modifies the payload to deserialize and load something else).
+
+Using this type requires inheriting from it and overriding the [Type BindToType(string assemblyName, string typeName)](/dotnet/api/system.runtime.serialization.serializationbinder.bindtotype#system-runtime-serialization-serializationbinder-bindtotype(system-string-system-string)) method.
+
+If your code uses a custom type that derives from `SerializationBinder`, it's likely that the list of serializable types is a **closed set**. If not, finding the list of all types that can get serialized and deserialized requires studying all the usages of `BinaryFormatter` in source code. **Knowing that list is crucial to determining how to move forward with the migration.**

docs/standard/serialization/binaryformatter-migration-guide/migration-to-data-contract-serializer.md

@@ -0,0 +1,32 @@
+---
+title: "BinaryFormatter Migration Guide: Migration to DataContractSerializer"
+description: "Describe the capabilities and limitations of DataContractSerializer."
+ms.date: 5/31/2024
+no-loc: [BinaryFormatter, Serialization]
+dev_langs:
+  - CSharp
+helpviewer_keywords:
+  - "BinaryFormatter"
+  - "serialization [WCF]"
+  - "serializing objects"
+  - "serialization"
+  - "objects, serializing"
+---
+
+# Migration to DataContractSerializer
+
+The .NET base class libraries provide two XML serializers: [XmlSerializer](../introducing-xml-serialization.md) and [DataContractSerializer](../../../fundamentals/runtime-libraries/system-runtime-serialization-datacontractserializer.md). There are some subtle differences between these two, but for the purpose of the migration, this section focuses only on `DataContractSerializer`. Why? Because it **fully supports the serialization programming model that was used by `BinaryFormatter`**. All the types that are already marked as `[Serializable]` or implement `ISerializable` can be serialized with `DataContractSerializer`. Where is the catch? Known types must be specified up front (that's why it's secure). You need to know them and be able to get the `Type`, **even for private types**.
+
+```csharp
+DataContractSerializer serializer = new(
+    type: input.GetType(),
+    knownTypes: new Type[]
+    {
+        typeof(MyType1),
+        typeof(MyType2)
+    });
+```
+
+It's not required to specify most popular collections or primitive types like `string` or `DateTime` (the serializer has its own default allowlist), but there are exceptions like `DateTimeOffset`. For more information about the supported types, see [Types supported by the data contract serializer](../../../framework/wcf/feature-details/types-supported-by-the-data-contract-serializer.md).
+
+[Partial trust](../../../framework/wcf/feature-details/partial-trust.md) is a .NET Framework feature that wasn't ported to .NET (Core). If your code runs on .NET Framework and uses this feature, read about the [limitations](../../../framework/wcf/feature-details/types-supported-by-the-data-contract-serializer.md#limitations-of-using-certain-types-in-partial-trust-mode) that might apply to such a scenario.

docs/standard/serialization/binaryformatter-migration-guide/migration-to-message-pack.md

@@ -0,0 +1,26 @@
+---
+title: "BinaryFormatter Migration Guide: Migration to MessagePack"
+description: "Describe the capabilities and limitations of MessagePack serializer."
+ms.date: 5/31/2024
+no-loc: [BinaryFormatter, Serialization]
+helpviewer_keywords:
+  - "BinaryFormatter"
+  - "serializing objects"
+  - "serialization"
+  - "objects, serializing"
+---
+
+# Migration to MessagePack
+
+MessagePack provides a highly efficient binary serialization format, resulting in smaller message sizes compared to JSON and XML. It's [performant](https://github.com/MessagePack-CSharp/MessagePack-CSharp?tab=readme-ov-file#performance) and ships with built-in support for LZ4 compression and a full set of general-purpose expressive data types:
+
+- By default, only public types are serializable. Private and internal structs and classes can be serialized only when `StandardResolverAllowPrivate.Options` is provided as an argument to `MessagePackSerializer.Serialize` and `MessagePackSerializer.Deserialize` methods.
+- MessagePack requires each serializable type to be annotated with the `[MessagePackObject]` attribute. It's possible to avoid that by using the [ContractlessStandardResolver](https://github.com/MessagePack-CSharp/MessagePack-CSharp?tab=readme-ov-file#object-serialization), but it might cause issues with versioning in the future.
+- Every serializable non-static field and a property needs to be annotated with the `[Key]` attribute. If you annotate the type with the `[MessagePackObject(keyAsPropertyName: true)]` attribute, then members don't require explicit annotations. In such case, to ignore certain public members, use the `[IgnoreMember]` attribute.
+- To serialize private members, use [DynamicObjectResolverAllowPrivate](https://github.com/MessagePack-CSharp/MessagePack-CSharp?tab=readme-ov-file#object-serialization).
+- `System.Runtime.Serialization` annotations can be used instead of MessagePack annotations: `[DataContract]` instead of`[MessagePackObject]`, `[DataMember]` instead of `[Key]`, and `[IgnoreDataMember]` instead of `[IgnoreMember]`. These annotations can be useful if you want to avoid a dependency on MessagePack in the library that defines serializable types.
+- It supports readonly/immutable types and members. The serializer will try to use the public constructor with the best matched argument list. The constructor can be specified in an explicit way by using `[SerializationConstructor]` attribute.
+- The serializer supports most frequently used built-in types and collections provided by the .NET base class libraries. You can find the full list in [official docs](https://github.com/MessagePack-CSharp/MessagePack-CSharp?tab=readme-ov-file#built-in-supported-types). It has [extension points](https://github.com/MessagePack-CSharp/MessagePack-CSharp?tab=readme-ov-file#extensions) that allow for customization.
+
+> [!WARNING]
+> MessagePack has APIs to allow for deserializing data without type restrictions. Per [MessagePack Security Notes](https://github.com/MessagePack-CSharp/MessagePack-CSharp?tab=readme-ov-file#security), these APIs should be avoided.

docs/standard/serialization/binaryformatter-migration-guide/migration-to-protobuf-net.md

@@ -0,0 +1,21 @@
+---
+title: "BinaryFormatter Migration Guide: Migration to protobuf-net"
+description: "Describe the capabilities and limitations of protobuf-net serializer."
+ms.date: 5/31/2024
+no-loc: [BinaryFormatter, Serialization]
+helpviewer_keywords:
+  - "BinaryFormatter"
+  - "serializing objects"
+  - "serialization"
+  - "objects, serializing"
+---
+
+# Migration to protobuf-net
+
+[protobuf-net](https://github.com/protobuf-net/protobuf-net) is a contract-based serializer for .NET code that writes data in the _protocol buffers_ serialization format engineered by Google.
+
+- By default, both public and non-public types are serializable. Every type needs to provide a parameterless constructor.
+- protobuf-net requires each serializable type to be annotated with `[ProtoContract]` attribute.
+- Every serializable non-static field and a property needs to be annotated with `[ProtoMember(int tag)]` attribute. The member names aren't encoded in the data. Instead, the users must pick an integer to identify each member.
+- [Inheritance](https://github.com/protobuf-net/protobuf-net?tab=readme-ov-file#inheritance) must be explicitly declared via `[ProtoInclude(...)]` attribute on each type with known subtypes.
+- Read-only fields are supported by default.