Skip to content

Commit 2a676ce

Browse files
alies-devalies-dev
committed
Add .NET documentation
Add detailed usage examples and AI-friendly flags for .NET CLI tools including build, test, publish, pack, restore, format, and coverlet. Include information on verbosity levels, console logger parameters, environment variables, and Terminal Logger settings. Extend tool list and usage in AGENTS.md/CLAUDE.md template.
1 parent aaeb461 commit 2a676ce

1 file changed

Lines changed: 232 additions & 2 deletions

File tree

‎dotnet.md‎

Lines changed: 232 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,235 @@
11
# .NET
22

3-
Contributions welcome! See [contributing guidelines](CONTRIBUTING.md).
3+
## Quick Reference
44

5-
Tools to cover (draft list): dotnet build, dotnet test, dotnet publish, dotnet format, nuget, msbuild, xunit, nunit, coverlet.
5+
| Tool | AI-Friendly Flags |
6+
|----------------|-------------------------------------------------------------|
7+
| dotnet build | `--nologo -v:q --tl:off -clp:NoSummary` |
8+
| dotnet test | `--nologo -v:q --tl:off --logger "console;verbosity=quiet"` |
9+
| dotnet publish | `--nologo -v:q --tl:off -clp:NoSummary` |
10+
| dotnet pack | `--nologo -v:q --tl:off -clp:NoSummary` |
11+
| dotnet restore | `-v:q --tl:off` |
12+
| dotnet format | `--verbosity quiet --verify-no-changes` (check) |
13+
| dotnet-ef | `--no-color --prefix-output` |
14+
| coverlet | `--verbosity quiet --format cobertura` |
15+
16+
## Environment Variables
17+
18+
Set these globally for all .NET CLI commands:
19+
20+
| Variable | Effect |
21+
|---------------------------------|-------------------------------------------------|
22+
| `DOTNET_NOLOGO=1` | Suppresses welcome message and telemetry notice |
23+
| `DOTNET_CLI_TELEMETRY_OPTOUT=1` | Opts out of telemetry data collection |
24+
| `MSBUILDTERMINALLOGGER=off` | Disables Terminal Logger globally (see below) |
25+
26+
`DOTNET_NOLOGO=1` replaces the older `DOTNET_SKIP_FIRST_TIME_EXPERIENCE=true` (no longer supported since .NET Core 3.0).
27+
28+
## Terminal Logger (`--tl`)
29+
30+
The Terminal Logger is an animated, interactive output mode for MSBuild-based commands. Available since .NET 8, **default since .NET 9**. It uses ANSI escape codes and cursor movement that produce garbage in captured output.
31+
32+
```bash
33+
--tl:off # Disable — use classic console logger (what agents want)
34+
--tl:on # Force on (even in non-TTY)
35+
--tl:auto # Auto-detect (default since .NET 9)
36+
```
37+
38+
Supported by: `dotnet build`, `dotnet test`, `dotnet publish`, `dotnet pack`, `dotnet restore`.
39+
40+
In non-TTY environments, `--tl:auto` disables itself automatically. But `--tl:off` is safer to be explicit, especially since detection behavior varies across CI systems.
41+
42+
Env var equivalent: `MSBUILDTERMINALLOGGER=off`
43+
44+
## Verbosity Levels (`-v`)
45+
46+
All MSBuild-based commands (`build`, `test`, `publish`, `pack`, `restore`) support these levels. `dotnet format` also supports `--verbosity` with the same levels, though it is not MSBuild-based:
47+
48+
| Level | Short | Output |
49+
|--------------|--------|----------------------------------|
50+
| `quiet` | `q` | Errors only |
51+
| `minimal` | `m` | Errors + warnings + minimal info |
52+
| `normal` | `n` | Default MSBuild output |
53+
| `detailed` | `d` | Detailed build info |
54+
| `diagnostic` | `diag` | Full diagnostic output |
55+
56+
Usage: `-v:q` or `--verbosity quiet`
57+
58+
## Console Logger Parameters (`-clp`)
59+
60+
Fine-grained control over MSBuild console output. Semicolon-separated. Supported by `build`, `test`, `publish`, `pack`.
61+
62+
| Parameter | Effect |
63+
|-----------------------|------------------------------------------|
64+
| `NoSummary` | Hides error/warning summary at end |
65+
| `ErrorsOnly` | Shows only errors |
66+
| `WarningsOnly` | Shows only warnings |
67+
| `DisableConsoleColor` | Disables ANSI color codes |
68+
| `ForceNoAlign` | Disables padding to console buffer width |
69+
70+
Example: `-clp:NoSummary;ForceNoAlign;DisableConsoleColor`
71+
72+
## dotnet build
73+
74+
```bash
75+
dotnet build --nologo -v:q --tl:off --no-restore -clp:NoSummary;ForceNoAlign;DisableConsoleColor
76+
```
77+
78+
- `--nologo` — suppresses startup banner and copyright
79+
- `-v:q` — errors only
80+
- `--tl:off` — disables Terminal Logger (default since .NET 9)
81+
- `--no-restore` — skips implicit NuGet restore (use when already restored)
82+
- `-clp:NoSummary` — hides the "Build succeeded" / "Build FAILED" summary
83+
- `-clp:ForceNoAlign` — prevents padding to console width
84+
- `-clp:DisableConsoleColor` — disables ANSI colors
85+
86+
With `-v:q` and `-clp:NoSummary`, a clean build produces zero output. Only errors are shown.
87+
88+
To suppress specific warnings: `-p:NoWarn=CS1591` (or `--property:NoWarn=CS1591`).
89+
90+
For structured build logs: `-bl` produces a binary log file for offline analysis with [MSBuild Structured Log Viewer](https://msbuildlog.com/).
91+
92+
## dotnet test
93+
94+
```bash
95+
dotnet test --nologo -v:q --tl:off --no-restore --logger "console;verbosity=quiet"
96+
```
97+
98+
- `--nologo` — suppresses Microsoft TestPlatform banner
99+
- `-v:q` — minimal MSBuild output
100+
- `--tl:off` — disables Terminal Logger
101+
- `--no-restore` — skips implicit restore
102+
- `--no-build` — skips building (use when already built, implies `--no-restore`)
103+
- `--logger "console;verbosity=quiet"` — controls test runner output separately from MSBuild verbosity
104+
105+
Console logger verbosity levels: `quiet`, `minimal`, `normal`, `detailed`.
106+
107+
Single test: `dotnet test --filter "FullyQualifiedName~MyTestMethod"` or `dotnet test --filter "ClassName=MyTests"`
108+
109+
For structured output: `--logger "trx;logfilename=results.trx"` writes XML results. Multiple loggers can be combined:
110+
111+
```bash
112+
dotnet test --logger "console;verbosity=quiet" --logger "trx;logfilename=results.trx"
113+
```
114+
115+
The test results summary ("Passed! - Failed: 0, Passed: 42") always prints even at quiet verbosity — no flag suppresses it.
116+
117+
xUnit, NUnit, and MSTest all run via `dotnet test` — the flags above apply to all three. xUnit's `ITestOutputHelper` output only appears with `--logger "console;verbosity=detailed"`.
118+
119+
Other useful flags: `--blame` (identifies tests causing crashes), `--blame-hang-timeout 60s` (kills hanging tests).
120+
121+
## dotnet publish
122+
123+
```bash
124+
dotnet publish --nologo -v:q --tl:off --no-restore -clp:NoSummary;ForceNoAlign;DisableConsoleColor
125+
```
126+
127+
Same flags as `dotnet build`, plus:
128+
129+
- `--no-build` — skips building (implies `--no-restore`)
130+
131+
## dotnet pack
132+
133+
```bash
134+
dotnet pack --nologo -v:q --tl:off --no-restore --no-build -clp:NoSummary;ForceNoAlign;DisableConsoleColor
135+
```
136+
137+
Same flags as `dotnet build`, plus:
138+
139+
- `--no-build` — skips building (implies `--no-restore`)
140+
141+
## dotnet restore
142+
143+
```bash
144+
dotnet restore -v:q --tl:off
145+
```
146+
147+
- `-v:q` — errors only
148+
- `--tl:off` — disables Terminal Logger
149+
- `--ignore-failed-sources` — treats failed sources as warnings instead of errors
150+
151+
`dotnet restore` does not support `--nologo`.
152+
153+
Most workflows don't need explicit restore — `dotnet build` and `dotnet test` restore implicitly. Use `--no-restore` on those commands when you've already restored separately.
154+
155+
## dotnet format
156+
157+
```bash
158+
# Check (non-zero exit if changes needed)
159+
dotnet format --verbosity quiet --verify-no-changes --no-restore
160+
161+
# Fix
162+
dotnet format --verbosity quiet --no-restore
163+
```
164+
165+
- `--verbosity quiet` — minimal output
166+
- `--verify-no-changes` — check mode, returns non-zero exit code if formatting changes are needed
167+
- `--no-restore` — skips implicit restore
168+
- `--report <PATH>` — produces a JSON report to the specified directory
169+
- `--severity <info|warn|error>` — minimum diagnostic severity to fix
170+
- `--include <paths>` — include only specified files/folders
171+
- `--exclude <paths>` — exclude specified files/folders
172+
173+
Subcommands for targeted formatting: `dotnet format whitespace`, `dotnet format style`, `dotnet format analyzers` — all accept the same flags.
174+
175+
`dotnet format` does not support `--nologo`, `--tl`, or `-clp` — it is not MSBuild-based in the same way as build/test.
176+
177+
## dotnet-ef (Entity Framework Core)
178+
179+
```bash
180+
# List migrations
181+
dotnet ef migrations list --no-color --prefix-output --json --no-build
182+
183+
# Apply migrations
184+
dotnet ef database update --no-color --prefix-output --no-build
185+
186+
# Scaffold from database
187+
dotnet ef dbcontext scaffold --no-color --prefix-output --no-build
188+
```
189+
190+
- `--no-color` — disables ANSI color codes
191+
- `--prefix-output` — prefixes each line with log level (`info:`, `warn:`, `error:`), making output parseable
192+
- `--json` — structured JSON output (accepted on all commands, but only produces meaningful JSON on `migrations list`, `dbcontext list`, `dbcontext info`)
193+
- `--no-build` — skips building the project
194+
- `--verbose` / `-v` — show verbose output
195+
196+
## coverlet
197+
198+
```bash
199+
# Via dotnet test (simplest — using coverlet.collector package)
200+
dotnet test --collect:"XPlat Code Coverage"
201+
202+
# Via MSBuild (using coverlet.msbuild package)
203+
dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=cobertura /p:CoverletOutput=./coverage/
204+
205+
# Via global tool
206+
coverlet ./bin/test.dll --target dotnet --targetargs "test --no-build" \
207+
--output ./coverage/ --format cobertura --verbosity quiet
208+
```
209+
210+
Global tool flags:
211+
212+
- `--format <fmt>` — output format: `json` (default), `lcov`, `opencover`, `cobertura`, `teamcity`
213+
- `--output <path>` — output file/directory
214+
- `--verbosity <level>` — `Quiet`, `Minimal`, `Normal` (default), `Detailed`
215+
- `--threshold <N>` — fail if coverage below N%
216+
- Multiple formats: `--format "cobertura,opencover"` (comma-separated)
217+
218+
The `--collect:"XPlat Code Coverage"` approach is the simplest — it outputs Cobertura XML to `TestResults/` with no extra configuration.
219+
220+
## AGENTS.md / CLAUDE.md Template
221+
222+
Copy this into your project's AGENTS.md or CLAUDE.md:
223+
224+
```markdown
225+
## Running Tools
226+
227+
- Restore: `dotnet restore -v:q --tl:off`
228+
- Build: `dotnet build --nologo -v:q --tl:off --no-restore`
229+
- Tests: `dotnet test --nologo -v:q --tl:off --no-restore --logger "console;verbosity=quiet"`
230+
- Tests (single): `dotnet test --nologo -v:q --tl:off --filter "FullyQualifiedName~TestMethodName"`
231+
- Format check: `dotnet format --verbosity quiet --verify-no-changes --no-restore`
232+
- Format fix: `dotnet format --verbosity quiet --no-restore`
233+
- Publish: `dotnet publish --nologo -v:q --tl:off --no-restore`
234+
- EF migrations: `dotnet ef migrations list --no-color --prefix-output --json --no-build`
235+
```

0 commit comments

Comments
 (0)