# 機能設計書 88-動的プロファイル生成(Visual Studio)

## 概要

本ドキュメントは、Windows Terminal がインストール済みの Visual Studio インスタンスを検出し、Developer Command Prompt および Developer PowerShell 用のプロファイルを動的に生成する機能を記述する。

### 本機能の処理概要

**業務上の目的・背景**：Visual Studio の Developer Command Prompt（VsDevCmd.bat）や Developer PowerShell（VsDevShell.dll）は、C++ やその他のビルドツールを使った開発に不可欠である。本機能はインストール済みの Visual Studio を自動検出し、対応する開発者環境プロファイルを生成することで、ワンクリックで開発環境にアクセスできるようにする。

**機能の利用シーン**：Visual Studio がインストールされた環境で Windows Terminal を起動した際に自動的にプロファイルが生成される。複数バージョンの Visual Studio がインストールされている場合、最新バージョンのプロファイルのみが表示され、それ以外は非表示（hidden）で生成される。

**主要な処理内容**：
1. VsSetupConfiguration COM API を使用してインストール済み Visual Studio インスタンスを列挙
2. 各インスタンスに対して VsDevCmd（コマンドプロンプト版）と VsDevShell（PowerShell版）のプロファイルを生成
3. 最新バージョン以外のインスタンスのプロファイルは非表示に設定
4. VsDevCmd.bat / VsDevShell.dll の存在確認によるバリデーション

**関連システム・外部連携**：Visual Studio Setup Configuration COM API（ISetupConfiguration）。

**権限による制御**：特別な権限は不要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | バックグラウンド処理。直接の関連画面はない |

## 機能種別

データ連携 / 自動検出

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| profiles | std::vector<winrt::com_ptr<Profile>>& | Yes | 生成プロファイル格納先 | - |

### 入力データソース

- Visual Studio Setup Configuration API（VsSetupConfiguration::QueryInstances()）
- VsDevCmd.bat：`{VS_InstallPath}\Common7\Tools\VsDevCmd.bat`
- VsDevShell.dll：`{VS_InstallPath}\Common7\Tools\Microsoft.VisualStudio.DevShell.dll`（VS 16.2以上）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Profile | winrt::com_ptr<Profile> | 各 VS インスタンス用の Developer Command Prompt / PowerShell プロファイル |

### 出力先

profiles ベクタに追加。

## 処理フロー

### 処理シーケンス

```
1. VisualStudioGenerator::GenerateProfiles() が呼び出される
2. VsSetupConfiguration::QueryInstances() で VS インスタンスを列挙
3. 各インスタンスに対して：
   └─ VsDevCmdGenerator::GenerateProfiles() で Developer Command Prompt プロファイル生成
   └─ VsDevShellGenerator::GenerateProfiles() で Developer PowerShell プロファイル生成
4. 最初のインスタンス（最新）は表示、以降は hidden=true
```

### フローチャート

```mermaid
flowchart TD
    A[GenerateProfiles 開始] --> B[QueryInstances で VS 列挙]
    B --> C{各インスタンス}
    C --> D[VsDevCmdGenerator - コマンドプロンプト]
    D --> E[VsDevShellGenerator - PowerShell]
    E --> F{最初のインスタンス?}
    F -->|Yes| G[hidden=false]
    F -->|No| H[hidden=true]
    G --> C
    H --> C
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-88-01 | 最新バージョン優先 | インスタンスは最新→古い順。最新のみ表示 | 常時 |
| BR-88-02 | VsDevCmd バリデーション | VsDevCmd.bat が存在する場合のみプロファイル生成（VS 15.0+） | VsDevCmd 生成時 |
| BR-88-03 | VsDevShell バリデーション | VsDevShell.dll が存在し VS 16.2 以上の場合のみプロファイル生成 | VsDevShell 生成時 |
| BR-88-04 | GUID シード | "VsDevCmd" + instanceId / "VsDevShell" + instanceId でプロファイル GUID を生成 | 常時 |

### 計算ロジック

該当なし。

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | COM API 失敗 | VS Setup Configuration が利用不可 | 空のプロファイルリストを返す |
| - | バリデーション失敗 | VsDevCmd.bat / VsDevShell.dll が存在しない | そのプロファイルをスキップ |

### リトライ仕様

リトライなし。

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

該当なし。

## パフォーマンス要件

COM API 呼び出しのため若干の遅延が発生する可能性がある。

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

Visual Studio のインストールパスは Setup Configuration API から取得した信頼できるパスを使用。

## 備考

- 名前空間：`Windows.Terminal.VisualStudio`
- VsDevCmd アイコン：`ms-appx:///ProfileIcons/vs-cmd.png`
- VsDevShell アイコン：`ms-appx:///ProfileIcons/vs-powershell.png`
- ジェネレータアイコン：`ms-appx:///ProfileGeneratorIcons/VisualStudio.png`

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | VisualStudioGenerator.h | `src/cascadia/TerminalSettingsModel/VisualStudioGenerator.h` | VisualStudioGenerator クラスと IVisualStudioProfileGenerator 内部インターフェース（26-40行目） |

**読解のコツ**: VisualStudioGenerator は2つのサブジェネレータ（VsDevCmd / VsDevShell）に処理を委譲する。IVisualStudioProfileGenerator が内部インターフェース。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | VisualStudioGenerator.cpp | `src/cascadia/TerminalSettingsModel/VisualStudioGenerator.cpp` | GenerateProfiles メソッド（30-45行目） |

**主要処理フロー**:
1. **32行目**: VsSetupConfiguration::QueryInstances() でインスタンス列挙
2. **34-35行目**: VsDevCmdGenerator と VsDevShellGenerator を作成
3. **38-44行目**: 各インスタンスを走査。hidden フラグは最初のインスタンス以外 true

#### Step 3: サブジェネレータを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | VsDevCmdGenerator.h | `src/cascadia/TerminalSettingsModel/VsDevCmdGenerator.h` | Developer Command Prompt ジェネレータ。IsInstanceValid / GetProfileGuidSeed / GetDevCmdScriptPath メソッド |
| 3-2 | VsDevShellGenerator.h | `src/cascadia/TerminalSettingsModel/VsDevShellGenerator.h` | Developer PowerShell ジェネレータ。バージョン16.2以上の要件（32行目） |

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

```
VisualStudioGenerator::GenerateProfiles (30行目)
    │
    ├─ VsSetupConfiguration::QueryInstances()
    │
    ├─ VsDevCmdGenerator::GenerateProfiles (各インスタンス)
    │      ├─ IsInstanceValid (VsDevCmd.bat 存在確認)
    │      ├─ GetProfileName / GetProfileCommandLine
    │      └─ CreateDynamicProfile
    │
    └─ VsDevShellGenerator::GenerateProfiles (各インスタンス)
           ├─ IsInstanceValid (VS 16.2+ && VsDevShell.dll 存在確認)
           ├─ GetProfileName / GetProfileCommandLine
           └─ CreateDynamicProfile
```

### データフロー図

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

VS Setup Config API ───▶ QueryInstances ──▶ VsSetupInstance[]
                                                   │
                                                   ├──▶ VsDevCmdGenerator → DevCmd Profile
                                                   │
                                                   └──▶ VsDevShellGenerator → DevShell Profile
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| VisualStudioGenerator.h | `src/cascadia/TerminalSettingsModel/VisualStudioGenerator.h` | ヘッダ | メインジェネレータクラス定義 |
| VisualStudioGenerator.cpp | `src/cascadia/TerminalSettingsModel/VisualStudioGenerator.cpp` | ソース | メインジェネレータ実装 |
| VsDevCmdGenerator.h | `src/cascadia/TerminalSettingsModel/VsDevCmdGenerator.h` | ヘッダ | Developer Command Prompt ジェネレータ |
| VsDevCmdGenerator.cpp | `src/cascadia/TerminalSettingsModel/VsDevCmdGenerator.cpp` | ソース | VsDevCmd プロファイル生成実装 |
| VsDevShellGenerator.h | `src/cascadia/TerminalSettingsModel/VsDevShellGenerator.h` | ヘッダ | Developer PowerShell ジェネレータ |
| VsDevShellGenerator.cpp | `src/cascadia/TerminalSettingsModel/VsDevShellGenerator.cpp` | ソース | VsDevShell プロファイル生成実装 |
| VsSetupConfiguration.h | `src/cascadia/TerminalSettingsModel/VsSetupConfiguration.h` | ヘッダ | VS Setup Configuration API ラッパー |
