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

package/knowledge/Furion_Teaching_Manual/12-furion-dependency-injection.md

@@ -0,0 +1,408 @@
+# Furion 依賴注入 / 控制反轉（DI / IoC）筆記
+
+---
+
+## 1. 核心概念
+
+| 概念 | 簡稱 | 說明 |
+|------|------|------|
+| 依賴注入 | DI | 不在程式碼中手動 `new`，由外部容器自動注入所需物件 |
+| 控制反轉 | IoC | 將建立物件實例的控制權，從程式碼交給 IoC 容器管理 |
+
+**優點**：解耦、易擴展、易單元測試
+**缺點**：採用反射實現，有一定效能損耗
+
+---
+
+## 2. 三種注入方式
+
+### 2.1 建構子注入（推薦）
+
+```csharp
+public class FurionService
+{
+    private readonly IRepository _repository;
+
+    public FurionService(IRepository repository)
+    {
+        _repository = repository;
+    }
+}
+```
+
+✅ 依賴關係清晰，物件初始化後狀態正確
+❌ 參數可能過多；有些類（如 MVC Controller）不適合
+
+---
+
+### 2.2 屬性注入
+
+```csharp
+public class FurionService
+{
+    [FromServices]  // .NET 8+ 也支援 [FromKeyedServices]
+    public IRepository Repository { get; set; }
+}
+```
+
+✅ 靈活，可隨時替換依賴
+❌ 僅限 Controller / 動態 WebAPI；狀態不一致風險
+
+---
+
+### 2.3 方法參數注入
+
+```csharp
+public class FurionService
+{
+    public Person GetById([FromServices] IRepository repository, int id)
+    {
+        return repository.Find(id);
+    }
+}
+```
+
+✅ 靈活
+❌ 僅限 Controller / 動態 WebAPI；新增依賴會破壞方法簽章
+
+---
+
+## 3. 生命週期
+
+| 介面 | 生命週期 | 說明 |
+|------|----------|------|
+| `ITransient` | 暫時（Transient） | 每次請求都建立新實例，適合輕量無狀態服務 |
+| `IScoped` | 範圍（Scoped） | 每個 HTTP 請求建立一次，請求結束後釋放 |
+| `ISingleton` | 單例（Singleton） | 首次請求後全程共用同一實例 |
+
+> ⚠️ 以上介面只能由**實例類**實現，靜態類、抽象類、介面不可實現。
+
+---
+
+## 4. 常見用法
+
+### 4.1 基本用法（介面 + 實作）
+
+```csharp
+// Service 層
+public interface IBusinessService { Person Get(int id); }
+
+public class BusinessService : IBusinessService, ITransient
+{
+    private readonly IRepository<Person> _personRepository;
+
+    public BusinessService(IRepository<Person> personRepository)
+    {
+        _personRepository = personRepository;
+    }
+
+    public Person Get(int id) => _personRepository.Find(id);
+}
+
+// Controller 層
+public class PersonController : ControllerBase
+{
+    private readonly IBusinessService _businessService;
+
+    public PersonController(IBusinessService businessService)
+    {
+        _businessService = businessService;
+    }
+}
+```
+
+---
+
+### 4.2 泛型注入
+
+```csharp
+public class BusinessService<T> : IBusinessService<T>, ITransient { ... }
+
+// 注入
+public PersonController(IBusinessService<int> businessService) { ... }
+```
+
+---
+
+### 4.3 一個介面多個實作
+
+**推薦：`INamedServiceProvider`（Furion 3.8.6+）**
+
+```csharp
+public class BusinessService : IBusinessService, ITransient { ... }
+public class OtherBusinessService : IBusinessService, ITransient { ... }
+
+// 注入並解析
+public class MyApi : IDynamicApiController
+{
+    private readonly INamedServiceProvider<IBusinessService> _provider;
+
+    public MyApi(INamedServiceProvider<IBusinessService> provider)
+    {
+        _provider = provider;
+    }
+
+    public string GetName()
+    {
+        // 方法一：透過反射（有效能損耗）
+        var s1 = _provider.GetService(nameof(BusinessService));
+
+        // 方法二：指定生命週期（無反射，推薦）
+        var s2 = _provider.GetService<ITransient>(nameof(OtherBusinessService));
+
+        return s1.GetName() + s2.GetName();
+    }
+}
+```
+
+**自訂解析名稱：`[Injection(Named = "...")]`**
+
+```csharp
+[Injection(Named = "BusName1")]
+public class BusinessService : IBusinessService, ITransient { ... }
+
+[Injection(Named = "BusName2")]
+public class OtherBusinessService : IBusinessService, ITransient { ... }
+```
+
+---
+
+### 4.4 無介面注入（直接注入實作類）
+
+```csharp
+public class SelfService : ITransient
+{
+    // ...
+}
+
+// Controller 直接注入實作類
+public ValueController(SelfService selfService) { ... }
+```
+
+---
+
+## 5. `[Injection]` 特性配置
+
+| 屬性 | 類型 | 說明 |
+|------|------|------|
+| `Action` | `InjectionActions` | `Add`（預設，允許多實作）/ `TryAdd`（已存在則跳過） |
+| `Pattern` | `InjectionPatterns` | `Self` / `FirstInterface` / `SelfWithFirstInterface` / `ImplementedInterfaces` / `All`（預設） |
+| `Named` | `string` | 別名，預設為類名 |
+| `Order` | `int` | 注冊排序，數字越大越晚注冊 |
+| `Proxy` | `Type` | AOP 代理類型 |
+| `ExceptInterfaces` | `Type[]` | 排除不注冊的介面 |
+
+---
+
+## 6. appsettings.json 動態注冊
+
+可不修改程式碼，直接透過設定檔實現熱插拔：
+
+```json
+{
+  "DependencyInjectionSettings": {
+    "Definitions": [
+      {
+        "Interface": "Furion.Application;Furion.Application.ITestService",
+        "Service": "Furion.Application;Furion.Application.TestService",
+        "RegisterType": "Transient",
+        "Action": "Add",
+        "Pattern": "SelfWithFirstInterface",
+        "Named": "TestService",
+        "Order": 1,
+        "Proxy": "Furion.Application;Furion.Application.LogDispatchProxy"
+      }
+    ]
+  }
+}
+```
+
+> 💡 格式：`程式集名稱;完整類別名稱`
+> 💡 外部程式集需先在 `AppSettings.ExternalAssemblies` 中註冊
+
+**注冊優先級**：`appsettings.json` > `[Injection]` > 預設掃描
+
+---
+
+## 7. AOP 攔截
+
+> ⚠️ 僅支援**介面注入**，不支援直接注入類。動態 API 請改用 Filter 方式。
+
+### 7.1 建立代理類
+
+```csharp
+public class LogDispatchProxy : AspectDispatchProxy, IDispatchProxy
+{
+    public object Target { get; set; }
+    public IServiceProvider Services { get; set; }
+
+    // 同步攔截
+    public override object Invoke(MethodInfo method, object[] args)
+    {
+        Console.WriteLine("方法被呼叫");
+        var result = method.Invoke(Target, args);
+        Console.WriteLine("返回值：" + result);
+        return result;
+    }
+
+    // 非同步無回傳值
+    public async override Task InvokeAsync(MethodInfo method, object[] args)
+    {
+        Console.WriteLine("方法被呼叫");
+        await (method.Invoke(Target, args) as Task);
+    }
+
+    // 非同步有回傳值
+    public async override Task<T> InvokeAsyncT<T>(MethodInfo method, object[] args)
+    {
+        var result = await (method.Invoke(Target, args) as Task<T>);
+        return result;
+    }
+}
+```
+
+> 💡 取得方法特性：`method.GetActualCustomAttribute<TAttribute>()`
+
+### 7.2 套用代理
+
+```csharp
+[Injection(Proxy = typeof(LogDispatchProxy))]
+public class TestService : ITestService, ITransient { ... }
+```
+
+### 7.3 全域攔截
+
+```csharp
+// IDispatchProxy 改為 IGlobalDispatchProxy
+public class LogDispatchProxy : AspectDispatchProxy, IGlobalDispatchProxy { ... }
+
+// 排除特定類
+[SuppressProxy]
+public class SkipService : ISkipService, ITransient { ... }
+```
+
+**攔截優先級**：`[SuppressProxy]` > `[Injection(Proxy)]` > 全域攔截
+
+### 7.4 在 AOP 中解析服務
+
+```csharp
+var someService = Services.GetService<ISomeService>(); // 推薦
+// 或
+var someService = App.GetService<ISomeService>();
+```
+
+---
+
+## 8. 非 Web / 多執行緒中解析服務
+
+Web 請求外框架不會自動管理作用域，需手動建立：
+
+```csharp
+// 方式一：IServiceProvider
+using var scope = serviceProvider.CreateScope();
+var services = scope.ServiceProvider;
+var repo = Db.GetRepository<Person>(services);
+var other = services.GetService<XXX>();
+
+// 方式二：IServiceScopeFactory
+using var scope = serviceScopeFactory.CreateScope();
+var services = scope.ServiceProvider;
+
+// 方式三：Scoped 靜態類（Furion 提供）
+Scoped.Create((factory, scope) => {
+    var services = scope.ServiceProvider;
+});
+```
+
+---
+
+## 9. 在單例中解析非單例服務
+
+透過 `IServiceScopeFactory` 建立範圍再解析：
+
+```csharp
+public class SomeService : ISomeService, ISingleton
+{
+    private readonly IServiceScopeFactory _scopeFactory;
+
+    public SomeService(IServiceScopeFactory scopeFactory)
+    {
+        _scopeFactory = scopeFactory;
+    }
+
+    public async Task Method()
+    {
+        using var scope = _scopeFactory.CreateScope();
+        var repo = scope.ServiceProvider.GetService<IRepository<User>>();
+    }
+}
+```
+
+---
+
+## 10. WinForm / WPF 支援（Furion 4.8.7.23+）
+
+將所有 `new Form()` / `new Window()` 替換為 `Native.CreateInstance<T>()`。
+
+### WinForm
+
+```csharp
+// Program.cs
+static void Main()
+{
+    Serve.RunNative();
+    ApplicationConfiguration.Initialize();
+    Application.Run(Native.CreateInstance<Form1>()); // ← 替換 new Form1()
+}
+
+// 開啟新視窗（支援傳入其他參數）
+Native.CreateInstance<Form2>("我是參數").ShowDialog();
+
+// 取得已開啟視窗實例
+var form1 = Application.OpenForms.OfType<Form>().FirstOrDefault(f => f is Form1);
+```
+
+### WPF
+
+```csharp
+// App.xaml.cs（移除 StartupUri）
+public partial class App : Application
+{
+    public App() { Serve.RunNative(); }
+
+    protected override void OnStartup(StartupEventArgs e)
+    {
+        Native.CreateInstance<MainWindow>().Show();
+        base.OnStartup(e);
+    }
+}
+
+// 開啟新視窗
+Native.CreateInstance<Window1>("我是參數").Show();
+
+// 取得已開啟視窗實例
+var w = Application.Current.Windows.OfType<Window>().FirstOrDefault(w => w is MainWindow);
+```
+
+> 💡 透過 `Native.CreateInstance<T>()` 建立的視窗支援建構子注入。
+
+---
+
+## 11. 自訂掃描注冊（Scrutor）
+
+```csharp
+services.Scan(scan => scan
+    .FromAssemblyOf<ITransientService>()
+        .AddClasses(c => c.AssignableTo<ITransientService>())
+            .AsImplementedInterfaces()
+            .WithTransientLifetime()
+        .AddClasses(c => c.AssignableTo<IScopedService>())
+            .As<IScopedService>()
+            .WithScopedLifetime()
+        // 泛型注冊
+        .AddClasses(c => c.AssignableTo(typeof(IOpenGeneric<>)))
+            .AsImplementedInterfaces()
+);
+```
+
+> 📖 詳見 [Scrutor GitHub](https://github.com/khellang/Scrutor)

package/knowledge/Furion_Teaching_Manual/13-/347/211/251/344/273/266/350/263/207/346/226/231/346/230/240/345/260/204/357/274/210Mapster/357/274/211.md

@@ -0,0 +1,162 @@
+# Furion 物件資料映射（Mapster）筆記
+
+---
+
+## 1. 概念說明
+
+將一個物件的資料，依照特定規則批量映射到另一個物件，減少手工賦值操作與人為出錯率。常見場景：`DTO ↔ Entity` 互轉。
+
+> 💡 Furion 推薦使用 **Mapster**（高效能、易使用）。若需使用 AutoMapper，無需安裝 Furion 的 Mapster 擴展包。
+
+---
+
+## 2. 安裝
+
+在 `Furion.Core` 層安裝擴展包，Furion 會自動載入，無需手動呼叫：
+
+```
+Furion.Extras.ObjectMapper.Mapster
+```
+
+---
+
+## 3. 基本用法
+
+### 3.1 傳統手動賦值（舊寫法）
+
+```csharp
+var entity = repository.Find(1);
+
+var dto = new Dto();
+dto.Id = entity.Id;
+dto.Name = entity.Name;
+dto.Age = entity.Age;
+dto.FullName = entity.FirstName + entity.LastName;
+dto.IdCard = entity.IdCard.Replace("1234", "****");
+```
+
+### 3.2 使用 Mapster（新寫法）
+
+```csharp
+var entity = repository.Find(1);
+var dto = entity.Adapt<Dto>(); // 一行搞定
+```
+
+---
+
+## 4. 自訂映射規則
+
+對於需要特殊處理的欄位（如組合欄位、資料遮罩），建立映射規則類：
+
+```csharp
+using Mapster;
+
+public class Mapper : IRegister
+{
+    public void Register(TypeAdapterConfig config)
+    {
+        config.ForType<Entity, Dto>()
+            .Map(dest => dest.FullName, src => src.FirstName + src.LastName)
+            .Map(dest => dest.IdCard, src => src.IdCard.Replace("1234", "****"));
+    }
+}
+```
+
+> 💡 `Mapper.cs` 可放在任意專案或資料夾，Furion 啟動時會自動掃描並注入設定。
+
+---
+
+## 5. 依賴注入方式
+
+```csharp
+public class PersonService
+{
+    private readonly IMapper _mapper;
+
+    public PersonService(IMapper mapper)
+    {
+        _mapper = mapper;
+    }
+
+    public Dto GetDto(Entity entity)
+    {
+        return _mapper.Map<Dto>(entity);
+    }
+}
+```
+
+---
+
+## 6. 搭配 EF Core（ProjectToType）
+
+避免手動 `Select` 逐欄位對應：
+
+```csharp
+// 傳統寫法
+var list = context.Sources
+    .Select(p => new Destination
+    {
+        Id = p.Id,
+        Name = p.Name,
+        // ...
+    }).ToList();
+
+// Mapster 寫法
+var list = context.Sources
+    .ProjectToType<Destination>()
+    .ToList();
+```
+
+---
+
+## 7. 全域預設設定
+
+在 `Startup` 中統一設定全域映射行為：
+
+```csharp
+TypeAdapterConfig.GlobalSettings.Default
+    .PreserveReference(true);
+```
+
+---
+
+## 8. Dictionary Key 變小寫問題
+
+Mapster 映射後 `Dictionary` 的 Key 預設會變小寫，有兩種解決方式：
+
+### 方式一：全域設定（推薦）
+
+```csharp
+TypeAdapterConfig.GlobalSettings.Default
+    .NameMatchingStrategy(NameMatchingStrategy.Exact);
+```
+
+### 方式二：單獨設定該映射
+
+```csharp
+public class TestMapper : IRegister
+{
+    public void Register(TypeAdapterConfig config)
+    {
+        config.ForType<TestDemo, TestDemo2>()
+            .AfterMapping(dest =>
+            {
+                dest.Dic = new Dictionary<string, string>(
+                    dest.Dic,
+                    StringComparer.OrdinalIgnoreCase);
+            });
+    }
+}
+```
+
+---
+
+## 快速速查
+
+| 方法 | 說明 |
+|------|------|
+| `entity.Adapt<Dto>()` | 物件轉換（最常用） |
+| `_mapper.Map<Dto>(entity)` | DI 注入方式轉換 |
+| `query.ProjectToType<Dto>()` | EF Core Linq 投影轉換 |
+| `IRegister` | 自訂映射規則介面 |
+| `TypeAdapterConfig.GlobalSettings.Default` | 全域設定入口 |