Breaking changes in Windows Forms

Windows Forms support was added to .NET Core in version 3.0. This article lists breaking changes for Windows Forms by the .NET Core version in which they were introduced. If you're upgrading a Windows Forms app from .NET Framework or from a previous version of .NET Core (3.0 or later), this article is applicable to you.

The following breaking changes are documented on this page:

Breaking change Version introduced
Removed status bar controls 5.0
WinForms methods now throw ArgumentException 5.0
WinForms methods now throw ArgumentNullException 5.0
WinForms properties now throw ArgumentOutOfRangeException 5.0
Removed controls 3.1
CellFormatting event not raised if tooltip is shown 3.1
Control.DefaultFont changed to Segoe UI 9 pt 3.0
Modernization of the FolderBrowserDialog 3.0
SerializableAttribute removed from some Windows Forms types 3.0
AllowUpdateChildControlIndexForTabControls compatibility switch not supported 3.0
DomainUpDown.UseLegacyScrolling compatibility switch not supported 3.0
DoNotLoadLatestRichEditControl compatibility switch not supported 3.0
DoNotSupportSelectAllShortcutInMultilineTextBox compatibility switch not supported 3.0
DontSupportReentrantFilterMessage compatibility switch not supported 3.0
EnableVisualStyleValidation compatibility switch not supported 3.0
UseLegacyContextMenuStripSourceControlValue compatibility switch not supported 3.0
UseLegacyImages compatibility switch not supported 3.0
Change of access for AccessibleObject.RuntimeIDFirstItem 3.0
Duplicated APIs removed from Windows Forms 3.0

.NET 5.0

Removed status bar controls

Starting in .NET 5.0 Preview 1, some Windows Forms controls are no longer available.

Change description

Starting with .NET 5.0 Preview 1, some of the status bar-related Windows Forms controls are no longer available. Replacement controls that have better design and support were introduced in .NET Framework 2.0. The deprecated controls were previously removed from designer toolboxes but were still available to be used. Now, they have been completely removed.

The following types are no longer available:

  • StatusBar
  • StatusBarDrawItemEventArgs
  • StatusBarDrawItemEventHandler
  • StatusBarPanel
  • StatusBarPanelAutoSize
  • StatusBarPanelBorderStyle
  • StatusBarPanelClickEventArgs
  • StatusBarPanelClickEventHandler
  • StatusBarPanelStyle

Version introduced

5.0 Preview 1

Move to the replacement APIs for these controls and their scenarios:

Old Control (API) Recommended Replacement
StatusBar StatusStrip
StatusBarPanel ToolStripStatusLabel

Category

Windows Forms

Affected APIs


WinForms methods now throw ArgumentException

Some Windows Forms methods now throw an ArgumentException for invalid arguments, where previously they did not.

Change description

Previously, passing arguments of an unexpected or incorrect type to certain Windows Forms methods would result in an indeterminate state. Starting in .NET 5.0, these methods now throw an ArgumentException when passed invalid arguments.

Throwing an ArgumentException conforms to the behavior of the .NET runtime. It also improves the debugging experience by clearly communicating which argument is invalid.

The following table lists the affected methods and parameters:

Method Parameter name Condition Version added
System.Windows.Forms.TabControl.GetToolTipText(Object) item Argument is not of type TabPage. 5.0 Preview 1
System.Windows.Forms.DataFormats.GetFormat(String) format Argument is null, String.Empty, or white space. 5.0 Preview 5

Version introduced

.NET 5.0

  • Update the code to prevent passing invalid arguments.
  • If necessary, handle an ArgumentException when calling the method.

Category

Windows Forms

Affected APIs


WinForms methods now throw ArgumentNullException

Some Windows Forms methods now throw an ArgumentNullException for null arguments, where previously they threw a NullReferenceException.

Change description

Previously, certain Windows Forms methods threw a NullReferenceException if passed an argument that was null. Starting in .NET 5.0, these methods now throw an ArgumentNullException for null arguments, instead.

Throwing an ArgumentNullException conforms to the behavior of the .NET runtime. It also improves the debugging experience by clearly communicating that an argument is null and which argument it is.

Version introduced

.NET 5.0

If you call any of these methods and your code currently catches a NullReferenceException for null arguments, catch an ArgumentNullException instead. In addition, consider updating the code to prevent passing null arguments to the listed methods.

Category

Windows Forms

Affected APIs

The following table lists the affected methods and parameters:

Method Parameter name Version added
Control.ControlCollection(Control) owner 5.0 Preview 1
TabControl.GetToolTipText(Object) item 5.0 Preview 1
TableLayoutControlCollection(TableLayoutPanel) container 5.0 Preview 1
ToolStripRenderer.OnRenderArrow(ToolStripArrowRenderEventArgs) e 5.0 Preview 1
ToolStripRenderer.OnRenderItemCheck(ToolStripItemImageRenderEventArgs) e 5.0 Preview 1
ToolStripRenderer.OnRenderItemImage(ToolStripItemImageRenderEventArgs) e 5.0 Preview 1
ToolStripRenderer.OnRenderItemText(ToolStripItemTextRenderEventArgs) e 5.0 Preview 1
ToolStripRenderer.OnRenderStatusStripSizingGrip(ToolStripRenderEventArgs) > e 5.0 Preview 1
DataGridViewComboBoxEditingControl.ApplyCellStyleToEditingControl(DataGridViewCellStyle) dataGridViewCellStyle 5.0 Preview 2
RichTextBox.LoadFile(Stream, RichTextBoxStreamType) data 5.0 Preview 2
ListBox.IntegerCollection(ListBox) owner 5.0 Preview 5
ListBox.IntegerCollection.CopyTo(Array, Int32) destination 5.0 Preview 5
ListViewGroup.ISerializable.GetObjectData(SerializationInfo, StreamingContext) info 5.0 Preview 5
VisualStyleRenderer(String, Int32, Int32) className 5.0 Preview 5
ListBox.ObjectCollection(ListBox) owner 5.0 Preview 6
ListBox.ObjectCollection(ListBox, Object[]) owner, value 5.0 Preview 6
ListBox.ObjectCollection(ListBox, ListBox+ObjectCollection) owner, value 5.0 Preview 6
ListBox.ObjectCollection.AddRange(Object[]) items 5.0 Preview 6
ListBox.ObjectCollection.AddRange(ListBox+ObjectCollection) value 5.0 Preview 6
ListBox.ObjectCollection.CopyTo(Object[], Int32) destination 5.0 Preview 6
ListBox.ObjectCollection.ICollection.CopyTo(Array, Int32) destinationq` 5.0 Preview 6

WinForms properties now throw ArgumentOutOfRangeException

Some Windows Forms properties now throw an ArgumentOutOfRangeException for invalid arguments, where previously they did not.

Change description

Previously, these properties threw various exceptions, such as NullReferenceException, IndexOutOfRangeException, or ArgumentException, when passed out-of-range arguments. Starting in .NET 5.0, these properties now throw an ArgumentOutOfRangeException when passed arguments that are out of range.

Throwing an ArgumentOutOfRangeException conforms to the behavior of the .NET runtime. It also improves the debugging experience by clearly communicating which argument is invalid.

Version introduced

.NET 5.0

Category

Windows Forms

Affected APIs

The following table lists the affected properties and parameters:

Property Parameter name Version added
ListBox.IntegerCollection.Item[Int32] index 5.0 Preview 5
TreeNode.ImageIndex value 5.0 Preview 6
TreeNode.SelectedImageIndex value 5.0 Preview 6

.NET Core 3.1

Removed controls

Starting in .NET Core 3.1, some Windows Forms controls are no longer available.

Change description

Starting with .NET Core 3.1, various Windows Forms controls are no longer available. Replacement controls that have better design and support were introduced in .NET Framework 2.0. The deprecated controls were previously removed from designer toolboxes but were still available to be used.

The following types are no longer available:

Version introduced

3.1

Each removed control has a recommended replacement control. Refer to the following table:

Removed control (API) Recommended replacement Associated APIs that are removed
ContextMenu ContextMenuStrip
DataGrid DataGridView DataGridCell, DataGridRow, DataGridTableCollection, DataGridColumnCollection, DataGridTableStyle, DataGridColumnStyle, DataGridLineStyle, DataGridParentRowsLabel, DataGridParentRowsLabelStyle, DataGridBoolColumn, DataGridTextBox, GridColumnStylesCollection, GridTableStylesCollection, HitTestType
MainMenu MenuStrip
Menu ToolStripDropDown, ToolStripDropDownMenu MenuItemCollection
MenuItem ToolStripMenuItem
ToolBar ToolStrip ToolBarAppearance
ToolBarButton ToolStripButton ToolBarButtonClickEventArgs, ToolBarButtonClickEventHandler, ToolBarButtonStyle, ToolBarTextAlign

Category

Windows Forms

Affected APIs


CellFormatting event not raised if tooltip is shown

A DataGridView now shows a cell's text and error tooltips when hovered by a mouse and when selected via the keyboard. If a tooltip is shown, the DataGridView.CellFormatting event is not raised.

Change description

Prior to .NET Core 3.1, a DataGridView that had the ShowCellToolTips property set to true showed a tooltip for a cell's text and errors when the cell was hovered by a mouse. Tooltips were not shown when a cell was selected via the keyboard (for example, by using the Tab key, shortcut keys, or arrow navigation). If the user edited a cell, and then, while the DataGridView was still in edit mode, hovered over a cell that did not have the ToolTipText property set, a CellFormatting event was raised to format the cell's text for display in the cell.

To meet accessibility standards, starting in .NET Core 3.1, a DataGridView that has the ShowCellToolTips property set to true shows tooltips for a cell's text and errors not only when the cell is hovered, but also when it's selected via the keyboard. As a consequence of this change, the CellFormatting event is not raised when cells that don't have the ToolTipText property set are hovered while the DataGridView is in edit mode. The event is not raised because the content of the hovered cell is shown as a tooltip instead of being displayed in the cell.

Version introduced

3.1

Refactor any code that depends on the CellFormatting event while the DataGridView is in edit mode.

Category

Windows Forms

Affected APIs

None


.NET Core 3.0

Default control font changed to Segoe UI 9 pt

Change description

In .NET Framework, the Control.DefaultFont property was set to Microsoft Sans Serif 8 pt. The following image shows a window that uses the default font.

Default control font in .NET Framework

Starting in .NET Core 3.0, the default font is set to Segoe UI 9 pt (the same font as SystemFonts.MessageBoxFont). As a result of this change, forms and controls are sized about 27% larger to account for the larger size of the new default font. For example:

Default control font in .NET Core

This change was made to align with Windows user experience (UX) guidelines.

Version introduced

3.0

Because of the change in the size of forms and controls, ensure that your application renders correctly.

To retain the original font, set your form's default font to Microsoft Sans Serif 8 pt. For example:

public MyForm()
{
    InitializeComponent();
    Font = new Font(new FontFamily("Microsoft Sans Serif"), 8f);
}

Category

  • Windows Forms

Affected APIs

None.


Modernization of the FolderBrowserDialog

The FolderBrowserDialog control has changed in Windows Forms applications for .NET Core.

Change description

In the .NET Framework, Windows forms uses the following dialog for the FolderBrowserDialog control:

The FolderBrowserDialogControl in the .NET Framework

In .NET Core 3.0, Windows Forms users a newer COM-based control that was introduced in Windows Vista:

The FolderBrowserDialogControl in the .NET Core

Version introduced

3.0

The dialog will be upgraded automatically.

If you desire to retain the original dialog, set the FolderBrowserDialog.AutoUpgradeEnabled property to false before showing the dialog, as illustrated by the following code fragment:

var dialog = new FolderBrowserDialog();
dialog.AutoUpgradeEnabled = false;
dialog.ShowDialog();

Category

Windows Forms

Affected APIs


SerializableAttribute removed from some Windows Forms types

The SerializableAttribute has been removed from some Windows Forms classes that have no known binary serialization scenarios.

Change description

The following types are decorated with the SerializableAttribute in .NET Framework, but the attribute has been removed in .NET Core:

Historically, this serialization mechanism has had serious maintenance and security concerns. Maintaining SerializableAttribute on types means those types must be tested for version-to-version serialization changes and potentially framework-to-framework serialization changes. This makes it harder to evolve those types and can be costly to maintain. These types have no known binary serialization scenarios, which minimizes the impact of removing the attribute.

For more information, see Binary serialization.

Version introduced

3.0 Preview 9

Update any code that may depend on these types being marked as serializable.

Category

Windows Forms

Affected APIs

  • None

AllowUpdateChildControlIndexForTabControls compatibility switch not supported

The Switch.System.Windows.Forms.AllowUpdateChildControlIndexForTabControls compatibility switch is supported in Windows Forms on .NET Framework 4.6 and later versions but is not supported in Windows Forms starting with .NET Core 3.0.

Change description

In .NET Framework 4.6 and later versions, selecting a tab reorders its control collection. The Switch.System.Windows.Forms.AllowUpdateChildControlIndexForTabControls compatibility switch allows an application to skip this reordering when this behavior is undesirable.

In .NET Core, the Switch.System.Windows.Forms.AllowUpdateChildControlIndexForTabControls switch is not supported.

Version introduced

3.0 Preview 9

Remove the switch. The switch is not supported, and no alternative functionality is available.

Category

Windows Forms

Affected APIs

  • None

DomainUpDown.UseLegacyScrolling compatibility switch not supported

The Switch.System.Windows.Forms.DomainUpDown.UseLegacyScrolling compatibility switch, which was introduced in .NET Framework 4.7.1, is not supported in Windows Forms on .NET Core 3.0.

Change description

Starting with the .NET Framework 4.7.1, the Switch.System.Windows.Forms.DomainUpDown.UseLegacyScrolling compatibility switch allowed developers to opt-out of independent DomainUpDown.DownButton() and DomainUpDown.UpButton() actions. The switch restored the legacy behavior, in which the DomainUpDown.UpButton() is ignored if context text is present, and the developer is required to use DomainUpDown.DownButton() action on the control before the DomainUpDown.UpButton() action. For more information, see <AppContextSwitchOverrides> element.

In .NET Core, the Switch.System.Windows.Forms.DomainUpDown.UseLegacyScrolling switch is not supported.

Version introduced

3.0 Preview 9

Remove the switch. The switch is not supported, and no alternative functionality is available.

Category

Windows Forms

Affected APIs


DoNotLoadLatestRichEditControl compatibility switch not supported

The Switch.System.Windows.Forms.UseLegacyImages compatibility switch, which was introduced in .NET Framework 4.7.1, is not supported in Windows Forms on .NET Core 3.0.

Change description

In the .NET Framework 4.6.2 and previous versions, the RichTextBox control would instantiate the Win32 RichEdit control v3.0, and for applications that target .NET Framework 4.7.1, the RichTextBox control would instantiate RichEdit v4.1 (in msftedit.dll). The Switch.System.Windows.Forms.DoNotLoadLatestRichEditControl compatibility switch was introduced to allow applications that target .NET Framework 4.7.1 and later versions to opt-out of the new RichEdit v4.1 control and use the old RichEdit v3 control instead.

In .NET Core, the Switch.System.Windows.Forms.DoNotLoadLatestRichEditControl switch is not supported. Only new versions of the RichTextBox control are supported.

Version introduced

3.0 Preview 9

Remove the switch. The switch is not supported, and no alternative functionality is available.

Category

Windows Forms

Affected APIs


DoNotSupportSelectAllShortcutInMultilineTextBox compatibility switch not supported

The Switch.System.Windows.Forms.DoNotSupportSelectAllShortcutInMultilineTextBox compatibility switch, which was introduced in .NET Framework 4.6.1, is not supported in Windows Forms on .NET Core 3.0.

Change description

Starting with .NET Framework 4.6.1, selecting the Ctrl + A shortcut key in a TextBox control selected all text. In .NET Framework 4.6 and previous versions, selecting the Ctrl + A shortcut key failed to select all text if the Textbox.ShortcutsEnabled and TextBox.Multiline properties were both set to true. The Switch.System.Windows.Forms.DoNotSupportSelectAllShortcutInMultilineTextBox compatibility switch was introduced in .NET Framework 4.6.1 to retain the original behavior. For more information see TextBox.ProcessCmdKey.

In .NET Core, the Switch.System.Windows.Forms.DoNotSupportSelectAllShortcutInMultilineTextBox switch is not supported.

Version introduced

3.0 Preview 9

Remove the switch. The switch is not supported, and no alternative functionality is available.

Category

Windows Forms

Affected APIs

  • None

DontSupportReentrantFilterMessage compatibility switch not supported

The Switch.System.Windows.Forms.DontSupportReentrantFilterMessage compatibility switch, which was introduced in .NET Framework 4.6.1, is not supported in Windows Forms on .NET Core 3.0.

Change description

Starting with the .NET Framework 4.6.1, the Switch.System.Windows.Forms.DontSupportReentrantFilterMessage compatibility switch addresses possible IndexOutOfRangeException exceptions when the Application.FilterMessage message is called with a custom IMessageFilter.PreFilterMessage implementation. For more information, see Mitigation: Custom IMessageFilter.PreFilterMessage Implementations.

In .NET Core, the Switch.System.Windows.Forms.DontSupportReentrantFilterMessage switch is not supported.

Version introduced

3.0 Preview 9

Remove the switch. The switch is not supported, and no alternative functionality is available.

Category

Windows Forms

Affected APIs


EnableVisualStyleValidation compatibility switch not supported

The Switch.System.Windows.Forms.EnableVisualStyleValidation compatibility switch is not supported in Windows Forms on .NET Core 3.0.

Change description

In .NET Framework, the Switch.System.Windows.Forms.EnableVisualStyleValidation compatibility switch allowed an application to opt out of validation of visual styles supplied in a numeric form.

In .NET Core, the Switch.System.Windows.Forms.EnableVisualStyleValidation switch is not supported.

Version introduced

3.0 Preview 9

Remove the switch. The switch is not supported, and no alternative functionality is available.

Category

Windows Forms

Affected APIs

  • None

UseLegacyContextMenuStripSourceControlValue compatibility switch not supported

The Switch.System.Windows.Forms.UseLegacyContextMenuStripSourceControlValue compatibility switch, which was introduced in .NET Framework 4.7.2, is not supported in Windows Forms on .NET Core 3.0.

Change description

Starting with the .NET Framework 4.7.2, the Switch.System.Windows.Forms.UseLegacyContextMenuStripSourceControlValue compatibility switch allows the developer to opt out of the new behavior of the ContextMenuStrip.SourceControl property, which now returns a reference to the source control. The previous behavior of the property was to return null. For more information, see <AppContextSwitchOverrides> element.

In .NET Core, the Switch.System.Windows.Forms.UseLegacyContextMenuStripSourceControlValue switch is not supported.

Version introduced

3.0 Preview 9

Remove the switch. The switch is not supported, and no alternative functionality is available.

Category

Windows Forms

Affected APIs


UseLegacyImages compatibility switch not supported

The Switch.System.Windows.Forms.UseLegacyImages compatibility switch, which was introduced in .NET Framework 4.8, is not supported in Windows Forms on .NET Core 3.0.

Change description

Starting with the .NET Framework 4.8, the Switch.System.Windows.Forms.UseLegacyImages compatibility switch addressed possible image scaling issues in ClickOnce scenarios in high DPI environments. When set to true, the switch allows the user to restore legacy image scaling on high DPI displays whose scale is set to greater than 100%. For more information, see .NET Framework 4.8 Release Notes on GitHub.

In .NET Core, the Switch.System.Windows.Forms.UseLegacyImages switch is not supported.

Version introduced

3.0 Preview 9

Remove the switch. The switch is not supported, and no alternative functionality is available.

Category

Windows Forms

Affected APIs

  • None

Change of access for AccessibleObject.RuntimeIDFirstItem

Starting in .NET Core 3.0 RC1, the accessibility of AccessibleObject.RuntimeIDFirstItem has changed from protected to internal.

Change description

Starting with .NET Core 3.0 Preview 4, the AccessibleObject.RuntimeIDFirstItem field was protected. Starting with .NET Core 3.0 RC1, it has changed from protected to internal to align with the accessibility of the field in the .NET Framework.

Version introduced

3.0 RC1

The change can affect you if you've developed a .NET Core app with a type that derives from AccessibleObject and accesses the RuntimeIDFirstItem field. If this is the case, you can define a local constant as follows:

const int RuntimeIDFirstItem = 0x2a;

Category

Windows Forms

Affected APIs

  • Not detectable via API analysis.

Duplicated APIs removed from Windows Forms

A number of APIs accidentally duplicated in the System.Windows.Forms namespace starting in .NET Core 3.0 Preview 4 have been removed in .NET Core 3.0 RC1.

Change description

.NET Core 3.0 Preview 4 inadvertently duplicated a number of types in the System.Windows.Forms namespace that already existed in the System.ComponentModel.Design namespace. Starting with .NET Core 3.0 RC1, these duplicated types are no longer available. The following table shows lists the original type and its duplicated type:

Original type Duplicated type
System.ComponentModel.Design.DesignerActionListsChangedEventArgs System.Windows.Forms.DesignerActionListsChangedEventArgs
System.ComponentModel.Design.DesignerActionListsChangedEventHandler System.Windows.Forms.DesignerActionListsChangedEventHandler
System.ComponentModel.Design.DesignerActionListsChangedType System.Windows.Forms.DesignerActionListsChangedType
System.ComponentModel.Design.DesignerActionUIService System.Windows.Forms.DesignerActionUIService
System.ComponentModel.Design.DesignerCommandSet System.Windows.Forms.DesignerCommandSet

Version introduced

3.0 RC1

Update the code to reference the original type, as shown in the Original type column of the table.

Category

Windows Forms

Affected APIs

  • None.

See also