Breaking changes in Windows Forms for .NET Core 3.0 and 3.1

Article
11/20/2021

Windows Forms support was added to .NET Core in version 3.0. This article lists breaking changes for Windows Forms by the .NET 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 applies to you.

The following breaking changes are documented on this page:

Breaking change	Version introduced
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
About and SplashScreen templates are broken for Visual Basic	3.0

.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

Recommended action

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

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

Recommended action

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.25 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

Recommended action

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

To retain the original font for a single form, set its default font to Microsoft Sans Serif 8.25 pt. For example:

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

Or, you can change the default font for an entire application in either of the following ways:

By setting the ApplicationDefaultFont MSBuild property to "Microsoft Sans Serif, 8.25pt". This is the preferred technique because it allows Visual Studio to use the new settings in the designer.
```
<PropertyGroup>
  <ApplicationDefaultFont>Microsoft Sans Serif, 8.25pt</ApplicationDefaultFont>
</PropertyGroup>
```

By calling Application.SetDefaultFont(Font).

class Program
{
    [STAThread]
    static void Main()
    {
        Application.EnableVisualStyles();
        Application.SetCompatibleTextRenderingDefault(false);
        Application.SetHighDpiMode(HighDpiMode.SystemAware);
        Application.SetDefaultFont(new Font(new FontFamily("Microsoft Sans Serif"), 8.25f));
        Application.Run(new Form1());
    }
}

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 uses a newer COM-based control that was introduced in Windows Vista:

The FolderBrowserDialogControl in the .NET Core

Version introduced

3.0

Recommended action

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

FolderBrowserDialog

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:

System.InvariantComparer
System.ComponentModel.Design.ExceptionCollection
System.ComponentModel.Design.Serialization.CodeDomSerializerException
System.ComponentModel.Design.Serialization.CodeDomComponentSerializationService.CodeDomSerializationStore
System.Drawing.Design.ToolboxItem
System.Resources.ResXNullRef
System.Resources.ResXDataNode
System.Resources.ResXFileRef
System.Windows.Forms.Cursor
System.Windows.Forms.NativeMethods.MSOCRINFOSTRUCT
System.Windows.Forms.NativeMethods.MSG

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

Recommended action

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 on .NET Core or .NET 5.0 and later.

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 and .NET 5.0 and later, the Switch.System.Windows.Forms.AllowUpdateChildControlIndexForTabControls switch is not supported.

Version introduced

3.0

Recommended action

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 or .NET 5.0 and later.

Change description

Starting with .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 and .NET 5.0 and later, the Switch.System.Windows.Forms.DomainUpDown.UseLegacyScrolling switch is not supported.

Version introduced

3.0

Recommended action

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

Category

Windows Forms

None

About and SplashScreen templates are broken

The About.vb and SplashScreen.vb files generated by Visual Studio contain references to types in the My namespace that aren't available .NET Core 3.0 and 3.1.

Version introduced

3.0

Change description

.NET Core 3.0 and 3.1 don't contain full Visual Basic My support. The About and SplashScreen form templates in Visual Studio for Visual Basic Windows Forms apps reference properties in the My.Application.Info type that aren't available.

Recommended action

Visual Basic My support was improved in .NET 5, upgrade your project to .NET 5 or later.

-or-

Fix the compiler errors in the About and SplashScreen types in your app. Use the System.Reflection.Assembly class to get the information provided by the My.Application.Info type. A straight port of both forms is available here.

Tip

This is sample code and unoptimized. The list of attributes should be cached to reduce form load time.

About

Imports System.Reflection

Public NotInheritable Class About

    Private Sub about_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
        ' Set the title of the form.
        Dim applicationTitle As String = Assembly.GetExecutingAssembly().GetCustomAttribute(Of AssemblyTitleAttribute)()?.Title

        If String.IsNullOrEmpty(applicationTitle) Then
            applicationTitle = System.IO.Path.GetFileNameWithoutExtension(Assembly.GetExecutingAssembly().GetName().Name)
        End If

        Me.Text = String.Format("About {0}", applicationTitle)
        ' Initialize all of the text displayed on the About Box.
        ' TODO: Customize the application's assembly information in the "Application" pane of the project
        '    properties dialog (under the "Project" menu).
        Me.LabelProductName.Text = If(Assembly.GetExecutingAssembly().GetCustomAttribute(Of AssemblyProductAttribute)()?.Product, "")
        Me.LabelVersion.Text = String.Format("Version {0}", Assembly.GetExecutingAssembly().GetName().Version)
        Me.LabelCopyright.Text = If(Assembly.GetExecutingAssembly().GetCustomAttribute(Of AssemblyCopyrightAttribute)()?.Copyright, "")
        Me.LabelCompanyName.Text = If(Assembly.GetExecutingAssembly().GetCustomAttribute(Of AssemblyCompanyAttribute)()?.Company, "")
        Me.TextBoxDescription.Text = If(Assembly.GetExecutingAssembly().GetCustomAttribute(Of AssemblyDescriptionAttribute)()?.Description, "")
    End Sub

    Private Sub OKButton_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles OKButton.Click
        Me.Close()
    End Sub

End Class

SplashScreen

Imports System.Reflection

Public NotInheritable Class SplashScreen

    Private Sub SplashScreen1_Load(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Load
        'Set up the dialog text at runtime according to the application's assembly information.  

        'TODO: Customize the application's assembly information in the "Application" pane of the project
        '  properties dialog (under the "Project" menu).

        'Application title
        Dim appTitle As String = Assembly.GetExecutingAssembly().GetCustomAttribute(Of AssemblyTitleAttribute)()?.Title

        If String.IsNullOrEmpty(appTitle) Then
            appTitle = System.IO.Path.GetFileNameWithoutExtension(Assembly.GetExecutingAssembly().GetName().Name)
        End If

        ApplicationTitle.Text = appTitle

        Dim versionValue = Assembly.GetExecutingAssembly().GetName().Version

        'Format the version information using the text set into the Version control at design time as the
        '  formatting string.  This allows for effective localization if desired.
        '  Build and revision information could be included by using the following code and changing the
        '  Version control's designtime text to "Version {0}.{1:00}.{2}.{3}" or something similar.  See
        '  String.Format() in Help for more information.
        '
        '    Version.Text = System.String.Format(Version.Text, versionValue.Major, versionValue.Minor, versionValue.Build, versionValue.Revision)

        Version.Text = System.String.Format(Version.Text, versionValue.Major, versionValue.Minor)

        'Copyright info
        Copyright.Text = If(Assembly.GetExecutingAssembly().GetCustomAttribute(Of AssemblyCopyrightAttribute)()?.Copyright, "")
    End Sub

End Class

Category

Visual Basic Windows Forms

Affected APIs

None

Share via

Breaking changes in Windows Forms for .NET Core 3.0 and 3.1

.NET Core 3.1

Removed controls

Change description

Version introduced

Recommended action

Category

Affected APIs

CellFormatting event not raised if tooltip is shown

Change description

Version introduced

Recommended action

Category

Affected APIs

.NET Core 3.0

Default control font changed to Segoe UI 9 pt

Change description

Version introduced

Recommended action

Category

Affected APIs

Modernization of the FolderBrowserDialog

Change description

Version introduced

Recommended action

Category

Affected APIs

SerializableAttribute removed from some Windows Forms types

Change description

Version introduced

Recommended action

Category

Affected APIs

AllowUpdateChildControlIndexForTabControls compatibility switch not supported

Change description

Version introduced

Recommended action

Category

Affected APIs

DomainUpDown.UseLegacyScrolling compatibility switch not supported

Change description

Version introduced

Recommended action

Category

Affected APIs

DoNotLoadLatestRichEditControl compatibility switch not supported

Change description

Version introduced

Recommended action

Category

Affected APIs

DoNotSupportSelectAllShortcutInMultilineTextBox compatibility switch not supported

Change description

Version introduced

Recommended action

Category

Affected APIs

DontSupportReentrantFilterMessage compatibility switch not supported

Change description

Version introduced

Recommended action

Category

Affected APIs

EnableVisualStyleValidation compatibility switch not supported

Change description

Version introduced

Recommended action

Category

Affected APIs

UseLegacyContextMenuStripSourceControlValue compatibility switch not supported

Change description

Version introduced

Recommended action

Category

Affected APIs

UseLegacyImages compatibility switch not supported

Change description

Version introduced

Recommended action