Edit

Windows Forms Add Configuration Element

  • Article

The <add> element adds a predefined key that specifies whether your Windows Form app supports features added to Windows Forms apps in the .NET Framework 4.7 or later.

Syntax

<System.Windows.Forms.ApplicationConfigurationSection>
  <add key="key-name" value="key-value" />
</System.Windows.Forms.ApplicationConfigurationSection>

Attributes and elements

The following sections describe attributes, child elements, and parent elements.

Attributes

Attribute Description
key Required attribute. A predefined key name that corresponds to a particular Windows Forms customizable feature.
value Required attribute. The value to assign to key.

key attribute names and associated values

key name Values Description
"AnchorLayout.DisableSinglePassControlScaling" "true"|"false" Indicates whether anchored controls are scaled in a single pass. "true" to disable single pass scaling; otherwise, false. See the "Single pass scaling" section in the Remarks for more information.
"DpiAwareness" "PerMonitorV2"|"false" Indicates whether an application is DPI-aware. Set the key to "PerMonitorV2" to support Dpi awareness; otherwise, set it to "false". DPI awareness is an opt-in feature; to take advantage of Windows Forms' high DPI support, you should set its value to "PerMonitorV2". See the Remarks section for more information.
"CheckedListBox.DisableHighDpiImprovements" "true"|"false" Indicates whether the CheckedListBox control takes advantage of scaling and layout improvements introduced in .NET Framework 4.7. "true" to opt out of scaling and layout improvements; otherwise, "false".
"DataGridView.DisableHighDpiImprovements" "true"|"false" Indicates whether the DataGridView control scaling and layout improvements introduced in .NET Framework 4.7. "true" to opt out of DPI awareness; "false" otherwise.
"DisableDpiChangedMessageHandling" "true"|"false" "true" to opt out of receiving messages related to DPI scaling changes; "false" otherwise. See the Remarks section for more information.
"EnableWindowsFormsHighDpiAutoResizing" "true"|"false" Indicates whether a Windows Forms application is automatically resized due to DPI scaling changes. "true" to enable automatic resizing; otherwise, false.
"Form.DisableSinglePassControlScaling" "true"|"false" Indicates whether the Form is scaled in a single pass. "true" to disable single-pass scaling; otherwise, false. See the "Single pass scaling" section in the Remarks for more information.
"MonthCalendar.DisableSinglePassControlScaling" "true"|"false" Indicates whether the MonthCalendar control is scaled in a single pass. "true" to disable single-pass scaling; otherwise, false. See the "Single pass scaling" section in the Remarks for more information.
"Toolstrip.DisableHighDpiImprovements" "true"|"false" Indicates whether the ToolStrip control takes advantage of scaling and layout improvements introduced in .NET Framework 4.7. "true" to opt out of DPI awareness; "false" otherwise.

Child elements

None.

Parent elements

Element Description
<System.Windows.Forms.ApplicationConfigurationSection> Configures support for new Windows Forms application features.

Remarks

Starting with .NET Framework 4.7, the <System.Windows.Forms.ApplicationConfigurationSection> element allows you to configure Windows Forms applications to take advantage of features added in recent releases of the .NET Framework.

The <System.Windows.Forms.ApplicationConfigurationSection> element allows you to add one or more child <add> elements, each of which defines a specific configuration setting.

For an overview of Windows Forms High DPI support, see High DPI Support in Windows Forms.

DpiAwareness

Windows Forms apps that run under Windows versions starting with Windows 10 Creators Edition and target versions of the .NET Framework starting with the .NET Framework 4.7 can be configured to take advantage of high DPI improvements introduced in .NET Framework 4.7. These include:

  • Support for dynamic DPI scenarios in which the user changes the DPI or scale factor after a Windows Forms application has been launched.

  • Improvements in the scaling and layout of a number of Windows Forms controls, such as the MonthCalendar control and the CheckedListBox control.

High DPI awareness is an opt-in feature; by default, the value of DpiAwareness is false. You can opt into Windows Forms' support for DPI awareness by setting the value of this key to PerMonitorV2 in the application configuration file. If DPI awareness is enabled, all individual DPI features are also enabled. These include:

  • DPI changed messages, which are controlled by the DisableDpiChangedMessageHandling key.

  • Dynamic DPI support, which is controlled by the EnableWindowsFormsHighDpiAutoResizing key.

  • Single-pass control scaling, which is controlled by the Form.DisableSinglePassControlScaling for individual Form controls, by the AnchorLayout.DisableSinglePassControlScaling key for anchored controls, and by the MonthCalendar.DisableSinglePassControlScaling key for the MonthCalendar control

  • High DPI scaling and layout improvements, which is controlled by the CheckListBox.DisableHighDpiImprovements key for the CheckedListBox control, by the DataGridView.DisableHighDpiImprovements key for the DataGridView control, and by the Toolstrip.DisableHighDpiImprovements key for the ToolStrip control.

The single default opt-in setting provided by setting DpiAwareness to PerMonitorV2 is generally adequate for new Windows Forms applications. However, You can then opt out of individual high DPI improvements by adding the corresponding key to the application configuration file. For example, to take advantage of all the new DPI features except for dynamic DPI support, you would add the following to your application configuration file:

<System.Windows.Forms.ApplicationConfigurationSection>
   <add key="DpiAwareness" value="PerMonitorV2" />
   <!-- Disable dynamic DPI support -->
   <add key="EnableWindowsFormsHighDpiAutoResizing" value="false" />
</System.Windows.Forms.ApplicationConfigurationSection>

Typically, you opt out of a particular feature because you've chosen to handle it programmatically.

For more information on taking advantage of High DPI support in Windows Forms applications, see High DPI Support in Windows Forms.

DisableDpiChangedMessageHandling

Starting with .NET Framework 4.7, Windows Forms controls raise a number of events related to changes in DPI scaling. These include the DpiChangedAfterParent, DpiChangedBeforeParent, and DpiChanged events. The value of the DisableDpiChangedMessageHandling key determines whether these events are raised in a Windows Forms application.

Single-pass scaling

Single or multi-pass scaling influences the perceived responsiveness of the user interface and the visual appearance of user interface elements as they are scaled. Starting with .NET Framework 4.7, Windows Forms uses single pass scaling. In previous versions of the .NET Framework, scaling was performed through multiple passes, which caused some controls to be scaled more than was necessary. Single-pass scaling should only be disabled if your app depends on the old behavior.

See also