John Wu's Blog

AI Coding Agent 實戰工作坊 — 中階場 (Claude)

2026-04-17T10:00:00.000Z

本篇分享 AI Coding Agent 實戰工作坊中階場的內容，以 Claude Code 作為主要示範工具，帶大家從「會用 AI」進一步到「設計 AI 的工作環境」。中階場的核心不是背更多術語，而是學會判斷結果不穩時，該補哪一層。

簡報下載

AI Coding Agent 實戰工作坊 — 中階場 (Claude) (PDF)

從單次協作到可重複流程

初階場學的是「完成一次可驗收的人機協作」，中階場要往前一步：

角度	你在做什麼
單次協作	把需求講清楚，讓 AI 幫你完成一次任務
可重複流程	設計規則、流程、工具，讓 AI 能穩定完成很多次任務

你不只是想做出一道菜，而是開始設計整間廚房怎麼穩定運作。同樣一道菜，有人每次都靠運氣，有人靠制度穩定出餐。

AI 工作環境的三大支柱

中階場的核心框架是 Prompt / Context / Harness，三者缺一不可：

支柱	餐廳比喻	白話
Prompt	你怎麼點餐	你給 AI 的指令、限制、輸出要求
Context	菜單、廚房規矩、食材資訊	AI 取得到的專案知識與外部資訊
Harness	廚房制度、權限、安全檢查	AI 可以怎麼做、做到哪裡、何時該停下來

為什麼同一句需求，結果還是會飄？

通常不是單一原因：

Prompt 不夠清楚：任務、限制、輸出格式沒有講明
Context 不夠完整：AI 不知道 repo 規範、現有 code、外部資料
Harness 不夠穩：沒有檢查點、權限邊界或 workflow 約束

所以要學的不是「寫超長 prompt」，而是判斷這次要補的是哪一層。

Prompt — 你怎麼點餐

不是每件事都要用同樣鬆緊度：

任務類型	建議鬆緊度
資料庫遷移	嚴格（指定做法、限制風險）
API 實作	中等（講清規格，保留部分空間）
Code Review	中等到寬鬆（給目標與觀察角度）
寫文件	寬鬆（講清受眾與格式）

越危險的操作，prompt 越要明確；越探索的任務，可以留多一點空間。

Context — 廚房知道什麼

如果 Prompt 是點餐，那 Context 就是：這是一家什麼餐廳、廚房有什麼規矩、現在有哪些食材、有沒有外部系統可以查資料。

1	常見 context = 對話內容 + 相關檔案 + 專案指引檔 + 需要時取得的外部資訊

⚠ context 不只影響品質，也影響成本與效率——塞太多不相關的東西，判斷會變差、資源也會浪費。

專案指引檔是廚房規矩

概念	Claude Code	Codex	Gemini
專案指引檔	`CLAUDE.md`	`AGENTS.md`	`GEMINI.md`
作用	告訴 AI 專案身份、規範、工作方式	同類型概念	同類型概念

你是在跟 AI 說：「這是我們家的廚房，我們平常就是這樣做事」。寫一次，之後每次對話都比較容易站在同一套規則上。

專案指引檔怎麼寫才有用？

要寫	不要寫
規則（約束怎麼工作、什麼不能做）	介紹（項目是什麼、目錄結構）
團隊/倉庫獨有的限制	模型本來就會的常識
長期有效的流程	臨時任務（應寫成 Skill 或 Hook）
反面例子「不要這樣做」	正面套話「保持優雅」

每一行都佔全局上下文。不寫就會出錯的才寫進去，同樣錯誤出現兩次再更新。

⚠️ 有研究指出：AI 自己生的指引檔，任務成功率反而下降；人寫但塞太多，也幾乎沒幫助。只寫最小必要規則，效果最好。

Prompt 其實是組裝出來的

你寫的不只是一份 CLAUDE.md，而是可組合的模組：

1
2
3

CLAUDE.md → role → policy → stack → skills → templates
━━━━━━━━━━━━━━━━━━━━━━━━━   ━━━━━━━━━━━━━━━━━━━━━━━━━━
     每次都載入（核心）                 按需選用

核心模組：身份、規則 — 每次對話都帶著
Skills：怎麼做 — 任務有固定 SOP 時載入
Templates：結構化的資訊格式 — 任務背景、報告、提案都是模板

Harness — 廚房怎麼被管住

機制	餐廳比喻	說明
權限 / approval	哪些事要店長批准	高風險操作先確認
Hooks / 自動檢查	出餐前先過品管	在特定時機自動跑檢查或流程
Workflow 約束	廚房標準流程	先看 code、再改、最後驗證

例如在 .claude/settings.json 設一個 hook，每次 AI 改完檔案自動跑 lint：

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit",
      "hooks": [{ "type": "command", "command": "pnpm lint --fix" }]
    }]
  }
}

Harness 像安全帶 — 不是綁手綁腳，而是讓你敢放手讓 AI 跑。

Harness 的兩個面向

面向	做什麼
自動護欄	hooks、權限、檢查點，防止出錯
反覆調校	根據結果回頭修正 Prompts & Skills

只有護欄沒有調校，規則會僵化；只有調校沒有護欄，每次都靠人盯。兩者搭配才完整。

Skills / MCP / Plugins，分別在做什麼？

概念	白話
Prompt	你怎麼下指令
CLAUDE.md / AGENTS.md	專案背景與做事方式
Skills	讓 AI 按步驟完成一種任務
MCP	讓 AI 連到外部工具或資料
Plugins	把常用能力打包成可重用組合

Skills — 把做事方法變成 SOP

Skill 把常見任務的流程寫好：

1	模糊需求 → brainstorming → plan → implementation → verification

Skill 不只是 prompt 模板，而是可重複套用的工作流程。

MCP — 讓廚房自己去拿資訊

MCP 讓 AI 在需要時自己去查資料或做操作，例如讀 issue、查資料庫、看團隊討論脈絡、讀檔案。關鍵不是「接了多少系統」，而是：AI 能不能在對的時候，自己拿到它需要的資訊。

Live Demo：從 0 到 1 做一個 RWD 任務管理系統

Demo 的主軸是讓 AI 按流程做出產品雛形，對應三大支柱：

Prompt / Context：先定角色與規則
Context → Spec：用 brainstorming 把需求收斂
Harness：用 plan、回饋迴圈推進與修正

1. 先建立 Role / Skill 系統

在專案中建立三個 Role Prompts：

Frontend：專注 UI 結構、RWD、互動與元件拆分
Backend：專注 API、資料結構、驗證與錯誤處理
QA：專注測試案例、邊界條件與風險提醒

每個角色再配一個 Skill：

Frontend skill：先定頁面結構，再定 breakpoint，再拆元件
Backend skill：先定 schema，再定 API，再補 validation
QA skill：先寫 test plan，再補 edge cases 與 E2E checklist

2. 建立約束條件

用 /init 產生 CLAUDE.md，再把規則寫進去：

1	/init 這個專案每次執行任務時，只帶一個角色與對應 Skill，Skill 最多 3 個

情境	沒約束	有約束
角色混用	前後端混扮，風格不一致	一次一個角色，職責清楚
Skill 爆量	太多 SOP 互相衝突	最多 3 個，聚焦當前任務
規則遺失	每次對話都要重新交代	寫進 CLAUDE.md，自動生效

3. Brainstorm 把需求收斂成 Design Spec

安裝 Superpowers 後：

1	/superpowers:brainstorm 我想做一個 RWD 的任務管理系統

一句模糊需求會被逐步澄清成可落地規格，決定架構方案與技術棧。關鍵不是直接寫 code，而是把需求先收斂成可以分工與驗收的 spec。

4. 從 Plan 到逐步實作

先把 spec 變成可執行計畫：

把 spec 拆出 N 個 tasks
依序讓 AI 實作每個 task
最後用 build / test 當驗收標準

執行順序：後端 schema + API → 前端元件 + 頁面 → QA 補測試案例與驗收。

5. 根據回饋即時修正

請 AI 修改完自動啟動 backend 與 frontend，用瀏覽器實際操作。發現問題時，判斷該補哪一層：

問題	該補什麼	修正方式
手機版任務卡片排版跑掉	Context（規範）	調整 flex / media query
新增任務後 API 回 404	Prompt（路由細節）	檢查路由與 controller
篩選「已完成」仍顯示全部	Harness（測試檢查點）	確認 query 與 filter

成品不會一次到位，關鍵是判斷該補哪一層，再回饋給 AI。

6. 用 OpenSpec 提出需求變更

OpenSpec 是需求、設計、實作、驗收的變更帳本：

openspec init 啟用
/opsx:explore：提出需求
/opsx:propose：建立需求文件及分工規劃
/opsx:apply：依照 spec 實作
/opsx:archive：驗收完成後歸檔

OpenSpec 不是文件倉庫，而是讓每次變更都有脈絡可追。

實務提醒：成本與 context 意識

前面提過，context 不只影響品質，也影響成本。這些情況通常都比較耗資源：

行為	常見影響	建議
超長對話	context 越來越重	適時開新對話，保持主題乾淨
一次塞太多不相關資訊	判斷品質下降	只給真正相關的內容
反覆試錯但不收斂	花時間也花額度	退一步先補 context 或規則
不必要的多工具串接	複雜度上升	先解決核心問題，再加工具

省資源的方法通常不是少問，而是讓每次提問更有結構。

三個 Takeaway

Prompt + Context + Harness 三者缺一不可 — 好的結果，通常不是靠單一神 prompt，而是三層一起補
CLAUDE.md / AGENTS.md 是團隊共享的廚房規矩 — 寫一次，之後每次合作都不用重新對齊規矩
Skills + MCP 讓 AI 從聊天工具變成工作環境的一部分 — 不只會回答，還能按流程做事、在需要時自己拿資訊

中階的核心不是「更會用 AI」，而是「更會設計 AI 怎麼工作」。

參考

Claude Code - Anthropic
Superpowers - 可重用技能包
OpenSpec - Spec 驅動開發

AI Coding Agent 實戰工作坊 — 初階場 (Codex)

2026-04-15T10:00:00.000Z

本篇分享 AI Coding Agent 實戰工作坊初階場的內容，以 Codex 作為主要示範工具，帶大家從零開始體驗 AI 輔助開發的完整流程。初階場的核心目標不是背名詞，而是完成一次可驗收的人機協作。

簡報下載

AI Coding Agent 實戰工作坊 — 初階場 (Codex) (PDF)

三個心智模型轉換

在開始使用 AI 工具之前，先調整三個思維方式：

以前	現在
搜尋 — Google、Stack Overflow 找答案	對話 — 直接問 AI，它給你完整答案
複製貼上 — 找到 code 改改看能不能用	描述意圖 — 說你要什麼，AI 量身打造
獨自開發 — 自己想、自己寫	人機協作 — 你做決策，AI 做執行

這就是所謂的 Vibe Coding：不再逐行手寫，而是用自然語言「說出你要什麼」，AI 生成第一版，你負責驗收和迭代。

AI 開發的六個層次

工作坊用「開餐廳」的比喻來串聯所有觀念：

你說的話	餐廳比喻	對應概念
「我想吃辣的」	先做一版試吃再調整	Vibe Coding
「宮保雞丁，不要花生，少油」	講越具體，出餐越準	Prompts
「這是川菜館，大火快炒」	廚房規矩寫好	Project Instructions
食譜 + 檢查點 + 工具清單	標準作業流程	Skills
接上供應商、倉庫、外送系統	對外接口	MCP

Prompts — 你當下怎麼開口

你對 AI 說的每一句話都是 Prompt。描述越具體，AI 的結果越接近你要的。

同一個需求，不同說法差很多：

	Prompt	預期結果
❌	「改好一點」	AI 不知道要改什麼
⚠️	「UI 醜醜的，幫我改」	AI 隨便改，可能不是你要的
✅	「把背景改成草地主題，地鼠換成卡通風格，按鈕加圓角和陰影，被打到時要有特效，游標變錘子」	AI 精準執行

Project Instructions — 讓 AI 先了解你的專案

在專案根目錄放一個專案指引檔（Codex 用 AGENTS.md），AI 每次開工都會自動讀取，不用每次重講。

# 打地鼠遊戲

## 技術棧
HTML + CSS + vanilla JavaScript，不用任何框架

## 規則
- 所有文字使用繁體中文
- CSS 使用卡通風格，圓角 + 明亮配色
- 每次修改後要能直接開 index.html 測試

寫一次，全團隊受益。

Skills — 讓 AI 按照流程做事

把常見工作流程寫成可重用的能力，讓 AI 在需要時套用。例如建立一個 code-review Skill，每次做收尾檢查時自動執行：

檢查有沒有 console.log 殘留
確認所有文字都是繁體中文
測試遊戲能不能正常開啟
列出這次改了哪些檔案

不用每次重複交代，寫一次就能重複使用。進一步還可以安裝 Superpowers 這類整套技能包，直接取得 brainstorming、TDD、code review 等常見 workflow。

MCP — 讓 AI 連接外部工具與資料

讓 AI 不只看你貼的內容，還能連到外部系統查資料、讀文件、做操作。例如：

連 GitLab → 讀 Issue、MR
連 JIRA → 讀 Ticket
連 Telegram → 收發訊息

AI 從「只會聊天」進一步變成「能查、能讀、能動手做事」。

補充觀念

Context — AI 看到的全貌

每次你跟 AI 對話，工具會整理相關的 Context 給它：

你的 prompt + 對話歷史 + 相關檔案內容
+ 專案指引檔（如 AGENTS.md）
+ 需要時載入的 Skills
+ 呼叫 MCP 後取得的結果

Context 越大通常越慢、越貴；對話越長，前面的重點越可能被稀釋。所以：講重點、必要時開新對話、不要把什麼都塞進去。

Models — AI 的法術強度

不同模型像遊戲裡不同等級的法術：

法術等級	感覺	適合場景
小招級	最快、最省	整理文案、格式修正、簡單問答
主力技	速度和品質平衡	日常 feature 開發、大部分工作
大招級	處理難題比較穩	卡很久的 bug、架構設計、複雜重構

原則很簡單：簡單事別亂開大招，殺雞不用牛刀。同一個模型也有不同的推理程度（蓄力時間），蓄力越久答案通常越完整，但也更慢更貴，不是每次都要拉滿。

Token — AI 的魔力值

Token 是 AI 處理資訊的計量單位。你講得越多、AI 回得越多、對話越長，消耗就越大。強模型、長對話、重工具使用通常都更耗資源。所以：講重點，少廢話，卡住就開新對話。

實作心法

選題三判準

小 — 單一功能、單一 bug、單一整理任務
清楚 — 你能用一句話說清楚要它做什麼
可驗收 — 能用測試、畫面、或 checklist 判斷結果

開口模板

工程師：「這是我的小任務：____。請你先做第一版，如果需要修改程式碼就直接改，最後告訴我怎麼驗收。」

QA：「這是我要測的功能：____。請幫我整理成 test checklist 或 bug report，格式要清楚、可直接拿去用。」

BA：「這是我的需求描述：____。請幫我整理成 user story、acceptance criteria，並指出哪裡還不夠清楚。」

卡住時怎麼接著問

「測試失敗，錯誤如下，請修到通過：____」
「結果跟我預期不同，差異是：____」
「先不要一次做完，請拆成 3 個步驟」
「先告訴我你準備怎麼改，再開始動手」

安全提醒

AI 不是保險箱，以下內容不要貼給 AI：

類型	範例	風險
機密程式碼	核心演算法、未公開功能	敏感資訊送進第三方服務
客戶資料	個資、交易紀錄	違反隱私法規
認證資訊	API key、密碼、token	外洩即可被利用
內部文件	未公開的商業策略	競爭資訊外洩

是否可使用，依公司政策、工具設定與資料分級規範為準。不確定能不能貼？先用公開或模擬資料。

三個 Takeaway

AI 是你的 Pair Programmer — AI 是協作者，不是代做者；你要負責驗收
AI 不只靠 Prompts — 不是越長越好，而是越清楚越好；先講目標、限制、驗收
AI 會犯錯 — 卡住時不要自己硬修；把錯誤和預期差異丟回 AI

參考

Codex - OpenAI
Superpowers - 可重用技能包
OpenSpec - Spec 驅動開發

數學練習小程式

2020-12-25T08:17:00.000Z

小學二年級的女兒學到乘法時，隨手寫的練習程式。由於工作關係，三年多沒碰前端，順便練習寫一下 ReactJS；這是我第一次寫 ReactJS，寫得不好的地方請多指教。

這是免費的線上九九乘法數學練習小程式，程式碼也公開在 GitHub 上給需要的人自取。

更新內容

2021/01
- 舒爾特方格表
  - 數字, 注音, 英文大小寫, 日文平假名片假名
- 填充題作答方式
- 自訂答題限時
2020/12
- 首發 9 x 9 乘法練習
- 新增 19 x 19 乘法練習
- 新增加法練習
- 新增減法練習
- 新增時鐘練習

更新計畫

之後會隨著女兒及兒子的課業內容不定期更新，如果有改善建議歡迎在下面留言處跟我說。
或是有能力開發的人，也歡迎發 MR 給我，底下有 GitHub 連結。

操作截圖

由左到右為：

主選單畫面
9 x 9 乘法選單畫面
9 x 9 乘法選擇題作答畫面

由左到右為：

9 x 9 乘法作答逾時畫面
9 x 9 乘法填充題作答畫面
9 x 9 乘法作答完成畫面

由左到右為：

5 x 5 舒爾特方格表畫面
時鐘練習作答畫面
時鐘練習作答完成畫面

程式碼下載

GitHub - math-exercise

.NET Core - 在 Mac 開發階段發生 ObjectDisposedException

2020-01-16T08:06:00.000Z

在 Mac 使用 Rider 開發時，突然遇到執行測試失敗，顯示的錯誤訊息如下：

1 2	System.ObjectDisposedException: Cannot access a disposed object. Object name: 'IServiceProvider'.

前一刻才剛跑過所有的測試，突然間就死一片，如圖：

主要原因是本機整合測試時，為了要使用 IServiceProvider，所以建立出 IHostBuilder 實體。
但很不幸的是這個 Host 死在背景，而且站著資源放不掉，所以重跑測試時一直無法 Build 出新的 Host，導致 IServiceProvider 不能被使用。

可透過以下指令找出在背景的 dotnet process，在強制刪除，如下：

# 找到死在背景的 dotnet process
ps x | grep "dotnet exec"

# 強制停止該 dotnet process
kill -9 

# 整合以上兩行
kill -9 $(ps -ax | grep "dotnet exec" | awk '{ print $1 }') 2> /dev/null

刪除後又回復正常了。

ASP.NET Core 3 系列 - 注入多個相同的介面 (Interface)

2019-10-29T15:52:00.000Z

通常在使用 ASP.NET Core 依賴注入 (Dependency Injection, DI) 都是一個介面對應一個實作類別。
若有多個類別時做相同的介面時，注入的方式就會有點變化。
本篇將介紹 ASP.NET Core 依賴注入多個相同的介面 (Interface)

前置準備

以下介面作為範例：

public enum WalletType
{
    Alipay,
    CreditCard,
    LinePay
}

public interface IWalletService
{
    WalletType WalletType { get; }
    void Debit(decimal amount);
}

public class AlipayService : IWalletService
{
    public WalletType WalletType { get; } = WalletType.Alipay;
    public void Debit(decimal amount)
    {
        // 從支付寶扣錢
    }
}

public class CreditCardService : IWalletService
{
    public WalletType WalletType { get; } = WalletType.CreditCard;
    public void Debit(decimal amount)
    {
        // 從信用卡扣錢
    }
}

public class LinePayService : IWalletService
{
    public WalletType WalletType { get; } = WalletType.LinePay;
    public void Debit(decimal amount)
    {
        // 從 Line Pay 扣錢
    }
}

服務註冊

用相同的介面，註冊不同的實作類別：

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc();

        // 註冊 Services
        services.AddSingleton();
        services.AddSingleton();
        services.AddSingleton();
    }
}

Service Injection

在 Constructor Injection 時用 IEnumerable 注入，便可取得相同介面的全部實例，再依照使用情境選擇要用的實例。範例如下：

using System.Collections.Generic;
using System.Linq;
using Microsoft.AspNetCore.Mvc;

namespace MyWebsite.Controllers
{
    public class ShoppingCartController : Controller
    {
        private readonly IEnumerable _walletServices;

        public ShoppingCartController(IEnumerable walletServices)
        {
            _walletServices = walletServices;
        }

        public IActionResult Checkout(WalletType walletType, decimal amount)
        {
            var walletService = _walletServices.Single(x => x.WalletType == walletType);
            walletService.Debit(amount);
            return Ok();
        }
    }
}

示意圖如下：

注意！
通常只建議 Singleton 類型的服務這樣使用，因為使用 Transient 或 Scoped 類型的服務，注入時會 new 新的實例，若沒用到的話，就變成不必要的效能耗損。

如果服務註冊用相同的介面，註冊不同的實作類別，Constructor Injection 時不是用 IEnumerable 注入，就只會得到最後一個註冊的類別，如上例會得到 LinePayService 的實例。

示意圖如下：

ASP.NET Core 3 系列 - 自行建置 Service Provider

2019-10-29T14:44:00.000Z

一般情況 IHostBuilder 建置 Host 實例的時候，就會自動建置 Service Provider。
所以大部份情境不需要自行建置 Service Provider，但如果想在 IHostBuilder 建置出 Host 實例之前取得 Service Provider，就可以用 IServiceCollection 的擴充方法 BuildServiceProvider 建置出 Service Provider。
本篇將介紹 ASP.NET Core 如何透過 BuildServiceProvider 建置 Service Provider，以及要注意的地方。

建置 Service Provider

通常會在 Startup.ConfigureServices 方法中，註冊 Services，待 Host 成立實體後，即可透過 Constructor Injection，提供 Services。
Host 建立實體前，若要使用 Service Provider，就需要透過 IServiceCollection 的擴充方法 BuildServiceProvider 建置，範例如下：

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;

namespace MyWebsite
{
    public class Startup
    {
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc();

            // 註冊 Services
            services.AddSingleton();

            // 建置 Service Provider
            var serviceProvider = services.BuildServiceProvider();

            // 從 Service Provider 取得服務使用
            var logger = serviceProvider.GetService>();
            var sample = serviceProvider.GetService();
            logger.LogInformation($"Type: {sample.GetType()}\r\n"
                                  + $"HashCode: {sample.GetHashCode()}\r\n"
                                  + $"Id: {sample.Id}");
        }

        public void Configure(IApplicationBuilder app)
        {
            app.UseRouting();
            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllerRoute(
                    "default",
                    "{controller=Home}/{action=Index}/{id?}"
                );
            });
        }
    }
}

注意事項

Host 實例使用的 Service Provider 與自行建立的 Service Provider 是完全不同的實體，而 services.AddSingleton 所註冊的 Services 僅在 Service Provider 實體中 Singleton，不同的 Service Provider 實體會各自存在自己的 Services。

以上例來說，雖然 Sample 是使用 AddSingleton 註冊，但實際啟動時，會有兩個 Sample 的實體。圖如：

實際運行上例程式碼，Log Output 的 Sample 實例 HashCode 與 Controller 注入的 Sample 實例 HashCode 並不一樣，表示這兩個式不同的實例，範例執行結果：

附註

Sample 類別的範例程式：

public interface ISampleSingleton
{
    int Id { get; }
}

public class Sample : ISampleSingleton
{
    private static int _counter;
    private int _id;

    public Sample()
    {
        _id = ++_counter;
    }

    public int Id => _id;
}

範例 Controllers\HomeController.cs：

using Microsoft.AspNetCore.Mvc;

namespace MyWebsite.Controllers
{
    public class HomeController : Controller
    {
        private readonly ISample _singleton;

        public HomeController(ISampleSingleton singleton)
        {
            _singleton = singleton;
        }

        public string Index()
        {
            return $"Type: {_singleton.GetType()}\r\n"
                   + $"HashCode: {_singleton.GetHashCode()}\r\n"
                   + $"Id: {_singleton.Id}";
        }
    }
}

ASP.NET Core 3 系列 - 程式進入點 Main 方法取得 DI 註冊的 Services

2019-10-28T15:47:00.000Z

大多數情況使用 ASP.NET Core 依賴注入 (Dependency Injection, DI) 取得 Services 都是透過 Request 的 Controller 建構子而來，但在程式進入點 Main 方法中，並沒有 Constructor Injection。
本篇將介紹如何在程式進入點 Main 方法取得 ASP.NET Core 依賴注入的服務。

HostBuilder

在 ASP.NET Core 的起手式，都會透過靜態類別 Host 或 WebHost 建立 HostBuilder，再透過 HostBuilder 建置出 Host 的實例，如下：

using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Hosting;

namespace MyWebsite
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var hostBuilder = CreateHostBuilder(args);
            var host = hostBuilder.Build();
            host.Run();
        }

        private static IHostBuilder CreateHostBuilder(string[] args) =>
            Host.CreateDefaultBuilder(args)
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder
                        .UseStartup();
                });
    }
}

在 HostBuilder 建置出 Host 的實例之前，需要透過 ConfigureServices 先宣告 DI Services，當 HostBuilder 建置出 Host 實例時，就會依照 ConfigureServices 註冊的配置告知 Service Provider，讓 Service Provider 可以提供請求者 Services。
而 Service Provider 的實例會一直存在 Host 的實例之中。

取用 Service Provider

為了方便說明，用之前ASP.NET Core 3 系列 - 依賴注入 (Dependency Injection) 的 Sample 類別當作範例：

public interface ISample
{
    int Id { get; }
}

public interface ISampleTransient : ISample
{
}

public interface ISampleScoped : ISample
{
}

public interface ISampleSingleton : ISample
{
}

public class Sample : ISampleTransient, ISampleScoped, ISampleSingleton
{
    private static int _counter;
    private int _id;

    public Sample()
    {
        _id = ++_counter;
    }

    public int Id => _id;
}

在 Main 方法 HostBuilder 建置出的 Host 實例，再從 Service Provider 中獲取需要的服務。

Singleton 及 Transient 類型的服務，都可以直接透過 Service Provider 取出，但 Scoped 類型的服務，必須先建立出 Service Scope，才可以在該 Scope 內的 Service Provider 中取出服務。
範例如下：

public class Program
{
    public static void Main(string[] args)
    {
        var hostBuilder = CreateHostBuilder(args);
        var host = hostBuilder.Build();

        var singleton = host.Services.GetService();
        var transient = host.Services.GetService();

        using (var scope = host.Services.CreateScope())
        {
            var scoped = scope.ServiceProvider.GetService();
        }

        host.Run();
    }
}

參考

Introduction to Dependency Injection in ASP.NET Core

ASP.NET Core 3 系列 - 依賴注入 (Dependency Injection)

2019-10-28T14:09:00.000Z

ASP.NET Core 使用了大量的依賴注入 (Dependency Injection, DI)，把控制翻轉 (Inversion Of Control, IoC) 運用的相當落實。
DI 可算是 ASP.NET Core 最精華的一部分，有用過 Autofac 或類似的 DI Framework 對此應該不陌生。
本篇將介紹 ASP.NET Core 的依賴注入。

DI 容器介紹

在沒有使用 DI Framework 的情況下，假設在 UserController 要呼叫 UserLogic，會直接在 UserController 實例化 UserLogic，如下：

public class UserLogic {
    public void Create(User user) {
        // ...
    }
}

public class UserController : Controller {
    public void Register(User user){
        var logic = new UserLogic();
        logic.Create(user);
        // ...
    }
}

xxxLogic 邏輯層分層命名，有興趣可以參考這篇：軟體分層架構模式

以上程式基本上沒什麼問題，但程式相依性就差了點。UserController 必須要依賴 UserLogic 才可以運作，就算拆出介面改成：

public interface IUserLogic {
    void Create(User user);
}

public class UserLogic : IUserLogic {
    public void Create(User user) {
        // ...
    }
}

public class UserController : Controller {
    private readonly IUserLogic _userLogic;

    public UserController() {
        _userLogic = new UserLogic();
    }

    public void Register(User user){
        _userLogic.Create(user);
        // ...
    }
}

UserController 與 UserLogic 的相依關係只是從 Action 移到建構子，依然還是很強的相依關係。

ASP.NET Core 透過 DI 容器，切斷這些相依關係，實例的產生不會是在使用方(指上例 UserController 建構子的 new)，而是在 DI 容器。
DI 容器的註冊方式也很簡單，在 ConfigureServices 註冊。Startup.cs 範例如下：

// ...
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc();
    }
}

services 就是一個 DI 容器。
此例把 MVC 的服務註冊到 DI 容器，等到需要用到 MVC 服務時，才從 DI 容器取得物件實例。

基本上要注入到 Service 的類別沒什麼限制，除了靜態類別。
以下範例程式就只是一般的 Class 繼承 Interface：

public interface ISample
{
    int Id { get; }
}

public class Sample : ISample
{
    private static int _counter;

    public Sample()
    {
        Id = ++_counter;
    }

    public int Id { get; }
}

要注入的 Service 需要在 ConfigureServices 中註冊實做類別。Startup.cs 如下：

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;

namespace MyWebsite
{
    public class Startup
    {
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc();

            // 在 Startup 註冊服務
            services.AddScoped();
        }

        public void Configure(IApplicationBuilder app)
        {
            app.UseRouting();
            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllerRoute(
                    "default",
                    "{controller=Home}/{action=Index}/{id?}"
                );
            });
        }
    }
}

第一個泛型為注入的類型
建議用 Interface 來包裝，這樣在才能把相依關係拆除。
第二個泛型為實做的類別

ASP.NET Core 3 開始，建議透過 Generic Host 建立 Web Host，所以也能用 HostBuilter 中的 ConfigureServices 方法註冊：

using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

namespace MyWebsite
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var hostBuilder = CreateHostBuilder(args);
            var host = hostBuilder.Build();
            host.Run();
        }

        private static IHostBuilder CreateHostBuilder(string[] args) =>
            Host.CreateDefaultBuilder(args)
                .ConfigureServices(services =>
                {
                    // 在 Generic Host Builder 註冊服務
                    // services.AddScoped();
                })
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder
                        .ConfigureServices(services =>
                        {
                            // 在 Web Host Builder 註冊服務
                            // services.AddScoped();
                        })
                        .UseStartup();
                });
    }
}

注意！重複註冊，會產生出重複的結果。

DI 運作方式

ASP.NET Core 的 DI 是採用 Constructor Injection，也就是說會把實例化的物件從建構子傳入。
如果要取用 DI 容器內的物件，只要在建構子加入相對的 Interface 即可。例如 Controllers\HomeController.cs：

using Microsoft.AspNetCore.Mvc;

namespace MyWebsite.Controllers
{
    public class HomeController : Controller
    {
        private readonly ISample _sample;

        public HomeController(ISample sample)
        {
            _sample = sample;
        }

        public string Index()
        {
            return $"[{nameof(ISample)}]\r\n"
                   + $"Id: {_sample.Id}\r\n"
                   + $"HashCode: {_sample.GetHashCode()}\r\n"
                   + $"Type: {_sample.GetType()}";
        }
    }
}

輸出內容如下：

[ISample]
Id: 1
HashCode: 14145203
Tpye: MyWebsite.Sample

ASP.NET Core 實例化 Controller 時，發現建構子有 ISample 這個類型的參數，就把 Sample 的實例注入給該 Controller。

每個 Request 都會把 Controller 實例化，所以 DI 容器會從建構子注入 ISample 的實例，把 sample 存到欄位 _sample 中，就能確保 Action 能夠使用到被注入進來的 ISample 實例。

注入實例過程，情境如下：

Service 生命週期

註冊在 DI 容器的 Service 有分三種生命週期：

Transient
每次注入時，都重新 new 一個新的實例。
Scoped
每個 Request 都重新 new 一個新的實例，同一個 Request 不管經過多少個 Pipeline 都是用同一個實例。上例所使用的就是 Scoped。
Singleton
被實例化後就不會消失，程式運行期間只會有一個實例。

小改一下 Sample 類別的範例程式：

public interface ISample
{
    int Id { get; }
}

public interface ISampleTransient : ISample
{
}

public interface ISampleScoped : ISample
{
}

public interface ISampleSingleton : ISample
{
}

public class Sample : ISampleTransient, ISampleScoped, ISampleSingleton
{
    private static int _counter;
    private int _id;

    public Sample()
    {
        _id = ++_counter;
    }

    public int Id => _id;
}

在 Startup.ConfigureServices 中註冊三種不同生命週期的服務。如下：

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddTransient();
        services.AddScoped();
        services.AddSingleton();
        // Singleton 也可以用以下方法註冊
        // services.AddSingleton(new Sample());
    }
}

如果有特殊需求，也可以透過委派的方式註冊。如下：

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddTransient(srv => {
            var sample = new Sample();
            // Do something ...
            return sample;
        });
        services.AddScoped(srv => new Sample());
        services.AddSingleton(srv => new Sample());
    }
}

Service Injection

只要是透過 WebHost 產生實例的類別，都可以在建構子定義型態注入。

所以 Controller、View、Filter、Middleware 或自訂的 Service 等都可以被注入。
此篇我只用 Controller、View、Service 做為範例。

Controller

在 HomeController 中注入上例的三個 Services，範例 Controllers\HomeController.cs：

public class HomeController : Controller
{
    private readonly ISample _transient;
    private readonly ISample _scoped;
    private readonly ISample _singleton;

    public HomeController(
        ISampleTransient transient,
        ISampleScoped scoped,
        ISampleSingleton singleton)
    {
        _transient = transient;
        _scoped = scoped;
        _singleton = singleton;
    }

    public IActionResult Index() {
        ViewBag.TransientId = _transient.Id;
        ViewBag.TransientHashCode = _transient.GetHashCode();

        ViewBag.ScopedId = _scoped.Id;
        ViewBag.ScopedHashCode = _scoped.GetHashCode();

        ViewBag.SingletonId = _singleton.Id;
        ViewBag.SingletonHashCode = _singleton.GetHashCode();

        return View();
    }
}

Views\Home\Index.cshtml：

<table border="1">
    <tr><td colspan="3">Cotrollertd>tr>
    <tr><td>Lifetimestd><td>Idtd><td>Hash Codetd>tr>
    <tr><td>Transienttd><td>@ViewBag.TransientIdtd><td>@ViewBag.TransientHashCodetd>tr>
    <tr><td>Scopedtd><td>@ViewBag.ScopedIdtd><td>@ViewBag.ScopedHashCodetd>tr>
    <tr><td>Singletontd><td>@ViewBag.SingletonIdtd><td>@ViewBag.SingletonHashCodetd>tr>
table>

輸出內容如下：

從左到又打開頁面三次，可以發現 Singleton 的 Id 及 HashCode 都是一樣的，此例還看不太出來 Transient 及 Scoped 的差異。

Service 實例產生方式：

圖例說明：

A 為 Singleton 物件實例
一但實例化，就會一直存在於 DI 容器中。
B 為 Scoped 物件實例
每次 Request 就會產生新的實例在 DI 容器中，讓同 Request 週期的使用方，拿到同一個實例。
C 為 Transient 物件實例
只要跟 DI 容器請求這個類型，就會取得新的實例。

View

View 注入 Service 的方式，直接在 *.cshtml 使用 @inject，如範例 Views\Home\Index.cshtml：

@using MyWebsite

@inject ISampleTransient transient
@inject ISampleScoped scoped
@inject ISampleSingleton singleton

<table border="1">
    <tr><td colspan="3">Cotrollertd>tr>
    <tr><td>Lifetimestd><td>Idtd><td>Hash Codetd>tr>
    <tr><td>Transienttd><td>@ViewBag.TransientIdtd><td>@ViewBag.TransientHashCodetd>tr>
    <tr><td>Scopedtd><td>@ViewBag.ScopedIdtd><td>@ViewBag.ScopedHashCodetd>tr>
    <tr><td>Singletontd><td>@ViewBag.SingletonIdtd><td>@ViewBag.SingletonHashCodetd>tr>
table>
<hr />
<table border="1">
    <tr><td colspan="3">Viewtd>tr>
    <tr><td>Lifetimestd><td>Idtd><td>Hash Codetd>tr>
    <tr><td>Transienttd><td>@transient.Idtd><td>@transient.GetHashCode()td>tr>
    <tr><td>Scopedtd><td>@scoped.Idtd><td>@scoped.GetHashCode()td>tr>
    <tr><td>Singletontd><td>@singleton.Idtd><td>@singleton.GetHashCode()td>tr>
table>

輸出內容如下：

從左到又打開頁面三次，Singleton 的 Id 及 HashCode 如前例是一樣的。
Transient 及 Scoped 的差異在這次就有明顯差異，Scoped 在同一次 Request 的 Id 及 HashCode 都是一樣的，如紅綠籃框。

Service

簡單建立一個 CustomService，注入上例三個 Service，程式碼類似 HomeController。如下 Services\CustomService.cs：

public class CustomService
{
    public ISample Transient { get; private set; }
    public ISample Scoped { get; private set; }
    public ISample Singleton { get; private set; }

    public CustomService(ISampleTransient transient,
        ISampleScoped scoped,
        ISampleSingleton singleton)
    {
        Transient = transient;
        Scoped = scoped;
        Singleton = singleton;
    }
}

註冊 CustomService：

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        // ...
        services.AddScoped();
    }
}

第一個泛型也可以是類別，不一定要是介面。
缺點是使用方以 Class 作為相依關係，變成強關聯的依賴。

在 Views\Home\Index.cshtml 注入 CustomService：

@using MyWebsite

@inject ISampleTransient transient
@inject ISampleScoped scoped
@inject ISampleSingleton singleton
@inject CustomService customService

<table border="1">
    <tr><td colspan="3">Cotrollertd>tr>
    <tr><td>Lifetimestd><td>Idtd><td>Hash Codetd>tr>
    <tr><td>Transienttd><td>@ViewBag.TransientIdtd><td>@ViewBag.TransientHashCodetd>tr>
    <tr><td>Scopedtd><td>@ViewBag.ScopedIdtd><td>@ViewBag.ScopedHashCodetd>tr>
    <tr><td>Singletontd><td>@ViewBag.SingletonIdtd><td>@ViewBag.SingletonHashCodetd>tr>
table>
<hr />
<table border="1">
    <tr><td colspan="3">Viewtd>tr>
    <tr><td>Lifetimestd><td>Idtd><td>Hash Codetd>tr>
    <tr><td>Transienttd><td>@transient.Idtd><td>@transient.GetHashCode()td>tr>
    <tr><td>Scopedtd><td>@scoped.Idtd><td>@scoped.GetHashCode()td>tr>
    <tr><td>Singletontd><td>@singleton.Idtd><td>@singleton.GetHashCode()td>tr>
table>
<hr />
<table border="1">
    <tr><td colspan="3">Custom Servicetd>tr>
    <tr><td>Lifetimestd><td>Idtd><td>Hash Codetd>tr>
    <tr><td>Transienttd><td>@customService.Transient.Idtd><td>@customService.Transient.GetHashCode()td>tr>
    <tr><td>Scopedtd><td>@customService.Scoped.Idtd><td>@customService.Scoped.GetHashCode()td>tr>
    <tr><td>Singletontd><td>@customService.Singleton.Idtd><td>@customService.Singleton.GetHashCode()td>tr>
table>

輸出內容如下：

從左到又打開頁面三次：

Transient
如預期，每次注入都是不一樣的實例。
Scoped
在同一個 Requset 中，不論是在哪邊被注入，都是同樣的實例。
Singleton
不管 Requset 多少次，都會是同一個實例。

參考

ASP.NET Core 3 系列 - Middleware 讀取 Request/Response Body

2019-10-24T17:18:00.000Z

本篇將介紹 ASP.NET Core 3 透過 Middleware 讀寫 Request/Response Body 的用法。
若對 Middleware 基本知識不熟習的話，可以參考 ASP.NET Core 3 系列 - Middleware。

讀取 Request Body

在 Middleware 的 Invoke 可以獲取到 HttpContext，其中會包含 Request 的內容，包含 URL、Header 等。
Request Body 是 Stream 型別，要取出內容，可以透過 StreamReader 如下：

using System;
using System.IO;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;

namespace MyWebsite
{
    public class FirstMiddleware
    {
        private readonly RequestDelegate _next;

        public FirstMiddleware(RequestDelegate next)
        {
            _next = next;
        }

        public async Task Invoke(HttpContext context)
        {
            string requestContent;

            using (var reader = new StreamReader(context.Request.Body))
            {
                requestContent = await reader.ReadToEndAsync();
                context.Request.Body.Seek(0, SeekOrigin.Begin);
            }

            await _next(context);

            Console.WriteLine($"Request.Body={requestContent}");
        }
    }
}

注意！Seek(0, SeekOrigin.Begin) 非常重要，如果把 Stream 讀完後，不把 Stream Position 還原，之後的 Pipeline、Action 在取得 Request Body 時，會從 Stream 的結尾開始取資料，意味著取出來都是空資料。

讀取 Response Body

Middleware 取得 Response Body 相較於 Request 麻煩很多，因為 Response.Body 的 Stream 並不允許被讀取讀取，但可以被替換。
所以在 Response.Body 開始被寫入之前，先抽換成 MemoryStream；這樣之後的 Pipeline 在寫入 Response.Body 時，實際上都是寫入到被抽換的 MemoryStream 之中。
等到下層 Pipeline 都做完的時候，就可以讀取 MemoryStream 的資料，讀完後再把 MemoryStream 寫到真實的 Response.Body。
範例如下：

using System;
using System.IO;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;

namespace MyWebsite
{
    public class SecondMiddleware
    {
        private readonly RequestDelegate _next;

        public SecondMiddleware(RequestDelegate next)
        {
            _next = next;
        }

        public async Task Invoke(HttpContext context)
        {
            string responseContent;

            var originalBodyStream = context.Response.Body;
            using (var fakeResponseBody = new MemoryStream())
            {
                context.Response.Body = fakeResponseBody;

                await _next(context);

                fakeResponseBody.Seek(0, SeekOrigin.Begin);
                using (var reader = new StreamReader(fakeResponseBody))
                {
                    responseContent = await reader.ReadToEndAsync();
                    fakeResponseBody.Seek(0, SeekOrigin.Begin);

                    await fakeResponseBody.CopyToAsync(originalBodyStream);
                }
            }
            Console.WriteLine($"Response.Body={responseContent}");
        }
    }
}

上例 Seek(0, SeekOrigin.Begin) 被呼叫了兩次，原因：

_next(context) 會寫入內容到 fakeResponseBody，導致 Stream Position 會被指到結尾，為了讀取 fakeResponseBody 內容，所以要把 Stream Position 指回起始位置。
讀取完 fakeResponseBody 內容後，Stream Position 又會被指到結尾，為了把 fakeResponseBody 複製回原本的 Response.Body，所以要把 Stream Position 指回起始位置。

執行流程如下：

參考

ASP.NET Core 3 系列 - Middleware

2019-10-24T13:39:00.000Z

過去 ASP.NET 中使用的 HTTP Modules 及 HTTP Handlers，在 ASP.NET Core 中已不復存在，取而代之的是 Middleware。
Middleware 除了簡化了 HTTP Modules/Handlers 的使用方式，還帶入了 Pipeline 的概念。
本篇將介紹 ASP.NET Core 3 的 Middleware 概念及用法。

Middleware 概念

ASP.NET Core 在 Middleware 的官方說明中，使用了 Pipeline 這個名詞，意旨 Middleware 像水管一樣可以串聯在一起，所有的 Request 及 Response 都會層層經過這些水管。
用圖例可以很容易理解，如下圖：

App.Use

Middleware 的註冊方式是在 Startup.cs 的 Configure 對 IApplicationBuilder 使用 Use 方法註冊。
大部分擴充的 Middleware 也都是以 Use 開頭的方法註冊，例如：

UseRouting()：Request 路由使用的 Middleware
UseRewriter()：URL rewriting 的 Middleware

一個簡單的 Middleware 範例。Startup.cs 如下：

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;

namespace MyWebsite
{
    public class Startup
    {
        public void Configure(IApplicationBuilder app)
        {
            app.Use(async (context, next) =>
            {
                await context.Response.WriteAsync("First Middleware in. \r\n");
                await next.Invoke();
                await context.Response.WriteAsync("First Middleware out. \r\n");
            });

            app.Use(async (context, next) =>
            {
                await context.Response.WriteAsync("Second Middleware in. \r\n");
                await next.Invoke();
                await context.Response.WriteAsync("Second Middleware out. \r\n");
            });

            app.Use(async (context, next) =>
            {
                await context.Response.WriteAsync("Third Middleware in. \r\n");
                await next.Invoke();
                await context.Response.WriteAsync("Third Middleware out. \r\n");
            });

            app.Run(async context =>
            {
                await context.Response.WriteAsync("Hello World! \r\n");
            });
        }
    }
}

用瀏覽器打開網站任意連結，輸出結果：

First Middleware in.
Second Middleware in.
Third Middleware in.
Hello World!
Third Middleware out.
Second Middleware out.
First Middleware out.

在 Pipeline 的概念中，註冊順序是很重要的事情。資料經過的順序一定是先進後出。

Request 流程如下圖：

Middleware 也可以作為攔截使用，Startup.cs 如下：

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;

namespace MyWebsite
{
    public class Startup
    {
        public void Configure(IApplicationBuilder app)
        {
            app.Use(async (context, next) =>
            {
                await context.Response.WriteAsync("First Middleware in. \r\n");
                await next.Invoke();
                await context.Response.WriteAsync("First Middleware out. \r\n");
            });

            app.Use(async (context, next) =>
            {
                await context.Response.WriteAsync("Second Middleware in. \r\n");

                // 水管阻塞，封包不往後送
                var condition = false;
                if(condition) {
                    await next.Invoke();
                }

                await context.Response.WriteAsync("Second Middleware out. \r\n");
            });

            app.Use(async (context, next) =>
            {
                await context.Response.WriteAsync("Third Middleware in. \r\n");
                await next.Invoke();
                await context.Response.WriteAsync("Third Middleware out. \r\n");
            });

            app.Run(async context =>
            {
                await context.Response.WriteAsync("Hello World! \r\n");
            });
        }
    }
}

輸出結果：

First Middleware in.
Second Middleware in.
Second Middleware out.
First Middleware out.

在 Second Middleware 中，因為沒有達成條件，所以封包也就不在往後面的水管傳送。流程如圖：

App.Run

Run 是 Middleware 的最後一個行為，以上面圖例來說，就是最末端的 Action。
它不像 Use 能串聯其它 Middleware，但 Run 還是能完整的使用 Request 及 Response。

App.Map

Map 是能用來處理一些簡單路由的 Middleware，可依照不同的 URL 指向不同的 Run 及註冊不同的 Use。
新增一個路由，Startup.cs 如下：

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;

namespace MyWebsite
{
    public class Startup
    {
        public void Configure(IApplicationBuilder app)
        {
            app.Use(async (context, next) =>
            {
                await context.Response.WriteAsync("First Middleware in. \r\n");
                await next.Invoke();
                await context.Response.WriteAsync("First Middleware out. \r\n");
            });

            app.Map("/second", mapApp =>
            {
                mapApp.Use(async (context, next) =>
                {
                    await context.Response.WriteAsync("Second Middleware in. \r\n");
                    await next.Invoke();
                    await context.Response.WriteAsync("Second Middleware out. \r\n");
                });
                mapApp.Run(async context =>
                {
                    await context.Response.WriteAsync("Second. \r\n");
                });
            });

            app.Run(async context =>
            {
                await context.Response.WriteAsync("Hello World! \r\n");
            });
        }
    }
}

開啟網站任意連結，會顯示：

1
2
3

First Middleware in.
Hello World!
First Middleware out.

開啟網站 http://localhost:5000/second，則會顯示：

First Middleware in.
Second Middleware in.
Second.
Second Middleware out.
First Middleware out.

建立 Middleware 類別

如果 Middleware 全部都寫在 Startup.cs，程式碼應該很難維護，所以應該把自製的 Middleware 邏輯獨立出來。
建立 Middleware 類別不需要額外繼承其它類別或介面，一般的類別即可，FirstMiddleware.cs 範例如下：

using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;

namespace MyWebsite
{
    public class FirstMiddleware
    {
        private readonly RequestDelegate _next;

        public FirstMiddleware(RequestDelegate next)
        {
            _next = next;
        }

        public async Task Invoke(HttpContext context)
        {
            await context.Response.WriteAsync($"{nameof(FirstMiddleware)} in. \r\n");

            await _next(context);

            await context.Response.WriteAsync($"{nameof(FirstMiddleware)} out. \r\n");
        }
    }
}

全域註冊

在 Startup.cs 的 Configure 註冊 Middleware 就可以套用到所有的 Request。如下：

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;

namespace MyWebsite
{
    public class Startup
    {
        public void Configure(IApplicationBuilder app)
        {
            app.UseMiddleware();

            app.Run(async context =>
            {
                await context.Response.WriteAsync("Hello World! \r\n");
            });
        }
    }
}

區域註冊

Middleware 也可以只套用在特定的 Controller 或 Action。註冊方式如 Controllers\HomeController.cs：

// ..
[MiddlewareFilter(typeof(FirstMiddleware))]
public class HomeController : Controller
{
    // ...

    [MiddlewareFilter(typeof(SecondMiddleware))]
    public IActionResult Index()
    {
        // ...
    }
}

Extensions

大部分擴充的 Middleware 都會用一個靜態方法包裝，如：UseRouting()、UseRewriter()等。
自製的 Middleware 當然也可以透過靜態方法包，範例 CustomMiddlewareExtensions.cs 如下：

using Microsoft.AspNetCore.Builder;

namespace MyWebsite
{
    public static class CustomMiddlewareExtensions
    {
        public static IApplicationBuilder UseFirstMiddleware(this IApplicationBuilder builder)
        {
            return builder.UseMiddleware();
        }
    }
}

註冊 Extension Middleware 的方式如下：

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;

namespace MyWebsite
{
    public class Startup
    {
        public void Configure(IApplicationBuilder app)
        {
            app.UseFirstMiddleware();

            app.Run(async context =>
            {
                await context.Response.WriteAsync("Hello World! \r\n");
            });
        }
    }
}

參考

ASP.NET Core 3 系列 - 程式生命週期 (Application Lifetime)

2019-10-23T17:42:00.000Z

要了解程式的運作原理，要先知道程式的進入點及生命週期。
過往 ASP.NET MVC 啟動方式，是繼承 HttpApplication 做為網站開始的進入點。
ASP.NET Core 改變了網站啟動的方式，是用 Console Application 的方式，Host Kestrel，提供 HTTP 的服務。
本篇將介紹 ASP.NET Core 3 的程式生命週期 (Application Lifetime) 及捕捉 Application 停啟事件。

程式進入點

.NET Core 把 Web 及 Console 專案都變成一樣的啟動方式，預設從 Program.cs 的 Main() 做為程式進入點，再從程式進入點把 Kestrel 實例化。

透過 .NET Core CLI 建置的 Program.cs 內容大致如下：

using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Hosting;

namespace MyWebsite
{
    public class Program
    {
        public static void Main(string[] args)
        {
            CreateHostBuilder(args).Build().Run();
        }

        private static IHostBuilder CreateHostBuilder(string[] args) =>
            Host.CreateDefaultBuilder(args)
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder.UseStartup();
                });
    }
}

Main() 透過 CreateHostBuilder 方法宣告需要相依的相關服務，並設定 WebHost 啟動後要執行 Startup 類別。

CreateHostBuilder
透過此方法宣告相依的服務及組態設定等，其中包含 WebHost。
可以在 Host 產生之前設定一些前置準備動作，當 Host 建立完成時，就可以使用已準備好的物件等。
UseStartup
設定 WebHostBuilder 產生的 WebHost 時，所要執行的類別。
Build
當前置準備都設定完成後，就可以呼叫此方法實例化 Host，同時也會實例化 WebHost。
Run
啟動 Host。

.NET Core 3.0 官方建議的方式是透過 Generic Host 建立 Web Host。
但如果真的不想透過 Generic Host 建立 Web Host，可改成以下方式：

using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Hosting;

namespace MyWebsite
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var hostBuilder = CreateHostBuilder(args);
            var host = hostBuilder.Build();
            host.Run();
        }

        private static IHostBuilder CreateHostBuilder(string[] args) =>
            WebHost.CreateDefaultBuilder(args)
                .UseStartup();
    }
}

Startup.cs

Host 建置時，WebHost 會呼叫 UseStartup 泛型類別的 ConfigureServices 方法。
Host 啟動後，WebHost 會呼叫 UseStartup 泛型類別的 Configure 方法。

透過 .NET Core CLI 建置的 Startup.cs 內容大致如下：

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

namespace MyWebsite
{
    public class Startup
    {
        public void ConfigureServices(IServiceCollection services)
        {
            // 註冊 Services ...
        }

        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            app.UseRouting();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapGet("/", async context =>
                {
                    await context.Response.WriteAsync("Hello World!");
                });
            });
        }
    }
}

ConfigureServices
ConfigureServices 是用來將服務註冊到 DI 容器用的。這個方法可不實做，並不是必要的方法。
(DI 可以參考這篇：ASP.NET Core 3 系列 - 依賴注入 (Dependency Injection))
Configure
這是必要的方法，一定要時做。但 Configure 方法的參數並不固定，參數的實例都是從 WebHost 注入進來，可依需求增減需要的參數。
- IApplicationBuilder 是最重要的參數也是必要的參數，Request 進出的 Pipeline 都是透過 ApplicationBuilder 來設定。
  (Pipeline 可以參考這篇：ASP.NET Core 3 系列 - Middleware)

對 WebHost 來說 Startup.cs 並不是必要存在的功能。
可以試著把 Startup.cs 中的兩個方法，都改成在 WebHost Builder 設定，變成啟動的前置準備。Program.cs 如下：

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Hosting;

namespace MyWebsite
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var hostBuilder = CreateHostBuilder(args);
            var host = hostBuilder.Build();
            host.Run();
        }

        private static IHostBuilder CreateHostBuilder(string[] args) =>
            Host.CreateDefaultBuilder(args)
                .ConfigureServices(services =>
                {
                    // Generic Host 註冊 Services ...
                })
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder
                        .ConfigureServices(services =>
                        {
                            // Web Host 註冊 Services ...
                        })
                        .Configure(app =>
                        {
                            app.UseRouting();
                            app.UseEndpoints(endpoints =>
                            {
                                endpoints.MapGet("/",
                                    async context => {
                                        await context.Response.WriteAsync("Hello World!");
                                    });
                            });
                        });
                });
    }
}

把 ConfigureServices 及 Configure 都改到 WebHost Builder 註冊，網站的執行結果會是一樣的。
若是透過 Generic Host 建立 Web Host，也可以在 HostBuilder 用 ConfigureServices 註冊 Services。

Application Lifetime

除了程式進入點外，WebHost 的啟停也是網站事件很重要一環，ASP.NET Core 不像 ASP.NET MVC 用繼承的方式捕捉啟動及停止事件。而是透過 IHostApplicationLifetime 來捕捉 WebHost 的停啟事件。

IHostApplicationLifetime 有三個註冊監聽事件及終止網站事件可以觸發。如下：

public interface IHostApplicationLifetime
{
    CancellationToken ApplicationStarted { get; }
    CancellationToken ApplicationStopping { get; }
    CancellationToken ApplicationStopped { get; }
    void StopApplication();
}

ApplicationStarted
當 WebHost 啟動完成後，會執行的啟動完成事件。
ApplicationStopping
當 WebHost 觸發停止時，會執行的準備停止事件。
ApplicationStopped
當 WebHost 停止事件完成時，會執行的停止完成事件。
StopApplication
可以透過此方法主動觸發終止網站。

範例程式

透過 Console 輸出執行的過程，Program.cs 範例如下：

using System;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Hosting;

namespace MyWebsite
{
    public class Program
    {
        public static void Main(string[] args)
        {
            Output("[Program] Start");

            Output("[Program] Create HostBuilder");
            var hostBuilder = CreateHostBuilder(args);

            Output("[Program] Build Host");
            var host = hostBuilder.Build();

            Output("[Program] Run Host");
            host.Run();

            Output("[Program] End");
        }

        private static IHostBuilder CreateHostBuilder(string[] args) =>
            Host.CreateDefaultBuilder(args)
                .ConfigureServices(services => {
                    Output("[Program] hostBuilder.ConfigureServices - Called");
                })
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder
                        .ConfigureServices(services => {
                            Output("[Program] webBuilder.ConfigureServices - Called");
                        })
                        .Configure(app => {
                            Output("[Program] webBuilder.Configure - Called");
                        })
                        .UseStartup();
                });

        public static void Output(string message)
        {
            Console.WriteLine($"[{DateTime.Now:yyyy/MM/dd HH:mm:ss}] {message}");
        }
    }
}

Startup.cs：

using System.Threading;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

namespace MyWebsite
{
    public class Startup
    {
        public Startup()
        {
            Program.Output("[Startup] Constructor - Called");
        }

        public void ConfigureServices(IServiceCollection services)
        {
            Program.Output("[Startup] ConfigureServices - Called");
        }

        public void Configure(IApplicationBuilder app, IHostApplicationLifetime appLifetime)
        {
            appLifetime.ApplicationStarted.Register(() =>
            {
                Program.Output("[Startup] ApplicationLifetime - Started");
            });

            appLifetime.ApplicationStopping.Register(() =>
            {
                Program.Output("[Startup] ApplicationLifetime - Stopping");
            });

            appLifetime.ApplicationStopped.Register(() =>
            {
                Thread.Sleep(5 * 1000);
                Program.Output("[Startup] ApplicationLifetime - Stopped");
            });

            app.UseRouting();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapGet("/", async context => { await context.Response.WriteAsync("Hello World!"); });
            });

            // For trigger stop WebHost
            var thread = new Thread(() =>
            {
                Thread.Sleep(5 * 1000);
                Program.Output("[Startup] Trigger stop WebHost");
                appLifetime.StopApplication();
            });
            thread.Start();

            Program.Output("[Startup] Configure - Called");
        }
    }
}

執行結果

[2019/10/24 01:24:59] [Program] Start
[2019/10/24 01:24:59] [Program] Create HostBuilder
[2019/10/24 01:24:59] [Program] Build Host
[2019/10/24 01:24:59] [Program] hostBuilder.ConfigureServices - Called
[2019/10/24 01:24:59] [Program] webBuilder.ConfigureServices - Called
[2019/10/24 01:24:59] [Startup] Constructor - Called
[2019/10/24 01:24:59] [Startup] ConfigureServices - Called
[2019/10/24 01:25:00] [Program] Run Host
[2019/10/24 01:25:00] [Startup] Configure - Called
[2019/10/24 01:25:00] [Startup] ApplicationLifetime - Started
[2019/10/24 01:25:05] [Startup] Trigger stop WebHost
[2019/10/24 01:25:05] [Startup] ApplicationLifetime - Stopping
[2019/10/24 01:25:10] [Startup] ApplicationLifetime - Stopped
[2019/10/24 01:25:10] [Program] End

輸出內容少了 [Program] webBuilder.Configure - Called，因為 Configure 只能有一個，後註冊的 Configure 會把之前註冊的蓋掉。

執行流程如下：

參考

ASP.NET Core 3 系列 - 從頭開始

2019-10-23T15:12:00.000Z

自九月推出 .NET Core 3.0 正式版後，最近終於開始把產品從 .NET Core 2 開始升級到 .NET Core 3.0。
之前寫的 ASP.NET Core 2 系列文章有部分內容已過時，所以將重新整理成 ASP.NET Core 3 的內容，並補充一些說明。
本篇主要介紹基本的 ASP.NET Core 3 環境準備及如何用 Visual Studio Code (VS Code) 開發 ASP.NET Core。

前言

開發 .NET Core 必需要安裝 .NET Core SDK，所以先到官網下載 .NET Core SDK 的安裝檔，官網下載位置點此。

.NET Core 是跨作業系統的框架，不再像 .NET Framework 要依附在 Windows 的作業系統才能執行，所以可以依照各平台版本進行下載及安裝。
文中範例用的截圖大部分是 Windows 作業系統，但本系列教學都會是以指令為主，並不受限於 Windows 平台。
(安裝軟體步驟太簡單，除了按下一步以外，幾乎沒什麼好解說的，所以不介紹怎麼安裝軟體。)

安裝完成後，可以透過 .NET Core CLI (Command-Line Interface) 確認 .NET Core SDK 安裝的版本，指令如下：

1	dotnet --version

建立網站專案

先建立一個專案資料夾 MyWebsite，然後在該資料夾執行 .NET Core CLI 建置網站的指令：

# 建立專案資料夾
mkdir MyWebsite

# 進入專案資料夾
cd MyWebsite

# 建立 ASP.NET Core 專案
dotnet new web

.NET Core CLI 會在該資料夾，建立一個空的 ASP.NET Core 專案，內容如下：

obj/                            # 專案暫存目錄
Properties/                     # 開發用的環境設定
MyWebsite.csproj                # 專案檔
appsettings.Development.json    # 執行程式組態設定(開發階段)
appsettings.json                # 執行程式組態設定(預設)
Program.cs                      # 程式進入檔
Startup.cs                      # 啟動網站設定

.NET Core 3.0 之後，*.csproj 專案檔變得很乾淨俐落，如上圖。
當宣告就會預設參考 Microsoft.AspNetCore.App 套件。

啟動網站

建立完成後，就可以用 .NET Core CLI 啟動網站了。啟動網站指令：

1	dotnet run

.NET Core CLI 預設會起一個http://localhost:5000/的站台，用瀏覽器打開此連結就可以看到 ASP.NET Core 網站了。如下：

Visual Studio Code

.NET Core 都已經跨作業系統了，開發工具當然也就不再限制於 Visual Studio IDE (Visual Studio 2019/2017 等)。基本上純文字編輯器搭配 .NET Core CLI 就可以開發 ASP.NET Core 了，但沒有中斷點除錯或 Autocomplete 開發有些辛苦。

Windows 作業系統，最推薦的當然還是 Visual Studio IDE
跨平台的話強烈推薦 JetBrains 公司出的 Rider
最輕量化跨平台推薦 Visual Studio Code (簡稱 VS Code)。

VS Code 是一套可安裝擴充套件的文字編輯器，有支援 Windows、Mac 及 Linux 版本，極輕量又免費。
只要安裝擴充套件就變成了 IDE，並且支援多種不同的程式語言。下載位置點此。

範例選擇用 VS Code 最主要的原因是免費且跨平台。

安裝擴充套件

打開 VS Code 可以在左邊看到五個 Icon，點選最下面的那個 Extensions 圖示，並在 Extensions 搜尋列輸入 C# ，便可以找到 C# 的擴充套件安裝。如下圖：

開啟專案

VS Code 跟一般文字編輯器有些不同，它是以資料夾為工作區域，開啟一個目錄，就等同於是開啟一個專案。從上方工具列 File -> Open Folder 選擇 ASP.NET Core 專案目錄，大概隔幾秒後，VS Code 會提示是否要幫此專案加入 Build/Debug 的設定。如下圖：

Build/Debug 設定

如果沒有自動提示加入 Build/Debug 設定，可以在左邊 Icon，點選倒數第二個 Debug 圖示，手動加入 Build/Debug 設定。如下步驟：

設定完成後，VS Code 會自動建立 .vscode 目錄及設定檔 launch.json、tasks.json。
目錄結構如下：

.vscode/                        # VS Code 設定檔目錄
  launch.json                   # 用 VS Code 啟動程式的設定檔
  tasks.json                    # 定義 launch.json 會用道的指令設定檔
obj/                            # 專案暫存目錄
Properties/                     # 開發用的環境設定
MyWebsite.csproj                # 專案檔
appsettings.Development.json    # 執行程式組態設定(開發階段)
appsettings.json                # 執行程式組態設定(預設)
Program.cs                      # 程式進入檔
Startup.cs                      # 啟動網站設定

如果 VS Code 自動建立失敗，那就手動新增 launch.json 及 tasks.json 吧…
內容如下：

launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": ".NET Core Launch",
      "type": "coreclr",
      "request": "launch",
      "preLaunchTask": "build",
      "program": "${workspaceFolder}/bin/Debug/netcoreapp3.0/MyWebsite.dll",
      "args": [],
      "cwd": "${workspaceFolder}",
      "console": "internalConsole",
      "stopAtEntry": false
    }
  ]
}

tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build",
      "command": "dotnet",
      "type": "process",
      "args": [
        "build"
      ],
      "problemMatcher": "$msCompile"
    }
  ]
}

中斷點除錯

在程式碼行號左邊點擊滑鼠就可以下中斷點了，跟一般 IDE 差不多。然後在 Debug 側欄啟動偵錯：

當執行到該中斷點後，就會停下來，並在 Debug 側欄顯示當前變數狀態等，也可以用滑鼠移到變數上面檢視該變數的內容。如下：

偵錯方式跟大部分的 IDE 都差不多，可以 Step over、Step in/out 等。
如此一來就可以用 VS Code 輕鬆開發 ASP.NET Core。

Docker 教學 - .NET Core 程式碼分析報告 (SonarQube)

2019-09-04T15:02:00.000Z

SonarQube 是常見的程式碼分析工具，本篇介紹如何透過 Docker 進行 .NET Core 程式碼分析；
並搭配 Coverlet 產生程式碼測試覆蓋率分析，一併傳送至 SonarQube。

SonarQube

如果沒有 SonarQube 環境的話，可透過以下 docker 指令，快速啟動 SonarQube：

1	docker run --name SonarQube -p 9000:9000 sonarqube

啟動後，用瀏覽器打開 http://localhost:9000/ 就能看到 SonarQube 站台。
預設帳號/密碼為：admin / admin

登入後，可新增 SonarQube 專案，步驟如下：

分析報告要上傳到 SonarQube Server 時，需要用到 Project Key 及步驟 8 的 Token。

Dockerfile

build-unit-test.dockerfile

FROM mcr.microsoft.com/dotnet/core/sdk:2.2
# 安裝 Coverlet 及 SonarScanner
RUN dotnet tool install --global coverlet.console && \
    dotnet tool install --global dotnet-sonarscanner
ENV PATH=$PATH:/root/.dotnet/tools/
# 安裝 JRE，SonarScanner 是基於 Java 撰寫，所以需要 JRE
RUN apt-get update && \
    apt-get install -y openjdk-8-jdk
WORKDIR /
COPY . .
# 啟動 SonarScanner
RUN dotnet sonarscanner begin /k:"" \
    /d:sonar.host.url=http://192.168.1.11:9000 \
    /d:sonar.login= \
    /d:sonar.exclusions=**/*.js,**/*.ts,**/*.css,bin/**/*,obj/**/*,wwwroot/**/*,ClientApp/**/* \
    /d:sonar.cs.opencover.reportsPaths=/coverage/coverage.opencover.xml \
    /d:sonar.coverage.exclusions=**/*Model.cs,MyProject.Test/**/*
# 執行 dotnet test
RUN dotnet test \
    /p:CollectCoverage=true \
    /p:CoverletOutputFormat=opencover \
    /p:CoverletOutput=/coverage/ \
    UnitTest.sln
# 結束 SonarScanner
RUN dotnet sonarscanner end /d:sonar.login=

Docker Image 建置指令：

1	docker build -f build-unit-test.dockerfile .

前一篇文章 Docker 教學 - .NET Core 測試報告 (Coverlet + ReportGenerator) 有基本介紹一下 Coverlet，本篇就不再贅述。

啟動 SonarScanner
- /k
  SonarQube 的 Project Key 是必填欄位。
- /d:sonar.host.url
  是 SonarQube Server 的位置。
- /d:sonar.login
  SonarQube 的 Token，錯誤的話無法成功上傳到 SonarQube Server。
- /d:sonar.exclusions
  忽略程式碼分析的檔案或目錄。可用 , 隔開指定多個 Patterns。
  此例忽略 *.js、*.ts 及 *.css 的檔案，如果要分析 *.js、*.ts 或 *.css，還需要在 Dockerfile 安裝 node.js。
- /d:sonar.cs.opencover.reportsPaths
  指定匯入 OpenCover 格式的測試報告路徑。可用 , 隔開匯入多個檔案。
- /d:sonar.coverage.exclusions
  忽略測試覆蓋率分析報告的檔案或目錄。可用 , 隔開指定多個 Patterns。
結束 SonarScanner
- /d:sonar.login
  SonarQube 的 Token，錯誤的話無法成功上傳到 SonarQube Server。

執行結果

參考

Docker 教學 - .NET Core 測試報告 (Coverlet + ReportGenerator)

2019-08-28T16:59:00.000Z

本篇將介紹如何透過 Coverlet + ReportGenerator 產生 .NET Core 的測試報告；
並用 Dockerfile 產生測試報告的 Docker Image，以網頁的形式查看程式碼覆蓋率。

Coverlet

dotnet cli 提供的 dotnet test 指令，並沒有支援測試覆蓋率，可透過第三方套件分析程式碼覆蓋率。
Coverlet 是一套支援 .NET Core 且跨平台的程式碼覆蓋率分析工具。

可透過 dotnet cli 的 dotnet tool 安裝，指令如下：

1	dotnet tool install --global coverlet.console

除了安裝 dotnet tool 外，測試專案也需要安裝 NuGet 套件 coverlet.msbuild，安裝指令：

1	dotnet add package coverlet.msbuild

安裝完成後，就可透過 dotnet test 指令，附帶參數執行程式碼覆蓋率分析：

dotnet test /p:CollectCoverage=true \
  /p:CoverletOutputFormat=opencover \
  /p:CoverletOutput=./coverage/ \
  UnitTest.sln

CollectCoverage
使否啟用程式碼覆蓋率分析。
(預設為 false)
CoverletOutputFormat
程式碼覆蓋率分析報告的格式。
支援的格式有：json、lcov、opencover、cobertura、teamcity。
(預設為 JSON 格式)
CoverletOutput
分析報告的輸出路徑。
上例會在測試專案目錄下的 coverage 資料夾產生 coverage.opencover.xml 檔案。
(預設為測試專案目錄)

dotnet test 程式碼覆蓋率分析完成會輸出如下畫面：

ReportGenerator

上面步驟透過 Coverlet 產生的 coverage.opencover.xml 檔案並不適合閱讀，所以透過 ReportGenerator 這套工具，把 opencover 格式的測試報告轉換成 HTML，再透過瀏覽器打開，呈現圖形化介面報告。

ReportGenerator 支援多種測試報告格式轉換，官方資料：

輸入格式	輸出格式
OpenCover (NuGet) OpenCover format is also generated by coverlet and altcover dotCover (NuGet, /ReportType=DetailedXML) Visual Studio (vstest.console.exe, CodeCoverage.exe) NCover (tested version 1.5.8, other versions may not work) Cobertura JaCoCo Clover Mono (mprof-report) gcov lcov	HTML, HTMLSummary, HTMLInline, HtmlInline_AzurePipelines, HtmlInline_AzurePipelines_Dark, HTMLChart, MHTML Cobertura SonarQube XML, XMLSummary Latex, LatexSummary TextSummary CsvSummary PngChart Badges Custom reports

安裝方式一樣可透過 dotnet cli 的 dotnet tool 安裝，指令如下：

1	dotnet tool install --global dotnet-reportgenerator-globaltool

安裝完成後，就可透過 reportgenerator 指令，將測試報告格式轉換：

reportgenerator \
  -reports:./coverage/coverage.opencover.xml \
  -reporttypes:Html \
  -targetdir:./coverage

reports
要被轉換的測試報告來源檔案路徑。
reporttypes
轉換輸出的格式。
(預設為 Html)
targetdir
轉換輸出的位置。

轉換完成就會生成一大堆的 HTML 檔案。如下：

用瀏覽器開啟 index.htm 就可以看到圖形化的測試報告進入點。

Dockerfile

build-unit-test.dockerfile

FROM mcr.microsoft.com/dotnet/core/sdk:2.2 AS dotnet-test-env
RUN dotnet tool install --global coverlet.console && \
    dotnet tool install --global dotnet-reportgenerator-globaltool
ENV PATH=$PATH:/root/.dotnet/tools/
WORKDIR /
COPY . .
RUN dotnet test \
    /p:CollectCoverage=true \
    /p:CoverletOutputFormat=opencover \
    /p:CoverletOutput=/coverage/ \
    UnitTest.sln
RUN reportgenerator -reports:/coverage/coverage.opencover.xml -targetdir:/coverage

FROM nginx:alpine
RUN rm /usr/share/nginx/html/index.html
COPY --from=dotnet-test-env /coverage /usr/share/nginx/html

Docker Image 建置指令：

1	docker build -f build-unit-test.dockerfile -t my-project-coverage .

以上 Dockerfile 共分為兩個階段：

第一階段產生名稱為 dotnet-test-env 的暫存 Container
1. 安裝 Coverlet 及 ReportGenerator
2. 把程式碼複製到 Container
3. 執行程式碼覆蓋率分析
4. 將測試報告轉換為 HTML 格式
第二階段把 dotnet-test-env 的 /coverage 目錄內檔案，複製到 nginx 預設目錄內，打包成最終階段的 Docker Image。

建置完成後，就可以用 docker run 把測試報告的 Docker Image 執行起來了。
指令：

1	docker run -p 8080:80 my-project-coverage

用瀏覽器開啟 http://localhost:8080/ 就可以看到圖形化的測試報告了。

參考

ELK 筆記 - 硬體規格評估

2019-08-15T17:20:00.000Z

已經習慣把 Log 存到 Elasticsearch(以下簡稱 ES) 再透過 Kibana 查看日誌，所以每當有新產品要上線前，都會評估 ELK 需要的硬體規格。
依照產品大小不同，儲存 Log 的資料筆數跟空間，都有很大的差異，會直接影響到 CPU、記憶體、硬碟空間等。

近期產品是上到 GCP 跟阿里雲，本篇硬體規格會以雲端服務的 Server 規格做為參考的基準。

情境描述

本範例產品的參考資料：

在線數同時約：6000
交易量每秒約：20筆
Log 每週約：320萬筆 (25~30 GB)

算是一個不大的小系統，用 Kibana 查詢近期一週的 ES Index 用量。如圖：

使用資源

由於經費有限，所以只有使用兩台 ELK 做 HA，用Ｍaster/Slave 架構，沒有做到 Cluster。
兩台 Server 分別裝載著 ELK 三個服務，架構如下：

此範例幾個月前從 GCP 轉移到阿里雲，在這兩個平台使用的 VM 等級如下：

GCP (n1-highmem-8)
- vCPU: 8 core
- RAM: 52 GB
- Disk: 20 GB + 300 GB
阿里雲 (ecs.r5.2xlarge)
- vCPU: 8 core
- RAM: 64 GB
- Disk: 20 GB + 300 GB

Ｍaster/Slave 的機器規格都是一樣的。

產品運行超過半年，CPU 大約都落在 30% 左右，依照上述使用量，在阿里雲其中一台 ELK Server，近期一週的監控資訊：

找不到當時在 GCP 用量的截圖。

硬體規格評估

首先要評估預計要放到 ELK 的 Log 量，資料筆數及資料大小。
再來就是 Log Parsing 的規則，如果 Parsing 很複雜 CPU 就會佔用較高的資源。

ELK 三項服務，分別佔用資源情況：

服務	CPU	RAM	Disk
Elasticsearch	中高	高	極高
Logstash	中	低	低
Kibana	低	低	低

基本上可以完全不用考慮 Kibana 消耗資源。
主要高耗能的就是 Elasticsearch 跟 Logstash。

CPU

CPU 是比較難評估部分，因為 Log Parsing 的複雜度以及查詢 ES 的條件，都會強烈影響 CPU 的使用量。

ES 查詢所消耗的 CPU，阿里雲提供參考：
每個 vCPU core 大約可處理 20~40 GB 查詢資料。
(依據本例使用情境，CPU 消耗偏高一些，但也沒落差太多。)
Logstash 依照上述的情境，Log 每秒也才 500 筆左右，分配 vCPU * 1，其實綽綽有餘了。
建議每處理 1500 筆資料，就分一個 vCPU core。

RAM

ES 使用記憶體有兩個條件限制：
1. 最高只能設定為系統的 50%。例：系統 8 GB，ES 只能設定 4GB。
2. 不能超過 32 GB。
如果條件允許，就直上 64 GB 記憶體，然後把一半分給 ES。
ES 查詢很吃記憶體，尤其是大區間的查詢，根據阿里雲提供的參考：
每 1 GB RAM，大約可處理 10 GB 查詢資料。
Logstash 的記憶體用於緩存消化不完的資料，CPU 不夠力的情況下就會需要比較高的記憶體。
不過還是要依照實際使用量調整，在預估資源分配上，不用考慮太高的比重。
基本上 1 GB 以內都夠用，甚至 128 MB 都夠用。

Disk

ELK 實際存資料的是 ES，所以評估時就不考慮 Logstash 跟 Kibana。
系統碟分配 20 GB 基本上就很足夠了，甚至可以更低。
這邊只單純討論 ES 存資料的空間計算。

估計 ES 硬碟空間要注意的項目：

主要資料
ES 收到的內容及索引。
注意！儲存的資料大小，不等於原始資料的大小。
如果對資料加工不熟悉的話，建議在估計時 * 1.5 倍 當作彈性倍率。

原始資料若透過 Logstash 加工，產生了很多欄位，且保留原始內容，實際存放的大小就會比原始資料大很多，可能會多到一倍。
若加工的欄位建的好，且加工完就拋棄原始內容，實際存放就會比原始資料更小。如圖：

副本資料
主要資料的備援檔，大小與主要資料相等。
若有兩個以上的節點，預設會建立一份副本，可變更副本數量。
如果設定一份以上的副本，就會占用更多空間。
保留空間
預設儲存資料只會使用硬碟空間的 85%，超過 85% 就不會在寫入資料到 ES。

預估硬碟空間公式如下：

主要資料 = 原始資料 * 1.5(彈性倍率)
節點硬碟需求 = 主要資料 * 1.15(保留空間) * (1 + 副本數量) / ES節點數量

假設預估每週產生 10 GB 的 Log，希望可以留 4 週，每個 ES 節點所需的硬碟空間：

一台 ES
10 GB * 4 * 1.5 * 1.15 * (1 + 0) / 1 ≒ 69 GB
兩台 ES 做 Master/Slave 架構
10 GB * 4 * 1.5 * 1.15 * (1 + 1) / 2 ≒ 70 GB
三台 ES 做 Cluster 架構
10 GB * 4 * 1.5 * 1.15 * (1 + 1) / 3 ≒ 46 GB
五台 ES 做 Cluster 架構，建立三分副本
10 GB * 4 * 1.5 * 1.15 * (1 + 3) / 5 ≒ 55 GB

參考

AlibabaCloudDocs - Elasticsearch 规格容量评估

ASP.NET Core 2 筆記 - HTTPS ERR_CONNECTION_CLOSED

2019-08-12T04:13:00.000Z

剛剛遇到近期開發的 ASP.NET Core 站台，在本機 MacOS 環境啟動後，瀏覽器用 HTTPS 打開會顯示以下錯誤：

無法連上這個網站  
localhost 拒絕連線。

ERR_CONNECTION_CLOSED

如圖：

解決方式

瀏覽器因為安全性問題，不讓 ASP.NET Core 站台使用 HTTPS，可以透過以下指令把開發憑證清除，再重建：

1 2	sudo dotnet dev-certs https --clean dotnet dev-certs https

回想一下原因，應該是上週將 MacOS 系統更新後，同時更新一些軟體等造成。(好像有更新 Chrome)

參考

HTTPS on macOS does not work running from the default ASP.NET Core Web App (MVC) template

Docker 教學 - Docker Image 混合公有及私有 Docker Registry

2019-08-05T15:02:00.000Z

本篇介紹如何依照不同的資料類型分層建置 Docker Image；
並把開放性資料及敏感資料的分層，分別推上公有和私有 Docker Registry。

情境描述

最近在一個特殊的網路環境下，因流量限制及安全性考量，產生了這個特別的需求，網路架構如下圖：

開發環境跟生產環境都可以連到外網，但兩邊的網路互不相通，只能透過 Cleanroom 存取兩邊的網路環境。
但上圖紅線部分，Cleanroom 連到生產環境有以下問題：

網路速度慢
連線品質不佳
網路費昂貴依流量計價
不能把原始碼放到生產環境

若直接將 Docker Images 從 Cleanroom 推上生產環境，每次佈署都會產生驚人的費用。
生產環境雖然可以連外網，但因安全性考量不能在外網建立私有 Docker Registry，所以只能在開發環境跟生產環境內部架設私有 Docker Registry。

製作 Docker Image

在建置 Docker Image 時，可利用 Docker Layer 的特性，將非敏感資料及敏感資料分層，把敏感資料的 Layer Size 降至最低，透過 Cleanroom 傳送到生產環境，其餘則直接退送到外部公開的 Docker Registry。

Docker Image 分為以下三個階段，分別建置出三個 Docker Image，再拼裝成可直接被運行的 Docker Image。
此範例主要是以 ASP.NET Core 作為建置範例，但此範例不侷限於 ASP.NET Core 專案。

ASP.NET Core 編譯出來的專案，會依照 namespase 區分出對應的 DLL，例如：

MyProject.Website 專案，會生成 MyProject.Website.dll
MyProject.Common 專案，會生成 MyProject.Common.dll

而外部參考的第三方套件，會有自己所屬名稱的 DLL，利用此特性將內部開發的 DLL 及外部參考的 DLL 分離。

Build Artifacts

首先建立一個專門編譯的 Container，將編譯後的結果依照名稱特性，區分到不同目錄：

檔案 artifacts.dockerfile：

FROM mcr.microsoft.com/dotnet/core/sdk:2.2
WORKDIR /src
COPY ./src .
# 編譯 ASP.NET Core，並將編譯結果輸出到 /publish 目錄
RUN dotnet publish -o /publish --configuration Release
# 把名稱為 MyProject 開頭的檔案，都複製到 /sensitive 目錄
RUN mkdir /sensitive; \
    cp -R /publish/MyProject* /sensitive
# 把 /publish 目錄中 MyProject 開頭的檔案全部移除
RUN rm -rf /publish/MyProject*

建置 Docker Image，並打上一個自訂的 Tag 名稱：

1	docker build -f artifacts.dockerfile -t artifacts:latest .

artifacts.dockerfile 所產出的 Docker Image 包含的原始碼及編譯後的 DLL，只用在以下兩個 Docker Image 建置時使用。
使用完畢應立即刪除，最好不要推上 Docker Registry。

Build Third-Party Reference

製作 ASP.NET Core Runtime 環境的 Docker Image，並以 Artifacts Image 作為檔案來源：

檔案 third-party.dockerfile：

FROM artifacts:latest as artifacts

FROM mcr.microsoft.com/dotnet/core/aspnet:2.2
WORKDIR /app
COPY --from=artifacts /publish .

建置 Third-Party DLL 的 Docker Image，作為基底 Image：

1	docker build -f third-party.dockerfile -t third-party:latest .

third-party.dockerfile 產出的 Docker Image，是基於微軟官方所提供，隨處可得的公開資料內容；
而從 Artifacts 所複製進來的檔案，也都是第三方套件，並沒有什麼敏感性資訊。
由於此 Docker Image 不帶有敏感資訊，所以推上 Docker Hub 也無所謂。

Build Final Image

最後以 third-party.dockerfile 為運行環境的基底，做出最後可被執行的 Docker Image。

檔案 app.dockerfile：

FROM artifacts:latest as artifacts

FROM third-party:latest
COPY --from=artifacts /sensitive .
ENTRYPOINT dotnet MyProject.Website.dll

建置運行環境的 Docker Image：

1	docker build -f app.dockerfile -t my-project:latest .

app.dockerfile 產出的 Docker Image，就是 Artifacts 當初編譯後的結果，只是將資料分在兩個 Dockre Image。

Push to Docker Registry

將以上 Docker Image 準備好後，就可以開始時實作此範例流程了：

# 1. 把 my-project 推上開發環境的 Registry
docker tag my-project:latest dev-private-registry/my-project:latest
docker push dev-private-registry/my-project:latest

# 2. 把 third-party 推上外部的 Registry
docker tag third-party:latest public-registry/third-party:latest
docker push public-registry/third-party:latest

# 3. 在生產環境把第二步的 Image 拉下來
docker pull public-registry/third-party:latest

# 4. 把 third-party 推上生產環境的 Registry
docker tag public-registry/third-party:latest prod-private-registry/third-party:latest
docker push prod-private-registry/third-party:latest

# 5. 從 Cleanroom 拉下開發環境的 my-project
docker pull dev-private-registry/my-project:latest

# 6. 從 Cleanroom 把 my-project 推上生產環境的 Registry
docker tag dev-private-registry/my-project:latest prod-private-registry/my-project:latest
docker push prod-private-registry/my-project:latest

# 7. Server 從生產環境的 Registry 取得可執行的 Docker Image
docker run prod-private-registry/my-project:latest

步驟 6 在推送的時候，會先比對目標 Docker Registry 使否已經有 Image 相依 Layers，如果有就不會傳送。
而 Layers 的比較依據是 sha，所以 Docker Image 名稱或 Tag 改變，也不會受影響。

dev-private-registry、prod-private-registry及public-registry請記得換上實際的 Docker Registry URL。

參考

Docker 官方文件 - Dockerfile reference

CentOS 安裝及設定 ASP.NET Core + Nginx Proxy

2019-07-31T15:17:00.000Z

本篇介紹在 CentOS 環境下，安裝及設定 ASP.NET Core Runtime 和 Nginx Proxy。
並將 ASP.NET Core 註冊成系統服務，便於開機後自動啟動，附上 Shell Script 寫的快速安裝腳本。

環境

CentOS 7 Minimal 版
ASP.NET Core Runtime 2.2 版

安裝腳本

新增一個檔案 setup-aspnet-core.sh 內容如下：

#!/bin/bash

main() {
    sudo yum -y install epel-release
    sudo yum -y update

    install_nginx
    install_dotnet

    sudo firewall-cmd --add-service=http --permanent
    sudo firewall-cmd --add-service=https --permanent
    sudo firewall-cmd --reload
}

install_nginx() {
    echo "###################################"
    echo "########## Install Nginx ##########"
    echo "###################################"
    sudo yum -y install httpd-tools nginx
    sudo setsebool -P httpd_can_network_connect on
    sudo sed -i 's/^SELINUX=.*/SELINUX=disabled/' /etc/selinux/config
    sudo setenforce 0
    sudo systemctl enable nginx
    sudo systemctl restart nginx
}

install_dotnet() {
    echo "###########################################"
    echo "########## Install .NET Core 2.2 ##########"
    echo "###########################################"
    sudo rpm -Uvh https://packages.microsoft.com/config/rhel/7/packages-microsoft-prod.rpm
    sudo yum -y install aspnetcore-runtime-2.2
}

main "$@"

透過以下指令執行安裝腳本，便會自動安裝 ASP.NET Core Runtime 及 Nginx。

1	sudo sh setup-aspnet-core.sh

註冊 ASP.NET Core 服務

在 /etc/systemd/system/<自訂名稱>.service 新增一個服務，把 ASP.NET Core 的啟停都透過系統服務控制。
例 /etc/systemd/system/my-website.service 內容如下：

[Unit]
# Description=<此服務的摘要說明>
Description=MyWebsite

[Service]
# WorkingDirectory=
WorkingDirectory=/usr/share/my-website

# ExecStart=/bin/dotnet 
ExecStart=/bin/dotnet MyWebsite.dll

# 啟動若失敗，就重啟到成功為止
Restart=always
# 重啟的間隔秒數
RestartSec=10

# 設定環境變數，注入給 ASP.NET Core 用
Environment=ASPNETCORE_ENVIRONMENT=Production
Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false

[Install]
WantedBy=multi-user.target

注意！ dotnet CLI 的路徑可能不一樣，有可能如上例在 /bin/dotnet 也有可能在 /usr/bin/dotnet
建議先用指令 which dotnet 查看 dotnet CLI 的路徑。

服務相關指令：

# 開啟，開機自動啟動服務
systemctl enable my-website.service

# 關閉，開機自動啟動服務
systemctl disable my-website.service

# 啟動服務
systemctl start my-website.service

# 重啟服務
systemctl restart my-website.service

# 停止服務
systemctl stop my-website.service

# 查看服務狀態
systemctl status my-website.service

執行啟動指令後，再執行查看服務狀態確認是否執行成功。

設定 Nginx Proxy

新增檔案 /etc/nginx/conf.d/default_proxy_settings，以便其它設定重複使用：

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $http_connection;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Host $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_cache_bypass $http_upgrade;

ASP.NET Core Proxy 設定 /etc/nginx/conf.d/my-website.conf：

upstream portal {
    # localhost:5000 改成 ASP.NET Core 所監聽的 Port
    server localhost:5000;
}

server {
    # 只要是透過這些 Domain 連 HTTP 80 Port，都會轉送封包到 ASP.NET Core
    listen 80;
    # 可透過空白區分，綁定多個 Domain
    server_name demo.johnwu.cc example.johnwu.cc;
    location / {
        proxy_pass http://portal/;
        include /etc/nginx/conf.d/default_proxy_settings;
    }
}

# 用 HTTPS 必須要有 SSL 憑證，如果沒有要綁定 SSL 可以把下面整段移除
server {
    # 只要是透過這些 Domain 連 HTTPS 443 Port，都會轉送封包到 ASP.NET Core
    listen 443 ssl;
    server_name demo.johnwu.cc;
    ssl_certificate /etc/nginx/ssl/demo.johnwu.cc_bundle.crt;
    ssl_certificate_key /etc/nginx/ssl/demo.johnwu.cc.key;

    location / {
        proxy_pass http://portal/;
        include /etc/nginx/conf.d/nginx_proxy_conf;
    }
}

修改完成後，執行以下指令檢查及套用：

# 檢查 Nginx 的設定是否有誤
nginx -t

# 若沒有錯誤，即可套用
nginx -s reload

套用以上設定後，架構如下圖：

參考

Install .NET Core SDK on Linux CentOS / Oracle - x64

Docker 教學 - 打包 ASP.NET Core 前後端專案 Docker Image

2019-07-30T15:14:00.000Z

本篇將介紹如何透過 Dockerfile 製作 ASP.NET Core 的 Docker Image。
並透過 .dockerignore 及 docker 指令參數等小技巧，讓專案目錄整理得比較乾淨。

前置說明

這個範例有使用到前端及後端的專案，目錄結構大致長成這樣：

build/                      # 存放建置 docker image 所需的檔案
doc/                        # 專案相關的文件
scripts/                    # 開發環境所需的腳本
src/                        # dotnet 的專案目錄
    XXXX.Domain/            # 函式庫專案目錄
    XXXX.WebPortal/         # ASP.NET Core 專案目錄
        ClientApp/          # 前端的專案
            node_modules/   # 前端專案的相依目錄
            package.json    # 前端專案的相依設定
        wwwroot/            # 前端專案打包的結果
test/                       # dotnet 的測試專案目錄
    XXXX.IntegrationTest/   # 整合測試專案目錄
    XXXX.UnitTest/          # 單元測試專案目錄
XXXX.sln                    # dotnet 的方案檔

Dockerfile

dotnet core

大部分的 Dockerfile 範例，會把這個檔案放在方案根目錄；
但此檔跟建置相關，放到 build 目錄會比較是適合，同時改一下檔案名稱，比較容易識別。如：

build/build-image.dockerfile 內容如下：

### Build Stage
FROM mcr.microsoft.com/dotnet/core/sdk:2.2 AS dotnet-build-env
ARG project_name
COPY ./src /src
WORKDIR /src
RUN dotnet publish $project_name -o /publish --configuration Release

### Publish Stage
FROM mcr.microsoft.com/dotnet/core/aspnet:2.2
ARG project_name
WORKDIR /app
COPY --from=dotnet-build-env /publish .
ENV project_dll="${project_name}.dll"
ENTRYPOINT dotnet $project_dll

檔案名稱可以自訂，附檔名也沒有任何限制；但可透過修改 IDE 自動偵測附檔名，把 *.dockerfile 都以 Dockerfile 的格式開啟會比較方便。
ASPNET_PROJECT_NAME
名稱從外部帶入有個好處，就是大部分的 dotnet core 專案都適用這個 Dockerfile 建置 Docker Image。

建置指令：

1
2

docker build -f [DOCKERFILE_PATH] -t [IMAGE_NAME]:[TAG] --build-arg project_name=[ASPNET_PROJECT_NAME] .
# 範例： docker build -f build/build-image.dockerfile -t web-portal:develop --build-arg project_name=XXXX.WebPortal .

以上 Dockerfile 共分為兩個階段：

第一階段產生名稱為 dotnet-build-env 的暫存 Container，然後把方案根目錄的 src 複製到 dotnet-build-env，執行 dotnet publish 把建置的結果放到 /publish 目錄。
mcr.microsoft.com/dotnet/core/sdk:2.2 是拿來編譯用的，大小約 1.74 GB。
第二階段把 dotnet-build-env /publish 目錄內的檔案，全部複製到最終階段 Container 的 /app 目錄，並指定 Docker 啟動時要執行的指令。
mcr.microsoft.com/dotnet/core/aspnet:2.2 是執行階段用的，大小約 260 MB。
若要追求最小化 Docker Image，可選用 alpine 版本。

建置流程如下：

npm

此範例除了有 ASP.NET Core 專案，同時也包含了前端專案在裡面，前端專案如果是用 TypeScript 編寫或其它需要 Webpack 打包等動作，都會需要 node.js。
因此，可以透過另一個暫存 Container，負責打包前端專案。

build/build-image.dockerfile 內容如下：

### Build Stage - dotnet
FROM mcr.microsoft.com/dotnet/core/sdk:2.2 AS dotnet-build-env
ARG project_name
COPY ./src /src
WORKDIR /src
RUN dotnet publish $project_name -o /publish --configuration Release

### Build Stage - npm
FROM node:11 AS npm-build-env
ARG project_name
RUN mkdir -p /publish
RUN npm set progress=false;
COPY ./src /src
WORKDIR /src/$project_name
RUN if [ -f "package.json" ]; then \
        npm i; \
        npm run build; \
        if [ -d "wwwroot" ]; then cp -R wwwroot /publish; fi; \
    fi

### Publish Stage
FROM mcr.microsoft.com/dotnet/core/aspnet:2.2
ARG project_name
WORKDIR /app
COPY --from=dotnet-build-env /publish .
COPY --from=npm-build-env /publish .
ENV project_dll="${project_name}.dll"
ENTRYPOINT dotnet $project_dll

npm-build-env 先判斷專案目錄內是否有 package.json 檔案，若存在才會執行 npm build。這樣做的好處是，不管 dotnet core 專案是否有前端專案，都可共用此 Dockerfile 建置 Docker Image。
以此範例來說，src/XXXX.WebPortal/wwwroot 目錄為前端專案打包的結果，ASP.NET Core 執行根路徑的 wwwroot 目錄為靜態檔案的位置。若實作上的目錄名稱不同，需自行更改位置。

以上 Dockerfile 分為三個階段，在中間又插入了 npm run build 的動作，然後把最終結果複製到 Publish Stage。

建置流程如下：

.dockerignore

從 Host 複製 src 目錄到 Container 時，可能會複製到不必要的檔案，如開發階段所產生的目錄： bin、obj 及 node_modules 等。
為了加速複製檔案，我們可以在方案根目錄新增 .dockerignore，告知 COPY 忽略這些目錄或檔案，例：

.git/
.vs/
.vscode/
build/
docs/
scripts/
**/bin/
**/obj/
**/packages/
**/node_modules/
**/publish/
**/coverage/
**/TestResults/

清除 Temp images

Dockerfile 執行建置後，只會把最後一個 Container 賦予名稱當作最終結果，其它的 Stage 並不會消失，若執行 docker images 指令，會發現有一大堆顯示為的 Docker Image。
可透過以下指令快速移除：

# Linux / MacOS
containers=`docker images -f "dangling=true" -q`; if [ -n "$containers" ] ; then docker rmi -f $containers; fi

# Windows
FOR /f "tokens=*" %i IN ('docker images -f "dangling=true" -q') DO docker rmi -f %i

參考

Docker 官方文件 - Dockerfile reference

ASP.NET Core 教學 - Open XML SDK 匯入 Excel

2019-04-17T13:54:00.000Z

之前介紹過 ASP.NET Core 用 Open XML SDK 匯出 Excel 的功能，但沒介紹匯入 Excel。
被網友提問後，馬上補了這篇介紹 ASP.NET Core 利用 Open XML SDK 匯入 Excel 的基本用法。

安裝 NuGet 套件

Open XML SDK 這個套件支援 .NET 操作 Word、Excel、PowerPoint。
打開 NuGet 找到 DocumentFormat.OpenXml 並安裝。

View

<form method="post" enctype="multipart/form-data" action="/api/import">
    <input type="file" name="files" accept="application/vnd.ms-excel,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" />
    <input type="submit" value="送出" />
form>

SpreadsheetDocument

要操作 Excel 檔案，主要是透過 SpreadsheetDocument 物件。
SpreadsheetDocument 可以讀取檔案，也可以直接讀取 Stream。
此範例是從 ASP.NET Core 的 Request 取得 FileStream，進而讀取 Excel 檔案：

using System.Linq;
using System.Threading.Tasks;
using DocumentFormat.OpenXml.Packaging;
using DocumentFormat.OpenXml.Spreadsheet;
using Microsoft.AspNetCore.Mvc;
using MyWebsite.Filters;

namespace MyWebsite.Controllers
{
    [Route("api/[controller]")]
    public class ImportController : Controller
    {
        [HttpPost]
        [DisableFormValueModelBinding]
        public async Task Post()
        {
            await Request.StreamFile(file =>
            {
                using (var document = SpreadsheetDocument.Open(file.FileStream, false))
                {
                    var workbookPart = document.WorkbookPart;
                    var sheet = workbookPart.Workbook.Sheets.GetFirstChild();
                    var worksheet = ((WorksheetPart)workbookPart.GetPartById(sheet.Id)).Worksheet;
                    var sheetData = worksheet.GetFirstChild();

                    foreach (var row in sheetData.ChildElements.Select(x=>x as Row))
                    {
                        // 取得每一行
                        foreach(var cell in row.ChildElements.Select(x => x as Cell))
                        {
                            // 取得每一欄
                            var innerText = cell.CellValue.Text;
                            // Do somethings
                        }
                    }
                }
                return file.FileStream;
            });
            return Ok();
        }
    }
}

DisableFormValueModelBinding 及 Request.StreamFile 擴充方法請參考 [鐵人賽 Day23] ASP.NET Core 2 系列 - 上傳/下載檔案

參考

Open-XML-SDK
Read Excel Files Using Open XML SDK In ASP.NET C#
How to create an Excel file in .NET using OpenXML – Part 1: Basics
歡迎使用 Open XML SDK 2.5 for Office