# 画面設計書 11-ビルドイベントプロパティページ

## 概要

本ドキュメントは、F# プロジェクトのビルドイベントを設定するためのプロパティページ「ビルドイベントプロパティページ」の画面設計を記載します。

### 本画面の処理概要

**業務上の目的・背景**：ビルドイベントプロパティページは、F# プロジェクトのビルドプロセスの前後に実行されるカスタムコマンドを設定するための画面です。この機能により、開発者はビルド前にリソースの準備、ビルド後にデプロイメントスクリプトの実行、テストの自動実行などの自動化タスクを設定できます。MSBuild タスクと連携し、継続的インテグレーション/デリバリー（CI/CD）パイプラインの一部として機能します。

**画面へのアクセス方法**：Visual Studio のソリューションエクスプローラーで F# プロジェクトを右クリックし、「プロパティ」を選択します。プロジェクトプロパティウィンドウが開いたら、「ビルド イベント」タブをクリックして本画面にアクセスします。

**主要な操作・処理内容**：
1. ビルド前イベントコマンドラインの入力・編集：ビルドが開始される前に実行されるコマンドを設定
2. ビルド後イベントコマンドラインの入力・編集：ビルドが完了した後に実行されるコマンドを設定
3. 「Edit Pre-build...」ボタンによる詳細編集：BuildEventCommandLineDialog を使用した高度なコマンド編集（マクロ挿入対応）
4. 「Edit Post-build...」ボタンによる詳細編集：同様に BuildEventCommandLineDialog を使用した高度なコマンド編集
5. ビルド後イベント実行条件の選択：Always / On successful build / When the build updates the project output から選択

**画面遷移**：
- この画面への遷移元：プロジェクトプロパティの他のタブ（アプリケーション、ビルド、デバッグ、参照パス）
- この画面からの遷移先：ビルドイベントコマンドラインダイアログ（Edit Pre-build... / Edit Post-build... ボタン押下時）

**権限による表示制御**：プロジェクトファイルへの書き込み権限がない場合、設定値の変更は反映されません。ソース管理下のプロジェクトでは、変更時にファイルのチェックアウトが必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 48 | MSBuildタスク（Fsc） | 主機能 | ビルド前後のコマンド設定による MSBuild タスクの制御 |

## 画面種別

設定（プロパティページ）

## URL/ルーティング

Visual Studio 内蔵のプロパティページとして動作するため、URL/ルーティングは存在しません。
COM クラス GUID: DD84AA8F-71BB-462a-8EF8-C9992CB325B7

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 必須 | 説明 |
|--------|-----------|----------|------|------|
| PreBuildEvent | 入力 | String | いいえ | ビルド前に実行するコマンドライン |
| PostBuildEvent | 入力 | String | いいえ | ビルド後に実行するコマンドライン |
| RunPostBuildEvent | 入力 | Integer (0-2) | いいえ | ビルド後イベントの実行条件 |

## 表示項目

| コントロール名 | 種類 | 説明 | データバインド |
|---------------|------|------|----------------|
| lblPreBuildEventCommandLine | Label | 「Pre-build event command line:」ラベル | - |
| txtPreBuildEventCommandLine | TextBox | ビルド前イベントコマンド入力欄（複数行、スクロールバー付き） | PreBuildEvent |
| btnPreBuildBuilder | Button | 「Edit Pre-build ...」ボタン | - |
| lblPostBuildEventCommandLine | Label | 「Post-build event command line:」ラベル | - |
| txtPostBuildEventCommandLine | TextBox | ビルド後イベントコマンド入力欄（複数行、スクロールバー付き） | PostBuildEvent |
| btnPostBuildBuilder | Button | 「Edit Post-build ...」ボタン | - |
| lblRunPostBuildEvent | Label | 「Run the post-build event:」ラベル | - |
| cboRunPostBuildEvent | ComboBox | ビルド後イベント実行条件選択（ドロップダウンリスト） | RunPostBuildEvent |

### cboRunPostBuildEvent の選択肢

| インデックス | 表示値 | 説明 |
|-------------|--------|------|
| 0 | Always | 常に実行 |
| 1 | On successful build | ビルド成功時のみ実行 |
| 2 | When the build updates the project output | プロジェクト出力が更新された場合のみ実行 |

## イベント仕様

### 1-PreBuildBuilderButton_Click

「Edit Pre-build ...」ボタン押下時の処理。

1. 現在の txtPreBuildEventCommandLine.Text を取得
2. LaunchEventBuilder メソッドを呼び出し、BuildEventCommandLineDialog を表示
3. ダイアログでの編集結果を txtPreBuildEventCommandLine.Text に反映
4. 変更があった場合、SetDirty を呼び出しページを変更状態にする

### 2-PostBuildBuilderButton_Click

「Edit Post-build ...」ボタン押下時の処理。

1. 現在の txtPostBuildEventCommandLine.Text を取得
2. LaunchEventBuilder メソッドを呼び出し、BuildEventCommandLineDialog を表示
3. ダイアログでの編集結果を txtPostBuildEventCommandLine.Text に反映
4. 変更があった場合、SetDirty を呼び出しページを変更状態にする

### 3-ControlData による自動バインディング

PropertyControlData による自動的なプロパティバインディング：
- VsProjPropId2.VBPROJPROPID_PreBuildEvent → txtPreBuildEventCommandLine
- VsProjPropId2.VBPROJPROPID_PostBuildEvent → txtPostBuildEventCommandLine
- VsProjPropId2.VBPROJPROPID_RunPostBuildEvent → cboRunPostBuildEvent

## データベース更新仕様

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

本画面はデータベースを使用しません。設定値はプロジェクトファイル (.fsproj) に保存されます。

| 操作（イベント） | 対象ファイル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Apply（適用） | .fsproj | UPDATE | PreBuildEvent, PostBuildEvent, RunPostBuildEvent プロパティを更新 |

### プロジェクトファイル更新項目詳細

#### .fsproj ファイル

| 操作 | 項目（要素名） | 更新値・取得条件 | 備考 |
|-----|--------------|-----------------|------|
| UPDATE | PreBuildEvent | テキストボックスの内容 | PropertyGroup 内に保存 |
| UPDATE | PostBuildEvent | テキストボックスの内容 | PropertyGroup 内に保存 |
| UPDATE | RunPostBuildEvent | コンボボックスの選択値 | Always/OnBuildSuccess/OnOutputUpdated |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| PPG_BuildEventsTitle | 表示 | Build Events | ページタイトル |
| PPG_PreBuildCommandLineTitle | 表示 | Pre-build Event Command Line | Pre-build ダイアログタイトル |
| PPG_PostBuildCommandLineTitle | 表示 | Post-build Event Command Line | Post-build ダイアログタイトル |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| プロジェクトファイル書き込み権限なし | ソース管理によるチェックアウトダイアログを表示、またはエラーメッセージを表示 |
| マクロ値取得失敗 | VSErrorHandler.ThrowOnFailure により例外をスロー |
| プロジェクトリロード発生 | m_ProjectReloadedDuringCheckout フラグにより処理を遅延 |

## 備考

- ビルドイベントでは MSBuild マクロ（$(OutDir), $(ConfigurationName) など）を使用可能
- サポートされるマクロ: OutDir, ConfigurationName, ProjectName, TargetName, TargetPath, ProjectPath, ProjectFileName, TargetExt, TargetFileName, DevEnvDir, TargetDir, ProjectDir, PlatformName, ProjectExt

---

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

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

### 推奨読解順序

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

まず、プロパティページで扱うプロパティとそのバインディング方法を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | PropertyControlData.vb | `vsintegration/src/FSharp.ProjectSystem.PropertyPages/PropertyPages/PropertyControlData.vb` | PropertyControlData クラスの構造、プロパティとコントロールのバインディング方式 |
| 1-2 | VSLangProj80 | (Visual Studio SDK) | VsProjPropId2 列挙型の VBPROJPROPID_PreBuildEvent 等の定義 |

**読解のコツ**: PropertyControlData はプロジェクトプロパティとUI コントロールを結びつける重要なクラスです。コンストラクタの引数（プロパティID、プロパティ名、コントロール参照）の関係を理解してください。

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

BuildEventsPropPage クラスの構造と初期化処理を把握します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | BuildEventsPropPage.vb | `vsintegration/src/FSharp.ProjectSystem.PropertyPages/PropertyPages/BuildEventsPropPage.vb` | ページの UI 構成、ControlData プロパティによるバインディング定義 |

**主要処理フロー**:
1. **行 25-33**: New() コンストラクタ - InitializeComponent と AddChangeHandlers の呼び出し
2. **行 188-200**: ControlData プロパティ - 3つの PropertyControlData の定義（PreBuildEvent, PostBuildEvent, RunPostBuildEvent）
3. **行 148-164**: Tokens 列挙型 - 使用可能なマクロトークンの定義

#### Step 3: イベントハンドラを理解する

ボタンクリック時の処理フローを追います。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | BuildEventsPropPage.vb | `vsintegration/src/FSharp.ProjectSystem.PropertyPages/PropertyPages/BuildEventsPropPage.vb` | PreBuildBuilderButton_Click, PostBuildBuilderButton_Click の実装 |
| 3-2 | BuildEventCommandLineDialog.vb | `vsintegration/src/FSharp.ProjectSystem.PropertyPages/PropertyPages/BuildEventCommandLineDialog.vb` | ダイアログの表示とマクロ挿入機能 |

**主要処理フロー**:
- **行 260-270**: PreBuildBuilderButton_Click - LaunchEventBuilder の呼び出し
- **行 242-252**: PostBuildBuilderButton_Click - LaunchEventBuilder の呼び出し
- **行 281-311**: LaunchEventBuilder - BuildEventCommandLineDialog の生成と表示

#### Step 4: マクロ値取得を理解する

ビルドイベントで使用可能なマクロの値取得処理を追います。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | BuildEventsPropPage.vb | `vsintegration/src/FSharp.ProjectSystem.PropertyPages/PropertyPages/BuildEventsPropPage.vb` | GetTokenValue, GetTokenValues メソッドの実装 |

**主要処理フロー**:
- **行 335-358**: GetTokenValue - IVsBuildMacroInfo を通じたマクロ値の取得
- **行 319-328**: GetTokenValues - 全マクロトークンの値を一括取得

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

```
FSharpBuildEventsPropPageComClass (COM エントリポイント)
    │
    └─ BuildEventsPropPage (ユーザーコントロール)
           │
           ├─ ControlData プロパティ
           │      └─ PropertyControlData[] (プロパティバインディング)
           │
           ├─ PreBuildBuilderButton_Click
           │      └─ LaunchEventBuilder
           │             ├─ BuildEventCommandLineDialog.New()
           │             ├─ SetFormTitleText()
           │             ├─ SetTokensAndValues()
           │             │      └─ GetTokenValues()
           │             │             └─ GetTokenValue()
           │             │                    └─ IVsBuildMacroInfo.GetBuildMacroValue()
           │             └─ ShowDialog()
           │
           └─ PostBuildBuilderButton_Click
                  └─ LaunchEventBuilder (同上)
```

### データフロー図

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

ユーザー入力           BuildEventsPropPage
(コマンドライン)  ───▶  txtPreBuildEventCommandLine  ───▶  .fsproj ファイル
                       txtPostBuildEventCommandLine        (PreBuildEvent)
                                                          (PostBuildEvent)

ドロップダウン選択  ───▶  cboRunPostBuildEvent  ───▶  .fsproj ファイル
                       RunPostBuildEventSet/Get           (RunPostBuildEvent)

Edit ボタン押下   ───▶  BuildEventCommandLineDialog
                       │
                       ├─▶ マクロ選択  ───▶  $(マクロ名) 挿入
                       │
                       └─▶ OK ボタン  ───▶  コマンドライン反映
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| BuildEventsPropPage.vb | `vsintegration/src/FSharp.ProjectSystem.PropertyPages/PropertyPages/BuildEventsPropPage.vb` | ソース | ビルドイベントプロパティページ本体 |
| BuildEventsPropPage.resx | `vsintegration/src/FSharp.ProjectSystem.PropertyPages/PropertyPages/BuildEventsPropPage.resx` | リソース | UI 文字列、レイアウト定義 |
| BuildEventCommandLineDialog.vb | `vsintegration/src/FSharp.ProjectSystem.PropertyPages/PropertyPages/BuildEventCommandLineDialog.vb` | ソース | コマンドライン編集ダイアログ |
| PropPageUserControlBase.vb | `vsintegration/src/FSharp.ProjectSystem.PropertyPages/PropertyPages/PropPageUserControlBase.vb` | ソース | プロパティページ基底クラス |
| FSharpPropPageBase.vb | `vsintegration/src/FSharp.ProjectSystem.PropertyPages/PropertyPages/FSharpPropPageBase.vb` | ソース | F# プロパティページ COM 基底クラス |
| SR.vb | `vsintegration/src/FSharp.ProjectSystem.PropertyPages/` | ソース | 文字列リソースアクセサ |
