Как пометить метод или класс как устаревший (deprecated/obsolete) в C#?

Использование атрибута [Obsolete] в C#

В C# для пометки устаревших типов, методов, свойств или других членов используется встроенный атрибут [Obsolete] (пространство имён System). Он позволяет указать, что элемент больше не рекомендуется к использованию, и выдаёт предупреждение или ошибку компиляции. Это стандартный механизм, принятый в .NET и в огромном количестве библиотек.

Базовое использование (предупреждение)

Самый простой способ — просто добавить атрибут [Obsolete] над методом или классом. Компилятор выдаст предупреждение (CS0618) при каждом обращении к этому элементу.

public class DataService
{
    [Obsolete]
    public string GetData(int id)
    {
        return "Old data";
    }

    public string FetchData(int id, bool useCache)
    {
        return "New data";
    }
}

// Использование:
var service = new DataService();
string result = service.GetData(5); // Предупреждение CS0618

Добавление сообщения для разработчика

Можно передать в конструктор атрибута строку с пояснением. Это сообщение будет отображаться в списке ошибок Visual Studio, Rider и других IDE, помогая разработчику понять, что использовать вместо устаревшего метода.

[Obsolete("Метод GetData устарел. Используйте FetchData с параметром useCache: false")]
public string GetData(int id)
{
    // ...
}

Теперь при наведении курсора на GetData(5) в IDE появится подсказка с вашим текстом.

Принудительная ошибка компиляции

Если вы хотите полностью запретить использование старого метода (чтобы код даже не компилировался), используйте второй параметр атрибута — bool error. Если передать true, компилятор выдаст ошибку вместо предупреждения.

[Obsolete("Метод GetData удалён. Используйте FetchData.", true)]
public string GetData(int id)
{
    // ...
}

// Теперь следующий код вызовет ошибку компиляции:
string result = service.GetData(5); // Ошибка CS0619

Это полезно, когда вы полностью удаляете старую функциональность в новой версии библиотеки.

Пометка целых классов и других элементов

Атрибут [Obsolete] можно применять не только к методам, но и к классам, интерфейсам, структурам, свойствам, событиям, полям и даже к сборкам (через [assembly: Obsolete]). Если класс помечен как устаревший, то предупреждение будет выдаваться при любом обращении к нему (создание экземпляра, наследование и т.д.).

[Obsolete("Используйте новый класс NewDataService.")]
public class OldDataService
{
    public string GetData(int id) => "old";
}

class Program
{
    static void Main()
    {
        var old = new OldDataService(); // Предупреждение
    }
}

Лучшие практики

• Всегда указывайте сообщение — объясните, что использовать взамен. Это сэкономит часы разработчикам, которые будут поддерживать ваш код.
• Не используйте error: true сразу — сначала выпустите версию с предупреждением, дайте пользователям время на миграцию, и только в следующей версии меняйте на ошибку.
• Указывайте версию, с которой элемент стал устаревшим — можно добавить это в текст сообщения: "Устарело с версии 2.0. Используйте FetchData."
• Используйте анализаторы кода — в современных проектах можно дополнительно написать Roslyn-анализатор, который будет более строго проверять использование устаревших API, но атрибут [Obsolete] — это первый и самый важный шаг.

[*.cs]
dotnet_diagnostic.CS0618.severity = error

// Пример своего атрибута (необязательно)
[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class)]
public class DeprecatedSinceAttribute : Attribute
{
    public string Version { get; }
    public string Message { get; }
    public DeprecatedSinceAttribute(string version, string message)
    {
        Version = version;
        Message = message;
    }
}