# Deprecate Analyzer Or Refactoring

> Use when obsoleting or retiring RCS####, RR####, or RCF#### in roslynator, replacing an analyzer with another id, or when tempted to use IsObsolete on an Analyzer entry — analyzers use Status Obsolete, not IsObsolete.

- Skill: `dotnet/deprecate-analyzer-or-refactoring` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add dotnet/deprecate-analyzer-or-refactoring`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dotnet/deprecate-analyzer-or-refactoring/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: .NET (Microsoft) (https://skillmd.com/u/dotnet)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/dotnet/deprecate-analyzer-or-refactoring

---


# Deprecate Analyzer or Refactoring

## Overview

Deprecation mechanism differs by artifact type. Wrong choice causes compile errors.

## When to Use

- Superseding an analyzer with another (`ObsoleteMessage` naming successor)
- Retiring a rule with no replacement (`Status=Disabled` for 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](references/mechanisms.md).

## Implementation

1. Update XML (mechanism per artifact — [references/mechanisms.md](references/mechanisms.md))
2. `cd tools && pwsh ./generate_code.ps1`
3. Remove implementation, registration, and `*Tests.cs`
4. **Keep** the obsolete XML entry — analyzers (`Status=Obsolete`), refactorings/RCF (`IsObsolete="true"`). Delete the whole `<Analyzer>` block only when retiring with `Status=Disabled`
5. `dotnet build` + format verify
6. `CHANGELOG.md` under `### 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 |