dotnet format on a WinForms project
A codebase with two styles is a codebase where every diff has a paragraph about braces. The .NET SDK ships the answer: dotnet format, a Roslyn-based tool that rewrites the whitespace, the style and the analyzer fixes of a project, and verifies them in a mode a build server can run. It works on a WinForms project like on any other, with one caveat about the designer files that this lesson shows.
The tool
dotnet format is part of the SDK and needs no package, which matters here: it is the one code-quality tool of this course that exists in the image. It has three verbs:
- dotnet format app.csproj formats the files of the project.
- dotnet format app.csproj --verify-no-changes changes nothing and reports every file that would change, with the rule and the fix.
- dotnet format whitespace app.csproj, style and analyzers restrict the run to one kind of fix.
The rules come from the SDK defaults and from an .editorconfig in the folder tree. The exit status is the interface: 0 when the code matches, 2 when the verify found a difference, and a build server needs nothing more. The run takes five to fifteen seconds on a small project because it loads the project and the whole compilation before it reformats a single line.
A three-file project
The project is a small WinForms application with a form, an invoice type and a report that formats one. The three .cs files are the unit the tool counts:
format-demo/
app.csproj
nuget.config
Program.cs Main and the form
Invoice.cs a plain model
Report.cs a formatter
Invoice.cs and Report.cs are ordinary classes with no Main, so the checker of this course counts them and does not build them separately; the whole program is Program.cs, which is self-contained and does not need them. In a real project the three compile together.
internal sealed class Invoice
{
public Invoice(string id, decimal total)
{
Id = id;
Total = total;
}
public string Id { get; }
public decimal Total { get; }
}
The report file was written badly on purpose: two-space indentation, an opening brace on the same line as the signature, and a call indented by five spaces. That is the state the next section verifies and then repairs.
internal static class Report
{
public static string Line(Invoice invoice) {
return $"{invoice.Id}: {invoice.Total:0.00}";
}
}
Program.cs
The form and its entry point, with the project file and the offline feed that the rest of the course uses. Built and not run:
using System;
using System.Drawing;
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 = "Formatting";
ClientSize = new Size(320, 100);
Controls.Add(new Label { Text = "Clean files", AutoSize = true, Location = new Point(16, 16) });
}
}
dotnet build app.csproj
Build succeeded.
0 Warning(s)
0 Error(s)
The listing is built and not run. The project file is the one of lesson 002, and the build is the same three seconds warm.
The real runs
First the verify on the project before the fix, from inside the project folder. The path in each line is the absolute path of the file on this machine, because the tool names the file it would change:
dotnet format app.csproj --verify-no-changes; echo $?
/tmp/wf/fmt/Report.cs(3,3): error WHITESPACE: Fix whitespace formatting. Insert '\s\s'. [/tmp/wf/fmt/app.csproj]
/tmp/wf/fmt/Report.cs(3,45): error WHITESPACE: Fix whitespace formatting. Replace 3 characters with '\n\s\s\s\s'. [/tmp/wf/fmt/app.csproj]
/tmp/wf/fmt/Report.cs(4,6): error WHITESPACE: Fix whitespace formatting. Insert '\s\s\s'. [/tmp/wf/fmt/app.csproj]
/tmp/wf/fmt/Report.cs(5,3): error WHITESPACE: Fix whitespace formatting. Insert '\s\s'. [/tmp/wf/fmt/app.csproj]
2
Four errors, all of them the same rule, and the status 2 at the end. The tool then fixes them. There is no output on success, which is the Unix convention and the reason the status is the thing to check:
dotnet format app.csproj; echo $?
0
The file after the fix is the one the reader expects, and a second verify prints nothing:
internal static class Report
{
public static string Line(Invoice invoice)
{
return $"{invoice.Id}: {invoice.Total:0.00}";
}
}
dotnet format app.csproj --verify-no-changes; echo $?
0
Nothing was printed by the verify, and the status was 0. That is the whole check a build server runs: a step that fails on a non-zero status, before the code is reviewed.
The four fixes are worth reading, because they are the rules an editor makes invisible. Line 3 began with two spaces where four belong, so the rule asks to insert two. The same line ended with three spaces before the brace, so the brace moved to its own line. Line 4 began with five spaces instead of eight. Line 5 closed the method with two instead of four. None of it changes what the code does, and all of it changes the next diff.
What it checks and what it does not
- Whitespace: indentation, spaces around operators, a brace on its own line. This is what the run above fixed, and it is the part that never changes behaviour.
- Style: the IDE rules of the SDK, such as var preferences and expression-bodied members, when the severity in .editorconfig asks for them.
- Analyzers: the compiler and platform analyzers that are already in the build, with their fixes applied. A WinForms project brings the WFO rules of lesson 052 along, and a fix that the analyzer offers can be applied here.
- Designer files: Form1.Designer.cs is C# and is formatted like the rest, which is why a team often excludes it in .editorconfig or keeps its generated shape. Rewriting it is harmless, and it makes the next designer save produce a large diff, so the usual rule is to leave the designer's indentation alone.
- Not a linter for behaviour: it does not find the null dereference, the missing -= or the blocking call. Those are tests, analyzers with rules of their own, and review.
One rule about the tool in a team: run it on the whole project, not on the files a change touched, or the untouched files drift and the next run reports them. And run the verify in the build, not only the fix on a developer machine, because the fix is a command anyone can forget.
Exercises
- Break the indentation of Program.cs in one place, run the verify and the fix, and compare the status of the two runs.
- Add an .editorconfig that sets the indent size to two and run the verify on the three files. What does it report?
- Explain why a build server should run the verify rather than the fix, and what a developer runs before a commit.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What is the exit status of a verify that found a difference?
Answer
2
The real run printed 2 after the four WHITESPACE errors.
-
What does a successful dotnet format print?
Answer
Nothing, which is why the status is the result
The successful runs in this lesson printed no output and exited 0.
-
Which command only reports and changes nothing?
Answer
dotnet format app.csproj --verify-no-changes
The verify mode is the build-server mode.
-
Which rule does the WHITESPACE error name?
Answer
Fix whitespace formatting
All four errors were the same whitespace rule.
-
What did the first error ask for at line 3, column 3?
Answer
Insert two spaces
The line began with two spaces where four belong.
-
What did the fix do to the brace of the method signature?
Answer
Moved it to its own line
The three spaces before it became a newline and four spaces.
-
Where do the formatting rules come from?
Answer
The SDK defaults and the .editorconfig of the folder tree
An .editorconfig can change indentation and severity.
-
Why is a designer file special for this tool?
Answer
It is C# and is formatted, which makes the next designer save a large diff
Teams often exclude it or accept the generated shape.
-
Which defect does dotnet format find?
Answer
None of the behavioural ones; it fixes formatting and analyzer-offered fixes
Those are tests, analyzers with specific rules and review.
-
Why run the verify on the whole project rather than on the changed files?
Answer
Untouched files drift and the next run reports them
The project is the unit the tool loads.
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. The headless logic of the other pages was also run on the same machine; this page runs dotnet format, and the command output printed above is that run.
Article author: Arthur Isaev