# 機能設計書 95-Win32Automation

## 概要

本ドキュメントは、Avaloniaフレームワークにおける Windows UIオートメーション（Win32Automation）機能の設計仕様を記述します。Win32Automationは、Windows UI Automation (UIA)フレームワークとの統合を提供し、スクリーンリーダーやテスト自動化ツールからAvaloniaアプリケーションのUIにアクセスできるようにします。

### 本機能の処理概要

Win32Automationは、AvaloniaのAutomationPeerをWindows UIオートメーションプロバイダとして公開し、アクセシビリティツールやテスト自動化フレームワークがAvaloniaのUI要素を検出・操作できるようにします。IRawElementProviderSimple、IRawElementProviderFragmentなどのCOMインターフェースを実装し、UIAクライアントとAvaloniaオートメーションピアの橋渡しを行います。

**業務上の目的・背景**：アクセシビリティは現代のソフトウェア開発において重要な要件です。視覚障害を持つユーザーがスクリーンリーダー（JAWS、NVDA、Windows Narrator等）を使用してアプリケーションを操作できるようにする必要があります。また、UIテスト自動化においても、UIオートメーションを介してUI要素を特定し操作することが一般的です。Win32Automationは、これらの要件をWindows上で満たすための基盤を提供します。

**機能の利用シーン**：
- スクリーンリーダーによるUI要素の読み上げ
- UIテスト自動化ツール（Microsoft UI Automation Client API）
- アクセシビリティ検証ツール（Accessibility Insights等）
- Windows Narrator対応
- Coded UI Test / Selenium等のテストフレームワーク連携

**主要な処理内容**：
1. AutomationPeerとAutomationNodeのマッピング管理
2. UIAプロパティの取得と変換
3. UIAパターン（Invoke、Value、Toggle等）の実装
4. UIAイベント（構造変更、プロパティ変更、フォーカス変更）の発火
5. UIAナビゲーション（親、子、兄弟要素の走査）

**関連システム・外部連携**：
- Windows UI Automation Core（UiaCoreTypesApi、UiaCoreProviderApi）
- COMインターフェース（IRawElementProviderSimple、IRawElementProviderFragment等）
- スクリーンリーダー、テスト自動化ツール

**権限による制御**：特別な権限は不要ですが、UIAクライアントはUIオートメーションアクセス権限が必要な場合があります。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 92 | Automation | 主機能 | オートメーションのテスト |

## 機能種別

アクセシビリティ / UIオートメーション / COM統合

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| AutomationPeer | AutomationPeer | Yes | Avalonia側のオートメーションピア | null不可 |
| patternId | int | - | UIAパターンID | UiaPatternId列挙値 |
| propertyId | int | - | UIAプロパティID | UiaPropertyId列挙値 |
| direction | NavigateDirection | - | ナビゲーション方向 | Parent/NextSibling等 |

### 入力データソース

- AvaloniaのAutomationPeerツリー
- UIAクライアントからのリクエスト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| プロパティ値 | object | 要求されたUIAプロパティの値 |
| パターンプロバイダ | object | 実装されたUIAパターンプロバイダ |
| 要素プロバイダ | IRawElementProviderFragment | ナビゲーション結果の要素 |
| BoundingRectangle | Rect | 要素の画面上の境界矩形 |

### 出力先

- UIAクライアント（COMインターフェース経由）

## 処理フロー

### 処理シーケンス

```
1. UIAクライアントからのリクエスト受信
   └─ COMメソッド呼び出し
2. AutomationNode取得
   └─ GetOrCreate(peer)でキャッシュから取得または生成
3. UIスレッドへのマーシャリング
   └─ InvokeSync()でDispatcher.UIThread経由実行
4. Avalonia AutomationPeerへの委譲
   └─ peer.GetName()、peer.GetProvider<T>()等
5. 結果の変換
   └─ AvaloniasタイプをUIA形式に変換
6. UIAクライアントへの返却
   └─ COMインターフェース経由
```

### フローチャート

```mermaid
flowchart TD
    A[UIAクライアントリクエスト] --> B{リクエスト種別}
    B -->|プロパティ取得| C[GetPropertyValue]
    B -->|パターン取得| D[GetPatternProvider]
    B -->|ナビゲーション| E[Navigate]
    C --> F[InvokeSync - UIスレッド実行]
    D --> F
    E --> F
    F --> G[AutomationPeerメソッド呼び出し]
    G --> H{結果変換}
    H -->|Control Type| I[ToUiaControlType]
    H -->|Landmark| J[ToUiaLandmarkType]
    H -->|その他| K[直接返却]
    I --> L[UIAクライアントへ返却]
    J --> L
    K --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-95-01 | ノードキャッシュ | ConditionalWeakTableでAutomationNodeをキャッシュ | AutomationPeer存在中 |
| BR-95-02 | UIスレッド実行 | AutomationPeerアクセスはUIスレッドで実行 | 常時 |
| BR-95-03 | ControlType変換 | AvaloniaのAutomationControlTypeをUiaControlTypeIdに変換 | プロパティ取得時 |
| BR-95-04 | RuntimeId生成 | {3, GetHashCode()}形式でランタイムIDを生成 | 要素識別時 |
| BR-95-05 | イベント通知 | プロパティ変更・構造変更・フォーカス変更をUIA通知 | 状態変化時 |

### 計算ロジック

BoundingRectangleはAutomationPeerのGetBoundingRectangle()結果をRootAutomationNodeのToScreen()で画面座標に変換します。

## データベース操作仕様

### 操作別データベース影響一覧

本機能はデータベース操作を伴いません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| UIA_E_ELEMENTNOTENABLED | COMException | 要素が無効状態 | ElementNotEnabledExceptionを変換 |
| NotSupportedException | NotSupportedException | 未サポートパターン | nullを返却 |

### リトライ仕様

エラー発生時のリトライは行いません。

## トランザクション仕様

本機能はUI処理のため、トランザクション管理は不要です。

## パフォーマンス要件

- ConditionalWeakTableによる効率的なノードキャッシュ
- UIスレッドへの同期呼び出しは最小限に

## セキュリティ考慮事項

- UIオートメーションはWindowsセキュリティモデルに従う
- ProcessIdの公開

## 備考

.NET 8.0以降ではGeneratedComClassアトリビュートによるSource Generator COM実装が使用されます。

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

まず、UIAインターフェースとAvaloniaオートメーションの対応関係を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | IRawElementProviderSimple.cs | `src/Windows/Avalonia.Win32.Automation/Interop/IRawElementProviderSimple.cs` | UIA基本インターフェース |
| 1-2 | IRawElementProviderFragment.cs | `src/Windows/Avalonia.Win32.Automation/Interop/IRawElementProviderFragment.cs` | フラグメントナビゲーション |
| 1-3 | UiaCoreProviderApi.cs | `src/Windows/Avalonia.Win32.Automation/Interop/UiaCoreProviderApi.cs` | UIAコアAPI |

**読解のコツ**: COMインターフェースの定義とP/Invoke宣言を確認し、Windows UIAの基本構造を把握してください。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | AutomationNode.cs | `src/Windows/Avalonia.Win32.Automation/AutomationNode.cs` | メインオートメーションノード |

**主要処理フロー**:
1. **34-60行目**: s_propertyMap - AvaloniaプロパティとUIAプロパティの対応
2. **62行目**: s_nodes - AutomationPeerとNodeのキャッシュ
3. **68-78行目**: コンストラクタ - イベント登録
4. **82-89行目**: GetBoundingRectangle - 境界矩形取得
5. **100-117行目**: GetPatternProvider - パターンプロバイダ取得
6. **119-159行目**: GetPropertyValue - プロパティ値取得
7. **163-194行目**: Navigate - ナビゲーション処理
8. **201-206行目**: GetOrCreate/Release - ノード管理

#### Step 3: パターン実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | AutomationNode.Toggle.cs | `src/Windows/Avalonia.Win32.Automation/AutomationNode.Toggle.cs` | Toggleパターン |
| 3-2 | AutomationNode.Value.cs | `src/Windows/Avalonia.Win32.Automation/AutomationNode.Value.cs` | Valueパターン |
| 3-3 | AutomationNode.Selection.cs | `src/Windows/Avalonia.Win32.Automation/AutomationNode.Selection.cs` | Selectionパターン |

#### Step 4: ルートノードを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | RootAutomationNode.cs | `src/Windows/Avalonia.Win32.Automation/RootAutomationNode.cs` | ルート要素実装 |
| 4-2 | InteropAutomationNode.cs | `src/Windows/Avalonia.Win32.Automation/InteropAutomationNode.cs` | 相互運用ノード |

### プログラム呼び出し階層図

```
AutomationNode
    │
    ├─ IRawElementProviderSimple
    │      ├─ GetProviderOptions()
    │      ├─ GetPatternProvider(patternId)
    │      └─ GetPropertyValue(propertyId)
    │
    ├─ IRawElementProviderFragment
    │      ├─ Navigate(direction)
    │      ├─ GetRuntimeId()
    │      └─ GetBoundingRectangle()
    │
    └─ パターンプロバイダ
           ├─ IInvokeProvider → Invoke()
           ├─ IToggleProvider → Toggle()
           ├─ IValueProvider → SetValue()
           └─ ISelectionProvider → GetSelection()
```

### データフロー図

```
[入力]                [処理]                      [出力]

UIAクライアント ────▶ AutomationNode ─────────▶ プロパティ値
         │                │
         │                ├─ InvokeSync()
         │                │      └─ Dispatcher.UIThread
         │                │
         │                └─ AutomationPeer
         │                       ├─ GetName()
         │                       ├─ GetProvider<T>()
         │                       └─ GetBoundingRectangle()
         │
         └─ UIAイベント通知 ◀────── RaisePropertyChangedEvent
                                   RaiseStructureChangedEvent
                                   RaiseAutomationEvent
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AutomationNode.cs | `src/Windows/Avalonia.Win32.Automation/AutomationNode.cs` | ソース | メインノード実装 |
| AutomationNode.Toggle.cs | `src/Windows/Avalonia.Win32.Automation/AutomationNode.Toggle.cs` | ソース | Toggleパターン |
| AutomationNode.Value.cs | `src/Windows/Avalonia.Win32.Automation/AutomationNode.Value.cs` | ソース | Valueパターン |
| AutomationNode.Selection.cs | `src/Windows/Avalonia.Win32.Automation/AutomationNode.Selection.cs` | ソース | Selectionパターン |
| AutomationNode.Scroll.cs | `src/Windows/Avalonia.Win32.Automation/AutomationNode.Scroll.cs` | ソース | Scrollパターン |
| AutomationNode.RangeValue.cs | `src/Windows/Avalonia.Win32.Automation/AutomationNode.RangeValue.cs` | ソース | RangeValueパターン |
| AutomationNode.ExpandCollapse.cs | `src/Windows/Avalonia.Win32.Automation/AutomationNode.ExpandCollapse.cs` | ソース | ExpandCollapseパターン |
| RootAutomationNode.cs | `src/Windows/Avalonia.Win32.Automation/RootAutomationNode.cs` | ソース | ルートノード |
| InteropAutomationNode.cs | `src/Windows/Avalonia.Win32.Automation/InteropAutomationNode.cs` | ソース | 相互運用ノード |
| IRawElementProviderSimple.cs | `src/Windows/Avalonia.Win32.Automation/Interop/IRawElementProviderSimple.cs` | ソース | UIAインターフェース |
| IRawElementProviderFragment.cs | `src/Windows/Avalonia.Win32.Automation/Interop/IRawElementProviderFragment.cs` | ソース | フラグメントインターフェース |
| UiaCoreProviderApi.cs | `src/Windows/Avalonia.Win32.Automation/Interop/UiaCoreProviderApi.cs` | ソース | UIAコアAPI |
| UiaCoreTypesApi.cs | `src/Windows/Avalonia.Win32.Automation/Interop/UiaCoreTypesApi.cs` | ソース | UIAタイプ定義 |
