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

package/knowledge/Furion_Teaching_Manual/23-JSON/345/272/217/345/210/227/345/214/226.md

@@ -0,0 +1,340 @@
+# 23. JSON 序列化
+
+---
+
+## 23.1 概述
+
+JSON 是一種輕量級的資料交換格式，在前後端資料互動中廣泛應用。
+
+---
+
+## 23.2 序列化庫
+
+| 庫 | 說明 |
+|---|------|
+| `System.Text.Json` | .NET Core 內建，Furion 框架**預設實作** |
+| `Newtonsoft.Json` | 使用人數最多，需安裝 `Microsoft.AspNetCore.Mvc.NewtonsoftJson`（Furion 4.6.5+ 已內建） |
+
+Furion 抽象出 `IJsonSerializerProvider` 介面，統一不同序列化工具的設定與用法差異。
+
+---
+
+## 23.3 IJsonSerializerProvider 介面
+
+```csharp
+public interface IJsonSerializerProvider
+{
+    string Serialize(object value, object jsonSerializerOptions = default);
+    T Deserialize<T>(string json, object jsonSerializerOptions = default);
+    object Deserialize(string json, Type returnType, object jsonSerializerOptions = default);
+    object GetSerializerOptions();
+}
+```
+
+預設實作：`SystemTextJsonSerializerProvider`（啟動時自動註冊）。
+
+---
+
+## 23.4 基本使用
+
+```csharp
+// 取得實例
+private readonly IJsonSerializerProvider _json;
+public MyService(IJsonSerializerProvider json) => _json = json;
+// 或靜態方式
+var json = JSON.GetJsonSerializer();
+
+// 序列化
+var str = _json.Serialize(new { Id = 1, Name = "Furion" });
+
+// 反序列化
+var obj = _json.Deserialize<MyModel>(jsonString);
+
+// 自訂選項
+var str = _json.Serialize(obj, new JsonSerializerOptions { WriteIndented = true });
+```
+
+> ⚠️ `System.Text.Json` 預設反序列化**大小寫敏感**，需設定 `PropertyNameCaseInsensitive = true`。
+
+---
+
+## 23.5 常見設定速查
+
+以下同時列出 `System.Text.Json`（STJ）和 `Newtonsoft.Json`（NJ）的設定方式。
+
+### 23.5.1 替換為 Newtonsoft.Json
+
+```csharp
+services.AddControllersWithViews().AddNewtonsoftJson();
+```
+
+建立 `NewtonsoftJsonSerializerProvider`（實作 `IJsonSerializerProvider, ISingleton`）：
+
+```csharp
+public class NewtonsoftJsonSerializerProvider : IJsonSerializerProvider, ISingleton
+{
+    public string Serialize(object value, object opts = null)
+        => JsonConvert.SerializeObject(value, (opts ?? GetSerializerOptions()) as JsonSerializerSettings);
+
+    public T Deserialize<T>(string json, object opts = null)
+        => JsonConvert.DeserializeObject<T>(json, (opts ?? GetSerializerOptions()) as JsonSerializerSettings);
+
+    public object Deserialize(string json, Type type, object opts = null)
+        => JsonConvert.DeserializeObject(json, type, (opts ?? GetSerializerOptions()) as JsonSerializerSettings);
+
+    public object GetSerializerOptions()
+        => App.GetOptions<MvcNewtonsoftJsonOptions>()?.SerializerSettings;
+}
+```
+
+### 23.5.2 屬性名原樣輸出（大寫開頭）
+
+```csharp
+// STJ
+options.JsonSerializerOptions.PropertyNamingPolicy = null;
+
+// NJ
+options.SerializerSettings.ContractResolver = new DefaultContractResolver();
+```
+
+### 23.5.3 時間格式化（時間戳轉時間）
+
+```csharp
+// STJ（4.6.5+，4.9.1.31+ 預設值為 yyyy-MM-dd HH:mm:ss）
+options.JsonSerializerOptions.Converters.AddDateTimeTypeConverters("yyyy-MM-dd HH:mm:ss");
+// UTC 自動轉本地：AddDateTimeTypeConverters("yyyy-MM-dd HH:mm:ss", true)
+
+// NJ（4.9.1.3+）
+options.SerializerSettings.Converters.AddDateTimeTypeConverters("yyyy-MM-dd HH:mm:ss");
+```
+
+> 4.9.1.3+ 還支援自動將 13/10 位時間戳轉換為 `DateTime` / `DateTimeOffset` 型別。
+
+### 23.5.4 忽略循環參考
+
+```csharp
+// STJ（.NET 6+）
+options.JsonSerializerOptions.ReferenceHandler = ReferenceHandler.IgnoreCycles;
+
+// NJ
+options.SerializerSettings.ReferenceLoopHandling = ReferenceLoopHandling.Ignore;
+```
+
+### 23.5.5~23.5.7 其他 STJ 設定
+
+```csharp
+options.JsonSerializerOptions.IncludeFields = true;                          // 包含成員欄位
+options.JsonSerializerOptions.AllowTrailingCommas = true;                    // 允許尾隨逗號
+options.JsonSerializerOptions.ReadCommentHandling = JsonCommentHandling.Skip; // 允許註解
+```
+
+### 23.5.8 處理中文亂碼
+
+```csharp
+// STJ
+options.JsonSerializerOptions.Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping;
+
+// NJ：無需設定
+```
+
+### 23.5.9 不區分大小寫
+
+```csharp
+// STJ
+options.JsonSerializerOptions.PropertyNameCaseInsensitive = true;
+
+// NJ：無需設定
+```
+
+### 23.5.10 忽略特定屬性
+
+```csharp
+[System.Text.Json.Serialization.JsonIgnore]  // STJ
+[Newtonsoft.Json.JsonIgnore]                  // NJ
+public string PropertyName { get; set; }
+```
+
+### 23.5.11 動態物件屬性名大寫問題
+
+```csharp
+// NJ
+options.SerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();
+```
+
+### 23.5.12 忽略所有 null 屬性
+
+```csharp
+// STJ
+options.JsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
+
+// NJ
+options.SerializerSettings.NullValueHandling = NullValueHandling.Ignore;
+```
+
+### 23.5.13 忽略所有預設值屬性
+
+```csharp
+// STJ
+options.JsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingDefault;
+
+// NJ
+options.SerializerSettings.DefaultValueHandling = DefaultValueHandling.Ignore;
+```
+
+### 23.5.14 控制屬性序列化順序
+
+```csharp
+[System.Text.Json.Serialization.JsonPropertyOrder(0)]  // STJ
+[Newtonsoft.Json.JsonProperty(Order = 0)]               // NJ
+```
+
+### 23.5.15 重新命名序列化名稱
+
+```csharp
+[System.Text.Json.Serialization.JsonPropertyName("newName")]  // STJ
+[Newtonsoft.Json.JsonProperty("newName")]                       // NJ
+```
+
+### 23.5.16 JSON 字串縮排
+
+```csharp
+// STJ
+options.JsonSerializerOptions.WriteIndented = true;
+
+// NJ
+options.SerializerSettings.Formatting = Formatting.Indented;
+```
+
+### 23.5.17 long 轉 string（防止 JS 精度溢位）
+
+```csharp
+// STJ
+options.JsonSerializerOptions.Converters.AddLongTypeConverters();
+// 4.9.1.23+ 可設定超過 17 位才轉換
+// options.JsonSerializerOptions.Converters.AddLongTypeConverters(overMaxLengthOf17: true);
+
+// NJ
+options.SerializerSettings.Converters.AddLongTypeConverters();
+```
+
+> `Dictionary<,>` 含 `long` 的情況 STJ 不支援，需改用 NJ。
+
+### 23.5.18 String 轉 Number
+
+```csharp
+// STJ
+options.JsonSerializerOptions.NumberHandling = JsonNumberHandling.AllowReadingFromString;
+
+// NJ：無需設定
+```
+
+### 23.5.19 Number / Boolean 轉 String（4.9.7.29+）
+
+```csharp
+// STJ
+options.JsonSerializerOptions.Converters.Add(new StringJsonConverter());
+```
+
+### 23.5.20 DateOnly / TimeOnly 支援（4.7.9+）
+
+```csharp
+// STJ
+options.JsonSerializerOptions.Converters.AddDateOnlyConverters();
+options.JsonSerializerOptions.Converters.AddTimeOnlyConverters();
+
+// NJ
+options.SerializerSettings.Converters.AddDateOnlyConverters();
+options.SerializerSettings.Converters.AddTimeOnlyConverters();
+```
+
+### 23.5.21 Clay 流變物件序列化
+
+```csharp
+// STJ
+options.JsonSerializerOptions.Converters.AddClayConverters();
+
+// NJ
+options.SerializerSettings.Converters.AddClayConverters();
+```
+
+### 23.5.22 DateTimeOffset 反序列化異常（NJ）
+
+```csharp
+// NJ（處理 0001-01-01 00:00:00 報錯）
+options.SerializerSettings.MetadataPropertyHandling = MetadataPropertyHandling.Ignore;
+options.SerializerSettings.DateParseHandling = DateParseHandling.None;
+options.SerializerSettings.Converters.Add(new IsoDateTimeConverter { DateTimeStyles = DateTimeStyles.AssumeUniversal });
+```
+
+### 23.5.23 繼承/衍生類別序列化
+
+```csharp
+// .NET 7 之前 STJ 需手動處理
+var json = JsonSerializer.Serialize<object>(value);
+var json = JsonSerializer.Serialize(value, value.GetType());
+```
+
+### 23.5.24 列舉與字串互轉
+
+```csharp
+// STJ 局部
+[JsonConverter(typeof(JsonStringEnumConverter))]
+public Gender Gender { get; set; }
+
+// STJ 全域
+options.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter());
+
+// NJ 局部
+[JsonConverter(typeof(StringEnumConverter))]
+public Gender Gender { get; set; }
+
+// NJ 全域
+options.SerializerSettings.Converters.Add(new StringEnumConverter());
+```
+
+### 23.5.25 檢查 JSON 有效性
+
+```csharp
+// 原生方式
+try { using var doc = JsonDocument.Parse(jsonString); }
+catch (JsonException) { /* 無效 */ }
+
+// Furion 靜態類（4.9.1.8+）
+bool isValid = JSON.IsValid(jsonString);
+```
+
+### 23.5.26 自訂型別序列化轉換器
+
+```csharp
+// STJ
+public class LongToStringJsonConverter : JsonConverter<long>
+{
+    public override long Read(ref Utf8JsonReader reader, Type type, JsonSerializerOptions options)
+        => reader.GetInt64();
+    public override void Write(Utf8JsonWriter writer, long value, JsonSerializerOptions options)
+        => writer.WriteStringValue(value.ToString());
+}
+
+// NJ
+public class LongToStringJsonConverter : JsonConverter<long>
+{
+    public override long ReadJson(JsonReader reader, Type type, long existingValue, bool hasExisting, JsonSerializer serializer)
+        => JValue.ReadFrom(reader).Value<long>();
+    public override void WriteJson(JsonWriter writer, long value, JsonSerializer serializer)
+        => writer.WriteValue(value.ToString());
+}
+```
+
+> 可空型別（如 `long?`）需建立獨立的轉換器。
+
+---
+
+## 23.6 DataTable / DataSet / Tuple / JArray / JObject / JToken
+
+`System.Text.Json` 不支援這些複雜型別，需替換為 `Newtonsoft.Json`（見 23.5.1）。
+
+---
+
+## 23.7 STJ vs NJ 完整差異對比
+
+請參閱微軟官方文件：[從 Newtonsoft.Json 遷移到 System.Text.Json](https://docs.microsoft.com/zh-tw/dotnet/standard/serialization/system-text-json-migrate-from-newtonsoft-how-to)

package/knowledge/Furion_Teaching_Manual/24-/345/215/263/346/231/202/351/200/232/350/250/212SignalR.md

@@ -0,0 +1,247 @@
+# 24. 即時通訊（SignalR）
+
+---
+
+## 24.1 概述
+
+即時通訊（IM）是指在網路上進行即時傳遞文字、文件、語音與視訊的系統。應用場景包括：聊天工具、網遊、直播、訂單推送、協同辦公等。
+
+Furion 框架整合了微軟 **SignalR** 庫來簡化即時通訊開發。SignalR 已內建於 .NET SDK 中，支援 Web、App、Console、Desktop 等多平台。
+
+---
+
+## 24.4 註冊 SignalR 服務
+
+```csharp
+// .NET 6+
+var builder = WebApplication.CreateBuilder(args).Inject();
+builder.Services.AddSignalR();
+
+var app = builder.Build();
+app.MapHubs();      // 註冊集線器
+app.MapControllers();
+app.Run();
+```
+
+```csharp
+// .NET 5 Startup 模式
+services.AddSignalR();
+
+app.UseEndpoints(endpoints =>
+{
+    endpoints.MapHubs();
+    endpoints.MapControllerRoute(name: "default", pattern: "{controller=Home}/{action=Index}/{id?}");
+});
+```
+
+---
+
+## 24.6 集線器 Hub 定義
+
+### Hub 方式
+
+```csharp
+[MapHub("/hubs/chathub")]
+public class ChatHub : Hub
+{
+    public Task SendMessage(string user, string message)
+        => Clients.All.SendAsync("ReceiveMessage", user, message);
+}
+```
+
+### Hub\<T\> 強型別方式
+
+```csharp
+public interface IChatClient
+{
+    Task ReceiveMessage(string user, string message);
+}
+
+[MapHub("/hubs/chathub")]
+public class StronglyTypedChatHub : Hub<IChatClient>
+{
+    public async Task SendMessage(string user, string message)
+        => await Clients.All.ReceiveMessage(user, message);
+}
+```
+
+> 使用 `Hub<IChatClient>` 可獲得編譯期檢查，避免魔法字串。
+
+### [MapHub] 設定連線位址
+
+```csharp
+[MapHub("/hubs/chathub")]
+public class ChatHub : Hub { }
+```
+
+### Hub 進階設定
+
+```csharp
+[MapHub("/hubs/chathub")]
+public class ChatHub : Hub
+{
+    public static void HttpConnectionDispatcherOptionsSettings(HttpConnectionDispatcherOptions options) { }
+    public static void HubEndpointConventionBuilderSettings(HubEndpointConventionBuilder builder) { }
+}
+```
+
+---
+
+## 24.7 取得 Hub 實例
+
+```csharp
+// 建構子注入（單例，可在任何地方使用）
+public HomeController(IHubContext<NotificationHub> hubContext) { }
+
+// 強型別
+public ChatController(IHubContext<ChatHub, IChatClient> chatHubContext) { }
+
+// HttpContext 解析
+var hubContext = context.RequestServices.GetRequiredService<IHubContext<ChatHub>>();
+
+// IHost 中解析
+var hubContext = host.Services.GetService(typeof(IHubContext<ChatHub>));
+
+// 泛型轉換（反射場景）
+await CommonHubContextMethod((IHubContext)myHubContext);
+```
+
+---
+
+## 24.8 服務端與客戶端雙工通訊
+
+| 方法 | 說明 |
+|------|------|
+| `Clients.All.方法(參數)` | 觸發所有客戶端 |
+| `Clients.Caller.方法(參數)` | 觸發呼叫者客戶端 |
+| `Clients.Others.方法(參數)` | 觸發呼叫者以外的客戶端 |
+| `Clients.User("userId").方法(參數)` | 觸發特定使用者 |
+| `Clients.Users("u1","u2").方法(參數)` | 觸發多個使用者 |
+| `Clients.Group("group").方法(參數)` | 觸發分組內客戶端 |
+| `Clients.Groups("g1","g2").方法(參數)` | 觸發多個分組 |
+| `Clients.GroupExcept("group").方法(參數)` | 觸發分組外的客戶端 |
+
+---
+
+## 24.9 自訂使用者唯一標識
+
+```csharp
+public class YourUserIdProvider : IUserIdProvider
+{
+    public virtual string GetUserId(HubConnectionContext connection)
+    {
+        // 透過 connection.User 取得 JWT 授權的使用者
+        return connection.User?.FindFirst(ClaimTypes.NameIdentifier)?.Value;
+    }
+}
+
+// 註冊
+builder.Services.AddSingleton<IUserIdProvider, YourUserIdProvider>();
+
+// 使用
+Clients.User(userId).方法(參數);
+```
+
+---
+
+## 24.11 各客戶端連線 API
+
+### 24.11.1 JavaScript 客戶端
+
+```bash
+npm install @microsoft/signalr
+```
+
+```javascript
+const connection = new signalR.HubConnectionBuilder()
+    .withUrl("/chathub")
+    .configureLogging(signalR.LogLevel.Information)
+    .build();
+
+async function start() {
+    try {
+        await connection.start();
+        console.log("SignalR Connected.");
+    } catch (err) {
+        console.log(err);
+        setTimeout(start, 5000);
+    }
+}
+
+connection.onclose(async () => await start());
+start();
+```
+
+或透過 CDN 引入：
+
+```html
+<script src="https://cdnjs.cloudflare.com/ajax/libs/microsoft-signalr/6.0.1/signalr.js"></script>
+```
+
+### 24.11.2 TypeScript 客戶端（Vue 3.2+）
+
+```bash
+npm i @microsoft/signalr @types/node
+```
+
+```typescript
+import { HubConnectionBuilder } from "@microsoft/signalr";
+import { ref } from "vue";
+
+const messages = ref("");
+
+const connection = new HubConnectionBuilder()
+    .withUrl("https://localhost:7260/chatHub")
+    .build();
+
+connection.start().then(() => connection.send("SendMessage", "Hello"));
+
+connection.on("ReciveMessage", (msg: string) => {
+    console.log("msg", msg);
+});
+
+const sendMsg = async () => {
+    await connection.send("SendMessage", messages.value);
+};
+```
+
+### 24.11.3 .NET 客戶端
+
+```bash
+Install-Package Microsoft.AspNetCore.SignalR.Client
+```
+
+```csharp
+var connection = new HubConnectionBuilder()
+    .WithUrl("http://localhost:53353/ChatHub")
+    .Build();
+
+connection.Closed += async (error) =>
+{
+    await Task.Delay(new Random().Next(0, 5) * 1000);
+    await connection.StartAsync();
+};
+
+connection.On<string, string>("ReceiveMessage", (user, message) =>
+{
+    Dispatcher.Invoke(() => messagesList.Items.Add($"{user}: {message}"));
+});
+
+await connection.StartAsync();
+await connection.InvokeAsync("SendMessage", user, message);
+```
+
+### 24.11.4 Java 客戶端
+
+```groovy
+// Gradle
+implementation 'com.microsoft.signalr:signalr:7.0.0'
+```
+
+```java
+HubConnection hubConnection = HubConnectionBuilder.create(url).build();
+hubConnection.send("Send", input);
+hubConnection.on("Send", (message) -> {
+    System.out.println("New Message: " + message);
+}, String.class);
+```