Каковы лучшие практики для постепенного отказа от устаревшего кода?

У меня есть необходимость отказаться от устаревшего метода. Я знаю об [Obsolete]атрибуте. Есть ли у Microsoft рекомендуемое руководство для этого?

Вот мой текущий план:

О. Я не хочу создавать новую сборку, потому что разработчики должны будут добавить новую ссылку на свои проекты, и я ожидаю получить много горя от моего начальника и коллег, если они должны сделать это. Мы также не поддерживаем несколько версий сборки. Мы используем только последнюю версию. Изменение этой практики потребует изменения нашего процесса развертывания, что является большой проблемой (нужно научить людей, как делать вещи с TFS вместо FinalBuilder и заставить их отказаться от FinalBuilder)

Б. Отметьте старый метод как устаревший.

C. Поскольку реализация меняется (не сигнатура метода), мне нужно переименовать метод, а не создавать перегрузку. Итак, чтобы пользователи знали о правильном методе, я планирую добавить сообщение к [Obsolete]атрибуту. Эта часть беспокоит меня, потому что единственное изменение, которое я делаю, - это отделение метода от строки подключения. Но, поскольку я не добавляю новую сборку, я не вижу способа обойти это.

Результат:

[Obsolete("Please don't use this anymore because it does not implement IMyDbProvider.  Use XXX instead.")];
        /// <summary>
        /// 
        /// </summary>
        /// <param name="settingName"></param>
        /// <returns></returns>
        public static Dictionary<string, Setting> ReadSettings(string settingName)
        {
            return ReadSettings(settingName, SomeGeneralClass.ConnectionString);
        }

        public Dictionary<string, Setting> ReadSettings2(string settingName)
        {
            return ReadSettings(settingName);// IMyDbProvider.ConnectionString private member added to class.  Probably have to make this an instance method.
        }

Microsoft использует атрибут [устаревший], чтобы сообщить разработчикам, что метод, свойство или класс устарели и могут быть изменены (или вообще не поддерживаться) в будущих выпусках.

Это дает вам по крайней мере один цикл выпуска, чтобы уведомить пользователей вашего API о том, что их функция «исчезает», и удалить ссылки на него в будущих выпусках их программного обеспечения.

Как долго вы оставляете оригинальную функцию полностью зависит от вас. Если вы хотите «настоятельно рекомендовать» разработчикам использовать ваши новые функции поверх старых, вам потребуется только один дополнительный цикл выпуска, чтобы удалить его. Если вы хотите иметь постоянную обратную совместимость, вы можете оставить ее навсегда.

Как указывает Брайан, если вы изменяете только базовую реализацию, но не сигнатуру метода, вам, возможно, вообще не нужно ничего делать.

Поскольку реализация меняется (не сигнатура метода), мне нужно переименовать метод, а не создавать перегрузку.

Я не понимаю Если реализация меняется, а подпись - нет, зачем вам это делать? Пусть «старый» метод использует новую и улучшенную реализацию. Любые разработчики, использующие этот API, будут закатывать глаза, когда увидят метод с точно такой же созданной сигнатурой и предупреждения об устаревании в существующих вызовах методов. (Можете ли вы вспомнить время, когда это случалось в API?)

Если вы не уверены, сработает ли базовая реализация этого метода, проверьте поведение с помощью модульных тестов до и после изменения реализации.