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

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

  1. Remove EnableWindowsTargeting and build in the container. Read the error and put the line back.
  2. Set OutputType to Exe and explain from the documentation what changes for a user who starts the program.
  3. 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.

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

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

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

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

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

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

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

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

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

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