Breaking changes for migration from .NET Framework to .NET Core 3.0

Important

This article is under construction. This is not a complete list of .NET Core breaking changes. For more information on .NET Core breaking changes, you can examine individual breaking changes issues in the dotnet/docs repository on GitHub.

If you are migrating a Windows Forms or Windows Presentation Foundation application from .NET Framework to .NET Core 3.0, review the following topics for breaking changes that may affect your app:

Windows Forms

Control.DefaultFont changed to Segoe UI 9pt

Change description

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

default control font in .NET Framework

In .NET Core starting with .NET Core 3.0, it is set to Segoe UI 9pt (the same font as SystemFonts.MessageBoxFont). As a result of this change, forms and controls will be 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 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 8pt. 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

Switch.System.Windows.Forms.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

Switch.System.Windows.Forms.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


Switch.System.Windows.Forms.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


Switch.System.Windows.Forms.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

Switch.System.Windows.Forms.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


Switch.System.Windows.Forms.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

Switch.System.Windows.Forms.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


Switch.System.Windows.Forms.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