# 機能設計書 89-XamlLoader

## 概要

本ドキュメントは、Avaloniaフレームワークにおける「XamlLoader」機能の設計仕様を記述する。AvaloniaRuntimeXamlLoaderクラスは、XAML文書を実行時に解析・読み込み、オブジェクトグラフに変換する中核的な機能を提供する。

### 本機能の処理概要

XamlLoaderは、XAML（eXtensible Application Markup Language）形式で記述されたUIマークアップを解析し、対応するAvaloniaオブジェクト（コントロール、リソース、スタイル等）のインスタンスを生成する。コンパイル時XAMLローダー（XamlIL）とランタイムXAMLローダーの両方をサポートし、動的なUI生成を可能にする。

**業務上の目的・背景**：XAMLは、UIの宣言的な記述を可能にする業界標準のマークアップ言語である。開発者は、C#コードを書くことなく複雑なUIレイアウトを定義できる。XamlLoaderは、このXAMLを実行可能なオブジェクトに変換する重要な役割を担う。デザイナーツールとの連携や動的UIの生成にも使用される。

**機能の利用シーン**：アプリケーション起動時のXAMLリソース読み込み、動的コンテンツの生成、デザイナープレビュー、ホットリロード機能で利用される。

**主要な処理内容**：
1. XAML文字列/ストリームの解析
2. XamlILコンパイラによる中間表現への変換
3. オブジェクトインスタンスの生成
4. プロパティバインディングの設定
5. リソース参照の解決
6. NameScopeへの登録

**関連システム・外部連携**：XamlILコンパイラ、MarkupExtension、TypeConverter、AvaloniaXamlLoaderと連携する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 全画面 | 補助機能 | XAMLからのUI構築 |

## 機能種別

パーサー / ファクトリ

## 入力仕様

### 入力パラメータ

**Load (文字列版)**:
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| xaml | string | Yes | XAML文字列 | nullの場合ArgumentNullException |
| localAssembly | Assembly? | No | clr-namespace用デフォルトアセンブリ | - |
| rootInstance | object? | No | 読み込み先のインスタンス | - |
| uri | Uri? | No | XAMLのURI | - |
| designMode | bool | No | デザインモードフラグ | - |

**Load (ストリーム版)**:
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| stream | Stream | Yes | XAMLストリーム | - |
| localAssembly | Assembly? | No | clr-namespace用デフォルトアセンブリ | - |
| rootInstance | object? | No | 読み込み先のインスタンス | - |
| uri | Uri? | No | XAMLのURI | - |
| designMode | bool | No | デザインモードフラグ | - |

### 入力データソース

XAML文字列、XAMLファイルストリーム、埋め込みリソース

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | object | 解析されたルートオブジェクト |

### 出力先

アプリケーションのビジュアルツリー

## 処理フロー

### 処理シーケンス

```
1. XAML入力受付
   └─ Load(xaml)またはLoad(stream)を呼び出し
   └─ 文字列の場合、UTF8でMemoryStreamに変換

2. RuntimeXamlLoaderDocumentの構築
   └─ URI、rootInstance、Streamを設定
   └─ RuntimeXamlLoaderConfigurationを作成

3. XamlILコンパイラ呼び出し
   └─ AvaloniaXamlIlRuntimeCompiler.Loadを呼び出し
   └─ XAMLをパースしてASTを構築
   └─ ILコードを生成

4. オブジェクト生成
   └─ 生成されたILを実行
   └─ ルートオブジェクトをインスタンス化
   └─ 子要素を再帰的に生成

5. 後処理
   └─ NameScopeへの登録
   └─ バインディングの解決
   └─ リソース参照の解決
```

### フローチャート

```mermaid
flowchart TD
    A[Load呼び出し] --> B{文字列入力?}
    B -->|Yes| C[UTF8でStreamに変換]
    B -->|No| D[Streamをそのまま使用]
    C --> E[RuntimeXamlLoaderDocument構築]
    D --> E
    E --> F[RuntimeXamlLoaderConfiguration構築]
    F --> G[AvaloniaXamlIlRuntimeCompiler.Load]
    G --> H[XAMLパース]
    H --> I[AST構築]
    I --> J[IL生成]
    J --> K[オブジェクト生成]
    K --> L{rootInstance指定?}
    L -->|Yes| M[既存インスタンスに適用]
    L -->|No| N[新規インスタンス作成]
    M --> O[後処理]
    N --> O
    O --> P[結果返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | XML構文検証 | XAMLはwell-formedなXMLである必要がある | Load呼び出し時 |
| BR-002 | 名前空間解決 | clr-namespaceはlocalAssemblyで解決される | 名前空間参照時 |
| BR-003 | DesignMode | designMode=trueの場合、デザイン時プロパティを評価 | デザイナー使用時 |
| BR-004 | 動的コード警告 | [RequiresUnreferencedCode]でトリミング警告 | AOT/トリミング時 |

### 計算ロジック

該当なし

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ArgumentNullException | xamlがnullの場合 | 有効なXAML文字列を渡す |
| - | XamlLoadException | XAMLの構文エラー | XAMLの構文を修正 |
| - | XamlX.TypeSystemException | 型が見つからない場合 | 名前空間とアセンブリを確認 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- XamlILによるIL生成で高速なオブジェクト生成
- 繰り返し使用されるXAMLはキャッシュ可能

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

- 信頼できないソースからのXAMLは実行しないこと
- XAMLインジェクション攻撃に注意

## 備考

Parse<T>メソッドは型安全なラッパーを提供する。LoadGroupは複数XAMLの一括読み込みをサポート。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | AvaloniaRuntimeXamlLoader.cs | `src/Markup/Avalonia.Markup.Xaml.Loader/AvaloniaRuntimeXamlLoader.cs` | Loadメソッド（25-33行目, 45-48行目）: メインエントリーポイント |

**主要処理フロー**:
1. **27行目**: nullチェック
2. **29-31行目**: UTF8でMemoryStreamに変換
3. **47-48行目**: AvaloniaXamlIlRuntimeCompiler.Loadを呼び出し

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | RuntimeXamlLoaderDocument.cs | `src/Markup/Avalonia.Markup.Xaml/RuntimeXamlLoaderDocument.cs` | ドキュメント定義 |
| 2-2 | RuntimeXamlLoaderConfiguration.cs | `src/Markup/Avalonia.Markup.Xaml/RuntimeXamlLoaderConfiguration.cs` | 設定定義 |

#### Step 3: XamlILコンパイラを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | AvaloniaXamlIlRuntimeCompiler.cs | `src/Markup/Avalonia.Markup.Xaml.Loader/AvaloniaXamlIlRuntimeCompiler.cs` | コンパイラ実装 |
| 3-2 | AvaloniaXamlIlCompiler.cs | `src/Markup/Avalonia.Markup.Xaml.Loader/CompilerExtensions/AvaloniaXamlIlCompiler.cs` | コンパイラ拡張 |

#### Step 4: 静的XAMLローダーを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | AvaloniaXamlLoader.cs | `src/Markup/Avalonia.Markup.Xaml/AvaloniaXamlLoader.cs` | 静的ローダー |

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

```
AvaloniaRuntimeXamlLoader
    │
    ├─ Load(string xaml, ...)
    │      ├─ Encoding.UTF8.GetBytes
    │      ├─ new MemoryStream
    │      └─ Load(Stream, ...)
    │
    ├─ Load(Stream stream, ...)
    │      ├─ new RuntimeXamlLoaderDocument
    │      ├─ new RuntimeXamlLoaderConfiguration
    │      └─ AvaloniaXamlIlRuntimeCompiler.Load
    │
    ├─ Load(RuntimeXamlLoaderDocument, RuntimeXamlLoaderConfiguration)
    │      └─ AvaloniaXamlIlRuntimeCompiler.Load
    │
    ├─ LoadGroup(IReadOnlyCollection<RuntimeXamlLoaderDocument>, ...)
    │      └─ AvaloniaXamlIlRuntimeCompiler.LoadGroup
    │
    └─ Parse<T>(string xaml, ...)
           └─ Load(xaml, ...)
```

### データフロー図

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

XAML文字列/Stream ──────▶ AvaloniaRuntimeXamlLoader ──▶ オブジェクトグラフ
                              │
                              ▼
                        RuntimeXamlLoaderDocument
                              │
                              ▼
                        AvaloniaXamlIlRuntimeCompiler
                              │
                              ├─ XAMLパース
                              ├─ AST構築
                              ├─ IL生成
                              └─ オブジェクト生成
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AvaloniaRuntimeXamlLoader.cs | `src/Markup/Avalonia.Markup.Xaml.Loader/AvaloniaRuntimeXamlLoader.cs` | ソース | ランタイムローダー |
| AvaloniaXamlIlRuntimeCompiler.cs | `src/Markup/Avalonia.Markup.Xaml.Loader/AvaloniaXamlIlRuntimeCompiler.cs` | ソース | ILコンパイラ |
| AvaloniaXamlIlCompiler.cs | `src/Markup/Avalonia.Markup.Xaml.Loader/CompilerExtensions/AvaloniaXamlIlCompiler.cs` | ソース | コンパイラ拡張 |
| RuntimeXamlLoaderDocument.cs | `src/Markup/Avalonia.Markup.Xaml/RuntimeXamlLoaderDocument.cs` | ソース | ドキュメント定義 |
| RuntimeXamlLoaderConfiguration.cs | `src/Markup/Avalonia.Markup.Xaml/RuntimeXamlLoaderConfiguration.cs` | ソース | 設定定義 |
| AvaloniaXamlLoader.cs | `src/Markup/Avalonia.Markup.Xaml/AvaloniaXamlLoader.cs` | ソース | 静的ローダー |
| XamlLoadException.cs | `src/Markup/Avalonia.Markup.Xaml/XamlLoadException.cs` | ソース | 例外定義 |
