Program.cs and ApplicationConfiguration.Initialize
Every .NET program starts at a method, and a WinForms program is no exception: its Main initialises the application and hands one form to the message loop. The generated template in Visual Studio writes that method in Program.cs, with one call to ApplicationConfiguration.Initialize() in front of Application.Run. This lesson is about those two calls.
Main
using System;
using System.Windows.Forms;
internal static class Program
{
[STAThread]
private static void Main()
{
ApplicationConfiguration.Initialize();
Application.Run(new Form1());
}
}
internal sealed class Form1 : Form
{
public Form1()
{
Text = "Notes";
}
}
The listing is one complete program and it is built, not run. Main is private static void: the runtime finds it by name and signature, and its access modifier does not matter. Application.Run does not return until the last form closes, so the line after it is the end of the program.
ApplicationConfiguration.Initialize
The call looks like a framework method, and it is not: the SDK's WinForms source generator writes the method into your compilation from four project properties. Every project that has UseWindowsForms set gets it, and a project that sets none of the four gets the modern defaults:
- ApplicationHighDpiMode, default SystemAware: the call passes it to Application.SetHighDpiMode.
- ApplicationVisualStyles, default true: Application.EnableVisualStyles().
- ApplicationUseCompatibleTextRendering, default false: Application.SetCompatibleTextRenderingDefault(false).
- ApplicationDefaultFont, default Segoe UI 9pt: Application.SetDefaultFont.
The point of the generator is that all four must be set before the first window exists, and a call at the top of Main is the only place where that is easy to guarantee. The properties go in the project file and are visible to the generator:
<PropertyGroup>
<OutputType>WinExe</OutputType>
<TargetFramework>net10.0-windows</TargetFramework>
<UseWindowsForms>true</UseWindowsForms>
<ApplicationHighDpiMode>PerMonitorV2</ApplicationHighDpiMode>
<ApplicationDefaultFont>Segoe UI, 10pt</ApplicationDefaultFont>
</PropertyGroup>
A WinForms project without UseWindowsForms has no ApplicationConfiguration type at all, and the call fails to compile like any other unknown name. That is the source of a confusing error for a project moved from an older template.
The same calls written out
The generated method is short, and writing it out is the clearest way to see what the call does. The listing below is one complete program that makes the same four calls by hand. It is built, not run.
using System;
using System.Drawing;
using System.Windows.Forms;
internal static class Program
{
[STAThread]
private static void Main()
{
Application.SetHighDpiMode(HighDpiMode.PerMonitorV2);
Application.EnableVisualStyles();
Application.SetCompatibleTextRenderingDefault(false);
Application.SetDefaultFont(new Font("Segoe UI", 10F));
Application.Run(new Form1());
}
}
internal sealed class Form1 : Form
{
public Form1()
{
Text = "Notes, written out";
}
}
dotnet build app.csproj
Build succeeded.
0 Warning(s)
0 Error(s)
The order is the one the generator uses, and it matters for the same reason: high-DPI mode and visual styles are read when the first window is created, which is inside Application.Run. A call after it is too late.
Why STAThread needs using System
The projects of this course do not enable implicit usings, so every name comes from a using line. [STAThread] is System.STAThreadAttribute, and without using System; the compiler has two candidates it cannot find:
using System.Windows.Forms;
internal static class Program
{
[STAThread]
private static void Main()
{
Application.Run(new Form());
}
}
dotnet build app.csproj
Program.cs(5,6): error CS0246: The type or namespace name 'STAThreadAttribute' could not be found (are you missing a using directive or an assembly reference?)
Program.cs(5,6): error CS0246: The type or namespace name 'STAThread' could not be found (are you missing a using directive or an assembly reference?)
Two errors for one attribute, because the compiler reports the name as written and the name it resolves to. The fix is the missing line, and the lesson is that a WinForms file starts with using System; for reasons that are not obvious until [STAThread] is on the method.
Exercises
- Move the four calls of the written-out listing after Application.Run and explain why they no longer have an effect, using the documentation of the four properties.
- Set ApplicationVisualStyles to false in the project file and describe what the controls look like.
- Write Main with the four written-out calls but the default font of the form, and build it.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
Which call hands a form to the message loop?
Answer
Application.Run
Initialize prepares the application; Run shows the form and reads messages until it closes.
-
Who writes ApplicationConfiguration.Initialize()?
Answer
The SDK's WinForms source generator, from four project properties
The method is generated into the compilation when UseWindowsForms is set.
-
What is the default value of ApplicationHighDpiMode?
Answer
SystemAware
PerMonitorV2 is the better mode for a new application, and it is not the default.
-
Why must the four application settings be made before the first window exists?
Answer
The runtime reads them when the first window is created
DPI mode, visual styles, text rendering and the default font are read once, when the first control is created.
-
Which call does ApplicationVisualStyles = true produce?
Answer
Application.EnableVisualStyles()
Visual styles switch the controls to the themed Windows renderer.
-
What happens when a project has no UseWindowsForms but calls ApplicationConfiguration.Initialize()?
Answer
The call fails to compile, because the type is not generated
The type comes from the generator that UseWindowsForms switches on.
-
How many errors does the compiler print for one [STAThread] without using System?
Answer
Two: STAThreadAttribute and STAThread
The real build printed both CS0246 lines on the same position.
-
What does [STAThread] request?
Answer
A single-threaded apartment for the user interface
WinForms needs a single-threaded apartment, and the runtime starts one for Main.
-
What is the access modifier of the Main method in the template?
Answer
private
The runtime finds Main by name and signature; it is private in the WinForms template.
-
What does Application.Run do when the last form closes?
Answer
It returns, and Main ends
Run blocks until the message loop ends, then the method returns and the process exits.
Every listing on this page was built with the .NET SDK 10.0.303 for net10.0-windows against the targeting pack Microsoft.WindowsDesktop.App.Ref 10.0.15 from the offline feed, in a Docker container on Alpine Linux 3.24.3 (x86_64). The programs were built, not run on Linux: WinForms needs Windows.
Article author: Arthur Isaev