- Razor Pages 在 ASP.NET Core 之上提供了一個以頁面為中心的模型，與 MVC 共享相同的強大路由、中間件和 Razor 視圖引擎。
- 實際專案都圍繞著 Pages 資料夾、wwwroot、appsettings.json 和 Program.cs 展開，在這些檔案中配置服務、中間件和錯誤處理。
- Visual Studio、Rider 和 VS Code 等工具簡化了模型、視圖和 Razor 語法的開發、偵錯、導覽和重構。
- ASP.NET Core 簡化了將 Razor 應用程式發佈到 IIS、Azure、自訂伺服器或 Docker 的流程，從而實現了可擴展且可重複的部署。
如果您之前使用過 Angular 和 ASP.NET Web API，並且開始喜歡在後端使用 C#，那麼 Razor Pages 是一種非常自然的方式，可以將這種樂趣帶到前端，而無需放棄您現有的 JavaScript 知識。 與其一頭栽進完全不同的 UI 堆疊，不如留在熟悉的 ASP.NET Core 領域，使用 Razor 語法進行伺服器端渲染，並在任何合適的地方仍然使用 JavaScript。
ASP.NET Core Razor Pages 是微軟推薦的在 .NET 上建立現代 Web 應用程式的方法，它提供了一個簡潔的基於頁面的模型，該模型建立在強大的 ASP.NET Core 管道之上。 它具有跨平台特性，可與 Visual Studio、Visual Studio Code 和 JetBrains Rider 等工具無縫協作，並能從小型原型擴展到生產級、資料庫支援的應用程式。在本指南中，我們將詳細介紹實際的 Razor Pages 應用程式的結構，Program.cs 如何將所有元件連接起來，靜態檔案和配置的工作原理，以及工具、調試和部署如何發揮作用。
ASP.NET Core Razor Pages 究竟是什麼（以及它與 MVC 的比較）
Razor Pages 是 ASP.NET Core 的一項功能，它允許您圍繞頁面而不是控制器建立 Web 應用程序，從而提供更簡單的思維模型，同時仍使用與 MVC 相同的底層框架。 其底層運行在與控制器和視圖相同的路由、中間件和託管堆疊上，但每個頁面都處理自己的行為，而不是將所有內容集中在控制器類別中。
每個 Razor 頁面通常由一對檔案表示：一個用於標記的 .cshtml 檔案和一個用於頁面 C# 邏輯的 .cshtml.cs 檔案。 .cshtml 檔案包含您的 HTML 與 Razor 語法（例如循環、條件和 HTML 輔助函數）混合在一起，而程式碼隱藏的 .cshtml.cs 檔案包含處理程序方法，例如 OnGet、OnPost、模型屬性以及呈現或處理頁面所需的任何邏輯。
在 Razor Pages 出現之前，ASP.NET 中的主流模式是 MVC，其中控制器會傳回視圖並透過操作方法路由所有請求。 MVC 仍然得到全面支持，並且是一種經過實戰檢驗的模式，具有強大的約定，但在許多情況下，Razor Pages 更容易理解，因為加載和處理頁面的代碼與頁面的標記在物理上是相鄰的，而不是隱藏在單獨的控制器中。
儘管 Razor Pages 將重點從控制器轉移開來，但它仍然使用相同的 Razor 視圖引擎，並且支援 HtmlHelpers 和 TagHelpers 來產生動態 HTML。 TagHelpers 特別方便：它們可以為普通的 HTML 標籤添加屬性，例如 asp-action, asp-controller or asp-route 這樣，您就可以將連結和表單連接到後端端點，而無需編寫大量手動 URL 或內聯 JavaScript。
對於已經了解 JavaScript 並且使用過 SPA 框架的開發人員來說，Razor Pages 提供了一種混合方法：伺服器渲染的 HTML 可以實現快速的首次載入和 SEO，並在需要的地方添加 JavaScript 和前端程式庫。 您無需受限於任何特定的 JS 框架，並且可以將後端和前端放在同一個解決方案中，從而簡化部署和維護。
建立和運行 Razor Pages Web 應用程式
當您使用 Visual Studio、Visual Studio Code 或 Rider 建立一個新的 ASP.NET Core Razor Pages 專案時，範本會連接一個最小但完整的應用程序，包括 Program.cs、Pages 資料夾、設定檔和靜態 Web 根目錄。 開箱即用，您將獲得一個可以立即運行的網站，然後您可以將其發展成更複雜的功能，例如電影目錄或任何其他數據驅動的應用程式。
在 HTTPS 上執行應用程式之前，ASP.NET Core 需要使用作業系統信任的開發證書，並且首次執行專案時，您可能會看到一個對話框，要求您信任該證書。 當出現該對話框時，選擇 可以 表示您同意在您的電腦上使用本機開發憑證進行 HTTPS 流量，這是在不發出瀏覽器警告的情況下正確測試安全端點所必需的。
在 Windows、macOS 或 Linux 系統上，Visual Studio Code 可讓您透過按任意鍵啟動應用程式。 按Ctrl+F5 可以不進行偵錯直接運行，或者如果要附加偵錯器，可以使用“運行和偵錯”面板。 首次運行時，VS Code 可能會提示您選擇偵錯器類型，例如： C#, .NET 5+ 和 .NET Core 或像特定的啟動配置 C#: RazorPagesMovie [https] RazorPagesMovie 具體取決於 .NET 版本和您的工作區配置。
啟動後，您的預設瀏覽器將開啟一個類似以下網址的 URL： https://localhost:<port>其中連接埠是隨機分配的，或在 launchSettings.json 中指定，您正在查看 Razor Pages 應用程式提供的首頁。 在某些模板中，您會看到 http://localhost:5001 或其他連接埠；關鍵是… localhost 這表示這是您自己的機器，而不是外部主機。
測試完成後，您可以從 IDE 中停止正在執行的應用程式：在 Visual Studio Code 中，使用「執行」功能表並選擇「停止偵錯」或按 Enter 鍵。 轉移+F5而在 Mac 版 Visual Studio 中，您可以使用「偵錯」>「停止偵錯」。 這將終止為該會話啟動的 Kestrel Web 伺服器實例，並釋放連接埠以供其他運行使用。
了解專案結構：資料夾和關鍵文件
實際的 Razor Pages 應用程式圍繞著幾個重要的資料夾和設定檔進行組織，您將持續使用這些資料夾和設定檔：Pages、wwwroot、appsettings.json 和 Program.cs（以及在舊版本中，Startup.cs）。 熟悉這些元素的使用方法至關重要，因為幾乎每個教學課程、範例或製作專案都使用相同的約定俗成的規則。
Pages 資料夾是 Razor Pages 專案的核心，其中包含所有 .cshtml 頁面及其 .cshtml.cs 程式碼隱藏文件，以及共用佈局和局部視圖。 每個頁面對（例如 Index.cshtml 和 Index.cshtml.cs）代表應用程式中的一個可調用端點，而以下劃線開頭的特殊文件，例如 _Layout.cshtml定義可在多個頁面中重複使用的內容。
佈局文件，通常名為 _Layout.cshtml定義了網站的邊框，例如頂部導覽列、頁腳和版權聲明，並提供了渲染每個單獨頁面主體的位置。 更改佈局時，會立即影響所有使用該佈局的 Razor 頁面的外觀和風格，因此它是編輯選單、品牌和共享腳本或樣式的首選位置。
wwwroot 資料夾是指定的網站根目錄，靜態資源（包括 CSS、JavaScript、圖片和純 HTML 檔案）就存放在這裡，這些檔案可以直接由 Web 伺服器提供服務。 任何放置在 wwwroot 下的內容都可以透過瀏覽器存取（取決於您的靜態檔案配置），因此它是網站樣式表、用戶端庫和標記中引用的圖像的理想存放位置。
應用程式的配置通常儲存在 appsettings.json （以及特定於環境的變體，如 appsettings.Development.json），其中包含連接字串和功能標誌等設定。 ASP.NET Core 的設定係統會載入這些文件，並將它們與環境變數和其他提供者合併，從而可以輕鬆地將各部分綁定到程式碼中的強型別選項類別。
Program.cs 和 ASP.NET Core 管道
Program.cs 檔案包含 Razor Pages 應用程式的入口點，並定義了在第一個要求到達您的網站之前如何設定 Web 主機、服務和中介軟體管道。 在現代 ASP.NET Core 版本中，Program.cs 使用精簡的「最小託管」模型，其中包含一個頂級語句，該語句會建立一個 WebApplicationBuilder 然後建置並配置 WebApplication 實例。
Program.cs 中的典型模式以…開頭 var builder = WebApplication.CreateBuilder(args); 它會設定一個具有通用預設值的主機，然後調用 builder.Services.AddRazorPages(); 將 Razor Pages 註冊到依賴注入容器中。 配置服務後， var app = builder.Build(); 建立應用程式對象，然後將其與中間件和端點連接起來。
錯誤處理和安全行為很大程度上取決於環境，因此通常會看到類似這樣的環境檢查。 if (!app.Environment.IsDevelopment()) 啟用生產級功能。 在這種情況下，你通常會發現 app.UseExceptionHandler("/Error"); 它會將未處理的錯誤傳送到專門的錯誤頁面，並且 app.UseHsts(); 它會啟動 HTTP 嚴格傳輸安全性 (HSTS)，指示瀏覽器始終對您的網域使用 HTTPS。
然後透過以下的呼叫來組裝中間件管道： app.UseHttpsRedirection();, app.UseStaticFiles(); or app.MapStaticAssets();, app.UseRouting(); 以及可選的 app.UseAuthorization(); 然後是端點映射。 HTTPS 重定向強制將不安全的 HTTP 請求升級為 HTTPS，靜態檔案中間件（或 .NET 9 中更新的靜態資源映射）允許直接從 wwwroot 提供資源，路由決定哪個端點處理每個傳入的 URL。
最後，Razor Pages 透過路由連接起來。 app.MapRazorPages(); 可選擇性地與 .WithStaticAssets(); 在新模板中整合靜態資源最佳化，應用程式使用以下方式啟動 app.Run();. 此時，應用程式正在監聽已配置的端口，Kestrel 伺服器已準備好處理實際請求，無論是在本地開發環境中還是在生產主機（例如 IIS、Azure 應用服務或 Docker）上。
Razor Pages、模型和視圖模型在實際應用中的應用
每個非平凡的 Razor Pages 應用背後都有一組領域模型和視圖模型，它們代表你的數據以及數據的顯示方式，無論你是管理電影目錄、部落格還是業務儀表板。 模型通常與資料庫實體緊密對應，而視圖模型可以針對特定螢幕或使用者流程進行定制，結合多個模型或預先格式化值以便更輕鬆地進行渲染。
常見的開發工作流程是從簡單的 C# 類別開始，這些類別使用欄位和方法簽章作為存根，然後逐步將其演變為具有封裝屬性、驗證特性和邏輯的適當模型。 JetBrains Rider 等工具透過有意操作使這種演變更加平滑，這些操作可以自動將欄位轉換為屬性，為繼承層次結構建立衍生類型，並在您完善物件模型時套用其他重構。
繼承和介面有助於為模型強制執行一致的結構，使它們與真正的業務規則保持一致，並實現多態性，其中某些行為是共享的，但實作方式不同。 例如，你可能有一個基地 ContentItem 衍生型別 Movie, Series 以及 Documentary 各個類別之間雖然存在細微差別，但在整個應用程式中都使用相同的合約。
模型就位後，即可手動或透過鷹架工具建立 Razor 頁面或 MVC 視圖，這些工具會產生用於列出、建立、編輯和刪除實體的頁面。 腳手架大大加快了早期開發速度，並確保路由、模型綁定和驗證正確連接，然後您可以使用自己的標記和樣式對其進行自訂。
.cshtml 檔案中使用的 Razor 語法與強型別模型和檢視模型完美結合，可讓您使用 HtmlHelpers 或 TagHelpers 顯示資料、執行迴圈和條件語句，以及產生連結和表單，而不會損失編譯時安全性。 這種 C# 和標記語言的混合使用，將許多邏輯保留在伺服器端，但仍然在瀏覽器中產生乾淨的 HTML，可以很好地與 CSS 和 JavaScript 配合使用。
在 Rider 中使用 Razor 語法、TagHerpers 和導航
Razor 語法是 HTML 之上的一個輕量級語法層，它會在以下情況下啟動： @ 符號出現後，即可輕鬆地將 C# 表達式、語句或輔助函數呼叫直接嵌入到標記中。 您可以循環遍歷項目列表，根據條件顯示或隱藏元素，或顯示值和格式化日期，而無需編寫單獨的模板語言或到處散佈 JavaScript。
TagHelpers 感覺像是 HTML 的自然擴展，它包含以字母開頭的特殊屬性。 asp- 修改元素的行為或輸出，通常會取代舊的 HtmlHelper 方法，並消除對內聯腳本黏合的需求。 例子包括： asp-action 以及 asp-controller 將錨標籤和表單路由到特定操作，或路由屬性，例如 asp-route-id 在 URL 中清晰地傳遞參數。
在深入 HTML 時，IDE 支援非常重要，Rider 提供了一些有用的功能，例如在編輯器底部顯示麵包屑導航，以顯示您在文件結構中的目前位置。 可以在編輯器部分的「首選項」或「選項」下自訂麵包屑導航，這樣瀏覽帶有嵌套標籤的長 Razor 檔案就輕鬆多了。
在 MVC 專案中，Rider 也理解控制器、操作和視圖之間的關聯約定，因此將滑鼠懸停在操作結果上可以顯示可能的視圖路徑， 按Ctrl +單擊 按住 Cmd 鍵並點選 在 macOS 上）直接跳到對應的 .cshtml 檔案。 快速方式 按Ctrl + B or Cmd-B 提供一種快速瀏覽程式碼庫的方法，無需在解決方案資源管理器中尋找。
除了 Razor 特有的工具之外，Rider 還包含一套廣泛的 HTML、CSS 和 JavaScript 意圖和快速修復功能，可協助您在與 C# 後端相同的 IDE 中編寫乾淨、結構良好的用戶端程式碼。 這種緊密整合在建置仍然依賴伺服器渲染的 Razor 視圖或頁面的複雜互動 UI 時，可以節省大量的上下文切換。
調試 Razor Pages 和 ASP.NET Core 應用程式
偵錯是 Web 開發中的日常活動，運行 Razor Pages 的 ASP.NET Core 應用程式也不例外，因此，IDE 中強大的偵錯支援至關重要。 Visual Studio 和 Rider 都提供了互動式偵錯器，可以附加到 Kestrel 進程，逐步執行 C# 程式碼，檢查變數並在應用程式運行時評估表達式。
Rider 的 Windows 偵錯器支援「編輯並繼續」功能，可讓您在應用程式暫停於斷點時調整程式碼，並在不重新啟動整個偵錯工作階段的情況下套用變更。 在調試過程中能夠修正小錯誤或進行試驗，可以顯著加快故障排除速度，尤其是在啟動時間較長的大型專案中。
當環境設定為開發時，ASP.NET Core 中的預設開發人員異常頁面會自動啟用，以便在發生未處理的異常時提供詳細的堆疊追蹤、請求資訊和診斷資訊。 此視圖在本地偵錯時非常有用，但在生產環境中卻很危險，因為它可能會洩露有關應用程式和環境的內部詳細資訊。
為了保護敏感訊息，生產和測試環境通常會停用開發人員異常頁面，而改用已配置的異常處理程序路由。 /Error，同時在伺服器端記錄真實細節，並顯示使用者友善的錯誤畫面。 此行為由 Program.cs 透過環境檢查和呼叫來控制。 UseExceptionHandler 以及 UseHsts.
當事情真的偏離正軌，教程與你的行為不符時，將你的專案與微軟或其他權威來源提供的已知優秀範例進行比較通常會很有幫助。 許多官方的 Razor Pages 教學都會發布一個完整的範例項目，您可以查看或下載該項目，以便與您自己的程式碼進行比較，並找出缺少的配置、拼字錯誤或檔案位置錯誤。
發布和部署真正的 ASP.NET Core Razor 應用程式
發布 Razor Pages 應用程式時，先前所有的結構和配置都將發揮作用，因為 ASP.NET Core 支援多種部署選項，以適應不同的託管環境和工作流程。 無論您喜歡 Windows 上的 IIS、Docker 中的 Linux 容器，還是 Azure 應用服務等託管平台，發布過程都可以由 MSBuild 驅動並整合到您的 CI/CD 管道中。
Visual Studio 和 Rider 都提供發布設定文件，可以將應用程式打包並使用 Web Deploy (MSDeploy) 將其部署到 IIS，將其複製到本地或網路資料夾，或透過 FTP、FTPS 或 SFTP 將其直接推送到遠端伺服器。 建立發佈設定檔會將您的部署設定進行編碼，以便將來發佈時只需選擇設定檔並點擊按鈕或執行命令即可。
對於雲端場景，Azure 應用程式服務是一個熱門目標，IDE 整合了 Azure 工具，可以直接從專案中建立和發布 Web 應用，其底層同樣依賴 MSBuild 和 MSDeploy。 這種方法可以保持本地環境和雲端環境之間的建置和部署的一致性，並且可以在 Azure DevOps、GitHub Actions 或其他 CI 系統中自動化。
Docker 是 ASP.NET Core 的另一個一流選擇，它允許您將 Razor Pages 應用程式容器化，以便它可以在任何支援容器的環境中可預測地運行。 Rider 和 Visual Studio 可以幫助您產生 Dockerfile 和 docker-compose 配置，從而實現一個工作流程，您可以在容器內開發、調試和部署您的應用程序，無論是在本地還是在 Kubernetes 等編排器中。
無論目標平台如何，發布步驟都會編譯您的 C# 程式碼，打包 Razor 視圖，複製靜態資源，並且根據設置，還可能產生一個獨立的運行時環境，這樣主機就不需要共享的 .NET 安裝。 這種打包方式可以將你的開發專案轉化為可部署的成品，供真實使用者使用。
Razor Pages 將所有這些部分整合在一起——從開發證書和 Program.cs，到 Pages 和 wwwroot，再到調試和發布——提供了一種務實的方法來構建真正的 ASP.NET Core Web 應用程序，這些應用程序可維護、高性能且舒適，適合已經喜歡使用 C# 並且不願在所有情況下都完全依賴單頁框架的開發人員。
