# 通知設計書 6-BindingError

## 概要

本ドキュメントは、Avalonia UIフレームワークにおけるBindingError（バインディングエラー）通知の設計について記述する。BindingError通知は、バインディングパスが解決できない場合などに発生するデータバインディングシステム内部の通知であり、BindingErrorType.Error として定義されている。

### 本通知の処理概要

BindingError通知は、XAMLで定義されたデータバインディングが正常に機能しない場合に、バインディングシステム内部で発生するエラー通知である。

**業務上の目的・背景**：MVVMパターンを採用するアプリケーションにおいて、ViewとViewModelの間のデータバインディングは重要な役割を果たす。バインディングパスの誤り、ソースオブジェクトのnull参照、型変換の失敗などが発生した場合、開発者がこれを検知して修正できる必要がある。BindingErrorは、このようなバインディングの問題をシステム内部で追跡し、デバッグを支援する。

**通知の送信タイミング**：バインディング式の評価時に、ソースプロパティが見つからない、型変換が失敗した、ソースオブジェクトがnullである、などのエラーが検出されたとき。バインディング評価はプロパティ変更通知やUIの初期化時に発生する。

**通知の受信者**：バインディングシステム内部で処理される。開発者は診断ツールやデバッグ出力を通じてこれらのエラーを確認できる。UIには直接表示されない内部的な通知メカニズムである。

**通知内容の概要**：Exception オブジェクトを含む BindingError インスタンスまたは BindingNotification インスタンスとして表現される。ErrorType が BindingErrorType.Error に設定され、エラーの詳細情報（プロパティパス、ソースの状態など）が Exception に含まれる。

**期待されるアクション**：開発者がデバッグ時にエラーを確認し、バインディング式の修正、ソースオブジェクトの初期化確認、型変換ロジックの追加などの対処を行う。実行時にはFallbackValueを使用してエラーを緩和することも可能。

## 通知種別

内部通知（データバインディングシステム内部）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（バインディング評価時） |
| 優先度 | 通常（内部処理） |
| リトライ | なし |

### 送信先決定ロジック

バインディングエラーは BindingExpression 内部で BindingError オブジェクトまたは BindingNotification オブジェクトとして生成され、BindingValue<T> 構造体を通じて伝播される。FallbackValue が設定されている場合はその値が使用される。

## 通知テンプレート

### バインディングエラーの場合

| 項目 | 内容 |
|-----|------|
| エラー情報 | BindingError.Exception プロパティ |
| エラータイプ | BindingErrorType.Error |
| フォールバック値 | BindingValue.FallbackValue（設定時） |

### エラー内容

```
BindingError
├── Exception: {発生した例外}
├── ErrorType: BindingErrorType.Error
└── FallbackValue: {フォールバック値（オプション）}
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| なし | - | - | 内部通知のため添付ファイルは存在しない |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| Exception | エラーの詳細を含む例外オブジェクト | バインディング評価時の例外 | Yes |
| ErrorType | エラーの種類（Error） | BindingErrorType.Error | Yes |
| Value | フォールバック値 | FallbackValue 設定 | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| バインディング評価 | プロパティパス解決失敗 | パスが見つからない | MissingMemberException |
| バインディング評価 | ソースオブジェクトnull | DataContext等がnull | NullReferenceException |
| バインディング評価 | 型変換失敗 | IValueConverter失敗 | InvalidCastException |
| バインディング評価 | インデクサー評価失敗 | コレクションアクセスエラー | IndexOutOfRangeException |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| FallbackValue設定時 | エラーは記録されるが、FallbackValueが使用される |
| TargetNullValue設定時 | nullソースの場合にTargetNullValueが使用される |

## 処理フロー

### エラー発生フロー

```mermaid
flowchart TD
    A[バインディング式評価開始] --> B{ソースオブジェクト確認}
    B -->|null| C[BindingError生成]
    B -->|OK| D{プロパティパス解決}
    D -->|失敗| C
    D -->|OK| E{型変換}
    E -->|失敗| C
    E -->|OK| F[値をターゲットに設定]
    C --> G{FallbackValue設定?}
    G -->|Yes| H[FallbackValue使用]
    G -->|No| I[UnsetValue使用]
    H --> J[エラー記録]
    I --> J
    J --> K[処理完了]
    F --> K
```

## データベース参照・更新仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| なし | - | 内部通知のためデータベースは使用しない |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| なし | - | 内部通知のためデータベースは使用しない |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| パス解決エラー | プロパティパスが無効 | バインディングパスを修正 |
| Null参照エラー | ソースがnull | DataContext設定を確認 |
| 型変換エラー | 変換不可能な型 | IValueConverterを実装 |
| インデクサーエラー | 範囲外アクセス | コレクション境界を確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（ソース変更時に再評価） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | なし |
| 1日あたり上限 | なし |

### 配信時間帯

バインディング評価時（アプリケーション実行中、常時）

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

- バインディングエラーに機密情報（パスワード等）のプロパティパスが含まれる可能性に注意
- 本番環境ではデバッグ出力を無効化することを推奨
- エラーメッセージをUIに表示する場合は、技術的詳細を隠蔽すること

## 備考

- BindingErrorType.Error はバインディングシステム内部のエラーを表す
- DataValidationError（No.7）とは異なり、バリデーションではなくバインディング自体の問題を示す
- デバッグビルドではより詳細なエラー情報が出力される
- AggregateException で複数のエラーが集約される場合がある

---

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

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

### 推奨読解順序

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

BindingError と BindingErrorType の定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | BindingNotification.cs | `src/Avalonia.Base/Data/BindingNotification.cs` | BindingErrorType 列挙型の定義（Error = 1） |
| 1-2 | BindingError.cs | `src/Avalonia.Base/Data/Core/BindingError.cs` | BindingError クラスの定義 |
| 1-3 | BindingValue.cs | `src/Avalonia.Base/Data/BindingValue.cs` | BindingValueType.BindingError の定義 |

**読解のコツ**: BindingErrorType は None（0）、Error（1）、DataValidationError（2）の3値を持つ。Error はバインディング自体の問題を示す。

#### Step 2: エラー生成ロジックを理解する

バインディングエラーがどのように生成されるかを確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | BindingValue.cs | `src/Avalonia.Base/Data/BindingValue.cs` | BindingError() ファクトリメソッド |

**主要処理フロー**:
- **340-345行目**: `BindingError(Exception e)` で BindingValueType.BindingError を生成
- **352-357行目**: `BindingError(Exception e, T fallbackValue)` でフォールバック値付きエラーを生成

#### Step 3: 通知変換を理解する

型付き/型なしバインディング間の変換を確認。

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

**主要処理フロー**:
- **158-159行目**: BindingError は BindingNotification に変換される

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

```
バインディング式評価
    │
    ├─ プロパティパス解決
    │      └─ 失敗時 → BindingValue<T>.BindingError(exception)
    │
    ├─ 型変換
    │      └─ 失敗時 → BindingValue<T>.BindingError(exception, fallback)
    │
    └─ BindingValue.ToUntyped()
           │
           └─ BindingNotification(Error, BindingErrorType.Error)
                  │
                  └─ FallbackValue または UnsetValue
```

### データフロー図

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

バインディング式         BindingExpression                  BindingValue<T>
├─ Path           ───▶   ├─ パス解決              ───▶    ├─ Type = BindingError
├─ Source               ├─ 型変換                         ├─ Error = Exception
├─ Converter            └─ エラー検出                      └─ Value = Fallback
└─ FallbackValue
                                │
                                ▼
                         BindingNotification
                         └─ ErrorType = Error
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| BindingNotification.cs | `src/Avalonia.Base/Data/BindingNotification.cs` | ソース | BindingErrorType 列挙型定義 |
| BindingError.cs | `src/Avalonia.Base/Data/Core/BindingError.cs` | ソース | BindingError クラス |
| BindingValue.cs | `src/Avalonia.Base/Data/BindingValue.cs` | ソース | BindingValue<T> 構造体 |
| UntypedBindingExpressionBase.cs | `src/Avalonia.Base/Data/Core/UntypedBindingExpressionBase.cs` | ソース | バインディング式基底クラス |
| BindingExpression.cs | `src/Avalonia.Base/Data/Core/BindingExpression.cs` | ソース | バインディング式実装 |
