After a C# service is retargeted from net6.0 to net10.0, the build reports CS8981 on a record named item; why, and what controls that warning?
answer
- new warnings arrive opt-in
- numbered by compiler release
- WarningLevel follows the target
- not LangVersion, not numeric AnalysisLevel
basics
~20 sCS8981 belongs to warning wave 7, reported only when WarningLevel is at least 7. The .NET SDK sets WarningLevel from the target framework's major version, so net6.0 built at level 6 and net10.0 builds at level 10.
solid answer
~40 sNew compiler warnings that could fire on existing code ship in **warning waves**, reported only when the compiler's warning level reaches the wave's number. `CS8981` (an all-lowercase type name) is wave 7, from the C# 11 compiler. When the project does not set `WarningLevel`, the .NET SDK uses the target framework's major version, so the retarget from net6.0 to net10.0 raised the level from 6 to 10 and switched on waves 7 to 10. `LangVersion` does not move it, and a numeric `AnalysisLevel` pins only the CA rules; `AnalysisLevel` set to `preview` raises it to 9999. The fix is usually to rename the type to `Item`; pinning `<WarningLevel>6</WarningLevel>` also works but silences every newer wave, and `NoWarn` can drop just `CS8981`.
code
csharp · 8 linesusing System;
record item(string Sku, int Quantity);
class Program
{
static void Main() => Console.WriteLine(new item("A-1", 2));
}go deeper
Recall that some compiler warnings are opt-in by level and that a project's WarningLevel decides which ones appear. Know that CS8981 complains about an all-lowercase type name.
Explain how the SDK derives WarningLevel from the target framework, why the retarget switched waves 7 to 10 on, and the difference between WarningLevel and LangVersion.
Diagnose a post-retarget build break quickly: identify the wave, show that numeric AnalysisLevel and LangVersion do not move it, and choose between renaming, one-id suppression and a temporary WarningLevel pin.
Plan retargets so the new waves are reviewed in the same change, and decide whether the repository ever pins WarningLevel or always takes the new warnings.
## What a warning wave is Each C# compiler release can add warnings that would fire on code that compiled cleanly before. So that an upgrade does not suddenly break such code, the compiler puts those warnings in a **warning wave**: a wave's warnings are reported only when the compiler's warning level (the `-warn:n` option, set by the `WarningLevel` MSBuild property) is at least the wave's number. Levels 0 to 4 hold the classic warnings; waves start at 5, one per compiler release that added any. | Wave | Compiler release | Example id | |---|---|---| | 5 | C# 9 (.NET 5) | `CS8073`, a struct compared to null is always false or true | | 6 | C# 10 (.NET 6) | `CS8826`, partial method declarations differ in signature | | 7 | C# 11 (.NET 7) | `CS8981`, a type name with only lowercase ASCII letters | | 8 | C# 12 (.NET 8) | `CS9123`, `&` on a local or parameter in an async method | | 10 | C# 14 (.NET 10) | `CS9265`, a `ref` field never ref-assigned | The compiler source also assigns one interceptor-related warning to wave 9 (C# 13), although the documentation tables list no wave 9 entry. ## Why the retarget triggered CS8981 When a project leaves `WarningLevel` unset, the .NET SDK fills it in for C# from the target framework: a .NET (`.NETCoreApp`) target gets its major version number. A net6.0 project therefore compiled at level 6, and the same project targeting net10.0 compiles at level 10. `CS8981` is wave 7, so a record that compiled silently before the retarget now warns, although not one line of code changed. With `TreatWarningsAsErrors` on, that warning is a broken build. The rule behind `CS8981` is about future keywords: new C# keywords are lowercase ASCII, and C# 14 itself made `field` (inside property accessors) and `extension` contextual keywords, so an all-lowercase type name is a collision waiting for a later release. ## What controls the level, measured On the .NET SDK 10.0.401, with the record below in a net10.0 project: - `-p:WarningLevel=6` removed `CS8981`. An explicit `WarningLevel` is never overridden by the SDK. - `-p:LangVersion=10` kept it. The warning level does not follow the language version. - `-p:AnalysisLevel=6` kept it. A numeric `AnalysisLevel` pins the CA rule set but leaves `WarningLevel` at 10; only `AnalysisLevel` set to `preview` changes it, to 9999, which opts into every wave the compiler knows. - A net8.0 project evaluated under the same SDK still gets level 8, so installing a newer SDK without retargeting does not raise the level. (SDKs before .NET 7 let `AnalysisLevel` overwrite `WarningLevel`; that is no longer the rule.) - A .NET Framework project gets level 4, and a netstandard2.0 project leaves `WarningLevel` empty, so the compiler falls back to its default of 4 and reports no waves. ## How to respond 1. **Fix the code** where that is cheap. Renaming `item` to `Item` removes the warning and the future collision, and is usually the right answer for `CS8981`. 2. **Suppress one id** with `NoWarn` or `dotnet_diagnostic.CS8981.severity = none` when many generated or legacy types trip it and renaming is not worth it yet. 3. **Pin `WarningLevel`** only as a short bridge. It switches off every newer wave at once, including warnings such as `CS9123` (an address taken in an async method can create a GC hole) that point at real defects. ## Why the design matters for a team Warning waves make retargeting a two-step change: the target framework moves, and a small, named set of new warnings appears with it. Reading the wave table before a retarget tells the team what to expect, and reviewing the new ids in the same pull request keeps a warnings-as-errors pipeline green. The trap is to treat the retarget as a pure runtime change and discover the new compiler warnings only when the build turns red. A short checklist for each retarget: - read the wave table for every compiler release the jump crosses; - build once with warnings as errors off and list the new ids per project; - fix or suppress them in the retarget's own pull request, never in a later clean-up that may not happen; - check that nobody pinned `WarningLevel` as a quick fix and forgot it.
- Does installing a newer .NET SDK, without retargeting, raise a project's warning level?Not for a .NET target. The SDK derives WarningLevel from the target framework's major version, so a net8.0 project evaluates to WarningLevel 8 under the .NET 10 SDK as well. Retargeting, setting WarningLevel yourself, or AnalysisLevel set to preview changes it.
- Why is pinning WarningLevel a poor long-term fix?WarningLevel is a threshold, not a list: a pinned level hides every wave above it, including later warnings that flag real defects such as CS9123 or CS9265. Fixing the code or suppressing the one id keeps the rest of the waves working.
- Upgrading the SDK alone switches on the newest warning wave for every project.
- Lowering LangVersion turns off the newer warning waves.
- A numeric AnalysisLevel such as 6.0 also caps the compiler's warning waves.
- CS8981 is a CA analyzer rule that AnalysisMode can disable.
- Pinning WarningLevel hides only the one warning that caused trouble.
Assumes the .NET 10 SDK (10.0.401) and its C# 14 compiler: net10.0 projects default to WarningLevel 10, and wave 10 (CS9265) is the newest shipped wave.