From 81027a7aae3255239af64c0ec3b3e4c0e0d8048d Mon Sep 17 00:00:00 2001 From: "Andy De George (adegeo)" Date: Tue, 19 Nov 2024 12:10:29 -0800 Subject: [PATCH 1/3] Add new analyzers; revamp toc --- .../net/winforms/compiler-messages/wfo0003.md | 131 ++++++++++++++++++ .../net/winforms/compiler-messages/wfo5001.md | 69 +++++++++ .../net/winforms/compiler-messages/wfo5002.md | 58 ++++++++ dotnet-desktop-guide/net/winforms/toc.yml | 20 ++- .../wfdev-diagnostics/obsoletions-overview.md | 64 --------- .../net/winforms/wfdev-diagnostics/wfac010.md | 3 + 6 files changed, 279 insertions(+), 66 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/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..3cb04ab007 --- /dev/null +++ b/dotnet-desktop-guide/net/winforms/compiler-messages/wfo0003.md @@ -0,0 +1,131 @@ +--- +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.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..03b97befac --- /dev/null +++ b/dotnet-desktop-guide/net/winforms/compiler-messages/wfo5001.md @@ -0,0 +1,69 @@ +--- +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: + +- 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..6f82039b13 --- /dev/null +++ b/dotnet-desktop-guide/net/winforms/compiler-messages/wfo5002.md @@ -0,0 +1,58 @@ +--- +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` +- `Control.InvokeAsync` +- `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: + +- 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\# From 45b503f56e90b515c58f65cea2f33faa8c56604b Mon Sep 17 00:00:00 2001 From: "Andy De George (adegeo)" Date: Tue, 19 Nov 2024 12:16:51 -0800 Subject: [PATCH 2/3] redirect --- .openpublishing.redirection.winforms.json | 4 ++++ redirects_generator/definitions.winforms.json | 5 +++++ 2 files changed, 9 insertions(+) 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/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 { From ea2349cce458d25c5fab88a7b7e63f0e7490c31e Mon Sep 17 00:00:00 2001 From: "Andy De George (adegeo)" Date: Wed, 20 Nov 2024 16:26:50 -0800 Subject: [PATCH 3/3] review items --- .../net/winforms/compiler-messages/wfo0003.md | 1 + .../net/winforms/compiler-messages/wfo5001.md | 9 +++++++++ .../net/winforms/compiler-messages/wfo5002.md | 10 +++++++++- dotnet-desktop-guide/net/winforms/whats-new/net90.md | 8 ++++---- 4 files changed, 23 insertions(+), 5 deletions(-) diff --git a/dotnet-desktop-guide/net/winforms/compiler-messages/wfo0003.md b/dotnet-desktop-guide/net/winforms/compiler-messages/wfo0003.md index 3cb04ab007..f151e4e7fe 100644 --- a/dotnet-desktop-guide/net/winforms/compiler-messages/wfo0003.md +++ b/dotnet-desktop-guide/net/winforms/compiler-messages/wfo0003.md @@ -124,6 +124,7 @@ 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 diff --git a/dotnet-desktop-guide/net/winforms/compiler-messages/wfo5001.md b/dotnet-desktop-guide/net/winforms/compiler-messages/wfo5001.md index 03b97befac..d7bc51e7d7 100644 --- a/dotnet-desktop-guide/net/winforms/compiler-messages/wfo5001.md +++ b/dotnet-desktop-guide/net/winforms/compiler-messages/wfo5001.md @@ -41,6 +41,15 @@ static class Program 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 diff --git a/dotnet-desktop-guide/net/winforms/compiler-messages/wfo5002.md b/dotnet-desktop-guide/net/winforms/compiler-messages/wfo5002.md index 6f82039b13..15768df0c8 100644 --- a/dotnet-desktop-guide/net/winforms/compiler-messages/wfo5002.md +++ b/dotnet-desktop-guide/net/winforms/compiler-messages/wfo5002.md @@ -16,7 +16,6 @@ This compiler error is generated when using any of the following methods: - `Form.ShowAsync` - `Form.ShowDialogAsync` -- `Control.InvokeAsync` - `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). @@ -37,6 +36,15 @@ private async void button1_Click(object sender, EventArgs e) 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 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