New WinForms diagnostic reference articles (#1938)

* Add new analyzers; revamp toc

* redirect

* review items

.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"
         }
     ]
 }

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 `<dpiAware>` setting:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1">
+  <!-- other settings omitted for brevity -->
+  <application xmlns="urn:schemas-microsoft-com:asm.v3">
+    <windowsSettings>
+      <dpiAware xmlns="http://schemas.microsoft.com/SMI/2005/WindowsSettings">true</dpiAware>
+    </windowsSettings>
+  </application>
+</assembly>
+```
+
+## 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 <xref:System.Windows.Forms.Application.SetHighDpiMode%2A?displayProperty=nameWithType> 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 <xref:System.Windows.Application.Run?displayProperty=nameWithType>.
+
+```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 `<Application*>` settings:
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>WinExe</OutputType>
+    <TargetFramework>net9.0-windows</TargetFramework>
+    <Nullable>enable</Nullable>
+    <UseWindowsForms>true</UseWindowsForms>
+    <ImplicitUsings>enable</ImplicitUsings>
+
+    <ApplicationHighDpiMode>SystemAware</ApplicationHighDpiMode>
+    <ApplicationVisualStyles>true</ApplicationVisualStyles>
+    <ApplicationUseCompatibleTextRendering>false</ApplicationUseCompatibleTextRendering>
+    <ApplicationDefaultFont>Microsoft Sans Serif, 8.25pt</ApplicationDefaultFont>
+
+  </PropertyGroup>
+
+</Project>
+```
+
+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
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>WinExe</OutputType>
+    <TargetFramework>net9.0-windows</TargetFramework>
+    <StartupObject>Sub Main</StartupObject>
+    <UseWindowsForms>true</UseWindowsForms>
+    <MyType>WindowsForms</MyType>
+
+    <ApplicationHighDpiMode>SystemAware</ApplicationHighDpiMode>
+    <ApplicationVisualStyles>false</ApplicationVisualStyles>
+    <ApplicationUseCompatibleTextRendering>false</ApplicationUseCompatibleTextRendering>
+    <ApplicationDefaultFont>Microsoft Sans Serif, 8.25pt</ApplicationDefaultFont>
+
+  </PropertyGroup>
+
+</Project>
+```
+
+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 <xref:Microsoft.VisualBasic.ApplicationServices.WindowsFormsApplicationBase.ApplyApplicationDefaults> 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
+```

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
+  <PropertyGroup>
+      <NoWarn>$(NoWarn);WFO5001</NoWarn>
+  </PropertyGroup>
+  ```
+
+- 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());
+      }    
+  }
+  ```

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
+  <PropertyGroup>
+      <NoWarn>$(NoWarn);WFO5002</NoWarn>
+  </PropertyGroup>
+  ```
+
+- 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
+  }
+  ```

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

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 <xref:System.Windows.Forms.Application.SetHighDpiMode%2A?displayProperty=nameWithType> API.
 
+> [!IMPORTANT]
+> Starting with .NET 9, this warning has changed to [WFO0003](../compiler-messages/wfo0003.md).
+
 ## Workarounds
 
 ### Using C\#