ASP.NET #include 伺服器端包含指令完整解析：靜態檔案重用、穿透式封裝與 User Control 差異比較

語法與基本用法

<!-- #include file="header.htm" -->      <!-- 相對路徑，不得跨目錄 -->
<!-- #include virtual="/Shared/header.htm" --> <!-- 虛擬路徑，站內任意位置 -->

• **處理時機**：在 **任何動態程式碼執行前** 將檔案內容**原文插入** .aspx/.ascx/.master 中。
• **支援檔案**：.htm/.html/.txt/.inc/.asp/.aspx/.ascx/.master 等純文字檔。
• **不支援**：二進位檔 (圖片、DLL)、需編譯的 .cs/.vb。

為何 ASP.NET 少見 #include？User Control 取而代之

MSDN 明確建議：「慣用做法是使用 Web 使用者控制項」。

#include 兩大獨特優勢 (User Control 難以取代)

優勢一：靜態內容零負擔重用 + 快取友善

• 頁尾版權、導覽列、SEO 中繼標籤、Google Analytics 碼等**純靜態 HTML**，用 User Control 會建立控制項樹、觸發 Init/Load/Render，純屬浪費。
• 搭配 **輸出快取** (`<%@ OutputCache Duration="3600" VaryByParam="none" %>`) 放在 .ascx 也可，但 #include 直接內嵌靜態文字，**零物件、零序列化、最快**。
• **部署彈性**：前端團隊產出靜態 HTML 片段，透過 CI/CD 自動佈署至共享資料夾，後端 `#include virtual="/Shared/footer.htm"` 即時生效，無需重新編譯網站。

優勢二：穿透式封裝 — 共享頁面變數與伺服器端標記

因為 `#include` 在 **動態碼執行前** 插入，被包含檔案可直接使用 **包含頁面的變數/屬性/方法**，甚至包含 `<%= %>`、`<% %>` 伺服器端標記：

範例：共用導覽列，動態標示目前頁面

<!-- _NavBar.inc -->
<ul class="nav">
  <li class="<%= CurrentPage == "Home" ? "active" : "" %>"><a href="/>首頁</a></li>
  <li class="<%= CurrentPage == "Product" ? "active" : "" %>"><a href="/Product">產品</a></li>
  <li class="<%= CurrentPage == "About" ? "active" : "" %>"><a href="/About">關於我們</a></li>
</ul>

<!-- Default.aspx -->
<%@ Page Language="C#" %>
<script runat="server">
    protected string CurrentPage = "Home"; // 頁面屬性
</script>
<!-- #include virtual="/Shared/_NavBar.inc" -->

✅ `_NavBar.inc` 直接存取 `CurrentPage`，**無需在 User Control 定義屬性、頁面賦值**。這就是「穿透式封裝」。

⚠️ **限制**：被包含檔若為 .aspx/.ascx，**其動態碼會先於主頁執行**，生命週期順序難控制，**不建議** `#include` 動態頁面。僅用於**靜態檔 (含伺服器端標記)**。

實務決策樹：何時用 #include？何時用 User Control？

1. 內容是否**純靜態** 或 **含簡單 `<%= %>` 運算**？→ 是 → **#include** (效能最佳、部署彈性)。
2. 是否需要**封裝邏輯、事件、狀態、複雜 UI 互動**？→ 是 → **User Control**。
3. 是否需**跨專案/跨團隊共用**、且前端獨立維護 HTML？→ **#include virtual** 指向共享資料夾。
4. 是否需**設計檢視拖曳、屬性視窗設定**？→ **User Control**。

進階：結合 OutputCache 的靜態片段快取策略

<!-- Shared/_Footer.inc -->
<footer>© 2024 MyCompany. <%= DateTime.Now.Year %></footer>

<!-- 頁面底部 -->
<%@ OutputCache Duration="86400" VaryByParam="none" Shared="true" %>
<!-- #include virtual="/Shared/_Footer.inc" -->

頁面級 `OutputCache` + `#include` 靜態片段，**整頁快取** 效果等同片段快取，但更簡單。注意：`Shared="true"` 讓多頁共用同一快取項目。

總結

`#include` 不是過時遺物，而是**靜態片段重用、前後端分離部署、穿透式變數共享**的利器。現代 ASP.NET Web Forms 專案建議：

• **導覽列、頁尾、SEO 標籤、第三方追蹤碼** → `#include virtual="/Shared/xxx.inc"`
• **表單區塊、資料列表、互動元件、需封裝邏輯** → `User Control (.ascx)`
• **大型專案** → 共享資料夾 + CI/CD 自動同步 `.inc` 檔，前端獨立維護，後端零修改部署。