[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#

Read More

[VisualStudio] VisualStudio 2019 開啟專案失敗 InternalErrorException: File should not depend on itself.

問題 
今天在公司與同事共同開發專案時發生離奇的問題，同事反映要使用 Visual Studio 開啟版控的專案時發生 發生異常，Visual Studio 顯示錯誤訊息為 'System.AggregateException: One or more errors occurred. ---> Microsoft.Assumes+InternalErrorException: File should not depend on itself. ' ，這篇文章就針對此問題的解決方式做分享，若是有不清楚或是錯誤的地方歡迎討論予糾正。

案發現場
當使用 Visual Studio 開啟專案時會無法正常開啟，異常發生時畫面如下

點選確定之後，可以看到異常的方案檔在這時候出現 unloaded 的字眼出現，接著整個專案檔內容也因為讀取失敗，而無法看到專案檔底下的資訊，如下圖所示

接著開啟 log 檔案中可以看到加載失敗的錯誤訊息資訊，Log 內容如下

  System.AggregateException: One or more errors occurred. ---> Microsoft.Assumes+InternalErrorException: File should not depend on itself.
   at Microsoft.VisualStudio.ProjectSystem.VS.Implementation.Package.ProjectFactory.Prefetcher.<LoadProjectAsync>d__20.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
   at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)
   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
   at Microsoft.VisualStudio.Threading.JoinableTask.CompleteOnCurrentThread()
   at Microsoft.VisualStudio.Threading.JoinableTask`1.CompleteOnCurrentThread()
   at Microsoft.VisualStudio.ProjectSystem.VS.Implementation.Package.ProjectFactory.CreateProject(String fileName, String location, String name, UInt32 flags, Guid& projectIid, IntPtr& project, Int32& canceled)
   at Microsoft.VisualStudio.Shell.Flavor.FlavoredProjectFactoryBase.Microsoft.VisualStudio.Shell.Interop.IVsProjectFactory.CreateProject(String fileName, String location, String name, UInt32 flags, Guid& projectGuid, IntPtr& project, Int32& canceled)
   --- End of inner exception stack trace ---
=================== 

從錯誤訊息中看不出可能異常的原因，由於專案是全新的剛剛才 commit 進版控，因此也無法從版控更改紀錄來確認是異動哪裡的 Code 造成異常， .csproj  主要是用來定義專案的內容，是由數組 XML 元素組合而成，像是此專案所用到的 TargetFramework 就會定義在  .csproj  中，因此遇到此情況只能逐一查看專案檔  .csproj  內的 XML 元素是否有異常而造成 Visual Studio 無法讀取，經過一段時間的抽絲剝繭之後發現問題在專案檔中的下列區塊

<Project>
  <!--省略-->
  <ItemGroup>
    <None Update="appsettings.Development.yml">
      <DependentUpon>appsettings.yml</DependentUpon>
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="appsettings.Production.yml">
      <DependentUpon>appsettings.yml</DependentUpon>
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="appsettings.yml">
      <DependentUpon>appsettings.yml</DependentUpon>
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
  </ItemGroup>
</Project>

可以看到在上述 ItemGroup 區塊中定義三個項目，主要用意是希望設定檔 appsettings 將前墜字串相同但環境不同的 Config 整合再一起，在 Visual Studio IDE 統一顯示在一個區塊中才不會在散落各地，因此在這使用  DependentUpon  屬性來定義所依賴的檔案，但也可以發現造成無法開啟專案檔的兇手在此，造成異常的原因為 appsettings.yml 內的 DependentUpon 屬性定義依賴的檔案為自己，在比對一開始錯誤訊息內容 File should not depend on itself.，就瞬間恍然大悟秒懂錯誤訊息所表達的意思 (在沒發現之前很難意會 XD)，了解原因之後修復的動作也很簡單，將 appsettings.yml 中的 DependentUpon 移除，並 reload Project 就可以正常開啟專案，正常畫面如下

解決完畢宣告除蟲大成功 !!!

參考
Common MSBuild project items

Read More