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

## 概要

AppX/MSIXパッケージをWindows SDKツールで検証するPowerShellスクリプトの設計書である。

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

本バッチは、Windows Terminal AppX/MSIXパッケージの品質検証を行う。パッケージをアンパックし、マニフェストとリソース（PRI）を検査して、必要なDLL、実行ファイル、リソースが正しく含まれていることを確認する。VCLibsへの不正な依存関係やバンドルの有無もチェックする。

**業務上の目的・背景**：AppXパッケージの構成ミスはユーザーに届いてから初めて発覚する場合があり、リリース後の修正は非常にコストが高い。ビルドパイプライン内でパッケージ内容を自動検証することで、不完全なパッケージの配布を防止する。特にInProcessServerの登録漏れ、VCLibsの混入、リソースマージの不備は致命的な問題となるため、これらを事前に検出する。

**バッチの実行タイミング**：CI/CDパイプラインのパッケージング後、リリース前の検証段階で実行される。

**主要な処理内容**：
1. AppX/MSIXパッケージのアンパック（MakeAppx.exe使用）
2. リソースPRIのXMLダンプ（MakePri.exe使用）
3. InProcessServerの検証（必須DLL 5つの存在確認）
4. VCLibs依存関係の検証（デスクトップ版・AppX版ともに含まれてはならない）
5. VCLibs DLLファイルの存在検証（vcruntime140.dll等が含まれてはならない）
6. App.xbfリソースの存在確認（リソースマージの正常性確認）
7. wt.exe/wtd.exe、OpenConsole.exeの存在確認
8. 検証完了後の一時ディレクトリのクリーンアップ

**前後の処理との関連**：Create-AppxBundle.ps1（No.45）で生成されたパッケージ、またはビルドで生成された個別AppXに対して実行される。

**影響範囲**：検証のみを行い、パッケージ自体は変更しない。検証失敗時はThrowによりビルドパイプラインが停止する。

## バッチ種別

パッケージ検証（品質ゲート）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（ビルド後検証） |
| 実行時刻 | N/A |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | CI/CDパイプライン |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| AppX/MSIXパッケージの存在 | Pathで指定されたパッケージファイルが存在すること |
| Windows SDKの存在 | MakeAppx.exeとMakePri.exeを含むWindows SDKがインストールされていること |

### 実行可否判定

必須パラメータ（Path）が指定され、Windows SDKパスが有効であること。

## 入力仕様

### 入力パラメータ

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

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| AppX/MSIXパッケージ | .appx / .msix | 検証対象のアプリケーションパッケージ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | 検証結果（Verbose出力） |
| 例外 | Throw | 検証失敗時のエラーメッセージ |

### 出力ファイル仕様

本バッチはファイル出力を行わない。

## 処理フロー

### 処理シーケンス

```
1. Windows SDKパスの検証
   └─ MakeAppx.exeとMakePri.exeのパスを構築
2. AppXパッケージのアンパック（Expand-ApplicationPackage関数）
   └─ 一時ディレクトリを作成し、MakeAppx.exe unpack /nv /oで展開
3. リソースPRIのダンプ
   └─ MakePri.exe dump /if resources.pri /of resources.pri.xml
4. InProcessServerの検証
   └─ 必須DLL: TerminalApp.dll, Microsoft.Terminal.Control.dll,
       Microsoft.Terminal.Settings.Editor.dll, Microsoft.Terminal.Settings.Model.dll,
       TerminalConnection.dll
5. VCLibs依存関係の検証
   └─ 5a. デスクトップ版VCLibs依存関係がないこと
   └─ 5b. AppX版VCLibs依存関係がないこと
   └─ 5c. デスクトップ版VCLibs DLLが含まれていないこと
   └─ 5d. AppX版VCLibs DLLが含まれていないこと
6. App.xbfリソースの存在確認
   └─ resources.pri.xml内にFiles/App.xbfリソースが存在すること
7. 実行ファイルの存在確認
   └─ wt.exeまたはwtd.exeが存在すること
   └─ OpenConsole.exeが存在すること
8. クリーンアップ（Finally）
   └─ 一時ディレクトリの削除（Remove-Item -Recurse -Force）
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B{Windows SDK存在?}
    B -->|なし| C[エラー終了]
    B -->|あり| D[AppXアンパック]
    D --> E[PRI XMLダンプ]
    E --> F{InProcessServer検証}
    F -->|失敗| G[Throw: DLL未検出]
    F -->|成功| H{VCLibs検証}
    H -->|失敗| I[Throw: VCLibs検出]
    H -->|成功| J{App.xbf存在?}
    J -->|なし| K[Throw: リソース未検出]
    J -->|あり| L{wt.exe/wtd.exe存在?}
    L -->|なし| M[Throw: EXE未検出]
    L -->|あり| N{OpenConsole.exe存在?}
    N -->|なし| O[Throw: OpenConsole未検出]
    N -->|あり| P[検証成功]
    G --> Q[クリーンアップ]
    I --> Q
    K --> Q
    M --> Q
    O --> Q
    P --> Q
    Q --> R[バッチ終了]
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| Exit 1 | SDK未検出 | WindowsKitPathにSDKが存在しない | Windows SDKをインストール |
| Throw | アンパック失敗 | MakeAppx.exe unpackが失敗 | パッケージファイルの整合性を確認 |
| Throw | PRIダンプ失敗 | MakePri.exe dumpが失敗 | resources.priの存在を確認 |
| Throw | InProcessServer不足 | 必須DLL（5つ）のいずれかが未登録 | ビルド構成を確認 |
| Throw | VCLibsデスクトップ依存 | VCLibs.UWPDesktopへの依存が存在 | パッケージ依存関係を確認 |
| Throw | VCLibsAppX依存 | VCLibs AppXへの依存が存在 | パッケージ依存関係を確認 |
| Throw | VCLibsデスクトップDLL混入 | vcruntime140.dllがパッケージに含まれる | ビルド設定を確認 |
| Throw | VCLibsAppX DLL混入 | vcruntime140_app.dllがパッケージに含まれる | ビルド設定を確認 |
| Throw | App.xbf未検出 | resources.pri内にApp.xbfが存在しない | リソースマージ処理を確認 |
| Throw | EXE未検出 | wt.exe/wtd.exeが存在しない | WAPパッケージングを確認 |
| Throw | OpenConsole未検出 | OpenConsole.exeが存在しない | WAPパッケージングを確認 |

### リトライ仕様

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

### 障害時対応

Throwメッセージにより具体的な失敗原因が示される。ビルド設定、パッケージ依存関係、リソースマージ処理を確認してパッケージを再生成する。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A（読み取り専用） |
| コミットタイミング | N/A |
| ロールバック条件 | N/A |

## パフォーマンス要件

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

## 排他制御

読み取り専用の検証処理であり、排他制御は不要。ただし一時ディレクトリの競合を避けるため、異なる一時パスが使用される。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| Verbose | パッケージ展開時 | "Expanding $Path" |
| Verbose | 展開完了時 | "Expanded to $AppxPackageRootPath" |
| Verbose | InProcessServer確認時 | "InProc Servers: $inProcServers" |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 検証失敗 | N/A | CI/CDパイプライン |

## 備考

- Try-Finallyブロックにより、検証の成否に関わらず一時ディレクトリは必ず削除される。
- Expand-ApplicationPackage関数内で`/nv`（no validation）オプションを使用してアンパックしている。これはパッケージ署名の検証をスキップする。
- VCLibsの検証はデバッグ版（*.Debug*、*d.dll）にも対応している。
- ValueFromPipeline=$trueが指定されているため、パイプラインからの入力に対応している。
- $ErrorActionPreference = "Stop"が設定されている。
- ソースファイルパス: `build/scripts/Test-WindowsTerminalPackage.ps1`
