Skip to content

Commit c4e83bb

Browse files
author
Cam Soper
authored
Add breaking change documentation for WPF and WinForms disambiguation (#45203)
* initial commit * lint * System.Windows.Controls.StatusBar isn't in API ref yet
1 parent 71baa7c commit c4e83bb

File tree

3 files changed

+79
-6
lines changed

3 files changed

+79
-6
lines changed

‎docs/core/compatibility/10.0.md

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -54,9 +54,10 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af
5454

5555
## Windows Forms
5656

57-
| Title | Type of change | Introduced version |
58-
|-------------------------------------------------------------------------------------------------------------------|---------------------|--------------------|
59-
| [API obsoletions](windows-forms/10.0/obsolete-apis.md) | Source incompatible | Preview 1 |
60-
| [Renamed parameter in HtmlElement.InsertAdjacentElement](windows-forms/10.0/insertadjacentelement-orientation.md) | Source incompatible | Preview 1 |
61-
| [TreeView checkbox image truncation](windows-forms/10.0/treeview-text-location.md) | Behavioral change | Preview 1 |
62-
| [StatusStrip uses System RenderMode by default](windows-forms/10.0/statusstrip-renderer.md) | Behavioral change | Preview 1 |
57+
| Title | Type of change | Introduced version |
58+
|-----------------------------------------------------------------------------------------------------------------------------------------------|---------------------|--------------------|
59+
| [API obsoletions](windows-forms/10.0/obsolete-apis.md) | Source incompatible | Preview 1 |
60+
| [Applications referencing both WPF and WinForms must disambiguate MenuItem and ContextMenu types](windows-forms/10.0/menuitem-contextmenu.md) | Source incompatible | Preview 1 |
61+
| [Renamed parameter in HtmlElement.InsertAdjacentElement](windows-forms/10.0/insertadjacentelement-orientation.md) | Source incompatible | Preview 1 |
62+
| [TreeView checkbox image truncation](windows-forms/10.0/treeview-text-location.md) | Behavioral change | Preview 1 |
63+
| [StatusStrip uses System RenderMode by default](windows-forms/10.0/statusstrip-renderer.md) | Behavioral change | Preview 1 |

‎docs/core/compatibility/toc.yml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,8 @@ items:
4646
items:
4747
- name: API obsoletions
4848
href: windows-forms/10.0/obsolete-apis.md
49+
- name: Applications referencing both WPF and WinForms must disambiguate MenuItem and ContextMenu types
50+
href: windows-forms/10.0/menuitem-contextmenu.md
4951
- name: Renamed parameter in HtmlElement.InsertAdjacentElement
5052
href: windows-forms/10.0/insertadjacentelement-orientation.md
5153
- name: TreeView checkbox image truncation
@@ -2128,6 +2130,8 @@ items:
21282130
items:
21292131
- name: API obsoletions
21302132
href: windows-forms/10.0/obsolete-apis.md
2133+
- name: Applications referencing both WPF and WinForms must disambiguate MenuItem and ContextMenu types
2134+
href: windows-forms/10.0/menuitem-contextmenu.md
21312135
- name: Renamed parameter in HtmlElement.InsertAdjacentElement
21322136
href: windows-forms/10.0/insertadjacentelement-orientation.md
21332137
- name: TreeView checkbox image truncation

‎docs/core/compatibility/windows-forms/10.0/menuitem-contextmenu.md

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
title: "Breaking change - Applications referencing both WPF and WinForms must disambiguate MenuItem and ContextMenu types"
3+
description: "Learn about the breaking change in .NET 10 Preview 1 where applications referencing both WPF and WinForms must disambiguate MenuItem and ContextMenu types."
4+
ms.date: 3/11/2025
5+
ai-usage: ai-assisted
6+
ms.custom: https://github.com/dotnet/docs/issues/44738
7+
---
8+
9+
# Applications referencing both WPF and WinForms must disambiguate MenuItem and ContextMenu types
10+
11+
This document describes a breaking change introduced in .NET 10 Preview 1. Applications that reference both Windows Presentation Foundation (WPF) and Windows Forms (WinForms) must disambiguate certain types, such as `MenuItem` and `ContextMenu`, to avoid compile-time errors.
12+
13+
## Version introduced
14+
15+
.NET 10 Preview 1
16+
17+
## Previous behavior
18+
19+
Previously, the types `ContextMenu`, `DataGrid`, `DataGridCell`, `Menu`, `MenuItem`, `ToolBar`, and `StatusBar` would resolve to the <xref:System.Windows.Controls> namespace because they did not exist in the <xref:System.Windows.Forms> namespace in .NET Core 3.1 through .NET 9.0.
20+
21+
```xml
22+
<ImplicitUsings>enable</ImplicitUsings>
23+
<UseWindowsForms>true</UseWindowsForms>
24+
<UseWPF>true</UseWPF>
25+
```
26+
27+
## New behavior
28+
29+
The affected types in the <xref:System.Windows.Forms> namespace cause a compile-time error when there is an ambiguous reference between <xref:System.Windows.Controls> and <xref:System.Windows.Forms>.
30+
31+
```output
32+
CS0104 'ContextMenu' is an ambiguous reference between 'System.Windows.Controls.ContextMenu' and 'System.Windows.Forms.ContextMenu'
33+
```
34+
35+
## Type of breaking change
36+
37+
This is a [source incompatible](../../categories.md#source-compatibility) change.
38+
39+
## Reason for change
40+
41+
The change facilitates migration from .NET Framework when third-party libraries cannot be updated. A .NET 10 application can continue to reference .NET Framework dependencies and handle errors at runtime.
42+
43+
## Recommended action
44+
45+
Use aliases to resolve conflicting namespaces. For example:
46+
47+
```csharp
48+
using ContextMenu = System.Windows.Controls.ContextMenu;
49+
```
50+
51+
Refer to the [alias name conflicts documentation](/dotnet/csharp/language-reference/compiler-messages/using-directive-errors#alias-name-conflicts) for more details.
52+
53+
## Affected APIs
54+
55+
- <xref:System.Windows.Forms.ContextMenu?displayProperty=fullName>
56+
- <xref:System.Windows.Forms.DataGrid?displayProperty=fullName>
57+
- <xref:System.Windows.Forms.DataGridCell?displayProperty=fullName>
58+
- <xref:System.Windows.Forms.Menu?displayProperty=fullName>
59+
- <xref:System.Windows.Forms.MenuItem?displayProperty=fullName>
60+
- <xref:System.Windows.Forms.ToolBar?displayProperty=fullName>
61+
- <xref:System.Windows.Forms.StatusBar?displayProperty=fullName>
62+
- <xref:System.Windows.Controls.ContextMenu?displayProperty=fullName>
63+
- <xref:System.Windows.Controls.DataGrid?displayProperty=fullName>
64+
- <xref:System.Windows.Controls.DataGridCell?displayProperty=fullName>
65+
- <xref:System.Windows.Controls.Menu?displayProperty=fullName>
66+
- <xref:System.Windows.Controls.MenuItem?displayProperty=fullName>
67+
- <xref:System.Windows.Controls.ToolBar?displayProperty=fullName>
68+
- `System.Windows.Controls.StatusBar`

0 commit comments

Comments
 (0)