# 機能設計書 44-AppBuilder

## 概要

本ドキュメントは、Avalonia UIフレームワークにおけるAppBuilder（アプリケーションビルダー）機能の設計仕様を定義する。AppBuilderはアプリケーションの構成と初期化を流暢なAPIで行うためのビルダークラスである。

### 本機能の処理概要

AppBuilderクラスは、Avaloniaアプリケーションの構成に必要なサブシステム（レンダリング、ウィンドウイング等）を設定し、アプリケーションを起動するためのビルダーパターンを提供する。流暢なAPI（Fluent API）により、メソッドチェーンでの設定が可能。

**業務上の目的・背景**：クロスプラットフォームアプリケーションでは、各プラットフォームに応じた初期化処理が必要となる。AppBuilderはプラットフォーム固有の初期化を抽象化し、シンプルなAPIでアプリケーション構成を可能にする。

**機能の利用シーン**：アプリケーションのエントリーポイント（Program.cs）でのアプリケーション構成、プラットフォーム固有サブシステムの設定、レンダリングエンジンの選択、デザインモード検出など。

**主要な処理内容**：
1. Applicationインスタンスのファクトリ設定
2. レンダリングサブシステムの設定
3. ウィンドウイングサブシステムの設定
4. ライフタイム管理の設定
5. サービス登録コールバックの管理
6. セットアップ完了後のアプリケーション起動

**関連システム・外部連携**：Application（アプリケーションクラス）、IClassicDesktopStyleApplicationLifetime、各種プラットフォームサブシステムと連携する。

**権限による制御**：本機能に権限による制御はない。すべてのアプリケーションで使用可能である。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | エントリーポイントで使用、画面には直接関連しない |

## 機能種別

初期化処理 / ビルダーパターン / 構成管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| TApp | Type | Yes | Applicationの型パラメータ | Application派生クラス |
| Instance | Application | No | 既存のApplicationインスタンス | - |
| RuntimePlatform | IRuntimePlatform | No | ランタイムプラットフォーム実装 | - |

### 入力データソース

- コード: AppBuilder.Configure<App>()からのメソッドチェーン
- プラットフォーム: 自動検出されるプラットフォーム情報

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Instance | Application | 構成されたApplicationインスタンス |
| WindowingSubsystemName | string | ウィンドウイングサブシステム名 |
| RenderingSubsystemName | string | レンダリングサブシステム名 |
| RuntimePlatform | IRuntimePlatform | ランタイムプラットフォーム |

### 出力先

- AvaloniaLocator: 各種サービスの登録

## 処理フロー

### 処理シーケンス

```
1. AppBuilder.Configure<TApp>()
   └─ AppBuilderインスタンス作成
   └─ Applicationファクトリの設定

2. UseXxx() メソッドチェーン
   └─ 各サブシステム初期化子の登録

3. SetupWithoutStarting() または Start()
   └─ RuntimePlatformServices初期化
   └─ RenderingSubsystem初期化
   └─ WindowingSubsystem初期化
   └─ Applicationインスタンス作成
   └─ Application.RegisterServices()

4. Start() の場合
   └─ ライフタイム開始
```

### フローチャート

```mermaid
flowchart TD
    A[Configure<TApp>] --> B[UseWindowingSubsystem]
    B --> C[UseRenderingSubsystem]
    C --> D[その他のUseXxx設定]
    D --> E{Start or Setup?}
    E -->|SetupWithoutStarting| F[Setup実行]
    E -->|Start| G[Setup実行]
    F --> H[完了 - 手動でライフタイム開始]
    G --> I[ライフタイム開始]
    I --> J[アプリケーション実行]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 重複Setup禁止 | 一度Setupを呼び出したら再呼び出し不可 | Setup後 |
| BR-002 | サブシステム必須 | レンダリングとウィンドウイングは必須 | Start時 |
| BR-003 | デザインモード検出 | IsDesignModeがtrueの場合、一部初期化をスキップ | デザイン時 |

### 計算ロジック

特記すべき計算ロジックなし。

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvalidOperationException | 重複Setup呼び出し | Setupは1回のみ |
| - | Exception | サブシステム初期化失敗 | サブシステム設定を確認 |

### リトライ仕様

アプリケーション初期化にリトライは適用されない。

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

トランザクション管理は不要。

## パフォーマンス要件

- Setup処理は500ms以内

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

特になし。

## 備考

- .NET Generic Hostとの統合も可能
- プラットフォーム拡張メソッドで各OS固有設定を追加

---

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

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

### 推奨読解順序

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

AppBuilderクラスが管理するデータを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | フィールド | `src/Avalonia.Controls/AppBuilder.cs` | 15-25行目。初期化子リスト、ファクトリ等 |
| 1-2 | プロパティ | `src/Avalonia.Controls/AppBuilder.cs` | 28-60行目。Instance、サブシステム名等 |

**読解のコツ**: _appFactory、_optionsInitializers、_afterPlatformServicesSetupCallbackがビルダーの核心。

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

ビルダーの開始点を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Configure static | `src/Avalonia.Controls/AppBuilder.cs` | 72-83行目。AppBuilderインスタンス作成 |
| 2-2 | Configure instance | `src/Avalonia.Controls/AppBuilder.cs` | 91-98行目。ファクトリ設定 |

**主要処理フロー**:
1. **73-74行目**: 既存インスタンスがあればエラー
2. **82行目**: _appFactoryにファクトリ関数を設定

#### Step 3: 設定メソッドを理解する

流暢APIの各種設定メソッド。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | AfterSetup | `src/Avalonia.Controls/AppBuilder.cs` | 110-116行目。セットアップ後コールバック |
| 3-2 | AfterPlatformServicesSetup | `src/Avalonia.Controls/AppBuilder.cs` | 125-131行目。プラットフォームサービス後コールバック |
| 3-3 | AfterApplicationSetup | `src/Avalonia.Controls/AppBuilder.cs` | 140-146行目。アプリケーション設定後コールバック |
| 3-4 | UseXxx各種 | `src/Avalonia.Controls/AppBuilder.cs` | 様々なUse系メソッド |

**主要処理フロー**:
- **113-114行目**: コールバックをリストに追加し自身を返す（流暢API）

#### Step 4: Setup処理を理解する

アプリケーションセットアップの本体。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Setup | `src/Avalonia.Controls/AppBuilder.cs` | 191-248行目。セットアップ処理 |
| 4-2 | SetupWithoutStarting | `src/Avalonia.Controls/AppBuilder.cs` | 264-269行目。起動なしセットアップ |
| 4-3 | Start | `src/Avalonia.Controls/AppBuilder.cs` | 275-280行目。セットアップと起動 |

**主要処理フロー**:
- **199-203行目**: 重複Setup防止チェック
- **208行目**: OptionsInitializers実行
- **211-217行目**: レンダリングサブシステム初期化
- **220-226行目**: ウィンドウイングサブシステム初期化
- **232行目**: Applicationインスタンス作成
- **237行目**: Application.RegisterServices()呼び出し
- **240行目**: Application.Initialize()呼び出し
- **245行目**: AfterSetupコールバック実行

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

```
Program.Main()
    │
    └─ AppBuilder.Configure<App>()
           │
           ├─ UseXxx() (メソッドチェーン)
           │      ├─ UseSkia
           │      ├─ UseWin32 / UseX11 / UseMacOS
           │      └─ その他
           │
           └─ Start(lifetime) または SetupWithoutStarting()
                  │
                  └─ Setup()
                         │
                         ├─ RuntimePlatformServices初期化
                         ├─ RenderingSubsystem初期化
                         ├─ WindowingSubsystem初期化
                         ├─ _appFactory() → Application作成
                         ├─ Application.RegisterServices()
                         ├─ Application.Initialize()
                         ├─ AfterApplicationSetupコールバック
                         └─ AfterSetupコールバック
```

### データフロー図

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

Configure<App> ────────▶ AppBuilder作成 ────────────────▶ AppBuilder
                              │
UseXxx設定 ────────────────▶ │
                              │
                         Setup
                              │
                    ┌─────────┼─────────┐
                    ▼         ▼         ▼
             Rendering   Windowing   Runtime
                    │         │         │
                    └─────────┴─────────┘
                              │
                              ▼
                    Application作成
                              │
                              ▼
                    [初期化完了したApplication]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AppBuilder.cs | `src/Avalonia.Controls/AppBuilder.cs` | ソース | AppBuilderクラスの実装 |
| Application.cs | `src/Avalonia.Controls/Application.cs` | ソース | Applicationクラス |
| AppBuilderDesktopExtensions.cs | `src/Avalonia.Controls/AppBuilderDesktopExtensions.cs` | ソース | デスクトップ拡張メソッド |
| IRuntimePlatform.cs | `src/Avalonia.Base/Platform/IRuntimePlatform.cs` | ソース | ランタイムプラットフォームインターフェース |
