# バッチ設計書 48-Test-WindowsTerminalPackage.ps1

## 概要

本ドキュメントは、AppX/MSIXパッケージをWindows SDKツールで検証するPowerShellスクリプト「Test-WindowsTerminalPackage.ps1」のバッチ設計書である。

### 本バッチの処理概要

AppX/MSIXパッケージを展開し、マニフェストの内容とリソースファイルの構成を複数の観点から検証する。InProcessServerの登録状況、VCLibsの依存関係・ファイル含有状態、リソースマージ結果、必須実行ファイルの存在を確認し、問題がある場合はThrowでエラーを発生させる。

**業務上の目的・背景**：Windows TerminalのAppXパッケージは、正しいマニフェスト構成とリソース統合が行われていないとインストール・起動に失敗する。特にInProcessServerの登録漏れ、VCLibsの二重バンドル、リソースマージの不備は頻出するリリースブロッカーである。本バッチはパッケージの品質ゲートとして機能し、リリース前に自動的にこれらの問題を検出する。

**バッチの実行タイミング**：CI/CDパイプラインにおいて、AppXパッケージ生成後の検証工程で実行される。

**主要な処理内容**：
1. MakeAppx.exeでAppX/MSIXパッケージを一時ディレクトリに展開する
2. MakePri.exeでresources.priをXMLにダンプする
3. AppxManifest.xmlの検証
   - 必須InProcessServer DLL（TerminalApp.dll等5種）の登録確認
4. VCLibs検証
   - デスクトップ版VCLibsの依存関係がないこと
   - AppX版VCLibsの依存関係がないこと
   - デスクトップ版VCLibs DLLがパッケージに含まれていないこと
   - AppX版VCLibs DLLがパッケージに含まれていないこと
5. リソース検証
   - resources.pri内にApp.xbf（TerminalAppプロジェクト）が含まれていること
6. 必須実行ファイル検証
   - wt.exeまたはwtd.exeが存在すること
   - OpenConsole.exeが存在すること
7. 一時ディレクトリのクリーンアップ（Finally）

**前後の処理との関連**：ビルドプロセスにおいてAppXパッケージ生成後に実行される品質検証バッチ。Create-AppxBundle.ps1（No.45）の前後いずれかで実行される。

**影響範囲**：パッケージの品質ゲートとして機能するため、検証失敗はリリースのブロックに直結する。

## バッチ種別

テスト実行（パッケージ検証）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（ビルド時・リリース時） |
| 実行時刻 | ビルドプロセス依存 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | CI/CDパイプライン／手動 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Windows SDKの存在 | WindowsKitPathで指定されたパスにWindows SDKがインストールされていること |
| MakeAppx.exeの存在 | Windows SDK配下のx86\MakeAppx.exeが存在すること |
| MakePri.exeの存在 | Windows SDK配下のx86\MakePri.exeが存在すること |
| AppXパッケージの存在 | Pathで指定されたパスに.appxまたは.msixファイルが存在すること |

### 実行可否判定

Windows SDKの存在チェックを行い、存在しない場合はWrite-ErrorでExit 1。パッケージ展開失敗時やPRIダンプ失敗時はThrowでエラーを発生させる。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| Path | string | Yes | なし | 検証対象の.appx/.msixファイルパス。パイプライン入力対応（ValueFromPipeline） |
| WindowsKitPath | string | No | C:\Program Files (x86)\Windows Kits\10\bin\10.0.22621.0 | Windows SDKのパス |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| AppX/MSIXパッケージ | .appx/.msix | 検証対象のWindows Terminalパッケージ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | 検証成功時は出力なし。失敗時はThrow例外メッセージ |

### 出力ファイル仕様

本スクリプトはファイル出力を行わない。検証結果は例外（Throw）またはスクリプトの正常完了で示される。

| 項目 | 内容 |
|-----|------|
| ファイル名 | 該当なし |
| 出力先 | 該当なし |
| 文字コード | 該当なし |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. Windows SDK存在チェック
   └─ WindowsKitPath配下の存在確認。存在しない場合はWrite-ErrorでExit 1
2. SDKツールパス構築
   └─ $makeAppx = "$WindowsKitPath\x86\MakeAppx.exe"
   └─ $makePri = "$WindowsKitPath\x86\MakePri.exe"
3. パッケージ展開（Expand-ApplicationPackage関数）
   ├─ 一時ディレクトリ作成（センチネルファイル方式）
   ├─ MakeAppx.exe unpack /p {パス} /d {一時ディレクトリ} /nv /o
   └─ LASTEXITCODE確認、失敗時Throw
4. PRIダンプ
   └─ MakePri.exe dump /if resources.pri /of resources.pri.xml /o
5. マニフェスト・PRI読み込み
   └─ AppxManifest.xmlとresources.pri.xmlをXMLとして読み込み
6. InProcessServer検証
   ├─ TerminalApp.dll
   ├─ Microsoft.Terminal.Control.dll
   ├─ Microsoft.Terminal.Settings.Editor.dll
   ├─ Microsoft.Terminal.Settings.Model.dll
   └─ TerminalConnection.dll
7. VCLibs検証（依存関係・ファイル存在の4パターン）
   ├─ デスクトップ版VCLibs依存関係なし
   ├─ AppX版VCLibs依存関係なし
   ├─ デスクトップ版VCLibs DLLなし
   └─ AppX版VCLibs DLLなし
8. リソース検証
   └─ resources.pri内のFiles/App.xbfの存在確認
9. 実行ファイル検証
   ├─ wt.exeまたはwtd.exeの存在
   └─ OpenConsole.exeの存在
10. クリーンアップ（Finally）
    └─ 一時ディレクトリの再帰削除
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B{Windows SDK存在?}
    B -->|なし| C[エラー・Exit 1]
    B -->|あり| D[MakeAppx.exe unpackでパッケージ展開]
    D --> E{展開成功?}
    E -->|失敗| F[Throw]
    E -->|成功| G[MakePri.exe dumpでPRI展開]
    G --> H{PRI展開成功?}
    H -->|失敗| I[Throw]
    H -->|成功| J[AppxManifest.xml/PRI XML読み込み]
    J --> K{InProcessServer 5DLL登録確認}
    K -->|不足あり| L[Throw]
    K -->|OK| M{VCLibs 4パターン検証}
    M -->|問題あり| N[Throw]
    M -->|OK| O{App.xbfリソース確認}
    O -->|なし| P[Throw]
    O -->|あり| Q{wt.exe/wtd.exe存在?}
    Q -->|なし| R[Throw]
    Q -->|あり| S{OpenConsole.exe存在?}
    S -->|なし| T[Throw]
    S -->|あり| U[検証成功]
    U --> V[Finally: 一時ディレクトリ削除]
    F --> V
    I --> V
    L --> V
    N --> V
    P --> V
    R --> V
    T --> V
    V --> W[バッチ終了]
```

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

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

本バッチはデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| Exit 1 | Windows SDK未検出 | WindowsKitPathにSDKが存在しない | Windows SDKをインストールする |
| Throw | パッケージ展開失敗 | MakeAppx.exe unpackが失敗 | AppXファイルの整合性を確認する |
| Throw | PRIダンプ失敗 | MakePri.exe dumpが失敗 | resources.priの整合性を確認する |
| Throw | InProcessServer不足 | 必須5DLLのいずれかがマニフェストに未登録 | GenerateAppxFromManifest.ps1の実行結果を確認する |
| Throw | デスクトップVCLibsファイル含有 | vcruntime140.dll/vcruntime140d.dllが存在 | ビルド設定を確認しVCLibsバンドルを除去する |
| Throw | デスクトップVCLibs依存関係 | PackageDependencyにUWPDesktop VCLibsが含まれる | マニフェストの依存関係を確認する |
| Throw | AppX VCLibsファイル含有 | vcruntime140_app.dll等が存在 | ビルド設定を確認する |
| Throw | AppX VCLibs依存関係 | PackageDependencyにAppX VCLibsが含まれる | マニフェストの依存関係を確認する |
| Throw | App.xbf未検出 | resources.priにApp.xbfが含まれない | リソースマージ処理を確認する |
| Throw | wt.exe/wtd.exe未検出 | パッケージにwt.exeもwtd.exeも存在しない | WAPパッケージングプロジェクトを確認する |
| Throw | OpenConsole.exe未検出 | パッケージにOpenConsole.exeが存在しない | WAPパッケージングプロジェクトを確認する |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（リトライ機構なし） |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

検証失敗はパッケージ構成の問題を示すため、ビルドプロセスの上流（AppXパッケージ生成、マニフェスト生成、リソースマージ等）を確認する必要がある。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし（読み取り専用の検証処理） |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1パッケージ |
| 目標処理時間 | 数十秒以内 |
| メモリ使用量上限 | 展開されたパッケージサイズに依存 |

## 排他制御

一時ディレクトリにランダムな名前を使用（センチネルファイル方式）。同一パッケージに対する並行実行は問題ない。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| Verbose | パッケージ展開時 | "Expanding $Path" |
| Verbose | 展開完了時 | "Expanded to $AppxPackageRootPath" |
| Verbose | InProcessServer確認時 | "InProc Servers: $inProcServers" |
| エラーログ | 検証失敗時 | Throwの例外メッセージ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 検証結果 | Throw発生時 | ビルドシステム（CI/CD） |

## 備考

- CmdletBindingが指定されており、-Verboseスイッチで詳細ログを確認できる。
- パイプライン入力（ValueFromPipeline）に対応しており、複数パッケージを連続検証可能。
- $ErrorActionPreference = "Stop"により、予期しないエラーでも即座にスクリプトが停止する。
- Try/Finallyブロックにより、検証成否に関わらず一時ディレクトリが確実にクリーンアップされる。
- MakeAppx.exe unpackの`/nv`フラグはバージョン検証をスキップし、`/o`フラグは既存ファイルの上書きを許可する。
- 必須InProcessServerリスト: TerminalApp.dll, Microsoft.Terminal.Control.dll, Microsoft.Terminal.Settings.Editor.dll, Microsoft.Terminal.Settings.Model.dll, TerminalConnection.dll
- VCLibs検証はDebug/Releaseの両バリアントをチェックしている。
- ソースファイルパス: `build/scripts/Test-WindowsTerminalPackage.ps1`
