[C#] 設定方法 (Method) 已過時 - Obsolete

前言
最近又再重操舊業開始撰寫共用 Library，共用 Library主要用意是希望可以加速同事開發上的速度，像是與 DB 溝通或是撰寫 CRUD 每個專案都會用到的 function 或是 API，或者是每個專案都會用到的檢查邏輯抽出來讓大家使用，讓大家不用在重複造輪子以加速其他同仁在專案上的開發速度，在此專案開發時由於迭代的速度與變化較快，因此也常遇到第一版提供的 API V1 版本經過兩天後就調整為 V2 版本提供新版，此時方案或專案中勢必會有已經在使用的 V1 的 method，最快速地解法就是直接使用 resharper rename ( Ctrl + R + R ) 將參考到的方法一併換掉，簡單又迅速不花太多時間，今天要介紹的是另外一種作法是使用  Obsolete  屬性，提醒其他開發者所定義的 method 已經過期 / 過時，這篇就針對 Obsolete 此屬性做簡單介紹，若有更好的方式歡迎隨時提出來一起討論。

使用方式
 ObsoleteAttribute  位於 system 的命名空間( namespace)，因此要使用時不需要 using 其他 namespace 就可以使用，在 ObsoleteAttribute 提供三組 API 簽章讓開發者來設定方法已過時或是棄用，針對各 API 使用分別介紹如下

ObsoleteAttribute
可以在過時的方法上加上 obsoletAttribute，使用沒有參數的建構子方法，下面為定義 method1 已過時

[Obsolete]
public static string Method1()
{
    return "I'm method1 !!";
}
static void Main(string[] args)
{
    Method1();
}

將滑鼠游標移至 Method1 上方時，可以看到參考到過時的方法時下方會出現淡綠色線，Visual Studio IDE 會提示開發者該方法已過時 ( Method1 is Obsolete)

ObsoleteAttribute(String)
第一種方式提示的訊息都是固定的 xxx is obsolete，如果希望提示訊息可以客製化可以使用此方法簽章，舉例來說 method1 已棄用，希望開發者在使用時可以改用 method2，可以參考下列 sample code

[Obsolete("Method is obsolete :( please use method2")]
public static void Method1()
{
    Console.WriteLine("I'm method1 !!");
}

public static void Method2()
{
    Console.WriteLine("I'm method2 !!");
}

static void Main(string[] args)
{
    Method1();
}

將滑鼠游標移至 Method1 上方時，可以看到參考到過時的方法會呈現自訂的訊息內容

ObsoleteAttribute(String, Boolean)
此簽章包含下列兩個屬性

Message : 型別為字串，定義過時 / 棄用方法要提示開發者的訊息

IsError : 型別為 bool，定義在編譯時是否要錯誤 (true)，如果不希望編譯時產生錯誤只是警告開發者則設定為 false

舉例來說希望強制有使用/參考到 method1 方法的類別都無法使用，則需要設定 IsError 為 true，參考下列 sample code

[Obsolete("Method1 is not support, Please use method2", true)]
public static void Method1()
{
    Console.WriteLine("I'm method1 !!");
}

public static void Method2()
{
    Console.WriteLine("I'm method2 !!");
}

static void Main(string[] args)
{
    Method1();
}

與上面的都不一樣，在編譯則會跳錯誤並提示開發者你所定義的訊息內容，如下所示

希望透過以上的說明，可以讓大家對於在 C# 中如何設定方法過期/棄用時更加了解，如果有不清楚的地方歡迎一起討論，hope it helps !

參考

Using the Obsolete Attribute in C#