ASP.NET Web Pages - 資料夾架構與路徑處理完整指南：邏輯結構、虛擬/實體路徑、三大路徑工具實戰

掌握 Web Pages 專案的資料夾組織原則、路徑解析機制與三大核心工具 (~ 運算子、Server.MapPath、Href)，解決跨環境部署路徑問題。

標準邏輯資料夾結構

實體路徑 vs 虛擬路徑 vs URL

關鍵對應：

URL:           https://example.com/html/html-tutorial.html
Server:        example.com
Virtual Path:  /html/html-tutorial.html
Physical Path: C:\WebSites\example\html\html-tutorial.html

三大路徑處理工具深度解析

1. ~ (Tilde) 運算子：虛擬路徑錨點

@{
 // 程式碼中使用 ~ 參考應用程式根目錄
 var imagesFolder = "~/Images";
 var styleSheet = "~/Styles/site.css";
 var dataFile = "~/App_Data/config.json";
}

優勢： 應用程式移至子目錄 (如 /MyApp) 時，~ 自動解析為正確根路徑，**程式碼零修改**。

2. Server.MapPath()：虛擬路徑轉實體路徑

@{
 var virtualPath = "~/App_Data/products.csv";
 var physicalPath = Server.MapPath(virtualPath);
// 結果: C:\WebSites\MyApp\App_Data\products.csv

 // 僅實體路徑可用於 File IO 操作
 var lines = File.ReadAllLines(physicalPath);
}

使用時機： File.Read/Write、StreamReader/Writer、XmlDocument.Load、XDocument.Load 等檔案系統 API。

3. Href()：虛擬路徑轉瀏覽器 URL

@{
 var styleSheet = "~/Styles/site.css";
 var imageUrl = "~/Images/logo.png";
}
<!-- 錯誤：瀏覽器不認識 ~ -->
<link href="~/Styles/site.css" rel="stylesheet" />

<!-- 正確：Href() 轉換 -->
<link href="@Href(styleSheet)" rel="stylesheet" />
<!-- 輸出: /Styles/site.css (或 /MyApp/Styles/site.css 子應用程式) -->

<img src="@Href(imageUrl)" alt="Logo" />

使用場景： HTML 標籤屬性：href (a/link)、src (img/script/iframe/video/audio)、action (form)、data-* 自訂屬性。

路徑處理最佳實務對照表

子應用程式 / 虛擬目錄部署考量

若網站部署為 IIS 子應用程式 (如 https://example.com/MyApp/)：

• ~ 解析為 /MyApp/
• Href("~/Images/logo.png") 產生 /MyApp/Images/logo.png
• Server.MapPath("~/App_Data/db.sdf") 正確對應實體路徑
• Request.ApplicationPath 回傳 /MyApp

**所有路徑工具自動處理子應用程式路徑前綴**，這是使用虛擬路徑而非硬編碼絕對路徑的核心優勢。

進階：路徑驗證與安全性

@functions {
 public static string ResolveSafePath(string virtualPath, string allowedRoot = "~/") {
 var fullVirtual = VirtualPathUtility.Combine(VirtualPathUtility.ToAbsolute(allowedRoot), virtualPath);
 var physical = Server.MapPath(fullVirtual);
 var allowedPhysical = Server.MapPath(allowedRoot);
 
 if (!physical.StartsWith(allowedPhysical, StringComparison.OrdinalIgnoreCase)) {
 throw new SecurityException("Path traversal attempt detected");
 }
 return physical;
 }
}

防止使用者輸入 ../../../windows/system32 等路徑遍歷攻擊。