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:

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

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

  1. Break the indentation of Program.cs in one place, run the verify and the fix, and compare the status of the two runs.
  2. Add an .editorconfig that sets the indent size to two and run the verify on the three files. What does it report?
  3. 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.

  1. What is the exit status of a verify that found a difference?

    Answer

    2

    The real run printed 2 after the four WHITESPACE errors.

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

  3. Which command only reports and changes nothing?

    Answer

    dotnet format app.csproj --verify-no-changes

    The verify mode is the build-server mode.

  4. Which rule does the WHITESPACE error name?

    Answer

    Fix whitespace formatting

    All four errors were the same whitespace rule.

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

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

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

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

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

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