Skip to content

Commit 44bba33

Browse files
KlausLoeffelmannKlausLoeffelmann
authored
Remove 5002 Experimental state for UI Async area (#13811)
This PR removes the experimental status of the UI Async APIs: * `Form.ShowAsync` * `Form.ShowDialogAsync` * `TaskDialog.ShowDialogAsync` It also amends the docs with additional information about best practices for using ShowAsync in MultiForm / ToolWindow-async scenarios. ###### Microsoft Reviewers: [Open in CodeFlow](https://microsoft.github.io/open-pr/?codeflow=https://github.com/dotnet/winforms/pull/13811)
2 parents 7fa23ac + 71598cf commit 44bba33

File tree

5 files changed

+44
-16
lines changed

5 files changed

+44
-16
lines changed

‎src/System.Windows.Forms/PublicAPI.Shipped.txt‎

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -18,12 +18,6 @@
1818
[WFO5001]virtual System.Windows.Forms.Form.OnFormCaptionBackColorChanged(System.EventArgs! e) -> void
1919
[WFO5001]virtual System.Windows.Forms.Form.OnFormCaptionTextColorChanged(System.EventArgs! e) -> void
2020
[WFO5001]virtual System.Windows.Forms.Form.OnFormCornerPreferenceChanged(System.EventArgs! e) -> void
21-
[WFO5002]static System.Windows.Forms.TaskDialog.ShowDialogAsync(nint hwndOwner, System.Windows.Forms.TaskDialogPage! page, System.Windows.Forms.TaskDialogStartupLocation startupLocation = System.Windows.Forms.TaskDialogStartupLocation.CenterOwner) -> System.Threading.Tasks.Task<System.Windows.Forms.TaskDialogButton!>!
22-
[WFO5002]static System.Windows.Forms.TaskDialog.ShowDialogAsync(System.Windows.Forms.IWin32Window! owner, System.Windows.Forms.TaskDialogPage! page, System.Windows.Forms.TaskDialogStartupLocation startupLocation = System.Windows.Forms.TaskDialogStartupLocation.CenterOwner) -> System.Threading.Tasks.Task<System.Windows.Forms.TaskDialogButton!>!
23-
[WFO5002]static System.Windows.Forms.TaskDialog.ShowDialogAsync(System.Windows.Forms.TaskDialogPage! page, System.Windows.Forms.TaskDialogStartupLocation startupLocation = System.Windows.Forms.TaskDialogStartupLocation.CenterScreen) -> System.Threading.Tasks.Task<System.Windows.Forms.TaskDialogButton!>!
24-
[WFO5002]System.Windows.Forms.Form.ShowAsync(System.Windows.Forms.IWin32Window? owner = null) -> System.Threading.Tasks.Task!
25-
[WFO5002]System.Windows.Forms.Form.ShowDialogAsync() -> System.Threading.Tasks.Task<System.Windows.Forms.DialogResult>!
26-
[WFO5002]System.Windows.Forms.Form.ShowDialogAsync(System.Windows.Forms.IWin32Window! owner) -> System.Threading.Tasks.Task<System.Windows.Forms.DialogResult>!
2721
[WFO5003]System.Windows.Forms.IAsyncDropTarget
2822
[WFO5003]System.Windows.Forms.IAsyncDropTarget.OnAsyncDragDrop(System.Windows.Forms.DragEventArgs! e) -> void
2923
~abstract System.Windows.Forms.DataGridColumnStyle.Commit(System.Windows.Forms.CurrencyManager dataSource, int rowNum) -> bool

‎src/System.Windows.Forms/PublicAPI.Unshipped.txt‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,7 @@
1-
System.Windows.Forms.VisualStyles.ComboBoxState.Focused = 5 -> System.Windows.Forms.VisualStyles.ComboBoxState
1+
static System.Windows.Forms.TaskDialog.ShowDialogAsync(nint hwndOwner, System.Windows.Forms.TaskDialogPage! page, System.Windows.Forms.TaskDialogStartupLocation startupLocation = System.Windows.Forms.TaskDialogStartupLocation.CenterOwner) -> System.Threading.Tasks.Task<System.Windows.Forms.TaskDialogButton!>!
2+
static System.Windows.Forms.TaskDialog.ShowDialogAsync(System.Windows.Forms.IWin32Window! owner, System.Windows.Forms.TaskDialogPage! page, System.Windows.Forms.TaskDialogStartupLocation startupLocation = System.Windows.Forms.TaskDialogStartupLocation.CenterOwner) -> System.Threading.Tasks.Task<System.Windows.Forms.TaskDialogButton!>!
3+
static System.Windows.Forms.TaskDialog.ShowDialogAsync(System.Windows.Forms.TaskDialogPage! page, System.Windows.Forms.TaskDialogStartupLocation startupLocation = System.Windows.Forms.TaskDialogStartupLocation.CenterScreen) -> System.Threading.Tasks.Task<System.Windows.Forms.TaskDialogButton!>!
4+
System.Windows.Forms.Form.ShowAsync(System.Windows.Forms.IWin32Window? owner = null) -> System.Threading.Tasks.Task!
5+
System.Windows.Forms.Form.ShowDialogAsync() -> System.Threading.Tasks.Task<System.Windows.Forms.DialogResult>!
6+
System.Windows.Forms.Form.ShowDialogAsync(System.Windows.Forms.IWin32Window! owner) -> System.Threading.Tasks.Task<System.Windows.Forms.DialogResult>!
7+
System.Windows.Forms.VisualStyles.ComboBoxState.Focused = 5 -> System.Windows.Forms.VisualStyles.ComboBoxState

‎src/System.Windows.Forms/System/Windows/Forms/Dialogs/TaskDialog/TaskDialog.cs‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,6 @@
44
using System.ComponentModel;
55
using System.Runtime.CompilerServices;
66
using System.Runtime.InteropServices;
7-
using System.Windows.Forms.Analyzers.Diagnostics;
87
using TASKDIALOGCONFIG_FooterIcon = Windows.Win32.UI.Controls.TASKDIALOGCONFIG._Anonymous2_e__Union;
98
using TASKDIALOGCONFIG_MainIcon = Windows.Win32.UI.Controls.TASKDIALOGCONFIG._Anonymous1_e__Union;
109
namespace System.Windows.Forms;
@@ -324,7 +323,6 @@ private static TaskDialogButton CreatePlaceholderButton(TaskDialogResult result)
324323
/// <exception cref="InvalidOperationException">
325324
/// The specified <paramref name="page"/> contains an invalid configuration.
326325
/// </exception>
327-
[Experimental(DiagnosticIDs.ExperimentalAsync, UrlFormat = DiagnosticIDs.UrlFormat)]
328326
public static Task<TaskDialogButton> ShowDialogAsync(
329327
TaskDialogPage page,
330328
TaskDialogStartupLocation startupLocation = TaskDialogStartupLocation.CenterScreen)
@@ -357,7 +355,6 @@ public static Task<TaskDialogButton> ShowDialogAsync(
357355
/// <exception cref="InvalidOperationException">
358356
/// The specified <paramref name="page"/> contains an invalid configuration.
359357
/// </exception>
360-
[Experimental(DiagnosticIDs.ExperimentalAsync, UrlFormat = DiagnosticIDs.UrlFormat)]
361358
public static Task<TaskDialogButton> ShowDialogAsync(
362359
IWin32Window owner,
363360
TaskDialogPage page,
@@ -391,7 +388,6 @@ public static Task<TaskDialogButton> ShowDialogAsync(
391388
/// <exception cref="InvalidOperationException">
392389
/// The specified <paramref name="page"/> contains an invalid configuration.
393390
/// </exception>
394-
[Experimental(DiagnosticIDs.ExperimentalAsync, UrlFormat = DiagnosticIDs.UrlFormat)]
395391
public static async Task<TaskDialogButton> ShowDialogAsync(
396392
nint hwndOwner,
397393
TaskDialogPage page,

‎src/System.Windows.Forms/System/Windows/Forms/Form.cs‎

Lines changed: 37 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5555,6 +5555,43 @@ public void Show(IWin32Window? owner)
55555555
/// There is no need to marshal the call to the UI thread manually if the call
55565556
/// originates from a different thread than the UI-Thread. This is handled automatically.
55575557
/// </para>
5558+
/// <para>
5559+
/// The returned <see cref="Task"/> carries a <see cref="WeakReference{T}"/> to the <see cref="Form"/> in its
5560+
/// <see cref="Task.AsyncState"/> property. This is particularly useful when managing multiple forms (such as tool windows)
5561+
/// in a task-based window manager, as it eliminates the need for a separate lookup table to synchronize between tasks and forms.
5562+
/// </para>
5563+
/// <para>
5564+
/// The following example shows how to retrieve the form from a completed task when managing multiple forms:
5565+
/// </para>
5566+
/// <code>
5567+
/// // Wait for any of the forms to complete
5568+
/// Task completedShowAsyncTask = await Task
5569+
/// .WhenAny(formAsyncTasks)
5570+
/// .ConfigureAwait(false);
5571+
///
5572+
/// // Retrieve the form using an extension method
5573+
/// if (completedShowAsyncTask.ToForm() is Form form)
5574+
/// {
5575+
/// // Handle the completed form
5576+
/// }
5577+
/// </code>
5578+
/// <para>
5579+
/// Where the extension method can be implemented as:
5580+
/// </para>
5581+
/// <code>
5582+
/// public static Form? ToForm(this Task task)
5583+
/// {
5584+
/// ArgumentNullException.ThrowIfNull(task);
5585+
///
5586+
/// if (task.AsyncState is WeakReference&lt;Form&gt; weakRefToForm
5587+
/// &amp;&amp; weakRefToForm.TryGetTarget(out Form? form))
5588+
/// {
5589+
/// return form;
5590+
/// }
5591+
///
5592+
/// return null;
5593+
/// }
5594+
/// </code>
55585595
/// </remarks>
55595596
/// <exception cref="InvalidOperationException">
55605597
/// <para>Thrown if:</para>
@@ -5573,7 +5610,6 @@ public void Show(IWin32Window? owner)
55735610
/// <exception cref="ArgumentException">
55745611
/// <para>Thrown if the owner window is trying to set itself as its own owner.</para>
55755612
/// </exception>
5576-
[Experimental(DiagnosticIDs.ExperimentalAsync, UrlFormat = DiagnosticIDs.UrlFormat)]
55775613
public Task ShowAsync(IWin32Window? owner = null)
55785614
{
55795615
// We lock the access to the task completion source to prevent
@@ -5834,7 +5870,6 @@ public DialogResult ShowDialog(IWin32Window? owner)
58345870
/// Thrown if the form is already displayed asynchronously or if no
58355871
/// <see cref="WindowsFormsSynchronizationContext"/> could be retrieved or installed.
58365872
/// </exception>
5837-
[Experimental(DiagnosticIDs.ExperimentalAsync, UrlFormat = DiagnosticIDs.UrlFormat)]
58385873
public Task<DialogResult> ShowDialogAsync() => ShowDialogAsyncInternal(owner: null);
58395874

58405875
/// <summary>
@@ -5875,7 +5910,6 @@ public DialogResult ShowDialog(IWin32Window? owner)
58755910
/// Thrown if the form is already displayed asynchronously or if
58765911
/// no <see cref="WindowsFormsSynchronizationContext"/> could be retrieved or installed.
58775912
/// </exception>
5878-
[Experimental(DiagnosticIDs.ExperimentalAsync, UrlFormat = DiagnosticIDs.UrlFormat)]
58795913
public Task<DialogResult> ShowDialogAsync(IWin32Window owner) => ShowDialogAsyncInternal(owner);
58805914

58815915
private Task<DialogResult> ShowDialogAsyncInternal(IWin32Window? owner)

‎src/test/unit/System.Windows.Forms/System/Windows/Forms/FormTests.cs‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2656,7 +2656,6 @@ public void Form_Show_SetsOwnerToTopLevelForm_WhenShownWithOwner(Action<Form, Co
26562656
Assert.False(child.IsHandleCreated);
26572657
}
26582658

2659-
#pragma warning disable WFO5002 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
26602659
[WinFormsFact]
26612660
public async Task Form_ShowAsync_GeneralTaskTests()
26622661
{
@@ -2719,7 +2718,6 @@ await Task.Delay(random.Next(20, 100))
27192718
formControlTasks.Remove(finishedTask);
27202719
}
27212720
}
2722-
#pragma warning restore WFO5002 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
27232721

27242722
[WinFormsFact]
27252723
public void Form_ParentThenSetShowInTaskbarToFalse()

0 commit comments

Comments
 (0)