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
- dotnet format --verify-no-changes in a CI job makes a pull request fail on a formatting diff, before a reviewer reads it.
- The style itself lives in .editorconfig at the root of the repository, and an IDE and the tool read the same file.
- --include and --exclude limit the run to a folder or a pattern, which a monorepo needs.
- --diagnostics also applies the code fixes of the analyzers, which is a change of code and not only of whitespace; the next lesson is about the analyzers themselves.
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
- Add an .editorconfig that requires braces on their own lines and run the tool again.
- Break one line, run --verify-no-changes and read the exit status in a shell.
- Run the tool on a folder with two projects and compare the output.
- 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.
-
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.
-
Which status did the verify command return?
Answer
2
The shell printed 2 after the command.
-
What does this program print?
var x=1; Console.WriteLine(x);Answer
1
The missing spaces are a formatting issue, not a compile error.
-
What does the WHITESPACE diagnostic say?
Answer
Fix whitespace formatting, insert a space
That is the message of the measured fifteen lines.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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