這週忙著打黑悟空，簡單記一下前陣子同事遇到的一個場景：

由於曆法的關係，SQL Server 的 datetime 範圍只能從 1753-01-01 開始。
如果我們要寫入 0001-01-01 進去的話就會報錯

SqlDateTime overflow. Must be between 1/1/1753 12:00:00 AM and 12/31/9999 11:59:59 PM.

補充：關於曆法的部份，有興趣的朋友可以參考這篇：
淺談：消失的日期，以關聯式資料庫的日期資料類型為例 - 德瑞克：SQL Server 學習筆記

這時候通常去把資料表欄位改成香香的 datetime2 就可以搞定，爽爽寫入 0001-01-01。

但如果我們正在使用 Dapper，預設會把 C# 的 DateTime 映射到 SQL Server 的 datetime，所以還是會寫入失敗。

這時候我們就需要明確地請 Dapper 幫我們使用 datetime2 來進行處理。

如果傳遞的只是某個參數，使用 DbType 就行了：

var parameters = new DynamicParameters();
parameters.Add("@Birthday", birthday, DbType.DateTime2);

但如果傳遞的是某個 Model 裡的特定欄位呢？例如：

public class HistoricalEvent
{
    public Guid EventId { get; set; }       // 歷史事件的唯一識別碼
    public string Description { get; set; } // 歷史事件的描述
    public DateTime EventDate { get; set; } // 歷史事件發生的日期, 可能早於 1753 年！
}

這種時候就可以使用 AddTypeMap 來調整一下 Dapper 的映射型別。

閱讀全文

在做上一篇 IOptions 的筆記時，剛好看到 FeatureManagement 這香東西。
馬上來收錄一篇。順便也簡單整理一下 Feature Flag (≒Feature Toggle) 的介紹。

認識一下 Feature Flag

本部落格秉持著「簡單、友善、我好菜」的精神，按照慣例先簡單介紹一下
已經知道的朋友就可以跳過這個小節，直接前往 #環境準備 囉。

假設我們原本有 Old 邏輯：

Old();

天庭傳來諭令，要我們改成 New 邏輯。這簡單，我們就把 Old 砍掉，換成 New。非常自然，改完就佈版

New();

隔天，天庭又傳來諭令，New 需要調整一下，先不要了
現在我們又需要把 New 邏輯砍掉，讓 Old 邏輯回來。
簡單，但看來我們得再上一版

Old();
// New();

再隔天，大家可能猜到天庭又要幹嘛了，總之又上了一版

// Old();
New();

如此往復三萬八千次，工程師終於受不了了：「俺老孫每天在這切換 Old 跟 New，改完還得佈版，每天搞這些就飽了，我滴媽呀，不幹了」

就在老孫關燈走人的那一瞬間，突然靈光一現：等等，俺加個開關還不行嗎？

閱讀全文

因為手邊的 .Net Core API 專案越來越多，蠻常會需要讀 appsetting.json 的 Config，每次都要重找文章有點麻煩，這邊就來筆記一篇。

認識 Appsettings.json

首先簡單介紹一下 appsettings.json 是在幹嘛的：

我們開發的時候，常常會需要先設定好一些服務參數、組態設定之類的設定值，再用這些設定值用來控制我們程式的某些行為。例如：

• 「某功能的上限值是 10」
• 「某項開關在測試環境是 false」
• 「某服務信件的發送者要用 noreply9527」

另外常見的還有連線字串、寫 Log 時的 logging level 等等。

這些設定值會和程式碼拆開，放在設定檔集中管理，再讓程式碼從設定檔讀取相關的設定值來用就好，藉此來把設定值的管理和使用做個關注點分離。

有了設定檔，要調整修改也比較方便：要增加或是修改設定值，都只要先往設定檔衝就行。並且因為兩邊拆開了，我們也就可以簡單地替換這些設定值來應對不同狀況（例如正式環境和測試環境套用兩組不同的設定檔，或是在自己電腦測試的時候快速改個值之類的），彈性可說是 UPUP！

更重要的是，這樣我們就不需要把一大堆東西寫死在程式碼的各個地方，也就不會要改個值還要先搜尋整個專案再一個一個挖出來改了。我按 Shift Ctrl F 已經按到哭

把設定值抽出去丟到設定檔之後，我們就得到了：集中管理設定值、方便修改和替換、減少程式碼中又重複又寫死的臭東西等等好處。

在 .Net Core 的世界裡，這個設定檔就是 appsettings.json。
前面提到的像是日誌等級、功能旗標之類的這些設定值，就會放在 appsettings.json 裡面。

而當我們想要從 appsettings.json 把這些設定值給讀出來的時候，
就可以使用我們的 IOptions 啦！

使用 IOptions 來註冊 & 注入

提醒：這篇的示範會用到一些些 .Net 依賴注入（DI）相關的操作。沒接觸過的朋友可以考慮先閱讀菜雞新訓記：依賴注入

假設我們有個專案，叫做大漢防禦管理系統。專案內的 appsettings.json 有以下內容：

{
  "StrongholdInfo": {
    "Index": 49,
    "Name": "劍閣",
    "Enabled": true, 
    "General": [
      "姜維",
      "廖化",
      "張翼",
      "董厥"
    ]
  }
}

我們正好在開發一個新功能，需要抓到這段設定值。現在就來示範一下：

閱讀全文

原本我都是用產生 FB 封面的「康熙字典體產生器」來做簡單的文字 Banner，就拿來當作文章的封面照

用了好一陣子也沒啥問題。結果某天文章寫好，吃著火鍋唱著歌，產生器打開一看，服務竟然就沒了！

當下是一個震驚啊，一氣之下決定直接打開 Linqpad 寫一個。

註：現在搜尋康熙字典體產生器，還查得到介面截圖，還真的蠻簡單方便的 Q_Q

以前面的菜雞與物件導向系列 Banner 為例，我們大概需要：

• 產生一張圖
• 在圖上面放主標題和副標題
• 關鍵字可以上色

稍微搜尋一下發現 .Net 已經有 System.Drawing 這個工具可以幫我們完成這些簡單的圖片任務，事不宜遲馬上就來嘗試！

閱讀全文

這是俺整理公司新訓內容的第七篇文章，目標是紀錄 Fluent Validation 這個好用套件。

FluentValidation 可以幫我們將 Api 傳入的參數的檢查用更口語、更乾淨的方式去處理，除了可以將檢查邏輯拆分成單獨的 Validator 類別，更提供了許多內建的檢查規則和自訂的彈性，相當方便。

並且因為將參數的檢查邏輯整理出去，就可以和 Controller 本身的工作做簡單的拆分，達到關注點分離的目標。

現在就讓我們來認識一下這個好用工具吧！首先要從很久很久以前開始說起…

前言

西元前的某一天，憂心的皇帝在朝堂內繞著柱子走，突然大臣奪門而入。

大臣：「陛下！敵軍已經攻到國境內啦！」

皇帝大驚：『邊境的那些檢查站和關口難道都陷落了嗎？不可能！』

大臣：「陛下，有內奸和敵國勾結，檢查站完全沒檢查！髒資料已經闖進來了！」

皇帝喊了一聲：『怎麼可能！讓朕看看！』就打開 Controller 和前一個版本的 Git Log，這一看差點就昏了過去。

原來 Controller 的舊程式碼就已經很亂了，檢查參數的條件 if/else 和其他呼叫的方法、組裝資料都雜在一起。結果這次專案改動時，某一行就被內奸改壞了，關鍵的參數竟然沒檢查到！

『可，可惡！來人啊，把工程師推出午門斬首！』

「皇上！他已經離職啦！」

皇帝跌坐在地，懊悔地說：『如果當初有好好把檢查參數跟實際組資料的部份都拆開的話，也許就不會這樣了…』

「是啊，如果我們有用 Fluent Validation…！」

專案現況

大臣提到的 FluentValidation 是一套能幫我們把傳入參數的分離出去、用更口語化的方式去撰寫的工具。

……如果當時他們有使用 Fluent Validation 來把驗證的邏輯和規則跟原本很亂的 Controller 切分的話，說不定就能及時發現問題吧，大概。

為了不要步上他們的後塵，就讓我們直接回到本系列的卡牌管理 API 服務來加上這個好用工具吧！

閱讀全文

這是俺整理公司新訓內容的第六篇文章，目標是紀錄什麼是依賴注入（Dependency Injection）。包含：

• 為什麼要依賴注入
• 依賴注入的種類（建構式注入、屬性注入、方法注入）
• .net Core 中依賴注入的生命週期

並用 .net Core 實際跑一次依賴注入，藉由將控制權轉移給注入容器，解除分層與分層間、類別與類別間的依賴和耦合關係，達到以介面分離實作的目標。

前言

西元前的某一天，憂心的皇帝在朝堂內繞著柱子走，正巧被路過的廷尉看見。

廷尉：「敢問陛下在煩惱什麼呢？」

皇帝：『朕這是在想封賞的事兒哪。前朝之所以覆滅，根本的原因就在於大肆封賞臣下，四處分封土地給他們做諸侯。

這些諸侯呢，肆意起用自己喜歡的人擔任要職、結黨營私，心情好就 new 將軍("我ㄉ朋友");，
十天就封了十個將軍。這些人若犯了錯，要處理他們還得看諸侯面子；而諸侯一聲令下，這些人便群起造反。

並且，這些諸侯之間彼此喜歡直接往來，動不動就在自家裡下命令給 隔壁諸侯.借糧草(100)，哪天就變成 隔壁諸侯.揪團造反()。彼此之間偷來暗去，實在難以掌握。

最後呢，一個逆賊起來造反，若要將他給辦了，附近諸侯就一起響應，每個都一齊報錯，Exception 成千上百，國家也就這樣滅了，想到這朕就頭痛得很，不知愛卿可有法子？』

廷尉想了一想，便說：「陛下，此事要點還是在於諸侯之間相互依賴、彼此耦合，致生禍端。

臣有一計，先收回諸侯的人事任命權，使其不可私自 new 自己人，所有人事異動，須由中央進行管理與派遣。這樣即使諸侯要造反，也不知道下面這群打工仔是不是自己人。大家各司其職，諸侯做好自己的行政作業，打工仔派到崗位就做好自己的工作，彼此不直接依賴，這樣出事的機率就少了。

其次，明令禁止諸侯私自往來，對諸侯們進行隔離，若是有公務上的需要，一律藉由中央提供的接口來溝通，彼此之間明訂契約，由中央進行隔離與調派，諸侯間就只需要按照協議好的合約下去合作，這樣勾結的機會也就少了，耦合也就降低了。陛下覺得如何？」

皇帝大喜：『如此甚好！治眾如治寡，在於分而治之。此計可有名字？』

「此乃－－依賴注入之計！」

閱讀全文

這是俺整理公司新訓內容的第五篇文章，目標是使用三層式架構 (3-Layer Architecture) 來切分服務的關注點和職責。

什麼是分層？分層可以吃嗎？

天地混沌如雞子，商業邏輯生其中。

萬八千歲，天地開闢。表現層為天。資料層為地。商業邏輯層在其中……

　　　　－－民明書坊《盤古與他的CRUD之旅》

根據民明書坊的文獻記載，我們常聽到的「天地玄黃，宇宙洪荒」云云，其實指的就是上古時期的開發狀況。當時世界還是一片混沌，所有的程式碼都混雜成一坨，不是所有東西寫在一起你儂我儂，一言不合就三千行；就是依賴關係交錯複雜，改了北極壞南極。

要說有多亂呢，大概就算前人嘗試引入了 MVC，也只是改成把所有程式都塞在 Controller 而已，其絕望程度可見一斑。

這時候隔壁課的老盤調過來接刀，一看不得了，便決定先對這屎山整頓一番。他大喝一聲，那些靠近使用者的便上浮起來化作了天，親近資料庫的便沉澱下去變成了地，而所有的商業邏輯就連接著兩者，支撐起了整個專案。這也就是分層架構的由來。

三層式架構

分層架構是運用最為廣泛的架構模式，幾乎每個軟體系統都需要通過層（Layer）來隔離不同的關注點（Concern Point），以此應對不同需求的變化，使得這種變化可以獨立進行；此外，分層架構模式還是隔離業務複雜度與技術複雜度的利器。 －－ Ray’s Notes

一般來說，最常見的分層架構就是三層式架構了。

三層式架構顧名思義就是把應用程式分成三層，通常會分成「展示層、商業邏輯層、資料存取層」。

閱讀全文

「你寫那什麼鬼東西？這個ＯＯＯ寫法比較好啦！」
『聽你在屁！明明是這個ＸＸＸ寫法快= =』

哇喔！等等！想戰效能嗎？那你一定需要這款 BenchmarkDotnet！

介紹與安裝

我們在 Coding 的時候，或多或少都會有「不知道這兩個寫法哪個比較好？」、「聽說Ａ寫法比Ｂ寫法快，真的嗎？」這類關於效能的疑問。

在遠古時期，當我們需要驗證這種想法，可能就要用記錄秒數的方式，或是搭配迴圈、然後再印在畫面上等等這類土法煉鋼的方式。

然而這種單純計秒數的 Print 流測試，可能比較到了時間成本，卻忽略了吃掉的記憶體這些空間成本；又或是每次都要插一堆列印文字的語句，因為麻煩就萌生退意等等…

這時候就是 BenchmarkDotnet 出場的時候啦！

BenchmarkDotnet 是一款簡單好用的效能比較工具，可以幫助我們比對多組程式碼，並告訴我們平均的執行時間、耗用的記憶體等等。

只要使用 BenchmarkDotnet 這個神奇妙妙幫手，它就能幫我們搞定這些麻煩的事情，讓我們可以專注在要測試的程式碼內容囉。

閱讀全文

這是俺整理公司新訓內容的第四篇文章，目標是簡單地使用 Swagger 工具來自動產生可互動的 API 文件。

API 文件與 Swagger

在 上一篇 我們建立了一個有簡單的 CRUD 的 Web API 服務，這篇我們就接續著 API 服務往下看吧！

之前我們介紹 API 的時候有提過：API 是為了讓兩個服務之間可以溝通、互動所產生的接口。而所有的溝通要有效，都一定要先有共識，隨著溝通的人數越來越多，或是內容的理解要越來越細，就會用文件或契約的方式來達成共識。

回到我們的 API 服務開發來說，就是你除了把服務生出來了，可以跑了以外，還有一個重要的點是：必須讓所有的使用者（包含幾個月後的你自己）知道怎麼使用這組 API 服務。

也就來說，就是要寫 API 規格文件 啦！

閱讀全文

這是俺整理公司新訓內容的第三篇文章，目標是在 .NET Core 簡單地使用 Dapper 連線到資料庫並完成 CRUD 的功能。

接續 上一篇 的進度，我們接著要來連線到資料庫中完成我們的 Web Api 的 CRUD 範例。因為從新訓時期到現在工作團隊作業上主要都是使用 Dapper 來做連線資料庫的工作，這邊就直接用 Dapper 來推進吧！

Dapper 有多好用呢？它輕量、它簡單、它快速。總之先把大神們的介紹文直接拿來鎮樓：

• 短小精悍的.NET ORM神器 – Dapper - 黑暗執行緒
• 另一種資料存取對映處理方式的選擇 - Dapper - mrkt 的程式學習筆記
• 好用的微型 ORM：Dapper - Huanlin 學習筆記

那麼按照慣例，我們先來 吹捧今天的主角 說明一點簡單的前因後果吧。想直接實作的朋友，可以跳到正式開工的小節呦。

閱讀全文