deprecation-and-migration

Deprecate a .NET API by first shipping a production-proven replacement, then marking the old type with [Obsolete] and publishing a migration guide. Migrate consumers incrementally, verify zero usage via telemetry or grep, and only then remove the code and unlist the old NuGet package.

Advisory deprecation uses [Obsolete("Message", error: false)] so consumers migrate on their own timeline, while compulsory deprecation uses error: true with a hard removal deadline. Default to advisory; use compulsory only when security risk or maintenance cost justifies forcing migration with tooling.

GetAwaiter().GetResult() is acceptable only inside an adapter whose explicit purpose is bridging sync callers to async code and whose host captures no SynchronizationContext. In WPF, WinForms, MAUI, or Avalonia UI threads it deadlocks; prefer making signatures async or using Task.Run with a busy state.

Migrate an EF Core schema incrementally using the dual-write pattern: write to both old and new columns behind a feature flag, backfill existing data, then flip reads to the new schema. This mirrors the strangler pattern and avoids a single high-risk cutover.

Remove zombie code when it has no owner, no commits in 6+ months, skipped tests, vulnerable NuGet dependencies, or an EOL TargetFramework. Either assign an owner and invest in maintenance, or deprecate it with a concrete migration plan — limbo is not an option.