Deprecate Analyzer or Refactoring
Overview
Deprecation mechanism differs by artifact type. Wrong choice causes compile errors.
When to Use
- Superseding an analyzer with another (
ObsoleteMessagenaming successor) - Retiring a rule with no replacement (
Status=Disabledfor analyzers) - Marking refactoring or compiler fix obsolete (
IsObsolete="true")
Not for: opt-in analyzers (IsEnabledByDefault=false is not deprecation).
Quick Reference
| Artifact | Mechanism |
|---|---|
| Analyzer (default) | <Status>Obsolete</Status> + <ObsoleteMessage> |
| Analyzer (retire) | <Status>Disabled</Status> — burns id |
| Refactoring / RCF | IsObsolete="true" on XML element |
Full detail: references/mechanisms.md.
Implementation
- Update XML (mechanism per artifact — references/mechanisms.md)
cd tools && pwsh ./generate_code.ps1- Remove implementation, registration, and
*Tests.cs - Keep the obsolete XML entry — analyzers (
Status=Obsolete), refactorings/RCF (IsObsolete="true"). Delete the whole<Analyzer>block only when retiring withStatus=Disabled dotnet build+ format verifyCHANGELOG.mdunder### Changed
Common Mistakes
| Mistake | Fix |
|---|---|
IsObsolete="true" on <Analyzer> |
Use <Status>Obsolete</Status> + <ObsoleteMessage> — compile error otherwise |
Delete entire <Analyzer> block when superseding |
Keep obsolete entry; remove implementation/tests only |
Status=Disabled with a successor |
Use Obsolete + ObsoleteMessage |
Confuse with IsEnabledByDefault=false |
Opt-in is not deprecation |
| Skip codegen after XML change | Descriptors/options pages stay stale |