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

package/knowledge/Furion_Teaching_Manual/19-2-HTTP/351/201/240/347/253/257/350/253/213/346/261/202/351/200/262/351/232/216/346/214/207/345/215/227.md

@@ -0,0 +1,928 @@
+# 19.Ⅱ HTTP 遠端請求 — 進階指南
+
+> **版本說明**：僅適用於 Furion 4.9.6+（HttpAgent），不支援 .NET8 以下版本。
+
+---
+
+## 19.6 IHttpContentProcessor 內容處理器
+
+用於根據原始請求內容和類型建構 `HttpContent` 實例，並設定為 `HttpRequestMessage.Content`。
+
+### 19.6.1 內建內容處理器
+
+| 處理器 | 適用條件 | 產出型別 |
+|--------|---------|----------|
+| `StringContentProcessor` | `application/json`、`application/json-patch+json`、`application/xml`、`text/xml`、`text/html`、`text/plain`、`application/soap+xml`（含 charset） | `StringContent` |
+| `StreamContentProcessor` | `Stream` / `StreamContent` | `StreamContent` |
+| `ByteArrayContentProcessor` | `byte[]` / `ByteArrayContent`（非 FormUrlEncoded / StringContent） | `ByteArrayContent` |
+| `FormUrlEncodedContentProcessor` | `FormUrlEncodedContent` 或 `application/x-www-form-urlencoded` | `FormUrlEncodedContent` |
+| `StringContentForFormUrlEncodedContentProcessor` | 同上 + `useStringContent = true`（派生自上者） | `StringContent` |
+| `ReadOnlyMemoryContentProcessor` | `ReadOnlyMemory<byte>` / `ReadOnlyMemoryContent` | `ReadOnlyMemoryContent` |
+| `MultipartFormDataContentProcessor` | `MultipartFormDataContent` 或 `multipart/form-data` | `MultipartFormDataContent` |
+| `MessagePackContentProcessor` | `application/msgpack` | `ByteArrayContent` |
+
+> `StringContentProcessor` 預設採用 `JsonSerializerOptions.Web` 配置。
+
+自訂 JSON 序列化：
+
+```csharp
+services.AddHttpRemote(builder => {})
+    .ConfigureOptions(options =>
+    {
+        options.JsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
+    });
+```
+
+### 19.6.2 IHttpContentProcessorFactory 工廠
+
+單例服務，按**最後新增**的處理器開始查詢 `CanProcess` 方法。找不到匹配時拋出 `InvalidOperationException`。
+
+```csharp
+public class YourService(IHttpContentProcessorFactory factory)
+{
+    public async Task<string> GetStringAsync()
+    {
+        var msg = new HttpRequestMessage(HttpMethod.Post, "https://furion.net/");
+        msg.Content = factory.Build(new { id = 1, name = "Furion" }, "application/json");
+        using var client = new HttpClient();
+        var res = await client.SendAsync(msg);
+        return await res.Content.ReadAsStringAsync();
+    }
+}
+```
+
+### 19.6.3 自訂內容處理器
+
+```csharp
+public class CustomStringContentProcessor : HttpContentProcessorBase
+{
+    public override bool CanProcess(object? rawContent, string contentType)
+        => contentType == "application/json";
+
+    public override HttpContent? Process(object? rawContent, string contentType, Encoding? encoding)
+    {
+        if (TryProcess(rawContent, contentType, encoding, out var httpContent)) return httpContent;
+        var content = rawContent is string or JsonElement
+            ? rawContent.ToString()
+            : JsonConvert.SerializeObject(rawContent, new JsonSerializerOptions());
+        return new StringContent(content!, encoding,
+            new MediaTypeHeaderValue(contentType) { CharSet = encoding?.BodyName ?? "utf-8" });
+    }
+}
+```
+
+套用方式：
+
+```csharp
+// 單次請求
+HttpRequestBuilder.Post("https://furion.net/")
+    .AddHttpContentProcessors(() => [new CustomStringContentProcessor()])
+    .SetJsonContent(new { id = 1, name = "Furion" });
+
+// 全域設定
+services.AddHttpRemote(b => b.AddHttpContentProcessors(() => [new CustomStringContentProcessor()]));
+```
+
+> `HttpContentProcessorBase` 內建 `ServiceProvider` 屬性，可解析 DI 服務。
+
+### 19.6.4 MessagePack 支援
+
+```bash
+dotnet add package MessagePack
+```
+
+```csharp
+public class MessagePackContentProcessor : HttpContentProcessorBase
+{
+    public override bool CanProcess(object? rawContent, string contentType)
+        => contentType == "application/msgpack";
+
+    public override HttpContent? Process(object? rawContent, string contentType, Encoding? encoding)
+    {
+        if (TryProcess(rawContent, contentType, encoding, out var httpContent)) return httpContent;
+        var content = rawContent as byte[] ?? MessagePackSerializer.Serialize(rawContent);
+        var byteContent = new ByteArrayContent(content);
+        byteContent.Headers.ContentType = new MediaTypeHeaderValue(contentType) { CharSet = encoding?.BodyName };
+        return byteContent;
+    }
+}
+```
+
+模型需加 `[MessagePackObject]` 與 `[MessagePack.Key(n)]` 特性。
+
+> 系統已內建 `MessagePackContentProcessor`（透過反射），安裝套件即自動啟用。對效能有極高要求時可自訂實作。
+
+### 19.6.5 Protobuf 支援
+
+```bash
+dotnet add protobuf-net
+```
+
+實作方式同上，`CanProcess` 匹配 `application/x-protobuf`，使用 `Serializer.Serialize(ms, rawContent)` 轉為 `byte[]`。模型需加 `[ProtoContract]` 與 `[ProtoMember(n)]`。
+
+---
+
+## 19.7 IHttpContentConverter 內容轉換器
+
+用於將 `HttpResponseMessage` 轉換為目標型別。
+
+### 19.7.1 內建內容轉換器
+
+| 轉換器 | 目標型別 | 內部實作 |
+|--------|---------|----------|
+| `StringContentConverter` | `string` | `ReadAsStringAsync` |
+| `StreamContentConverter` | `Stream` | `ReadAsStreamAsync` |
+| `ByteArrayContentConverter` | `byte[]` | `ReadAsByteArrayAsync` |
+| `HttpResponseMessageConverter` | `HttpResponseMessage` | 直接返回 |
+| `VoidContentConverter` | `void` / `VoidContent` | 返回空值 |
+| `IActionResultContentConverter` | `IActionResult` | 轉換為 ActionResult |
+| `ObjectContentConverter` | 其他型別 | `ReadFromJsonAsync` |
+
+### 19.7.2 IHttpContentConverterFactory 工廠
+
+單例服務，按最後新增的轉換器查詢泛型型別匹配。找不到時回退到 `IObjectContentConverterFactory`。
+
+### 19.7.3 IObjectContentConverterFactory
+
+回退工廠，預設返回 `ObjectContentConverter()` 實例，使用 `ReadFromJsonAsync` + `System.Text.Json`。
+
+> 手動轉換建議使用 `IHttpContentConverterFactory`（已內部包含 `IObjectContentConverterFactory`）。
+
+### 19.7.4 自訂物件內容轉換器
+
+需同時提供泛型和非泛型版本：
+
+```csharp
+public class CustomObjectContentConverter : ObjectContentConverter
+{
+    public override async Task<object?> ReadAsync(Type resultType, HttpResponseMessage res, CancellationToken ct = default)
+    {
+        var ctx = HttpRemoteUtility.ResolveJsonSerializationContext(resultType, res, ServiceProvider);
+        var value = await res.Content.ReadFromJsonAsync(ctx.ResultType, ctx.JsonSerializerOptions, ct);
+        return ctx.GetResultValue(value);
+    }
+    // 同步版本 Read() 類似
+}
+
+public class CustomObjectContentConverter<T> : CustomObjectContentConverter, IHttpContentConverter<T>
+{
+    public virtual async Task<T?> ReadAsync(HttpResponseMessage res, CancellationToken ct = default)
+        => (T?)await base.ReadAsync(typeof(T), res, ct);
+}
+```
+
+建立自訂工廠並註冊：
+
+```csharp
+public sealed class CustomObjectContentConverterFactory : IObjectContentConverterFactory
+{
+    public IHttpContentConverter<T> GetConverter<T>(HttpResponseMessage res)
+        => res.IsXmlContent() ? new XmlObjectContentConverter<T>() : new CustomObjectContentConverter<T>();
+    public IHttpContentConverter GetConverter(Type type, HttpResponseMessage res)
+        => res.IsXmlContent() ? new XmlObjectContentConverter() : new CustomObjectContentConverter();
+}
+
+services.AddHttpRemote(b => b.UseObjectContentConverterFactory<CustomObjectContentConverterFactory>());
+```
+
+### 19.7.5 自訂內容轉換器
+
+```csharp
+public class SpanCharContentConverter : HttpContentConverterBase<Span<char>>
+{
+    public override async Task<Span<char>?> ReadAsync(HttpResponseMessage res, CancellationToken ct = default)
+    {
+        var str = await res.Content.ReadAsStringAsync(ct);
+        return str.AsSpan();
+    }
+}
+
+// 全域
+services.AddHttpRemote(b => b.AddHttpContentConverters(() => [new SpanCharContentConverter()]));
+// 單次
+builder.AddHttpContentConverters(() => [new SpanCharContentConverter()]);
+```
+
+---
+
+## 19.8 IHttpRemoteService 服務 ✨
+
+HTTP 遠端請求的核心入口服務，預設以**單例**模式註冊。
+
+```csharp
+services.AddHttpRemote();
+// 若遇到二義性錯誤：
+services.AddHttpRemote(builder => {});
+```
+
+注入方式：
+
+```csharp
+// 建構子注入（.NET8+）
+public class YourService(IHttpRemoteService httpRemoteService) { }
+
+// 方法注入
+public Task<string> GetResource([FromServices] IHttpRemoteService httpRemoteService) { }
+
+// 無 DI 環境
+var httpRemoteService = App.GetRequiredService<IHttpRemoteService>();
+```
+
+### 19.8.1 HttpRemoteBuilder 設定一覽
+
+```csharp
+services.AddHttpRemote(builder =>
+{
+    builder.AddHttpContentProcessors(() => [...]);
+    builder.AddHttpContentConverters(() => [...]);
+    builder.UseObjectContentConverterFactory<CustomFactory>();
+    builder.AddHttpDeclarative<IHttpService>();
+    builder.AddHttpDeclaratives([typeof(IHttpService), typeof(IHttpService2)]);
+    builder.AddHttpDeclarativesFromAssemblies([Assembly.GetEntryAssembly()]);
+    builder.AddHttpDeclarativeExtractors(() => [...]);
+    builder.AddHttpDeclarativeExtractorsFromAssemblies([...]);
+});
+```
+
+### 19.8.2 HttpRemoteOptions 設定選項
+
+```csharp
+services.AddHttpRemote(builder => {})
+    .ConfigureOptions(options =>
+    {
+        options.DefaultContentType = "application/json";
+        options.DefaultFileDownloadDirectory = @"C:\Downloads\";
+        options.ProfilerLogLevel = LogLevel.Warning;
+        options.AllowAutoRedirect = true;                       // 預設 true
+        options.MaximumAutomaticRedirections = 50;              // 預設 50
+        options.FallbackBaseAddress = new Uri("https://localhost:5000");
+        options.JsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
+        options.Configuration = builder.Configuration;          // Furion: App.Configuration
+        options.UrlParameterFormatter = new UrlParameterFormatter();
+        options.FallbackLogger = Console.WriteLine;
+        options.HttpRequestBuilderConfigurer = null;
+    });
+
+// 支援服務解析的重載
+.ConfigureOptions((options, serviceProvider) => { });
+```
+
+### 19.8.3 統一設定 HttpClient
+
+```csharp
+services.ConfigureHttpClientDefaults(b => b.ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler()));
+// 或
+services.AddHttpRemote().ConfigureHttpClientDefaults(b => { });
+```
+
+### 19.8.4 內建方法速查
+
+**核心方法**（以 `HttpRequestBuilder` 為參數）：
+
+| 方法模式 | 回傳型別 |
+|---------|---------|
+| `Send / SendAsync` | `HttpResponseMessage` |
+| `SendAs<T> / SendAsAsync<T>` | `T` |
+| `Send<T> / SendAsync<T>` | `HttpRemoteResult<T>` |
+| `SendAs(resultType, ...) / SendAsAsync(resultType, ...)` | `object` |
+| `SendAsString / SendAsStringAsync` | `string` |
+| `SendAsByteArray / SendAsByteArrayAsync` | `byte[]` |
+| `SendAsStream / SendAsStreamAsync` | `Stream` |
+
+**請求謂詞方法**（GET / POST / PUT / DELETE / HEAD / OPTIONS / TRACE / PATCH）：
+
+每個謂詞提供上述全部回傳模式，簽名為：
+
+```csharp
+httpRemoteService.GetAsync(requestUri, configure, cancellationToken);
+httpRemoteService.GetAsAsync<T>(requestUri, configure, cancellationToken);
+httpRemoteService.GetAsync<T>(requestUri, configure, cancellationToken);        // HttpRemoteResult<T>
+httpRemoteService.GetAsStringAsync(requestUri, configure, cancellationToken);
+httpRemoteService.GetAsByteArrayAsync(requestUri, configure, cancellationToken);
+httpRemoteService.GetAsStreamAsync(requestUri, configure, cancellationToken);
+// 各謂詞均有同步版本和含 completionOption 的重載
+```
+
+**特定功能方法**：`DownloadFile(Async)`、`UploadFile(Async)`、`ServerSentEvents(Async)`、`StressTestHarness(Async)`、`LongPolling(Async)`、`Declarative(Async<T>)`。
+
+### 19.8.5 擴充 IHttpRemoteService
+
+```csharp
+public static class HttpRemoteServiceExtensions
+{
+    public static async Task<Span<char>> SendAsSpanAsync(this IHttpRemoteService svc,
+        HttpRequestBuilder builder, CancellationToken ct = default)
+    {
+        var str = await svc.SendAsStringAsync(builder, ct);
+        return str.AsSpan();
+    }
+}
+```
+
+---
+
+## 19.9 HttpRemoteResult\<TResult\> 回傳值
+
+不含 `As` 關鍵字的泛型方法回傳 `HttpRemoteResult<T>`，封裝了完整的回應資訊。
+
+主要屬性：`ResponseMessage`、`ContentType`、`CharSet`、`StatusCode`、`IsSuccessStatusCode`、`Result`、`RequestDuration`、`Headers`、`ContentHeaders`、`RawSetCookies`、`SetCookies`、`Version`、`HttpClientName`。
+
+```csharp
+// 解構表達式
+var (result, response) = await httpRemoteService.GetAsync<string>("https://furion.net/");
+var (result, response, isSuccess, statusCode) = await httpRemoteService.GetAsync<string>("https://furion.net/");
+
+// ToString() 輸出完整請求/回應標頭
+Console.WriteLine(httpResult.ToString());
+```
+
+---
+
+## 19.10 下載網路資源
+
+### 基本方式
+
+```csharp
+var stream = await httpRemoteService.GetAsStreamAsync("https://furion.net/img/furionlogo.png");
+using var fs = new FileStream(@"C:\file.png", FileMode.Create, FileAccess.Write, FileShare.None, 4096, true);
+await stream.CopyToAsync(fs);
+```
+
+### 框架內建下載
+
+```csharp
+var result = await httpRemoteService.DownloadFileAsync(
+    "https://example.com/file.exe", @"C:\Downloads\",
+    async progress => { progress.UpdateConsoleProgress(); await Task.CompletedTask; },
+    fileExistsBehavior: FileExistsBehavior.Overwrite);
+```
+
+`FileExistsBehavior`：`CreateNew`（預設，已存在則拋例外）、`Overwrite`（覆蓋）、`Skip`（跳過）。
+
+`FileTransferResult` 屬性：`IsSuccess`、`RequestUri`、`FilePath`、`FileSize`、`ElapsedMilliseconds`、`StatusCode`。
+
+`FileTransferProgress` 屬性：`FilePath`、`FileName`、`FileSize`、`Transferred`、`PercentageComplete`、`TransferRate`、`TimeElapsed`、`EstimatedTimeRemaining`。方法：`ToString()`、`ToSummaryString()`、`UpdateConsoleProgress()`。
+
+### 19.10.1 HttpFileDownloadBuilder
+
+```csharp
+HttpRequestBuilder.DownloadFile("https://furion.net/img/logo.png", @"C:\Downloads\")
+    .SetBufferSize(80 * 1024)
+    .SetDestinationPath(@"C:\Downloads\")
+    .SetFileExistsBehavior(FileExistsBehavior.Overwrite)
+    .SetProgressInterval(TimeSpan.FromSeconds(1))
+    .SetOnTransferStarted(() => {})
+    .SetOnProgressChanged(async progress => { })
+    .SetOnTransferCompleted(duration => {})
+    .SetOnTransferFailed(exception => {})
+    .SetOnFileExistAndSkip(() => {})
+    .SetEventHandler<CustomFileTransferEventHandler>()
+    .WithRequest(builder => {})
+    .SetMaxThreads(4);
+
+var result = await httpRemoteService.SendAsync(downloadBuilder, ct);
+```
+
+### 19.10.2 IHttpFileTransferEventHandler
+
+```csharp
+public class CustomFileTransferEventHandler : IHttpFileTransferEventHandler
+{
+    public void OnTransferStarted() {}
+    public Task OnProgressChangedAsync(FileTransferProgress progress) => Task.CompletedTask;
+    public void OnTransferCompleted(long duration) {}
+    public void OnTransferFailed(Exception exception) {}
+}
+
+services.TryAddTransient<CustomFileTransferEventHandler>();
+```
+
+> 事件觸發順序：Builder 回呼 → EventHandler 方法。
+
+---
+
+## 19.11 上傳檔案資源
+
+### Form 表單方式
+
+```csharp
+await httpRemoteService.PostAsync("https://localhost:7044/HttpRemote/AddFile",
+    b => b.SetMultipartContent(m => m.AddFileAsStream(@"C:\file.jpg", "file")));
+
+// 多檔上傳
+await httpRemoteService.PostAsync("https://localhost:7044/HttpRemote/AddFiles",
+    b => b.SetMultipartContent(m => m
+        .AddFileAsStream(@"C:\file1.jpg", "files")
+        .AddFileFromRemote("https://example.com/logo.png", "files")));
+```
+
+### 框架內建上傳（帶進度）
+
+```csharp
+await httpRemoteService.UploadFileAsync("https://localhost:7044/HttpRemote/AddFile",
+    @"C:\file.jpg", "file",
+    async progress => { progress.UpdateConsoleProgress(); await Task.CompletedTask; });
+```
+
+限制檔案類型與大小：
+
+```csharp
+HttpRequestBuilder.UploadFile("https://...", @"C:\file.jpg", "file")
+    .SetAllowedFileExtensions(".jpg;.png")
+    .SetMaxFileSizeInBytes(5 * 1024 * 1024);
+```
+
+### 19.11.1 HttpFileUploadBuilder
+
+```csharp
+HttpRequestBuilder.UploadFile("https://...", @"C:\file.jpg", "file")
+    .SetContentType("image/jpeg")
+    .SetAllowedFileExtensions([".jpg", ".png"])
+    .SetMaxFileSizeInBytes(5 * 1024 * 1024)
+    .SetProgressInterval(TimeSpan.FromSeconds(1))
+    .SetOnTransferStarted(() => {})
+    .SetOnProgressChanged(async progress => { })
+    .SetOnTransferCompleted(duration => {})
+    .SetOnTransferFailed(exception => {})
+    .SetEventHandler<CustomFileTransferEventHandler>()
+    .WithRequest(builder => {});
+```
+
+> `UploadFile` 擴充僅支援**單檔**上傳。使用上傳功能時建議**停用請求分析工具**。
+
+---
+
+## 19.12 壓力與模擬測試
+
+```csharp
+var result = await httpRemoteService.StressTestHarnessAsync("https://furion.net/");
+Console.WriteLine(result.ToString());
+```
+
+`StressTestHarnessResult` 屬性：`TotalRequests`、`TotalTimeInSeconds`、`SuccessfulRequests`、`FailedRequests`、`QueriesPerSecond`、`MinResponseTime`、`MaxResponseTime`、`AverageResponseTime`、`Percentile10/25/50/75/90/99/9999ResponseTime`。
+
+自訂參數：
+
+```csharp
+HttpRequestBuilder.StressTestHarness("https://furion.net/")
+    .SetNumberOfRequests(1000)
+    .SetNumberOfRounds(5)
+    .SetMaxDegreeOfParallelism(500)
+    .DisableCache()
+    .WithRequest(builder => {});
+```
+
+> 壓測自動加入 `X-Stress-Test: Harness` 標頭，且預設停用請求分析工具。
+
+---
+
+## 19.13 長輪詢 Long Polling
+
+```csharp
+await httpRemoteService.LongPollingAsync("https://localhost:7044/HttpRemote/LongPolling",
+    async (res, token) => { Console.WriteLine(await res.Content.ReadAsStringAsync(token)); await Task.CompletedTask; },
+    cancellationToken: ct);
+```
+
+### HttpLongPollingBuilder
+
+```csharp
+HttpRequestBuilder.LongPolling("https://...", async (res, token) => { })
+    .SetRetryInterval(TimeSpan.FromSeconds(2))
+    .SetMaxRetries(500)
+    .SetTimeout(TimeSpan.FromMinutes(5))
+    .SetOnError(async res => {})
+    .SetOnEndOfStream(async res => {})
+    .SetEventHandler<CustomLongPollingEventHandler>()
+    .WithRequest(builder => {});
+```
+
+`IHttpLongPollingEventHandler`：`OnDataReceivedAsync`、`OnErrorAsync`、`OnEndOfStreamAsync`。
+
+> 終止方式：`CancellationToken` 或回應標頭包含 `X-End-Of-Stream`。
+
+---
+
+## 19.14 Server-Sent Events 單向通訊
+
+```csharp
+await httpRemoteService.ServerSentEventsAsync("https://localhost:7044/HttpRemote/Events",
+    async (data, token) => { Console.WriteLine(data.Data.ToString()); await Task.CompletedTask; },
+    cancellationToken: ct);
+```
+
+`ServerSentEventsData` 屬性：`Event`、`Data`、`Id`、`Retry`、`CustomFields`。
+
+### HttpServerSentEventsBuilder
+
+```csharp
+HttpRequestBuilder.ServerSentEvents("https://...", async (data, token) => { })
+    .SetDefaultRetryInterval(2000)
+    .SetMaxRetries(500)
+    .SetOnOpen(() => Console.WriteLine("連線成功"))
+    .SetOnError(ex => Console.WriteLine(ex.Message))
+    .SetEventHandler<CustomServerSentEventsEventHandler>()
+    .WithRequest(builder => {});
+```
+
+> ⚠️ 發送 SSE 請求時應**停用請求分析工具**。框架支援任意請求謂詞配置 SSE。
+
+---
+
+## 19.15 WebSocket 雙工通訊
+
+```csharp
+using var ws = new WebSocketClient("wss://localhost:7044/ws");
+
+ws.Connected += (s, e) => Console.WriteLine("連線成功");
+ws.Closed += (s, e) => Console.WriteLine("連線關閉");
+ws.TextReceived += (s, r) => Console.WriteLine(r.Message);
+ws.BinaryReceived += (s, r) => Console.WriteLine(r.Message);
+
+await ws.ConnectAsync(ct);
+await ws.SendAsync("Hello", cancellationToken: ct);
+await ws.CloseAsync(ct);
+```
+
+`WebSocketClientOptions` 屬性：`ServerUri`、`ReconnectInterval`（預設 2 秒）、`MaxReconnectRetries`（預設 10）、`Timeout`、`ReceiveBufferSize`、`Configure`。
+
+事件：`Connecting`、`Connected`、`Reconnecting`、`Reconnected`、`Closing`、`Closed`、`ReceivingStarted`、`ReceivingStopped`、`TextReceived`、`BinaryReceived`。
+
+---
+
+## 19.16 HttpContext 轉發和代理 ✨
+
+### 前置設定
+
+```csharp
+services.AddHttpContextAccessor();   // Furion 已預設注入
+app.UseEnableBuffering();
+```
+
+### 基本使用
+
+```csharp
+[HttpGet]
+public Task<IActionResult?> ForwardToWebSite()
+    => httpContextAccessor.HttpContext.ForwardAsResultAsync("https://github.com");
+
+[HttpPost]
+public Task<YourModel?> ForwardToForm(int id, [FromForm] YourModel model)
+    => httpContextAccessor.HttpContext.ForwardAsAsync<YourModel>("https://localhost:7044/HttpRemote/AddForm");
+```
+
+### [Forward] 特性
+
+```csharp
+[HttpGet]
+[Forward("https://github.com")]
+public Task<IActionResult?> ForwardToWebSite() => throw new NotImplementedException();
+```
+
+`ForwardAttribute` 屬性：`RequestUri`、`Method`、`HttpClientName`、`CompletionOption`、`WithQueryParameters`、`WithRequestHeaders`、`WithResponseStatusCode`、`WithResponseHeaders`、`WithResponseContentHeaders`、`IgnoreRequestHeaders`、`IgnoreResponseHeaders`、`ResetHostRequestHeader`。
+
+### HttpContextForwardOptions
+
+| 屬性 | 預設值 | 說明 |
+|------|--------|------|
+| `WithQueryParameters` | `true` | 轉發查詢參數 |
+| `WithRequestHeaders` | `true` | 轉發請求標頭 |
+| `WithResponseStatusCode` | `true` | 轉發回應狀態碼 |
+| `WithResponseHeaders` | `true` | 轉發回應標頭 |
+| `WithResponseContentHeaders` | `true` | 轉發回應內容標頭 |
+| `ResetHostRequestHeader` | `true` | 重設 Host 標頭 |
+| `IgnoreRequestHeaders` | — | 忽略的請求標頭 |
+| `IgnoreResponseHeaders` | — | 忽略的回應標頭 |
+| `OnForward` | — | 轉發前自訂操作 |
+
+轉發擴充方法涵蓋：`Forward(Async)`、`ForwardAs<T>(Async)`、`ForwardAsString(Async)`、`ForwardAsByteArray(Async)`、`ForwardAsStream(Async)`、`ForwardAsResult(Async)`。
+
+### 微服務應用
+
+透過 `X-Forward-To` 請求標頭可動態取得轉發位址，配合負載均衡策略實現動態請求分發、API Gateway 等。
+
+### 轉發忽略標頭
+
+請求標頭自動忽略：`X-Forward-To`、`Host`、`Accept`、`Accept-CH/Charset/Encoding/Language/Patch/Post/Ranges`。  
+回應標頭自動忽略：`Content-Type`、`Transfer-Encoding`、`Keep-Alive`、`Upgrade`、`Proxy-Connection`。
+
+---
+
+## 19.17 FTP 客戶端功能展望
+
+> 框架尚未正式整合 FTP 客戶端功能，相關開發已初步完成。未來視需求增長可能納入。
+
+---
+
+## 19.18 CancellationToken 取消 HTTP 請求
+
+```csharp
+// 方式一：Controller Action 參數
+public async Task<string?> GetContent(CancellationToken cancellationToken)
+    => await httpRemoteService.GetAsAsync<string>("https://furion.net/", cancellationToken: cancellationToken);
+
+// 方式二：HttpContext.RequestAborted
+await httpRemoteService.GetAsAsync<string>("https://furion.net/",
+    cancellationToken: httpContextAccessor.HttpContext.RequestAborted);
+
+// 方式三：手動建立 CancellationTokenSource
+using var cts = new CancellationTokenSource();
+cts.CancelAfter(100);
+await httpRemoteService.GetAsAsync<string>("https://furion.net/", cancellationToken: cts.Token);
+```
+
+---
+
+## 19.19 HttpClient 實例設定 ✨
+
+### 19.19.1 常見屬性
+
+```csharp
+services.AddHttpClient(string.Empty, client =>
+{
+    client.BaseAddress = new Uri("http://localhost:5000");
+    client.Timeout = TimeSpan.FromMinutes(10);
+    client.MaxResponseContentBufferSize = 5 * 1024;
+    client.DefaultRequestVersion = HttpVersion.Version10;
+    client.DefaultRequestHeaders.Add("User-Agent", "...");
+    client.DefaultVersionPolicy = HttpVersionPolicy.RequestVersionOrHigher;
+});
+```
+
+### 19.19.2 IHttpClientBuilder
+
+```csharp
+services.AddHttpClient(string.Empty, client => {})
+    .ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler
+    {
+        AllowAutoRedirect = true,
+        UseDefaultCredentials = true,
+        UseCookies = true,
+    });
+```
+
+### 19.19.3 SSL 憑證
+
+```csharp
+// 客戶端憑證
+.ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler
+{
+    ClientCertificates = { X509CertificateLoader.LoadPkcs12FromFile("cert.pfx", "password") }
+});
+
+// 忽略 SSL 驗證
+.ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler
+{
+    ServerCertificateCustomValidationCallback = HttpRemoteUtility.IgnoreSslErrors,
+    SslProtocols = HttpRemoteUtility.AllSslProtocols
+});
+
+// SocketsHttpHandler 方式
+.ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler
+{
+    SslOptions = new SslClientAuthenticationOptions
+    {
+        RemoteCertificateValidationCallback = HttpRemoteUtility.IgnoreSocketSslErrors,
+        EnabledSslProtocols = HttpRemoteUtility.AllSslProtocols
+    }
+});
+
+// 單次請求
+HttpRequestBuilder.Get("https://furion.net/")
+    .SetHttpClientProvider(() => (new HttpClient(new HttpClientHandler
+    {
+        ServerCertificateCustomValidationCallback = HttpRemoteUtility.IgnoreSslErrors,
+        SslProtocols = HttpRemoteUtility.AllSslProtocols
+    }), client => client.Dispose()));
+```
+
+### 19.19.4 Proxy 代理
+
+```csharp
+.ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler
+{
+    Proxy = new WebProxy("http://proxyserver:8080", false)
+    {
+        Credentials = new NetworkCredential("username", "password")
+    },
+    UseProxy = true
+});
+```
+
+### 19.19.5 HTTP/3
+
+```csharp
+services.AddHttpClient(string.Empty, client =>
+{
+    client.DefaultRequestVersion = HttpVersion.Version30;
+    client.DefaultVersionPolicy = HttpVersionPolicy.RequestVersionExact;
+});
+```
+
+### 19.19.6 擴充設定（JSON 序列化）
+
+```csharp
+services.AddHttpClient(string.Empty)
+    .ConfigureOptions(options =>
+    {
+        options.JsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
+    });
+
+// 支援服務解析
+.ConfigureOptions((options, serviceProvider) => { });
+```
+
+### 19.19.7 服務解析設定
+
+```csharp
+services.AddHttpClient(string.Empty, (serviceProvider, client) =>
+{
+    var config = serviceProvider.GetRequiredService<IConfiguration>();
+    client.BaseAddress = new Uri(config["your-base-address"]);
+});
+```
+
+---
+
+## 19.20 DelegatingHandler 請求處理委託（攔截）
+
+可視為 HTTP 請求的「中介軟體」，用於請求前處理、回應後處理、錯誤處理、日誌記錄等。
+
+### 19.20.2 自訂 DelegatingHandler
+
+```csharp
+public class CustomHandler : DelegatingHandler
+{
+    protected override async Task<HttpResponseMessage> SendAsync(
+        HttpRequestMessage request, CancellationToken ct)
+    {
+        request.Headers.Add("Custom-Header", "Value");  // 請求前
+        var response = await base.SendAsync(request, ct);
+        Console.WriteLine($"Status: {response.StatusCode}"); // 回應後
+        return response;
+    }
+}
+
+services.TryAddTransient<CustomHandler>();
+services.AddHttpClient(string.Empty).AddHttpMessageHandler<CustomHandler>();
+```
+
+> 支援多次呼叫 `.AddHttpMessageHandler<T>()` 串接多個處理器，**執行順序與註冊順序一致**。
+
+### 19.20.3 自動重新整理授權 Token
+
+```csharp
+public class AuthorizationDelegatingHandler : DelegatingHandler
+{
+    protected override async Task<HttpResponseMessage> SendAsync(
+        HttpRequestMessage request, CancellationToken ct)
+    {
+        var clonedRequest = await request.CloneAsync(ct);
+        var response = await base.SendAsync(clonedRequest, ct);
+
+        if (response.StatusCode != HttpStatusCode.Unauthorized) return response;
+
+        var newToken = await GetNewTokenAsync();
+        clonedRequest = await clonedRequest.CloneAsync(ct);
+        clonedRequest.Headers.Authorization = new AuthenticationHeaderValue("Bearer", newToken);
+        return await base.SendAsync(clonedRequest, ct);
+    }
+}
+```
+
+---
+
+## 19.21 HttpClientHandler 底層處理器
+
+**呼叫鏈**：`CustomHandler3 → CustomHandler2 → CustomHandler1 → HttpClientHandler → 網路`
+
+- `DelegatingHandler`：可插拔的中介層邏輯
+- `HttpClientHandler`：最終執行網路 I/O 的處理器
+
+核心功能：`AllowAutoRedirect`、`UseCookies` + `CookieContainer`、`Proxy` + `UseProxy`、`ServerCertificateCustomValidationCallback`、`UseDefaultCredentials`、`AutomaticDecompression`。
+
+> **最佳實踐**：業務邏輯用 `DelegatingHandler`；底層 TLS/代理/Cookie 控制才考慮自訂 `HttpClientHandler`。
+
+---
+
+## 19.22 RateLimitedStream 帶速率限制的串流
+
+```csharp
+var stream = await httpRemoteService.GetAsStreamAsync("https://furion.net/", HttpCompletionOption.ResponseHeadersRead);
+var rateLimitedStream = new RateLimitedStream(stream, 1024 * 1024 * 1); // 限制 1MB/s
+```
+
+> 基於**令牌桶演算法**實作，實際速率可能有 ~5% 誤差。適用於 SaaS/PaaS 平台的上傳/下載速率控制。
+
+---
+
+## 19.23 FileTypeMapper 檔案 MIME 類型映射
+
+```csharp
+var mapper = new FileTypeMapper();
+mapper.TryGetContentType("image.jpg", out var mimeType); // "image/jpeg"
+```
+
+內建 389 種副檔名映射。所有檔案上傳方法（`AddFile`、`AddFileAsStream` 等）未指定 `contentType` 時自動解析，找不到則預設 `application/octet-stream`。
+
+---
+
+## 19.24 DigestCredentials 摘要身分認證
+
+```csharp
+var digestCredentials = DigestCredentials.GetDigestCredentials(
+    "https://furion.net/digest", "admin", "a123456789", HttpMethod.Get);
+httpRequestMessage.Headers.Authorization = new AuthenticationHeaderValue("Digest", digestCredentials);
+```
+
+---
+
+## 19.25 請求和回應策略（重試）
+
+```csharp
+// 基本重試
+var str = await Policy<string>.Retry(3)
+    .ExecuteAsync(async () => await httpRemoteService.GetAsStringAsync("https://furion.net/"));
+
+// 進階重試
+var str = await Policy<string>.Retry(3)
+    .Handle<HttpRequestException>()
+    .OnWaitRetry((ctx, delay) => Console.WriteLine($"等待 {delay.TotalSeconds} 秒"))
+    .OnRetrying(ctx => Console.WriteLine($"重試第 {ctx.RetryCount} 次"))
+    .WaitAndRetry(TimeSpan.FromSeconds(1), TimeSpan.FromSeconds(3))
+    .ExecuteAsync(async () => await httpRemoteService.GetAsStringAsync("https://furion.net/",
+        builder => builder.EnsureSuccessStatusCode()));
+```
+
+> 僅在 `ExecuteAsync` 內部拋出例外時觸發重試。建議搭配 `EnsureSuccessStatusCode()`。
+
+---
+
+## 19.26 HTTP 請求日誌（關閉）
+
+```json
+{
+  "Logging": {
+    "LogLevel": {
+      "System.Net.Http.HttpClient": "Warning"
+    }
+  }
+}
+```
+
+```csharp
+services.AddHttpClient(string.Empty).RemoveAllLoggers();
+// 一鍵關閉
+services.ConfigureHttpClientDefaults(b => b.RemoveAllLoggers());
+```
+
+---
+
+## 19.27 應用案例
+
+### 19.27.1 Clay 流變物件
+
+```csharp
+// 設定序列化轉換器
+services.AddHttpRemote(o => {})
+    .ConfigureOptions(o => o.JsonSerializerOptions.AddClayConverters());
+
+// 發送
+dynamic payload = new Clay();
+payload.id = 1;
+payload.name = "furion";
+var content = await httpRemoteService.PostAsStringAsync("https://...",
+    b => b.SetJsonContent(payload));
+dynamic clay = Clay.Parse(content);
+```
+
+自訂 `ClayContentConverter` 與 `DynamicContentConverter` 可直接使用 `Clay` / `dynamic` 作為泛型參數接收：
+
+```csharp
+services.AddHttpRemote(o =>
+    o.AddHttpContentConverters(() => [new ClayContentConverter(), new DynamicContentConverter()]));
+
+dynamic clay = await httpRemoteService.PostAsAsync<Clay>("https://...", b => b.SetJsonContent(payload));
+dynamic clay = await httpRemoteService.PostAsAsync<dynamic>("https://...", b => b.SetJsonContent(payload));
+```
+
+### 19.27.2 Blazor WebAssembly
+
+```csharp
+builder.Services.AddHttpRemote()
+    .ConfigureOptions((options, sp) =>
+    {
+        options.FallbackBaseAddress = new Uri(sp.GetRequiredService<NavigationManager>().BaseUri);
+    });
+```
+
+```razor
+@inject IHttpRemoteService Http
+
+@code {
+    protected override async Task OnInitializedAsync()
+    {
+        forecasts = await Http.GetAsAsync<WeatherForecast[]>("sample-data/weather.json");
+    }
+}
+```