Skip to content

Commit

Permalink
winforms: fix title and lint issues
Browse files Browse the repository at this point in the history
  • Loading branch information
lonitra committed Jul 31, 2024
1 parent f793dcc commit 4e76345
Showing 1 changed file with 12 additions and 5 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ helpviewer_keywords:
- "BinaryFormatter"
- "WinForms"
---
# WinForms Migration Guide

# BinaryFormatter Removal

Expand All @@ -15,6 +16,7 @@ Starting in .NET 9, BinaryFormatter is being moved to a separate, unsupported nu
# How BinaryFormatter Affects WinForms

WinForms itself has and still currently contains BinaryFormatter code internally for scenarios such as clipboard, drag/drop, and designer ResX, however, measures have been taken to mitigate the usage of BinaryFormatter behind the scenes for common primitive types, including primitive arrays and primitive lists. Usage of these types in clipboard and drag/drop scenarios will continue to work without using BinaryFormatter and without any gesture from the developer. Primitive types include the following

- `boolean`
- `byte`
- `char`
Expand All @@ -31,39 +33,44 @@ WinForms itself has and still currently contains BinaryFormatter code internally
- `nuint`

Additional types WinForms currently supports include the following

- `PointF`
- `RectangleF`
- `Bitmap`
- `ImageListStreamer`

## Clipboard

If your clipboard scenario does not involve the types above, BinaryFormatter would be used when [`Clipboard.SetData`](https://learn.microsoft.com/dotnet/api/system.windows.clipboard.setdata) is called with your type and when [`Clipboard.GetData`](https://learn.microsoft.com/dotnet/api/system.windows.clipboard.getdata) is called to get your type. BinaryFormatter will also be used if [`Clipboard.SetDataObject(object, copy: true)`](https://learn.microsoft.com/dotnet/api/system.windows.clipboard.setdataobject#system-windows-clipboard-setdataobject(system-object-system-boolean)) is called. With the BinaryFormatter removal, developers will now see a string about BinaryFormatter being removed on the clipboard when using those APIs with unsupported types.

## Drag/Drop
If your drag/drop scenario involves unsupported types, BinaryFormatter would be used when [`Control.DoDragDrop`](https://learn.microsoft.com/dotnet/api/system.windows.forms.control.dodragdrop) is called, and the item is dragged out of process and when DataObject.GetData is called to retrieve your type that has been dragged out of process. With the BinaryFormatter removal, developers will now see a string about BinaryFormatter being removed upon dropping the dragged item in another process when a drag operation starts with unsupported types.

If your drag/drop scenario involves unsupported types, BinaryFormatter would be used when [`Control.DoDragDrop`](https://learn.microsoft.com/dotnet/api/system.windows.forms.control.dodragdrop) is called, and the item is dragged out of process and when DataObject.GetData is called to retrieve your type that has been dragged out of process. With the BinaryFormatter removal, developers will now see a string about BinaryFormatter being removed upon dropping the dragged item in another process when a drag operation starts with unsupported types.

## The WinForms Designer
The WinForms designer also uses BinaryFormatter internally for ResX serialization/deserialization and CodeDom.

The WinForms designer also uses BinaryFormatter internally for ResX serialization/deserialization and CodeDom.

Types and properties may be participating in serialization without developers realizing due to the standard behavior of the WinForms designer. One way that BinaryFormatter is used where developers may not be aware of is when a property on a UserControl is introduced and that control is already populated at design-time, then it’s very likely that that data gets serialized into code or resource files. If all the following are true:

- A property contains data at the time when a Form in the Designer gets saved
- that property is not attributed with `DesignerSerializationVisibility(false)`
- that property does not have a DefaultValueAttribute
- that property does not have a respective bool ShouldSerialize\[PropertyName\] method returning false

the Designer looks if that property’s type has a type converter. If it does then it uses it to serialize the property content, otherwise BinaryFormatter is used to serialize the content into the resource file.
the Designer looks if that property’s type has a type converter. If it does then it uses it to serialize the property content, otherwise BinaryFormatter is used to serialize the content into the resource file.
WinForms has added analyzers along with code fixes to help bring awareness to this type of behavior where BinaryFormatter serialization may be occurring without the developer’s knowledge.



# Migrating Away from BinaryFormatter

If unsupported types are used in the affected scenarios, action will need to be taken to complete migration to .NET 9+.

## Clipboard and Drag/Drop

For unsupported types that are used in clipboard and drag/drop operations, it is recommended developers format those types as a byte[] or string payload before passing the data to clipboard or drag/drop APIs. Using JSON is one way to achieve this. Note that adjustments will need to be made to handle receiving a JSON formatted type just as adjustments have been made to place JSON formatted types on clipboard or drag/drop operations. For more information on how to serialize/deserialize the type with JSON, see [How to write .NET objects as JSON (serialize)](https://learn.microsoft.com/dotnet/standard/serialization/system-text-json/how-to)

## Designer Scenarios

For unsupported types that are being serialized into resources/code, which would be the case for the designer with ResX and CodeDom serialization scenarios, the prescribed way of migrating away from BinaryFormatter is to ensure a TypeConverter is registered to the type or property that is participating in serialization. This way, during serialization/deserialization, the TypeConverter will be used in lieu of where BinaryFormatter was once used. For more information on implementing a type converter, see [TypeConverter Class](https://learn.microsoft.com/dotnet/api/system.componentmodel.typeconverter#notes-to-inheritors)

# Compatibility Workaround (Not Recommended)
Expand Down

0 comments on commit 4e76345

Please sign in to comment.