@elf-express/admin-net-mcp 1.0.0 → 1.1.0

package/knowledge/Furion_Teaching_Manual/05-2-HttpContext.md

@@ -0,0 +1,217 @@
+# 5.2 HttpContext
+
+## 📝 模組更新日誌
+
+### 新特性
+
+- **新增** HttpContext 取得客戶端 IPv4 位址的 `GetRemoteIpAddressToIPv4` 方法 `xff` 參數 `4.9.4.3` ⏱️2024.07.01 `c280dfd`
+
+### 問題修復
+
+- **修復** 透過 HttpContext 擴充方法 `GetRemoteIpAddressToIPv4(true)` 取得客戶端 IP 位址出現 null 問題 `4.9.8.6` ⏱️2026.01.26 `8ff27e5` `@boaro` `!934`
+- **修復** 透過 HttpContext 擴充方法 `GetRemoteIpAddressToIPv4(true)` 取得客戶端 IP 位址出現多個 IP 問題 `4.9.7.246` ⏱️2026.01.14 `#IDJO6T`
+- **修復** `HttpRequest.GetRequestUrlAddress` 擴充取得請求位址遺失埠號問題 `4.9.4.5` ⏱️2024.07.11 `6df5dbd`
+- **修復** 啟用請求 Body 重複讀取且在授權之前讀取導致非 GET/HEAD/OPTION 請求異常 `4.8.7.15` ⏱️2023.03.19 `#I6NX9E`
+
+---
+
+## 5.2.1 關於 HttpContext
+
+在 ASP.NET 的時代，我們通常透過 `HttpContext` 全域靜態類別取得請求上下文，但在 ASP.NET Core 中，`HttpContext` 是一個非靜態的抽象類別，無法手動建立，也無法透過靜態方式取得。
+
+雖然在 ASP.NET Core 中無法直接取得 `HttpContext` 物件，但微軟提供了注入 `IHttpContextAccessor` 的方式來取得。
+
+---
+
+## 5.2.2 取得 HttpContext
+
+ASP.NET Core 和 Furion 提供了多種存取 `HttpContext` 的方式。
+
+### 5.2.2.1 在 ControllerBase 衍生類別中
+
+在 `ControllerBase` 衍生類別中，可以直接透過 `HttpContext` 屬性取得：
+
+```csharp
+public class HomeController : Controller
+{
+    public IActionResult Index()
+    {
+        // HttpContext 是 Controller/ControllerBase 物件的屬性
+        var httpContext = HttpContext;
+        return View();
+    }
+}
+```
+
+### 5.2.2.2 注入 IHttpContextAccessor
+
+在 Furion 框架中，預設已經註冊了 `IHttpContextAccessor` 服務，因此可以透過建構函式注入該介面：
+
+```csharp
+public class AppService
+{
+    public AppService(IHttpContextAccessor httpContextAccessor)
+    {
+        var httpContext = httpContextAccessor.HttpContext;
+    }
+}
+```
+
+### 5.2.2.3 透過 App.HttpContext
+
+`App` 靜態類別也提供了 `App.HttpContext` 來取得 `HttpContext` 物件：
+
+```csharp
+var request = App.HttpContext.Request;
+```
+
+> **非 Web 中存取**：在 Web 完整的生命週期內，`App.HttpContext` 都是有效的，但在非 Web 中會回傳 `null`，應避免在多執行緒、事件匯流排、定時任務等中使用。
+
+---
+
+## 5.2.3 HttpContext 擴充方法
+
+Furion 框架基於 `HttpContext` 提供了一些常用的擴充方法。
+
+### 5.2.3.1 取得當前請求的特性 Attribute
+
+下列程式碼通常用於授權 Handler 中：
+
+```csharp
+var attribute = httpContext.GetMetadata<SomeAttribute>();
+```
+
+**在 Middleware 中介軟體中取得特性的方式：**
+
+```csharp
+var endpointFeature = httpContext.Features.Get<IEndpointFeature>();
+var attribute = endpointFeature?.Endpoint?.Metadata?.GetMetadata<SomeAttribute>();
+```
+
+### 5.2.3.2 設定 Swagger 自動授權
+
+Swagger 預設不能記住授權資訊，一旦重新整理瀏覽器就會自動清空。Furion 提供了該擴充，即使重新整理瀏覽器也能保持授權狀態：
+
+```csharp
+// 檢查使用者登入和產生 token 的程式碼...
+
+// 呼叫該擴充，即可實現 Swagger 重新整理也能記住登入
+httpContext.SigninToSwagger("你的token");
+```
+
+### 5.2.3.3 退出 Swagger 授權
+
+透過後端程式碼強制讓 Swagger 授權失效，只針對下一次請求有效：
+
+```csharp
+httpContext.SignoutToSwagger();
+```
+
+### 5.2.3.4 取得本地 IP 位址
+
+```csharp
+// IPv4
+var ipv4 = httpContext.GetLocalIpAddressToIPv4();
+
+// IPv6
+var ipv6 = httpContext.GetLocalIpAddressToIPv6();
+```
+
+### 5.2.3.5 取得客戶端 IP 位址
+
+```csharp
+// IPv4
+var ipv4 = httpContext.GetRemoteIpAddressToIPv4();
+// Furion 4.9.4.3+ 版本支援設定 xff: true，優先取得請求標頭 X-Forwarded-For 轉發的 IP 位址
+
+// IPv6
+var ipv6 = httpContext.GetRemoteIpAddressToIPv6();
+```
+
+> **取得不到真實 IP 的處理方式**
+>
+> 使用了 Nginx 反向代理後可能會取得不到客戶端真實的 IP 位址，這時需要在 `Startup.cs` 中加入 IP 位址轉發設定：
+
+```csharp
+public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
+{
+    app.UseForwardedHeaders(new ForwardedHeadersOptions
+    {
+        ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto
+    });
+
+    // 其他程式碼...
+}
+```
+
+如果加入以上設定後取得的仍然是 Nginx 代理伺服器的位址，可以嘗試使用以下設定：
+
+```csharp
+// 註冊服務
+services.Configure<ForwardedHeadersOptions>(options =>
+{
+    options.ForwardedHeaders = ForwardedHeaders.All;
+    options.KnownNetworks.Clear();
+    options.KnownProxies.Clear();
+});
+
+// 中介軟體（確保第一個註冊）
+app.UseForwardedHeaders();  // 無需參數
+```
+
+### 5.2.3.6 設定回應標頭 Token
+
+```csharp
+httpContext.SetTokensOfResponseHeaders("token", "重新整理token");
+```
+
+---
+
+## 5.2.4 讀取 Body 內容（重複讀取）
+
+> **版本說明**：僅限 Furion 4.7.9+ 版本使用。
+
+預設情況下，ASP.NET Core 不支援重複讀取 Body 內容，Furion 框架提供了擴充方法，需要按照以下步驟操作：
+
+### 步驟一：啟用 Body 重複讀取功能
+
+**.NET5 版本：**
+
+```csharp
+public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
+{
+    // ...
+    app.EnableBuffering();
+    app.UseRouting();
+    // ....
+}
+```
+
+**.NET6+ 版本：**
+
+```csharp
+var builder = WebApplication.CreateBuilder(args).Inject();
+// ...
+var app = builder.Build();
+// ...
+app.UseInject();
+
+app.EnableBuffering();
+app.MapControllers();
+
+app.Run();
+```
+
+> ⚠️ `app.EnableBuffering()` 必須在 `app.UseRouting()` 或 `app.MapControllers()` 之前註冊。
+
+### 步驟二：使用擴充方法讀取
+
+```csharp
+// HttpContext 擴充
+var body = await httpContext.ReadBodyContentAsync();
+
+// HttpRequest 擴充
+var body = await httpContext.Request.ReadBodyContentAsync();
+```
+
+> **特別注意**：如果使用了 `AddJsonOptions` 或 `AddNewtonsoftJson` 序列化服務，請確保它們在 `.AddInjectXXX` 之前註冊。