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:

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

  1. 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.
  2. Set ApplicationVisualStyles to false in the project file and describe what the controls look like.
  3. 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.

  1. 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.

  2. 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.

  3. What is the default value of ApplicationHighDpiMode?

    Answer

    SystemAware

    PerMonitorV2 is the better mode for a new application, and it is not the default.

  4. 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.

  5. Which call does ApplicationVisualStyles = true produce?

    Answer

    Application.EnableVisualStyles()

    Visual styles switch the controls to the themed Windows renderer.

  6. 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.

  7. 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.

  8. 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.

  9. 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.

  10. 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