The project file for net10.0-windows
An SDK-style project file describes what is built, not how: the target framework, the kind of output and which frameworks the code uses. A WinForms application needs three settings that a console application does not, and each one answers a question the compiler cannot answer on its own: which platform, which reference assemblies, and whether the Windows-only build is allowed to run on a machine that is not Windows.
The file
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>WinExe</OutputType>
<TargetFramework>net10.0-windows</TargetFramework>
<UseWindowsForms>true</UseWindowsForms>
<EnableWindowsTargeting>true</EnableWindowsTargeting>
<NuGetAudit>false</NuGetAudit>
<Nullable>enable</Nullable>
</PropertyGroup>
</Project>
The file is named after the project: notes.csproj for a project in a folder called notes. The SDK globs every *.cs file under the folder into the compilation, so there is no item group and no file list. A form, its designer file and the program file are three files in the same folder and need no line here.
What each property does
- TargetFramework: net10.0-windows is .NET 10 with the Windows platform suffix. The suffix is what makes the Windows-only reference assemblies visible; without it UseWindowsForms is an error, which the next section shows.
- UseWindowsForms: adds the Windows Desktop framework reference to the compilation (System.Windows.Forms, System.Drawing.Common), and switches on the SDK's WinForms source generator, which is what makes ApplicationConfiguration.Initialize() exist.
- EnableWindowsTargeting: lets a machine that is not Windows build this project. Without it the SDK refuses before the compiler starts, with NETSDK1100. It changes nothing about running the program: the runtime is still the Windows Desktop runtime.
- OutputType WinExe: a GUI executable, so no console window is attached. The same program as Exe opens a console window next to the form; Console.WriteLine then goes to that window.
- Nullable: nullable annotations on, as the rest of the C# course uses. A WinForms code base written before C# 8 usually has it off.
- NuGetAudit: off, so a restore does not ask a vulnerability feed. The course builds with no network and the audit would only slow it down.
The errors of a wrong property
The platform suffix is not decoration. A project with net10.0 and UseWindowsForms stops before anything is compiled:
<TargetFramework>net10.0</TargetFramework>
<UseWindowsForms>true</UseWindowsForms>
dotnet build app.csproj
error NETSDK1136: The target platform must be set to Windows (usually by including '-windows' in the TargetFramework property) when using Windows Forms or WPF, or referencing projects or packages that do so.
The real line begins with the path of the SDK targets file and a position in it, which the command above leaves out; the message is verbatim. The rule is easy to remember: UseWindowsForms belongs with a target framework that ends in -windows.
The other half of the pair is just as strict. With the platform suffix but without UseWindowsForms, the platform is right and the framework reference is missing, so the ordinary compiler reports it:
Program.cs(2,22): error CS0234: The type or namespace name 'Forms' does not exist in the namespace 'System.Windows' (are you missing an assembly reference?)
That is the using System.Windows.Forms; line of the program, and the answer to the question in the message is yes: the property is the assembly reference. A reader who has not met the diagnostic before can read the lesson about compiler errors of the C# course, which explains the file, the position and the code.
Building on Linux
With the three settings in place the project builds on this site's Linux container:
using System;
using System.Windows.Forms;
internal static class Program
{
[STAThread]
private static void Main()
{
ApplicationConfiguration.Initialize();
Application.Run(new Form { Text = "Notes" });
}
}
dotnet build app.csproj
Build succeeded.
0 Warning(s)
0 Error(s)
The build reads the reference assemblies of the Windows Desktop runtime from the offline feed and writes a .dll for Windows. It is built, not run: the runtime that could start it is not in the image, which lesson 008 shows with the message it prints. On Windows the same project needs no EnableWindowsTargeting, because the machine is the target.
Exercises
- Remove EnableWindowsTargeting and build in the container. Read the error and put the line back.
- Set OutputType to Exe and explain from the documentation what changes for a user who starts the program.
- Add ApplicationHighDpiMode to the project and rebuild. Which type and method does the generated initialisation call use?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
Which target framework does a WinForms project need?
Answer
net10.0-windows
The Windows platform suffix is what makes the Windows-only reference assemblies visible.
-
What does UseWindowsForms add to the compilation?
Answer
The Windows Desktop framework reference and the WinForms source generator
It brings in System.Windows.Forms and System.Drawing.Common, and enables the generator behind ApplicationConfiguration.
-
What does EnableWindowsTargeting do?
Answer
Lets a machine that is not Windows build the project
It relaxes the build-time platform check; the program still needs the Windows Desktop runtime to run.
-
Which error does net10.0 with UseWindowsForms produce?
Answer
error NETSDK1136: The target platform must be set to Windows
The SDK checks the pair of properties before the compiler runs.
-
Which error does net10.0-windows without UseWindowsForms produce?
Answer
error CS0234: The type or namespace name 'Forms' does not exist in the namespace 'System.Windows'
The platform is right but the framework reference is missing, so the using line of the program fails.
-
What is the difference between OutputType Exe and WinExe for a WinForms program?
Answer
Exe attaches a console window, WinExe does not
A GUI executable has no console; with Exe, Console.WriteLine goes to a console window beside the form.
-
Why does the project file list no .cs files?
Answer
The SDK globs every .cs file under the folder into the compilation
An SDK-style project adds the folder's sources by convention, so a new form needs no project edit.
-
Why is NuGetAudit turned off in the projects of this course?
Answer
The restore then does not ask a vulnerability feed
The course builds offline, and the audit is a network request that adds nothing to a lesson.
-
What does the compiler need besides the project file to build a WinForms program on Linux?
Answer
The Windows Desktop targeting pack, here from the offline feed
Reference assemblies are enough to compile; the runtime is what is missing, and only for running.
-
Which property would you remove on a Windows machine?
Answer
EnableWindowsTargeting
It exists to allow a non-Windows build; on Windows the platform check passes without it.
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