Merge pull request #2064 from dotnet/main

Publish

Author: adegeo

dotnet-desktop-guide/framework/winforms/controls/printpreviewdialog-control-overview-windows-forms.md

@@ -1,7 +1,7 @@
 ---
 title: "PrintPreviewDialog Control Overview"
-description: This article provides an overview of the PrintPreviewDialog control in Windows Forms, which is a pre-configured dialog box.
-ms.date: "01/08/2018"
+description: This article provides an overview of the PrintPreviewDialog control in Windows Forms, which is a preconfigured dialog box.
+ms.date: 04/07/2025
 f1_keywords:
   - "PrintPreviewDialog"
 helpviewer_keywords:
@@ -10,43 +10,100 @@ ms.assetid: efd4ee8d-6edd-47ec-88e4-4a4759bd2384
 ---
 # PrintPreviewDialog control overview (Windows Forms)
 
-The Windows Forms <xref:System.Windows.Forms.PrintPreviewDialog> control is a pre-configured dialog box used to display how a [PrintDocument](printdocument-component-windows-forms.md) will appear when printed. Use it within your Windows-based application as a simple solution instead of configuring your own dialog box. The control contains buttons for printing, zooming in, displaying one or multiple pages, and closing the dialog box.
+The Windows Forms <xref:System.Windows.Forms.PrintPreviewDialog> control is a preconfigured dialog box used to display how a [PrintDocument](printdocument-component-windows-forms.md) appears when printed. Use it within your Windows-based application as a simple solution instead of configuring your own dialog box. The control contains buttons for printing, zooming in, displaying one or multiple pages, and closing the dialog box.
 
 ## Key properties and methods
 
 The control's key property is <xref:System.Windows.Forms.PrintPreviewDialog.Document%2A>, which sets the document to be previewed. The document must be a <xref:System.Drawing.Printing.PrintDocument> object. In order to display the dialog box, you must call its <xref:System.Windows.Forms.Form.ShowDialog%2A> method. Anti-aliasing can make the text appear smoother, but it can also make the display slower; to use it, set the <xref:System.Windows.Forms.PrintPreviewDialog.UseAntiAlias%2A> property to `true`.
 
-Certain properties are available through the <xref:System.Windows.Forms.PrintPreviewControl> that the <xref:System.Windows.Forms.PrintPreviewDialog> contains. (You do not have to add this <xref:System.Windows.Forms.PrintPreviewControl> to the form; it is automatically contained within the <xref:System.Windows.Forms.PrintPreviewDialog> when you add the dialog to your form.) Examples of properties available through the <xref:System.Windows.Forms.PrintPreviewControl> are the <xref:System.Windows.Forms.PrintPreviewControl.Columns%2A> and <xref:System.Windows.Forms.PrintPreviewControl.Rows%2A> properties, which determine the number of pages displayed horizontally and vertically on the control. You can access the <xref:System.Windows.Forms.PrintPreviewControl.Columns%2A> property as `PrintPreviewDialog1.PrintPreviewControl.Columns` in Visual Basic, `printPreviewDialog1.PrintPreviewControl.Columns` in Visual C#, or `printPreviewDialog1->PrintPreviewControl->Columns` in Visual C++.
+Certain properties are available through the <xref:System.Windows.Forms.PrintPreviewControl> that the <xref:System.Windows.Forms.PrintPreviewDialog> contains. (You don't have to add <xref:System.Windows.Forms.PrintPreviewControl> to the form; it's automatically contained within the <xref:System.Windows.Forms.PrintPreviewDialog> when you add the dialog to your form.) Examples of properties available through the <xref:System.Windows.Forms.PrintPreviewControl> are the <xref:System.Windows.Forms.PrintPreviewControl.Columns%2A> and <xref:System.Windows.Forms.PrintPreviewControl.Rows%2A> properties, which determine the number of pages displayed horizontally and vertically on the control. You can access the <xref:System.Windows.Forms.PrintPreviewControl.Columns%2A> property as `PrintPreviewDialog1.PrintPreviewControl.Columns` in Visual Basic, `printPreviewDialog1.PrintPreviewControl.Columns` in Visual C#, or `printPreviewDialog1->PrintPreviewControl->Columns` in Visual C++.
 
 ## PrintPreviewDialog performance
 
-Under the following conditions, the <xref:System.Windows.Forms.PrintPreviewDialog> control initializes very slowly:
+Under the following conditions, the <xref:System.Windows.Forms.PrintPreviewDialog> control initializes slowly:
 
 - A network printer is used.
 - User preferences for this printer, such as duplex settings, are modified.
 
-For apps running on the .NET Framework 4.5.2, you can add the following key to the \<appSettings> section of your configuration file to improve the performance of <xref:System.Windows.Forms.PrintPreviewDialog> control initialization:
+The optimization isn't applied if you use the <xref:System.Drawing.Printing.PrintDocument.QueryPageSettings> event to modify page settings.
 
-```xml
-<appSettings>
-   <add key="EnablePrintPreviewOptimization" value="true" />
-</appSettings>
-```
+To apply the optimization, set the `Switch.System.Drawing.Printing.OptimizePrintPreview` runtime config option to `true`.
+
+# [.NET](#tab/dotnet)
+
+The option can be set in the _runtimeconfig.json_ configuration file or the project file of an app:
+
+- **Configure a default in project file.**
+
+  To apply the setting in the project file, enable runtime config generation by setting `<GenerateRuntimeConfigurationFiles>true</GenerateRuntimeConfigurationFiles>` to in a `<PropertyGroup>`. Then, add the `<RuntimeHostConfigurationOption>` setting to an `<ItemGroup>`:
+
+  ```xml
+  <Project Sdk="Microsoft.NET.Sdk">
+
+    <!-- Other project settings ... -->  
+
+    <PropertyGroup>
+      <GenerateRuntimeConfigurationFiles>true</GenerateRuntimeConfigurationFiles>
+    </PropertyGroup>
+
+    <ItemGroup>      
+      <RuntimeHostConfigurationOption Include="Switch.System.Drawing.Printing.OptimizePrintPreview" Value="true" />
+    </ItemGroup>
 
-If the `EnablePrintPreviewOptimization` key is set to any other value, or if the key is not present, the optimization is not applied. This key has no effect if the application is running on .NET Framework 4.6 or later.
+  </Project>
+  ```
 
-For apps running on the .NET Framework 4.6 or later versions, you can add the following switch to the [\<AppContextSwitchOverrides>](/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element) element in the [\<runtime>](/dotnet/framework/configure-apps/file-schema/runtime/index) section of your app config file:
+- **Configure a default in the _runtimeconfig.template.json_ source file.**
+
+  To configure the default setting for your app, apply the setting in the _runtimeconfig.template.json_ source file. When the app is compiled or published, the template file is used to generate a runtime config file.
+
+  ```json
+  {
+    "configProperties": {
+      "Switch.System.Drawing.Printing.OptimizePrintPreview": true
+    }
+  }
+  ```
+
+  For more information about runtime config, see [.NET runtime configuration settings](/dotnet/core/runtime-config/).
+
+- **Configure a published app with the _{appname}.runtimeconfig.json_ output file.**
+
+  To configure the published app, apply the setting in the _{appname}.runtimeconfig.json_ file's `runtimeOptions/configProperties` section.
+
+  ```json
+  {
+    "runtimeOptions": {
+      "configProperties": {
+        "Switch.System.Drawing.Printing.OptimizePrintPreview": true,
+      }
+    }
+  }
+  ```
+
+  For more information about runtime config, see [.NET runtime configuration settings](/dotnet/core/runtime-config/).
+
+# [.NET Framework](#tab/dotnetframework)
+
+Add the following switch to the [`<AppContextSwitchOverrides>`](/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element) element in the [`<runtime>`](/dotnet/framework/configure-apps/file-schema/runtime/index) section of the app config file:
 
 ```xml
 <runtime >
-   <!-- AppContextSwitchOverrides values are in the form of 'key1=true|false;key2=true|false -->
-   <AppContextSwitchOverrides value = "Switch.System.Drawing.Printing.OptimizePrintPreview=true" />
+   <!-- AppContextSwitchOverrides values are in the form of "key1=true|false;key2=true|false" -->
+   <AppContextSwitchOverrides value="Switch.System.Drawing.Printing.OptimizePrintPreview=true" />
 </runtime >
 ```
 
-If the switch is not present or if it is set to any other value, the optimization is not applied.
+> [!TIP]
+> If .NET Framework 4.5.2 (no longer supported) is installed, enable the optimization by adding the following key to the `<appSettings>` section of your configuration file to improve the performance of <xref:System.Windows.Forms.PrintPreviewDialog> control initialization:
+>
+> ```xml
+> <appSettings>
+>    <add key="EnablePrintPreviewOptimization" value="true" />
+> </appSettings>
+> ```
 
-If you use the <xref:System.Drawing.Printing.PrintDocument.QueryPageSettings> event to modify printer settings, the performance of the <xref:System.Windows.Forms.PrintPreviewDialog> control will not improve even if an optimization configuration switch is set.
+---
 
 ## See also
 

dotnet-desktop-guide/index.yml

@@ -10,7 +10,7 @@ metadata:
   ms.product: dotnet
   author: adegeo
   ms.author: adegeo 
-  ms.date: 11/11/2024
+  ms.date: 04/02/2025
 
 # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | sample | tutorial | video | whats-new
 

dotnet-desktop-guide/net/winforms/controls-design/designer-differences-framework.md

@@ -1,7 +1,7 @@
 ---
 title: Designers changes from .NET Framework
 description: Learn about the Windows Forms designer changes from .NET Framework to .NET.
-ms.date: 11/14/2024
+ms.date: 04/02/2025
 ms.topic: overview
 no-loc: ["UserControl", "UserControl1", "UserControlProject", "Label", "Button", "Form", "TextBox"]
 dev_langs:

dotnet-desktop-guide/net/winforms/controls-design/designer-errors.md

@@ -1,7 +1,7 @@
 ---
 title: Design-time error troubleshooting
 description: Learn about some of the common errors that occur when the Windows Forms Designer fails to load. This article might help you troubleshoot those errors.
-ms.date: 07/19/2023
+ms.date: 04/01/2025
 ms.topic: troubleshooting
 f1_keywords: 
   - "DTELErrorList"

dotnet-desktop-guide/net/winforms/controls-design/designer-overview.md

@@ -1,7 +1,7 @@
 ---
 title: Visual Studio Design-time overview
 description: Learn about what capabilities are available in Visual Studio for Windows Forms designer support with your custom controls.
-ms.date: 06/01/2023
+ms.date: 04/01/2025
 ms.topic: overview
 no-loc: ["UserControl", "UserControl1", "UserControlProject", "Label", "Button", "Form", "TextBox"]
 dev_langs:
@@ -30,7 +30,7 @@ Many basic design elements of custom controls have remained the same from .NET F
 
 Visual Studio is a .NET Framework-based application, and as such, the Visual Designer you see for Windows Forms is also based on .NET Framework. With a .NET Framework project, both the Visual Studio environment and the Windows Forms app being designed run within the same process, **devenv.exe**. This poses a problem when you're working with a Windows Forms .NET (not .NET Framework) app. Both .NET and .NET Framework can't work within the same process. As a result, Windows Forms .NET uses a different designer, the "out-of-process" designer.
 
-The out-of-process designer is a process called **DesignToolsServer.exe**, and is run along-side Visual Studio's **devenv.exe** process. The **DesignToolsServer.exe** process runs in the same version and platform, such as .NET 9 and x64, of .NET that your app is targeting. When your custom control needs to display UI in the **devenv.exe** your custom control must implement a client-server architecture to facilitate the communication to and from **devenv.exe**. For more information, see [The designer changes since .NET Framework (Windows Forms .NET)](designer-differences-framework.md).
+The out-of-process designer is a process called **DesignToolsServer.exe**, and is run alongside Visual Studio's **devenv.exe** process. The **DesignToolsServer.exe** process runs in the same version and platform, such as .NET 9 and x64, of .NET that your app is targeting. When your custom control needs to display UI in Visual Studio, your custom control must implement a client-server architecture to facilitate the communication to and from **devenv.exe**. For more information, see [The designer changes since .NET Framework](designer-differences-framework.md).
 
 ## Property window
 

dotnet-desktop-guide/net/winforms/controls-design/designer-properties-overview.md

@@ -1,7 +1,7 @@
 ---
 title: Design-time properties overview
 description: Learn about how the Windows Forms Designer interacts with control and form properties during design-time.
-ms.date: 07/14/2023
+ms.date: 04/02/2025
 ms.topic: overview
 no-loc: ["UserControl"]
 dev_langs:
@@ -123,4 +123,4 @@ This should be converted into examples
 The **Properties** window automatically uses a type editor for a property when the type of the property is a built-in or known type. For example, a boolean value is edited as a combo box with **True** and **False** values and the <xref:System.DateTime> type uses a calendar dropdown.
 
 > [!IMPORTANT]
-> Custom type editors have changed since .NET Framework. For more information, see [The designer changes since .NET Framework (Windows Forms .NET)](designer-differences-framework.md).
+> Custom type editors have changed since .NET Framework. For more information, see [The designer changes since .NET Framework](designer-differences-framework.md).

dotnet-desktop-guide/net/winforms/controls-design/how-to-create-usercontrol.md

@@ -1,7 +1,7 @@
 ---
 title: How to create a user control
 description: This article teaches you how to create a user control, known as a composite control, that you can add to other forms.
-ms.date: 06/19/2023
+ms.date: 04/02/2025
 ms.topic: how-to
 no-loc: ["UserControl", "UserControl1", "UserControlProject", "Label", "Button", "Form", "TextBox"]
 dev_langs:
@@ -47,6 +47,7 @@ The user control is made up of _constituent controls_, which are the controls yo
 01. With the designer open, the user control design surface should be the selected object. If it's not, click on the design surface to select it. Set the following properties in the **Properties** window:
 
     > [!div class="mx-tableNormal"]
+    >
     > | Property    | Value      |
     > |-------------|------------|
     > | MinimumSize | `84, 53`   |
@@ -55,6 +56,7 @@ The user control is made up of _constituent controls_, which are the controls yo
 01. Add a **Label** control. Set the following properties:
 
     > [!div class="mx-tableNormal"]
+    >
     > | Property  | Value     |
     > |----------|------------|
     > | Name     | `lblTitle` |
@@ -63,6 +65,7 @@ The user control is made up of _constituent controls_, which are the controls yo
 01. Add a **TextBox** control. Set the following properties:
 
     > [!div class="mx-tableNormal"]
+    >
     > | Property  | Value     |
     > |----------|------------|
     > | Name     | `txtValue` |
@@ -73,6 +76,7 @@ The user control is made up of _constituent controls_, which are the controls yo
 01. Add a **Button** control. Set the following properties:
 
     > [!div class="mx-tableNormal"]
+    >
     > | Property  | Value     |
     > |----------|------------|
     > | Name     | `btnClear` |
@@ -132,6 +136,7 @@ If you created a new project in the last section, you have a blank Form named **
 01. Select one control and set the following properties:
 
     > [!div class="mx-tableNormal"]
+    >
     > | Property  | Value         |
     > |----------|----------------|
     > | Name     | `ctlFirstName` |
@@ -142,6 +147,7 @@ If you created a new project in the last section, you have a blank Form named **
 01. Select the other control and set the following properties:
 
     > [!div class="mx-tableNormal"]
+    >
     > | Property  | Value        |
     > |----------|---------------|
     > | Name     | `ctlLastName` |
@@ -152,6 +158,7 @@ If you created a new project in the last section, you have a blank Form named **
 01. Back in the **Toolbox** window, add a label control to the form, and set the following properties:
 
     > [!div class="mx-tableNormal"]
+    >
     > | Property  | Value        |
     > |----------|---------------|
     > | Name     | `lblFullName` |

dotnet-desktop-guide/net/winforms/controls-design/how-to-designer-properties-shouldserialize-reset.md

@@ -1,7 +1,7 @@
 ---
 title: How to use the Reset and ShouldSerialize methods
 description: Learn how to implement the Reset and ShouldSerialize methods to control a property during design-time in Windows Forms.
-ms.date: 07/20/2023
+ms.date: 04/02/2025
 ms.topic: how-to
 dev_langs:
   - "csharp"

dotnet-desktop-guide/net/winforms/controls-design/how-to-set-toolbox-icon.md

@@ -1,7 +1,7 @@
 ---
 title: How to set the toolbox icon
 description: Learn how to assign your control's icon. The icon appears in the Visual Studio Toolbox.
-ms.date: 07/20/2023
+ms.date: 04/02/2025
 ms.topic: how-to
 dev_langs:
   - "csharp"

dotnet-desktop-guide/net/winforms/controls-design/overview.md

@@ -1,7 +1,7 @@
 ---
 title: Create custom controls overview
 description: Learn about the different types of custom controls you can create in Windows Forms for .NET.
-ms.date: 06/01/2023
+ms.date: 04/02/2025
 ms.topic: overview
 f1_keywords: 
   - "UserControl"
@@ -117,7 +117,7 @@ If you need to implement a custom design-time experience, you can author your ow
 
 Use the <xref:System.ComponentModel.DesignerAttribute> to associate your control with your designer.
 
-The following information is out of date but may help you.
+The following information is out of date but it might help you.
 
 - [(Visual Studio 2013) Extending Design-Time Support](/previous-versions/visualstudio/visual-studio-2013/37899azc(v=vs.120)).
 - [(Visual Studio 2013) How to: Create a Windows Forms Control That Takes Advantage of Design-Time Features](/previous-versions/visualstudio/visual-studio-2013/307hck25(v=vs.120)).

dotnet-desktop-guide/net/winforms/controls-design/snippets/designer-properties-overview/csharp/CompassRose.cs

@@ -14,6 +14,7 @@ public partial class CompassRose : UserControl
 
     // <browsable>
     [Browsable(false)]
+    [DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)]
     public bool IsSelected { get; set; }
     // </browsable>
 

dotnet-desktop-guide/net/winforms/controls-design/snippets/designer-properties-overview/csharp/UserControlProject.csproj

@@ -1,11 +1,9 @@
 <Project Sdk="Microsoft.NET.Sdk">
-
   <PropertyGroup>
     <OutputType>WinExe</OutputType>
-    <TargetFramework>net7.0-windows</TargetFramework>
+    <TargetFramework>net9.0-windows</TargetFramework>
     <Nullable>enable</Nullable>
     <UseWindowsForms>true</UseWindowsForms>
     <ImplicitUsings>enable</ImplicitUsings>
   </PropertyGroup>
-
 </Project>

dotnet-desktop-guide/net/winforms/controls-design/snippets/designer-properties-overview/vb/CompassRose.vb

@@ -12,6 +12,7 @@ Public Class CompassRose
 
     '<browsable>
     <Browsable(False)>
+    <DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)>
     Public Property IsSelected As Boolean
     '</browsable>
 

dotnet-desktop-guide/net/winforms/controls-design/snippets/designer-properties-overview/vb/UserControlProjectVB.vbproj

@@ -1,33 +1,28 @@
 <Project Sdk="Microsoft.NET.Sdk">
-
   <PropertyGroup>
     <OutputType>WinExe</OutputType>
-    <TargetFramework>net7.0-windows</TargetFramework>
+    <TargetFramework>net9.0-windows</TargetFramework>
     <StartupObject>Sub Main</StartupObject>
     <UseWindowsForms>true</UseWindowsForms>
     <MyType>WindowsForms</MyType>
     <RootNamespace>UserControlProject</RootNamespace>
   </PropertyGroup>
-
   <ItemGroup>
     <Import Include="System.Data" />
     <Import Include="System.Drawing" />
     <Import Include="System.Windows.Forms" />
   </ItemGroup>
-
   <ItemGroup>
     <Compile Update="My Project\Application.Designer.vb">
       <DesignTime>True</DesignTime>
       <AutoGen>True</AutoGen>
       <DependentUpon>Application.myapp</DependentUpon>
     </Compile>
   </ItemGroup>
-
   <ItemGroup>
     <None Update="My Project\Application.myapp">
       <Generator>MyApplicationCodeGenerator</Generator>
       <LastGenOutput>Application.Designer.vb</LastGenOutput>
     </None>
   </ItemGroup>
-
 </Project>

dotnet-desktop-guide/net/winforms/controls-design/snippets/extend-existing/csharp/CustomControlProject.csproj

@@ -1,11 +1,9 @@
 <Project Sdk="Microsoft.NET.Sdk">
-
   <PropertyGroup>
     <OutputType>WinExe</OutputType>
-    <TargetFramework>net8.0-windows</TargetFramework>
+    <TargetFramework>net9.0-windows</TargetFramework>
     <Nullable>enable</Nullable>
     <UseWindowsForms>true</UseWindowsForms>
     <ImplicitUsings>enable</ImplicitUsings>
   </PropertyGroup>
-
 </Project>