跳至主要内容

GST.Rpa.Recorder — 錄製模式

適用對象：GST 內部開發人員 前置知識：C# / .NET 8 / Windows UI Automation 閱讀時間：10 分鐘 最後更新：2026-04-04 版本：0.1.0

開發狀態

本模組目前為骨架階段，僅包含 DI 註冊介面。以下標註「Planned」的章節描述規劃中的架構設計。

1. 模組職責​

GST.Rpa.Recorder 負責錄製使用者的 UI 操作，並自動產生對應的 C# 腳本。其核心流程為：

  1. 攔截使用者的滑鼠點擊、鍵盤輸入等 UI 事件
  2. 透過 UI Automation 識別目標控制項的屬性（AutomationId、ClassName、Name 等）
  3. 將事件序列轉換為可執行的 C# 腳本程式碼
  4. 對產生的腳本進行最佳化（合併重複動作、移除冗餘等待）

此模組依賴 GST.Rpa.Automation 提供的 UI 元素定位能力，以及 GST.Rpa.Core 的基礎型別定義。

2. NuGet 引用與相依​

Target Framework：net8.0-windows（繼承自 Directory.Build.props）

專案參考​

相依專案用途
GST.Rpa.Core核心型別、介面定義
GST.Rpa.AutomationUI Automation 元素定位與操作

NuGet 套件​

套件用途
Microsoft.Extensions.DependencyInjectionDI 容器註冊

完整 .csproj 內容：

<Project Sdk="Microsoft.NET.Sdk">

  <ItemGroup>
    <ProjectReference Include="..\GST.Rpa.Core\GST.Rpa.Core.csproj" />
    <ProjectReference Include="..\GST.Rpa.Automation\GST.Rpa.Automation.csproj" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
  </ItemGroup>

</Project>

3. 現有介面​

目前模組僅包含一個檔案 — DI 擴充方法，提供 AddRpaRecorder() 作為未來服務註冊的進入點。

ServiceCollectionExtensions​

using Microsoft.Extensions.DependencyInjection;

namespace GST.Rpa.Recorder;

public static class ServiceCollectionExtensions
{
    public static IServiceCollection AddRpaRecorder(this IServiceCollection services)
    {
        // TODO (GST-350): Register UI event recorder services
        return services;
    }
}

使用方式（在應用程式啟動時）：

services.AddRpaRecorder();

目前此方法為空實作，待後續開發階段逐步註冊錄製相關服務。

4. 規劃架構​

4.0 錄製時序總覽（Planned）​

下圖呈現規劃中的完整錄製流程：使用者操作經 Win32 Hook 與 UIA Event Handler 雙管道捕捉 → Recorder 關聯成 RecordedEvent → 透過 IObservable<RecordedEvent> 串流推送 → 停止錄製後產生 C# 腳本。

時序的兩個關鍵設計：

  • 雙管道捕捉：Win32 Hook 拿到「使用者實際做了什麼」（座標、鍵碼），UIA Event 拿到「對應的 UI 元素是誰」（AutomationId、ControlType）；Recorder 在收到事件時把兩者關聯起來，產出帶有元素資訊的 RecordedEvent
  • 串流 + 批次後處理：錄製過程使用 IObservable<RecordedEvent> 即時推送（UI 可邊錄邊顯示），但腳本產生與最佳化是 StopRecordingAsync 後一次性執行，便於做跨事件的 pattern 偵測（例如連續輸入合併為單一 TypeText）
Planned

4.1 IRpaRecorder 介面設計​

規劃中的核心介面，定義錄製模式的生命週期：

public interface IRpaRecorder
{
    Task StartRecordingAsync(RecordingOptions options, CancellationToken ct = default);
    Task StopRecordingAsync(CancellationToken ct = default);
    Task PauseRecordingAsync();
    Task ResumeRecordingAsync();
    IObservable<RecordedEvent> Events { get; }
    RecordingState State { get; }
}
  • StartRecordingAsync — 開始攔截 UI 事件
  • StopRecordingAsync — 停止錄製並輸出事件序列
  • Events — 以 Reactive 串流即時推送錄製到的事件
  • State — 目前錄製狀態（Idle / Recording / Paused）
Planned

4.2 UIAutomation Event Handler 機制​

透過 System.Windows.Automation 的事件訂閱機制，監聽目標應用程式的 UI 變化：

  • StructureChangedEvent — 偵測視窗開關、控制項新增/移除
  • FocusChangedEvent — 追蹤焦點切換
  • PropertyChangedEvent — 監控控制項屬性變更（如 Value、Selection）
  • InvokePattern — 捕捉按鈕點擊等叫用動作

預計整合 GST.Rpa.Automation 已封裝的 UIA Wrapper，避免直接操作低階 COM 介面。

Planned

4.3 Win32 Hook（Mouse / Keyboard）​

UIAutomation 事件無法涵蓋所有操作（例如拖曳、快捷鍵組合），因此需搭配 Win32 低階 Hook：

Hook 類型Win32 常數用途
滑鼠 HookWH_MOUSE_LL捕捉點擊座標、滾輪、拖曳
鍵盤 HookWH_KEYBOARD_LL捕捉按鍵序列、快捷鍵組合

Hook 回傳的原始事件會與 UIAutomation 的元素資訊做關聯，產生完整的 RecordedEvent。

Planned

4.4 Event → Script 轉換演算法​

將錄製的事件序列轉換為 C# 腳本的流程：

  1. Event Normalization — 統一事件格式，補充元素定位資訊
  2. Element Locator Resolution — 為每個 UI 元素選擇最穩定的定位策略（AutomationId 優先，備援 XPath）
  3. Action Mapping — 將原始事件對應到 GST.Rpa.Automation 的高階 API 呼叫
  4. Code Generation — 使用 Roslyn 或 Template 產生可編譯的 C# 程式碼

產生的腳本預計符合 GST.Rpa.Scripting 的腳本格式規範。

Planned

4.5 Script 最佳化策略​

錄製產生的原始腳本通常包含冗餘操作，需進行最佳化：

策略說明
動作合併連續的字元輸入合併為單一 TypeText() 呼叫
等待最佳化以智慧等待（WaitForElement）取代固定延遲
重複偵測辨識重複的操作模式，提取為迴圈或子程序
冗餘移除移除無效的 Focus 切換、多餘的滑鼠移動事件
定位器簡化優先使用 AutomationId，減少脆弱的座標定位

5. 版本紀錄​

版本日期說明
0.1.02026-04-04骨架初版 — 僅包含 DI 註冊擴充方法