You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/runtime-configuration.md
+73-82Lines changed: 73 additions & 82 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,98 +1,87 @@
1
-
# Support for application runtime configuration in WinForms applications
1
+
# Support for application runtime configuration in Windows Forms applications
2
2
3
3
## Overview
4
-
\
5
-
NET Winforms applications currently have [limited application
4
+
5
+
.NET Windows Forms applications currently have limited [application
6
6
configurations](https://aka.ms/applicationconfiguration) capabilities that are defined via MSBuils properties and are emitted into source code using source
7
7
generators at compile time. This document outlines expansion of those application-wide configurations further to cover runtime config options for .NET Windows Forms applications.
8
8
9
-
## Runtime configuration in .NET Framework applications
10
-
\
11
-
.NET Framework Windows Forms applications use app.config to define runtime configurations and application-wide settings. Following are the various sections in the app.config that define application's runtime behavior.
9
+
## .NET Framework runtime configuration
10
+
11
+
.NET Framework Windows Forms applications use `app.config` to define runtime configurations and application-wide settings. The following are the various sections in the app.config that define the application's runtime behavior.
12
12
13
13
### AppContext switches
14
14
15
-
These settings are used to opt-in or opt-out of a particular feature from WinForms runtime. Please refer to the [AppContext Switches](https://docs.microsoft.com/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element) documentation for more information
15
+
These settings are used to opt-in or opt-out of a particular feature from Windows Forms runtime. Refer to the [AppContext Switches](https://docs.microsoft.com/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element) documentation for more information.
This was introduced in .NET Framework 4.7 and is primarily used by Winforms runtime to enable high Dpi and other accessibility improvements. Please refer to the [ApplicationConfigurationSection](https://docs.microsoft.com/dotnet/framework/configure-apps/file-schema/winforms/windows-forms-add-configuration-element) documentation for more information.
26
+
This was introduced in .NET Framework 4.7, and it is primarily used by Windows Forms runtime to enable high DPI and other accessibility improvements. Please refer to the [ApplicationConfigurationSection](https://docs.microsoft.com/dotnet/framework/configure-apps/file-schema/winforms/windows-forms-add-configuration-element) documentation for more information.
### App settings from Settings designer/editor page
37
-
38
-
Unlike above, these settings are used by the user application. These are commonly defined via the Settings designer in Visual Studio, which intern serialize them into the app.config file. Please refer to the [Application Settings](https://docs.microsoft.com/dotnet/desktop/winforms/advanced/using-application-settings-and-user-settings?view=netframeworkdesktop-4.8) documentation for more information.
39
-
```XML
40
-
<userSettings>
41
-
<WinFormsApp2.Properties.Settings>
42
-
<settingname="ButtonName"serializeAs="String">
43
-
<value>LocalButton</value>
44
-
</setting>
45
-
</WinFormsApp2.Properties.Settings>
46
-
</userSettings>
47
-
<applicationSettings>
48
-
<WinFormsApp2.Properties.Settings>
49
-
<settingname="BoxName"serializeAs="String">
50
-
<value>LocalBox</value>
51
-
</setting>
52
-
</WinFormsApp2.Properties.Settings>
53
-
</applicationSettings>
36
+
### Application-wide and user-specific settings
37
+
38
+
These are commonly defined via the Settings designer in Visual Studio, which serializes those into `app.config`. Refer to the [Application Settings](https://docs.microsoft.com/dotnet/desktop/winforms/advanced/using-application-settings-and-user-settings) documentation for more information.
39
+
40
+
```xml
41
+
<userSettings>
42
+
<WinFormsApp2.Properties.Settings>
43
+
<settingname="ButtonName"serializeAs="String">
44
+
<value>LocalButton</value>
45
+
</setting>
46
+
</WinFormsApp2.Properties.Settings>
47
+
</userSettings>
48
+
49
+
<applicationSettings>
50
+
<WinFormsApp2.Properties.Settings>
51
+
<settingname="BoxName"serializeAs="String">
52
+
<value>LocalBox</value>
53
+
</setting>
54
+
</WinFormsApp2.Properties.Settings>
55
+
</applicationSettings>
54
56
```
55
57
56
58
57
-
## Winforms runtime configuration in .NET applications
58
-
\
59
-
app.config has limited support in .NET due to performance and reliability reasons. .NET runtime and other .NET teams use runtimeconfig.json to define .NET runtime configurations and appsettings.json to define application-level settings. In this proposal, we are leveraging runtimeconfig.json to define WinForms runtime configurations.
59
+
## .NET 7+ runtime configuration
60
+
61
+
`app.config` has limited support in .NET due to performance and reliability reasons. .NET runtime and other .NET teams use `runtimeconfig.json` to define .NET runtime configurations and `appsettings.json` to define application-level settings. In this proposal, we are leveraging `runtimeconfig.json` to define Windows Forms runtime configurations.
60
62
61
-
While this proposal is focusing on providing an alternative solution for existing configuration sections `AppContextSwitchOverrides` and `System.Windows.Forms.ApplicationConfigurationSection` that are primarily used for specifying feature flags impacting winforms runtime behavior, we will be looking into alternatives for `Application Settings` that doesn't require app.config in the upcoming releases of .NET.
63
+
While this proposal is focusing on providing an alternative solution for existing configuration sections `AppContextSwitchOverrides` and `System.Windows.Forms.ApplicationConfigurationSection` that are primarily used for specifying feature flags impacting Windows Forms runtime behavior, we will be looking into alternatives for `Application Settings` that doesn't require `app.config` in the future releases of .NET.
62
64
63
65
64
66
### Goals:
65
67
66
-
-A replacement for `AppContextSwitchOverrides` and `System.Windows.Forms.ApplicationConfigurationSection` of app.config.
67
-
-Users should be able to update/modify Winforms applications runtime configurations without recompiling the application.
68
-
-The existing applications should be able to seamlessly upgrade to the new configuration model when targeting the latest .NET runtiem.
69
-
-The existing [application configuration MSBuild properties](https://aka.ms/applicationconfiguration) continue to work.
68
+
- A replacement for `AppContextSwitchOverrides` and `System.Windows.Forms.ApplicationConfigurationSection` of `app.config`.
69
+
- Users should be able to update/modify Windows Forms applications runtime configurations without recompiling the application.
70
+
- The existing applications should be able to seamlessly upgrade to the new configuration model when targeting .NET 7+ runtime.
71
+
- The existing [application configuration MSBuild properties](https://aka.ms/applicationconfiguration) continue to work.
70
72
71
73
### Out of scope:
72
74
73
-
App settings that are serialized by the Settings designer/editor page. Applications should continue to use the current model.
74
-
-Dynamic/real-time (re-)loading of configuration values from runtimeconfig.json.
75
-
-Unification of comple/runtime configurations into one place, runtimeconfig.json.
75
+
- App settings that are serialized by the Settings designer/editor page. Applications should continue to use the current model.
76
+
- Dynamic/real-time (re-)loading of configuration values from `runtimeconfig.json`.
77
+
- Unification of comple/runtime configurations into one place, e.g., `runtimeconfig.json`.
76
78
77
79
78
-
#### Syntax of runtimeConfig.template.Json.
79
-
80
-
```xml
81
-
{
82
-
"configProperties": {
83
-
"System.Globalization.UseNls": true,
84
-
"System.Net.DisableIPv6": true,
85
-
"System.GC.Concurrent": false,
86
-
"System.Threading.ThreadPool.MinThreads": 4,
87
-
"System.Threading.ThreadPool.MaxThreads": 25
88
-
}
89
-
}
90
-
```
91
-
92
-
Windows Forms switches will be added to [`configProperties` section](https://docs.microsoft.com/dotnet/core/runtime-config) with the rest of the .NET switches. To avoid name conflics Windows Forms specific switches will be prefixed with `System.Windows.Forms`:
80
+
### Design proposal
93
81
82
+
Windows Forms switches will be added to **`runtimeConfig.template.json`** to the [`configProperties` section](https://docs.microsoft.com/dotnet/core/runtime-config) with the rest of the .NET switches. To avoid name conflics Windows Forms specific switches will be prefixed with `System.Windows.Forms`:
94
83
95
-
```xml
84
+
```json
96
85
{
97
86
"configProperties": {
98
87
"System.Globalization.UseNls": true,
@@ -101,21 +90,23 @@ Windows Forms switches will be added to [`configProperties` section](https://doc
When a project is [built](https://docs.microsoft.com/en-us/dotnet/core/runtime-config/#runtimeconfigjson), an _[appname].runtimeconfig.json_ file is generated in the output directory. If a _runtimeconfig.template.json_ file exists in the same folder as the project file, any configuration options it contains are inserted into the _[appname].runtimeconfig.json_ file.
115
-
This proposal focuses primarily on enabling the runtime configurations for WinForms applications. A support for analyzers and source generators may be considered in the future .NET releases. We will revisit this implementation to improve user-experience further, as we make progress.
116
-
For example, the content of _[appname].runtimeconfig.json_ generated from above content:
101
+
#### Reading Windows Forms runtime configurations
102
+
103
+
When a project is [built](https://docs.microsoft.com/dotnet/core/runtime-config/#runtimeconfigjson), an `[appname].runtimeconfig.json` file is generated in the output directory. If a `runtimeconfig.template.json` file exists in the same folder as the project file, any configuration options it contains are inserted into the `[appname].runtimeconfig.json` file.
104
+
105
+
This proposal focuses primarily on enabling the runtime configurations for Windows Forms applications. A support for analyzers and source generators may be considered in the future .NET releases. We will revisit this implementation to improve user-experience further, as we make progress.
106
+
107
+
For example, the content of `[appname].runtimeconfig.json` generated from above content:
117
108
118
-
```XML
109
+
```json
119
110
{
120
111
"runtimeOptions": {
121
112
"tfm": "net7.0",
@@ -135,29 +126,31 @@ For example, the content of _[appname].runtimeconfig.json_ generated from above
The target framework information added to _[appname].runtimeconfig.json_ file always match with the application target framework irrespective of runtime/SDK installed on the machine or runtime used ([roll-forward scenarios](https://docs.microsoft.com/dotnet/core/versions/selection#framework-dependent-apps-roll-forward)) by the Windows Forms application.
138
+
The target framework information added to `[appname].runtimeconfig.json` file always match with the application target framework irrespective of runtime/SDK installed on the machine or runtime used ([roll-forward scenarios](https://docs.microsoft.com/dotnet/core/versions/selection#framework-dependent-apps-roll-forward)) by the Windows Forms application.
139
+
140
+
#### .NET runtime support in reading `runtimeconfig.json`
147
141
148
-
### .NET runtime support in reading runtimeconfig.json:
149
-
\
150
-
WinForms is leveraging the [support](https://github.com/dotnet/runtime/blob/5098d45cc1bf9649fab5df21f227da4b80daa084/src/native/corehost/runtime_config.cpp) provided by .NET runtime in reading the _[appname].runtimeconfig.json_ file, and thus get all plumbing required for various hosting and environment scenarios.
151
-
WinForms adds the following wrapper on top of .NET runtime implementation to improve the performance by caching configuration options, and also by defining custom defaults values for the WinForms specific feature flags. This wrapper is very similar to the [.NET runtime's implementation](https://github.com/dotnet/runtime/blob/04dac7b0fede29d44f896c5fd793754f83974175/src/libraries/System.Private.CoreLib/src/System/AppContextConfigHelper.cs).
152
-
The below example illustrates how to define `ScaleTopLevelFormMinMaxSizeForDpi` feature flag, opt-in by default, if an application is running on Windows 10 and is targeting .NET 8:
142
+
The Windows Forms runtime is leveraging the [support](https://github.com/dotnet/runtime/blob/5098d45cc1bf9649fab5df21f227da4b80daa084/src/native/corehost/runtime_config.cpp) provided by .NET runtime in reading `[appname].runtimeconfig.json` file, and thus get all plumbing required for various hosting and environment scenarios. The Windows Forms runtime adds the following wrapper on top of .NET runtime implementation to improve the performance by caching configuration options, and also by defining custom defaults values for the Windows Forms specific feature flags. This wrapper is very similar to the [.NET runtime's implementation](https://github.com/dotnet/runtime/blob/04dac7b0fede29d44f896c5fd793754f83974175/src/libraries/System.Private.CoreLib/src/System/AppContextConfigHelper.cs).
143
+
144
+
The below example illustrates how to define `ScaleTopLevelFormMinMaxSizeForDpi` feature flag, opt-in by default, for an application targeting .NET 8 or later running on Windows 10:
@@ -226,9 +219,7 @@ internal static partial class LocalAppContextSwitches
226
219
```
227
220
228
221
229
-
WinForms runtime then uses the static `LocalAppContextSwitches` class to access the runtime configurations. The below sample demonstrates how to access the feature switch `System.Windows.Forms.ScaleTopLevelFormMinMaxSizeForDpi`:
230
-
231
-
Ex: Use of feature switch in ScaleContainerForDpi() method in ContainerControl.cs to scale Min/Max size of the Container.
222
+
The Windows Forms runtime then uses the static `LocalAppContextSwitches` class to access the runtime configurations. The below sample demonstrates the use of the feature switch `System.Windows.Forms.ScaleTopLevelFormMinMaxSizeForDpi` to scale min/max size of a container control:
0 commit comments