# 機能設計書 59-CompiledBinding

## 概要

本ドキュメントは、Avaloniaフレームワークにおけるコンパイル済みバインディング（CompiledBinding）機能の設計仕様を定義する。CompiledBindingは、リフレクションを使用せずにプロパティにアクセスするパフォーマンス最適化されたバインディング機能である。

### 本機能の処理概要

CompiledBindingは、ビルド時にバインディングパスをコンパイルし、ランタイムでリフレクションを使用せずにプロパティにアクセスするバインディング機能を提供する。AOT（Ahead-of-Time）コンパイル環境やトリミング環境での動作を保証し、パフォーマンスを向上させる。

**業務上の目的・背景**：.NET AOTコンパイルやトリミング（IL Linker）環境では、リフレクションベースのバインディングが正しく動作しない場合がある。CompiledBindingは、これらの環境で確実に動作し、かつリフレクションのオーバーヘッドを排除してパフォーマンスを向上させる。

**機能の利用シーン**：
- AOTコンパイルが必要なモバイル/組み込みアプリケーション
- トリミングが有効な軽量アプリケーション
- パフォーマンスクリティカルなバインディング
- 型安全なバインディングが必要な場合

**主要な処理内容**：
1. CompiledBindingPathによるプリコンパイルされたパス定義
2. ラムダ式からのバインディング生成（Create<TIn, TOut>メソッド）
3. ExpressionNode構築（リフレクションなし）
4. BindingExpression生成と値の同期

**関連システム・外部連携**：BindingBase、CompiledBindingPath、BindingExpressionVisitor、XAMLコンパイラと連携。

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | CompiledBindingは特定の画面に限定されず、アプリケーション全体で使用可能 |

## 機能種別

データバインディング / パフォーマンス最適化 / AOT対応

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Path | CompiledBindingPath? | No | コンパイル済みバインディングパス | null許容 |
| Mode | BindingMode | No | バインディングモード | 有効な列挙値 |
| Converter | IValueConverter? | No | 値コンバーター | null許容 |
| ConverterParameter | object? | No | コンバーターパラメーター | null許容 |
| ConverterCulture | CultureInfo? | No | コンバーターカルチャ | null許容 |
| Source | object? | No | バインディングソース | null許容 |
| FallbackValue | object? | No | エラー時のフォールバック値 | null許容 |
| TargetNullValue | object? | No | ソースがnull時の値 | null許容 |
| StringFormat | string? | No | 文字列フォーマット | null許容 |
| UpdateSourceTrigger | UpdateSourceTrigger | No | 更新トリガー | 有効な列挙値 |
| Priority | BindingPriority | No | バインディング優先度 | 有効な列挙値 |
| Delay | int | No | 更新遅延（ミリ秒） | 非負整数 |

### 入力データソース

- XAML {CompiledBinding}マークアップ拡張（XAMLコンパイラ生成）
- CompiledBinding.Create<TIn, TOut>メソッド（コードビハインド）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| BindingExpression | BindingExpression | アクティブなバインディング式 |

### 出力先

- ターゲットプロパティ（バインディング結果値）
- ソースプロパティ（TwoWay/OneWayToSource時）

## 処理フロー

### 処理シーケンス

```
1. CompiledBinding定義
   └─ XAMLコンパイラまたはCreateメソッドで生成
2. CompiledBindingPath構築
   └─ プリコンパイルされたアクセサーを保持
3. ExpressionNode生成
   └─ Path.BuildExpressionでノードリスト構築
4. ソース決定
   └─ SourceNode.SelectSourceまたはDataContext
5. BindingExpression生成
   └─ CreateInstanceでアクティブな式を作成
6. 値の購読開始
   └─ ソースプロパティの変更を監視
```

### フローチャート

```mermaid
flowchart TD
    A[CompiledBinding定義] --> B{Pathあり?}
    B -->|Yes| C[Path.BuildExpression]
    B -->|No| D[空のノードリスト]
    C --> E[ExpressionNodeリスト構築]
    D --> E
    E --> F{Source指定?}
    F -->|Yes| G[指定Sourceを使用]
    F -->|No| H{isRooted?}
    H -->|Yes| I[SourceNodeでソース選択]
    H -->|No| J[DataContextNode追加]
    G --> K[BindingExpression作成]
    I --> K
    J --> K
    K --> L[ソース購読開始]
    L --> M[値変換・適用]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-59-01 | パスなしバインディング | Path未指定でSource未設定の場合DataContextを使用 | Path == null && Source == UnsetValue |
| BR-59-02 | ルートパス判定 | $parent、$self、#elementNameで始まるパスはルート | BuildExpression時 |
| BR-59-03 | デフォルトモード解決 | Mode=Defaultの場合、メタデータからDefaultBindingModeを取得 | Mode == BindingMode.Default |
| BR-59-04 | トリガー解決 | UpdateSourceTrigger.DefaultはPropertyChangedに解決 | UpdateSourceTrigger == Default |

### 計算ロジック

特になし

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

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

該当なし（UIフレームワークのためデータベース操作は行わない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ExpressionParseException | ラムダ式解析失敗（Createメソッド） | 例外スロー |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- リフレクションを使用しないため、ReflectionBindingより高速
- ビルド時のコンパイルコストはランタイム性能向上で相殺

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

特になし

## 備考

- XAMLでx:CompileBindingsディレクティブを使用して有効化
- Create<TIn, TOut>メソッドはRequiresDynamicCode/RequiresUnreferencedCode属性あり

---

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

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

### 推奨読解順序

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

CompiledBindingで使用される型定義を先に把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | CompiledBindingPath.cs | `src/Avalonia.Base/Data/CompiledBindingPath.cs` | プリコンパイルパス、BuildExpressionメソッド |
| 1-2 | CompiledBinding.cs | `src/Avalonia.Base/Data/CompiledBinding.cs` | メインクラス、プロパティ定義 |

**読解のコツ**: CompiledBindingPathはビルド時に生成されるパス表現。内部のICompiledBindingPathElement配列がノードチェーンを構成。

#### Step 2: CompiledBindingクラスを理解する

メインクラスの構造とプロパティを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | CompiledBinding.cs | `src/Avalonia.Base/Data/CompiledBinding.cs` | コンストラクタ、Createメソッド、プロパティ群 |

**主要処理フロー**:
1. **22-30行目**: コンストラクタ（パス指定）
2. **90-119行目**: Createメソッド（ラムダ式からバインディング生成）
3. **130-193行目**: 各プロパティ定義（Delay、Converter、Mode等）

#### Step 3: CreateInstanceを理解する

BindingExpression生成ロジックを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | CompiledBinding.cs | `src/Avalonia.Base/Data/CompiledBinding.cs` | CreateInstanceメソッド |

**主要処理フロー**:
- **197-237行目**: CreateInstance実装
  - **202-206行目**: Path.BuildExpressionでノードリスト構築
  - **210-211行目**: ルートでない場合DataContextNode追加
  - **215-217行目**: ソース決定ロジック
  - **221-236行目**: BindingExpression生成

#### Step 4: ラムダ式解析を理解する

Createメソッドのラムダ式解析を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | BindingExpressionVisitor.cs | `src/Avalonia.Base/Data/Core/Parsers/BindingExpressionVisitor.cs` | ラムダ式からCompiledBindingPath構築 |

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

```
CompiledBinding.Create<TIn, TOut>(expression, ...)
    │
    └─ BindingExpressionVisitor<TIn>.BuildPath(expression)
           │
           └─ Expression Tree解析
                  └─ CompiledBindingPath構築

{CompiledBinding Path=...} (XAML)
    │
    └─ CompiledBinding (XAMLコンパイラ生成)
           │
           └─ CreateInstance (ターゲットにバインド時)
                  │
                  ├─ Path.BuildExpression
                  │      └─ ExpressionNodeリスト構築
                  │
                  ├─ SourceNode.SelectSource (ルートパス時)
                  │      └─ ソースオブジェクト決定
                  │
                  └─ new BindingExpression(...)
                         │
                         ├─ ソースプロパティ購読
                         ├─ 値変換 (Converter)
                         └─ ターゲットプロパティ更新
```

### データフロー図

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

CompiledBindingPath ───▶ CompiledBinding ───▶ ExpressionNodeリスト
  (ビルド時生成)           │
                           └─ BuildExpression

ラムダ式 ───▶ BindingExpressionVisitor ───▶ CompiledBindingPath
  (Createメソッド)    └─ Expression Tree解析

ソースプロパティ ───▶ BindingExpression ───▶ ターゲットプロパティ
  (型安全アクセス)     │                   (リフレクションなし)
                       └─ 値変換・適用
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| CompiledBinding.cs | `src/Avalonia.Base/Data/CompiledBinding.cs` | ソース | メインクラス |
| CompiledBindingPath.cs | `src/Avalonia.Base/Data/CompiledBindingPath.cs` | ソース | コンパイル済みパス |
| BindingBase.cs | `src/Avalonia.Base/Data/BindingBase.cs` | ソース | バインディング基底 |
| BindingExpression.cs | `src/Avalonia.Base/Data/Core/BindingExpression.cs` | ソース | バインディング式 |
| BindingExpressionVisitor.cs | `src/Avalonia.Base/Data/Core/Parsers/BindingExpressionVisitor.cs` | ソース | ラムダ式解析 |
| ExpressionNode.cs | `src/Avalonia.Base/Data/Core/ExpressionNodes/ExpressionNode.cs` | ソース | 式ノード基底 |
| SourceNode.cs | `src/Avalonia.Base/Data/Core/ExpressionNodes/SourceNode.cs` | ソース | ソースノード |
| TargetTypeConverter.cs | `src/Avalonia.Base/Data/Core/TargetTypeConverter.cs` | ソース | 型変換 |
