dotnet format

dotnet format is the formatter of the SDK. It reads the style from an .editorconfig and the defaults of the language, rewrites the files, and has a mode that only reports. This lesson runs both on a small project, with the real output and exit status.

A file that is not formatted

The project is one file with no spaces around the operators and a block on one line. It compiles, which is the point: formatting is not a correctness check, and a program can be valid and unreadable. The listing is the file before the tool runs:

var numbers=new[]{1,2,3}; var total=0; foreach(var n in numbers){total+=n;} Console.WriteLine($"total {total}");

dotnet build app.csproj

Build succeeded.

Verify no changes

--verify-no-changes reports what it would change and exits with a status a build can read. The command printed fifteen lines of the same kind; the first six are these:

dotnet format app.csproj --verify-no-changes --no-restore; echo $?

/tmp/cs/fmt/Program.cs(1,12): error WHITESPACE: Fix whitespace formatting. Insert '\s'. [/tmp/cs/fmt/app.csproj]
/tmp/cs/fmt/Program.cs(1,13): error WHITESPACE: Fix whitespace formatting. Insert '\s'. [/tmp/cs/fmt/app.csproj]
/tmp/cs/fmt/Program.cs(1,18): error WHITESPACE: Fix whitespace formatting. Insert '\s'. [/tmp/cs/fmt/app.csproj]
/tmp/cs/fmt/Program.cs(1,19): error WHITESPACE: Fix whitespace formatting. Insert '\s'. [/tmp/cs/fmt/app.csproj]
/tmp/cs/fmt/Program.cs(1,21): error WHITESPACE: Fix whitespace formatting. Insert '\s'. [/tmp/cs/fmt/app.csproj]
/tmp/cs/fmt/Program.cs(1,23): error WHITESPACE: Fix whitespace formatting. Insert '\s'. [/tmp/cs/fmt/app.csproj]
2

The exit status is 2, and the word is error even though nothing is wrong with the program: the tool reuses the diagnostic shape of the compiler. Every line names the file, the line, the column, the rule and a message, and ends with the project the file belongs to. A build script runs this command and fails when the status is not 0.

Format it

Without the flag the same command rewrites the file and prints nothing:

dotnet format app.csproj --no-restore; echo $?

0

The difference between the copy taken before and the file afterwards is the change the tool made:

diff -u /tmp/Before.cs Program.cs

--- /tmp/Before.cs
+++ Program.cs
@@ -1,4 +1,4 @@
-var numbers=new[]{1,2,3};
-var total=0;
-foreach(var n in numbers){total+=n;}
+var numbers = new[] { 1, 2, 3 };
+var total = 0;
+foreach (var n in numbers) { total += n; }
Console.WriteLine($"total {total}");

Spaces around the operators, spaces inside the braces of the array, a space after foreach. The tool did not expand the one-statement body of the loop onto its own lines, because that is a style choice the defaults do not make. The program still prints the same number:

dotnet run

total 6

In a build

Formatting is a decision of the team, and the tool is only the executor. This course keeps its own listings formatted with the same command, which is why the programs of the lessons pass --verify-no-changes when they are extracted.

Exercises

  1. Add an .editorconfig that requires braces on their own lines and run the tool again.
  2. Break one line, run --verify-no-changes and read the exit status in a shell.
  3. Run the tool on a folder with two projects and compare the output.
  4. Format a file with a very long line and see what the tool does with it.

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What does dotnet format --verify-no-changes do?

    Answer

    Reports the formatting differences and exits with a non-zero status

    The measured run printed fifteen error lines and exited with 2.

  2. Which status did the verify command return?

    Answer

    2

    The shell printed 2 after the command.

  3. What does this program print? var x=1; Console.WriteLine(x);

    Answer

    1

    The missing spaces are a formatting issue, not a compile error.

  4. What does the WHITESPACE diagnostic say?

    Answer

    Fix whitespace formatting, insert a space

    That is the message of the measured fifteen lines.

  5. Does formatting change the behavior of a correct program?

    Answer

    No, it changes only the layout of the text

    The formatted program still printed total 6.

  6. Where does the style of a repository live?

    Answer

    In .editorconfig, read by the tool and the IDE

    Both the command line and an editor read the same file.

  7. What did the formatter do with the one-line foreach body?

    Answer

    It spaced it and left it on one line

    The measured diff kept the braces and the body on the same line.

  8. Why run the verify command in a CI job?

    Answer

    A formatting diff fails the job before a reviewer sees it

    The exit status is a result the job can act on.

  9. What does --diagnostics add to a format run?

    Answer

    The code fixes of the analyzers

    It applies analyzer fixes, which change code and not only layout.

  10. What does this program print? using System.Text; var b = new StringBuilder(); b.Append("a"); b.Append("b"); Console.WriteLine(b.ToString());

    Answer

    ab

    The builder holds the two appended characters.

The code on this page was built with the .NET SDK 10.0.303 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev