From 1205e00bc8d99a547f22d7be66507aa1e5b9cefe Mon Sep 17 00:00:00 2001 From: "Andy (Steve) De George" <67293991+adegeo@users.noreply.github.com> Date: Thu, 21 Nov 2024 14:18:55 -0800 Subject: [PATCH] New WinForms diagnostic reference articles (#1938) * Add new analyzers; revamp toc * redirect * review items --- .openpublishing.redirection.winforms.json | 4 + .../net/winforms/compiler-messages/wfo0003.md | 132 ++++++++++++++++++ .../net/winforms/compiler-messages/wfo5001.md | 78 +++++++++++ .../net/winforms/compiler-messages/wfo5002.md | 66 +++++++++ dotnet-desktop-guide/net/winforms/toc.yml | 20 ++- .../wfdev-diagnostics/obsoletions-overview.md | 64 --------- .../net/winforms/wfdev-diagnostics/wfac010.md | 3 + .../net/winforms/whats-new/net90.md | 8 +- redirects_generator/definitions.winforms.json | 5 + 9 files changed, 310 insertions(+), 70 deletions(-) create mode 100644 dotnet-desktop-guide/net/winforms/compiler-messages/wfo0003.md create mode 100644 dotnet-desktop-guide/net/winforms/compiler-messages/wfo5001.md create mode 100644 dotnet-desktop-guide/net/winforms/compiler-messages/wfo5002.md delete mode 100644 dotnet-desktop-guide/net/winforms/wfdev-diagnostics/obsoletions-overview.md diff --git a/.openpublishing.redirection.winforms.json b/.openpublishing.redirection.winforms.json index 46922ef681..2a52ec0d29 100644 --- a/.openpublishing.redirection.winforms.json +++ b/.openpublishing.redirection.winforms.json @@ -499,6 +499,10 @@ { "source_path": "dotnet-desktop-guide/net/winforms/controls-design/index.md", "redirect_url": "/dotnet/desktop/winforms/controls-design/overview?view=netdesktop-9.0" + }, + { + "source_path": "dotnet-desktop-guide/net/winforms/wfdev-diagnostics/obsoletions-overview.md", + "redirect_url": "/dotnet/desktop/winforms/?view=netdesktop-9.0" } ] } diff --git a/dotnet-desktop-guide/net/winforms/compiler-messages/wfo0003.md b/dotnet-desktop-guide/net/winforms/compiler-messages/wfo0003.md new file mode 100644 index 0000000000..f151e4e7fe --- /dev/null +++ b/dotnet-desktop-guide/net/winforms/compiler-messages/wfo0003.md @@ -0,0 +1,132 @@ +--- +title: Compiler Warning WFO5003 +description: Learn more about compiler warning WFO5003. ColorMode is for evaluation purposes only and subject to change. +ms.date: 11/19/2024 +f1_keywords: + - "WFO5001" +helpviewer_keywords: + - "WFO5001" +--- + +# Compiler Warning WFO5003 + +Remove high DPI settings from app.manifest and configure via Application.SetHighDpiMode API or 'ApplicationHighDpiMode' project property. + +## Example + +Your project contains an _app.manifest_ file with the `` setting: + +```xml + + + + + + true + + + +``` + +## To correct this error + +Windows Forms applications should specify application DPI-awareness via the [application configuration](../whats-new/net60.md#new-application-bootstrap) or with the API. + +Alternatively, you can suppress the warning. For more information, see [How to suppress code analysis warnings](/dotnet/fundamentals/code-analysis/suppress-warnings). + +### Using C\# + +Call the `ApplicationConfiguration.Initialize` method before . + +```csharp +class Program +{ + [STAThread] + static void Main() + { + ApplicationConfiguration.Initialize(); + Application.Run(new Form1()); + } +} +``` + +The `ApplicationConfiguration.Initialize` method is generated when your app compiles, based on the settings in the app's project file. For example, look at the following `` settings: + +```xml + + + + WinExe + net9.0-windows + enable + true + enable + + SystemAware + true + false + Microsoft Sans Serif, 8.25pt + + + + +``` + +These settings generate the following method: + +```csharp +[CompilerGenerated] +internal static partial class ApplicationConfiguration +{ + public static void Initialize() + { + global::System.Windows.Forms.Application.EnableVisualStyles(); + global::System.Windows.Forms.Application.SetCompatibleTextRenderingDefault(false); + global::System.Windows.Forms.Application.SetHighDpiMode(HighDpiMode.SystemAware); + global::System.Windows.Forms.Application.SetDefaultFont(new Font(new FontFamily("Microsoft Sans Serif"), 8.25f, (FontStyle)0, (GraphicsUnit)3)); + } +} +``` + +### Using Visual Basic + +Visual Basic sets the High DPI mode in two places. The first is in the project properties, which affects the Visual Studio Designer, but doesn't affect the app at run-time. + +```xml + + + + WinExe + net9.0-windows + Sub Main + true + WindowsForms + + SystemAware + false + false + Microsoft Sans Serif, 8.25pt + + + + +``` + +The second place is in the Visual Basic Application Framework settings. These are in the project properties page, under **Application** > **Application Framework**. These settings are saved into the _My Project\\Application.myapp_ file or in an application startup event handler. + +### Setting the font in Visual Basic + +The run-time font, however, isn't configurable in Visual Basic through an app setting or the project file. It must be set in the event handler. + +```vb +Imports Microsoft.VisualBasic.ApplicationServices + +Namespace My + Partial Friend Class MyApplication + Private Sub MyApplication_ApplyApplicationDefaults(sender As Object, e As ApplyApplicationDefaultsEventArgs) Handles Me.ApplyApplicationDefaults + e.HighDpiMode = HighDpiMode.SystemAware + e.Font = New Font("Microsoft Sans Serif", 8.25) + End Sub + End Class +End Namespace +``` diff --git a/dotnet-desktop-guide/net/winforms/compiler-messages/wfo5001.md b/dotnet-desktop-guide/net/winforms/compiler-messages/wfo5001.md new file mode 100644 index 0000000000..d7bc51e7d7 --- /dev/null +++ b/dotnet-desktop-guide/net/winforms/compiler-messages/wfo5001.md @@ -0,0 +1,78 @@ +--- +title: Compiler Error WFO5001 +description: Learn more about compiler error WFO5001. ColorMode is for evaluation purposes only and subject to change. +ms.date: 11/19/2024 +f1_keywords: + - "WFO5001" +helpviewer_keywords: + - "WFO5001" +--- + +# Compiler Error WFO5001 + +'System.Windows.Forms.Application.SetColorMode(System.Windows.Forms.SystemColorMode)' is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed. + +-or- + +'System.Windows.Forms.SystemColorMode' is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed. + +The color mode feature is currently experimental and subject to change. This error is generated so that you understand the implications of writing code that sets the color mode of the Windows Forms project. The error must be suppressed to continue. For more information about this API, see [Dark mode](../whats-new/net90.md#dark-mode). + +## Example + +The following sample generates WFO5001: + +```csharp +namespace MyExampleProject; + +static class Program +{ + [STAThread] + static void Main() + { + ApplicationConfiguration.Initialize(); + Application.SetColorMode(SystemColorMode.Dark); + Application.Run(new Form1()); + } +} +``` + +## To correct this error + +Suppress the error and enable access to the API by either of the following methods: + +- Set the severity of the rule in the _.editorConfig_ file. + + ```ini + [*.{cs,vb}] + dotnet_diagnostic.WFO5001.severity = none + ``` + + For more information about editor config files, see [Configuration files for code analysis rules](/dotnet/fundamentals/code-analysis/configuration-files). + +- Add the following `PropertyGroup` to your project file to suppress the error: + + ```xml + + $(NoWarn);WFO5001 + + ``` + +- Suppress the error in code with the `#pragma warning disable WFO5001` directive: + + ```csharp + namespace MyExampleProject; + + static class Program + { + [STAThread] + static void Main() + { + ApplicationConfiguration.Initialize(); + #pragma warning disable WFO5001 + Application.SetColorMode(SystemColorMode.Dark); + #pragma warning restore WFO5001 + Application.Run(new Form1()); + } + } + ``` diff --git a/dotnet-desktop-guide/net/winforms/compiler-messages/wfo5002.md b/dotnet-desktop-guide/net/winforms/compiler-messages/wfo5002.md new file mode 100644 index 0000000000..15768df0c8 --- /dev/null +++ b/dotnet-desktop-guide/net/winforms/compiler-messages/wfo5002.md @@ -0,0 +1,66 @@ +--- +title: Compiler Error WFO5002 +description: Learn more about compiler error WFO5002. Async is for evaluation purposes only and subject to change. +ms.date: 11/19/2024 +f1_keywords: + - "WFO5002" +helpviewer_keywords: + - "WFO5002" +--- + +# Compiler Error WFO5002 + +'System.Windows.Forms.Form.ShowAsync' is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed. + +This compiler error is generated when using any of the following methods: + +- `Form.ShowAsync` +- `Form.ShowDialogAsync` +- `TaskDialog.ShowDialogAsync` + +The Windows Forms asynchronous API is currently experimental and subject to change. This error is generated so that you understand the implications of writing code that uses these APIs. The error must be suppressed to continue. For more information about this API, see [Async forms](../whats-new/net90.md#async-forms). + +## Example + +The following sample generates WFO5002: + +```csharp +private async void button1_Click(object sender, EventArgs e) +{ + Form1 newDialog = new(); + await newDialog.ShowAsync(); +} +``` + +## To correct this error + +Suppress the error and enable access to the API by either of the following methods: + +- Set the severity of the rule in the _.editorConfig_ file. + + ```ini + [*.{cs,vb}] + dotnet_diagnostic.WFO5002.severity = none + ``` + + For more information about editor config files, see [Configuration files for code analysis rules](/dotnet/fundamentals/code-analysis/configuration-files). + +- Add the following `PropertyGroup` to your project file to suppress the error: + + ```xml + + $(NoWarn);WFO5002 + + ``` + +- Suppress the error in code with the `#pragma warning disable WFO5002` directive: + + ```csharp + private async void button1_Click(object sender, EventArgs e) + { + Form1 newDialog = new(); + #pragma warning disable WFO5002 + await newDialog.ShowAsync(); + #pragma warning restore WFO5002 + } + ``` diff --git a/dotnet-desktop-guide/net/winforms/toc.yml b/dotnet-desktop-guide/net/winforms/toc.yml index 5a0d7f3d11..10e0acc8c1 100644 --- a/dotnet-desktop-guide/net/winforms/toc.yml +++ b/dotnet-desktop-guide/net/winforms/toc.yml @@ -187,16 +187,32 @@ items: href: data/how-to-synchronize-multiple-controls.md - name: Compiler warnings and errors items: + - name: Type + items: + - name: Application configuration + items: + - name: Migrate DPI settings + href: compiler-messages/wfo0003.md + - name: Experimental + items: + - name: Dark mode + href: compiler-messages/wfo5001.md + - name: Async + href: compiler-messages/wfo5002.md - name: Errors items: + - name: WFO5001 + href: compiler-messages/wfo5001.md + - name: WFO5002 + href: compiler-messages/wfo5002.md - name: WFAC001 href: wfdev-diagnostics/wfac001.md - name: WFAC002 href: wfdev-diagnostics/wfac002.md - name: Warnings items: - - name: Obsoletions overview - href: wfdev-diagnostics/obsoletions-overview.md + - name: WFO0003 + href: compiler-messages/wfo0003.md - name: WFAC010 href: wfdev-diagnostics/wfac010.md - name: WFDEV001 diff --git a/dotnet-desktop-guide/net/winforms/wfdev-diagnostics/obsoletions-overview.md b/dotnet-desktop-guide/net/winforms/wfdev-diagnostics/obsoletions-overview.md deleted file mode 100644 index c24a4a190b..0000000000 --- a/dotnet-desktop-guide/net/winforms/wfdev-diagnostics/obsoletions-overview.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Obsolete Windows Forms features in .NET -titleSuffix: "" -description: Learn about Windows Forms APIs that are marked as obsolete in .NET 7 and later versions that produce WFDEV compiler warnings. -ms.date: 11/14/2024 ---- - -# Obsolete Windows Forms features in .NET - -Starting in .NET 7, some Windows Forms APIs are marked as obsolete (or otherwise produce a warning) with custom diagnostic IDs of the format `WFDEVXXX`. - -If you encounter build warnings or errors due to usage of an obsolete API, follow the specific guidance provided for the diagnostic ID listed in the [Reference](#reference) section. Warnings or errors for these obsoletions *can't* be suppressed using the [standard diagnostic ID (CS0618)](/dotnet/csharp/language-reference/compiler-messages/cs0618) for obsolete types or members; use the custom `WFDEVXXX` diagnostic ID values instead. For more information, see [Suppress warnings](#suppress-warnings). - -## Reference - -The following table provides an index to the `WFDEVXXX` obsoletions and warnings in .NET 7+. - -| Diagnostic ID | Warning or error | Description | -| - | - | -| [WFDEV001](wfdev001.md) | Warning | Casting to/from is unsafe. Use `WParamInternal`, `LParamInternal`, or `ResultInternal` instead. | -| [WFDEV002](wfdev002.md) | Warning/error | is no longer used to provide accessible support for controls. Use instead. | -| [WFDEV003](wfdev003.md) | Warning | is no longer used to provide accessible support for items. Use instead. | - -## Suppress warnings - -It's recommended that you use an available workaround whenever possible. However, if you cannot change your code, you can suppress warnings through a `#pragma` directive or a `` project setting. If you must use the obsolete APIs and the `WFDEVXXX` diagnostic does not surface as an error, you can suppress the warning in code or in your project file. - -To suppress the warnings in code: - -```csharp -// Disable the warning. -#pragma warning disable WFDEV001 - -// Code that uses obsolete API. -//... - -// Re-enable the warning. -#pragma warning restore WFDEV001 -``` - -To suppress the warnings in a project file: - -```xml - - - net7.0 - - $(NoWarn);WFDEV001 - - $(NoWarn);WFDEV001 - $(NoWarn);WFDEV003 - - $(NoWarn);WFDEV001;WFDEV003 - - -``` - -> [!NOTE] -> Suppressing warnings in this way only disables the obsoletion warnings you specify. It doesn't disable any other warnings, including obsoletion warnings with different diagnostic IDs. - -## See also - -- [Obsolete .NET features](/dotnet/fundamentals/syslib-diagnostics/obsoletions-overview) - diff --git a/dotnet-desktop-guide/net/winforms/wfdev-diagnostics/wfac010.md b/dotnet-desktop-guide/net/winforms/wfdev-diagnostics/wfac010.md index 4eab8ffad6..037c74bfa4 100644 --- a/dotnet-desktop-guide/net/winforms/wfdev-diagnostics/wfac010.md +++ b/dotnet-desktop-guide/net/winforms/wfdev-diagnostics/wfac010.md @@ -7,6 +7,9 @@ ms.date: 11/15/2023 Windows Forms applications should specify application DPI-awareness via the [application configuration](../whats-new/net60.md#new-application-bootstrap) or with the API. +> [!IMPORTANT] +> Starting with .NET 9, this warning has changed to [WFO0003](../compiler-messages/wfo0003.md). + ## Workarounds ### Using C\# diff --git a/dotnet-desktop-guide/net/winforms/whats-new/net90.md b/dotnet-desktop-guide/net/winforms/whats-new/net90.md index 33ad58b2d7..65b1d8db82 100644 --- a/dotnet-desktop-guide/net/winforms/whats-new/net90.md +++ b/dotnet-desktop-guide/net/winforms/whats-new/net90.md @@ -22,14 +22,14 @@ The following a list of new methods added to support asynchronous scenarios: - [System.Windows.Forms.Form.ShowAsync](xref:System.Windows.Forms.Form.ShowAsync(System.Windows.Forms.IWin32Window)?displayProperty=nameWithType) - - -- +- (This API isn't experimental.) This API is guarded behind a compiler error because it's experimental. To suppress the error and enable access to the API, add the following `PropertyGroup` to your project file: :::code language="xml" source=".\snippets\net90\csharp\MyExampleProject.csproj" id="experimental_async"::: > [!TIP] -> You can use the `#pragma warning disable WFO5002` directive to suppress the error where it occurs instead of disabling it for the entire project. +> For more information about how to suppress this rule, see [Compiler Error WFO5002](../compiler-messages/wfo5002.md#to-correct-this-error). ## BinaryFormatter no longer supported @@ -48,7 +48,7 @@ For more information about `BinaryFormatter`, see [Windows Forms migration guide > [!IMPORTANT] > This feature set is experimental. -Preliminary support for dark mode has been added to Windows Forms, with the goal of finalizing support in .NET 10. The color mode for the app can be set to one of the following values: +Preliminary support for dark mode has been added to Windows Forms, with the goal of finalizing support in .NET 10. When the color mode changes, the are changed to match. The color mode for the app can be set to one of the following values: - `SystemColorMode.Classic`—(default) Light mode, the same as previous versions of Windows Forms. - `SystemColorMode.System`—Respect the light or dark mode set by Windows. @@ -64,7 +64,7 @@ This API is guarded behind a compiler error because it's experimental. To suppre :::code language="xml" source=".\snippets\net90\csharp\MyExampleProject.csproj" id="experimental_darkmode"::: > [!TIP] -> You can use the `#pragma warning disable WFO5001` directive to suppress the error where it occurs instead of disabling it for the entire project. +> For more information about how to suppress this rule, see [Compiler Error WFO5001](../compiler-messages/wfo5001.md#to-correct-this-error). ## FolderBrowserDialog enhancements diff --git a/redirects_generator/definitions.winforms.json b/redirects_generator/definitions.winforms.json index cd6adb5cee..d2f8addd16 100644 --- a/redirects_generator/definitions.winforms.json +++ b/redirects_generator/definitions.winforms.json @@ -12,6 +12,11 @@ "SourceUrl": "/dotnet/desktop/winforms/controls/custom?view=netdesktop-9.0", "TargetUrl": "/dotnet/desktop/winforms/controls-design/overview?view=netdesktop-9.0" }, + { + "Redirect": "Normal", + "SourceUrl": "/dotnet/desktop/winforms/wfdev-diagnostics/obsoletions-overview?view=netdesktop-9.0", + "TargetUrl": "/dotnet/desktop/winforms/?view=netdesktop-9.0" + }, // Basics {