# 画面設計書 169-サポートパッケージ

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるサポートパッケージ生成機能（New-DbatoolsSupportPackage）の画面設計書です。dbatoolsモジュールの問題やバグをトラブルシューティングするための包括的な診断パッケージを作成する機能を提供します。

### 本画面の処理概要

**業務上の目的・背景**：dbatoolsコマンドで問題が発生した場合やバグ報告を行う際に、効果的なデバッグに必要なすべての環境およびランタイム情報を収集します。手動で複数の情報を収集する手間を省き、問題報告時に重要な情報が欠落しないことを保証します。

**画面へのアクセス方法**：PowerShellコマンドラインから `New-DbatoolsSupportPackage` コマンドレットを実行してアクセスします。

**主要な操作・処理内容**：
1. OS・ハードウェア情報（CPU、RAM、OSバージョン）を収集
2. PowerShellおよび.NET Framework情報を収集
3. 現在のセッションのコマンド履歴を収集
4. dbatoolsの内部メッセージとエラーログを収集
5. コンソールバッファの内容を取得
6. 読み込まれているアセンブリ情報を収集
7. すべての情報をZIPアーカイブとして出力

**画面遷移**：本機能は単独のコマンドレットとして動作します。生成されたZIPファイルをdbatoolsチームに提出します。

**権限による表示制御**：WMIアクセス権限が必要です（OS/ハードウェア情報取得のため）。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 217 | New-DbatoolsSupportPackage | 主機能 | サポートパッケージの生成 |
| 89 | Get-DbatoolsLog | 内部呼出 | dbatoolsログ取得 |
| 88 | Get-DbaCmObject | 内部呼出 | WMI情報取得 |

## 画面種別

CLI（コマンドラインインターフェース）- 診断・サポート

## URL/ルーティング

PowerShellコマンド: `New-DbatoolsSupportPackage`

## 入出力項目

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| Path | string | No | 出力先ディレクトリ（デフォルト: デスクトップまたはホームディレクトリ） |
| Variables | string[] | No | 追加で含める変数名のリスト |
| PassThru | switch | No | FileInfoオブジェクトを返す |
| EnableException | switch | No | 例外を有効化 |

### 出力項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| FullName | string | 生成されたZIPファイルの完全パス |
| Name | string | ZIPファイル名 |
| DirectoryName | string | 出力先ディレクトリパス |
| Length | long | ファイルサイズ（バイト） |
| Exists | bool | ファイルの存在確認 |
| CreationTime | DateTime | ファイル作成日時 |
| LastWriteTime | DateTime | ファイル最終更新日時 |

### ZIPアーカイブ内容

| 収集項目 | 収集元 | 説明 |
|---------|--------|------|
| Messages | Get-DbatoolsLog | dbatoolsのログメッセージ |
| Errors | Get-DbatoolsLog -Errors | dbatoolsのエラーログ |
| ConsoleBuffer | Get-ShellBuffer | コンソール画面の内容 |
| OperatingSystem | Win32_OperatingSystem | OS情報 |
| CPU | Win32_Processor | CPU情報 |
| Ram | Win32_PhysicalMemory | メモリ情報 |
| PSVersion | $PSVersionTable | PowerShellバージョン |
| History | Get-History | コマンド履歴 |
| Modules | Get-Module | 読み込み済みモジュール |
| SnapIns | Get-PSSnapin | 読み込み済みスナップイン（Windows PowerShellのみ） |
| Assemblies | CurrentDomain.GetAssemblies() | 読み込み済みアセンブリ |
| Variables | Get-Variable | 指定された追加変数 |

## 表示項目

出力はFileInfoオブジェクトとして返され、生成されたZIPファイルの情報がPowerShellコンソールに表示されます。また、セキュリティに関する警告メッセージが表示されます。

## イベント仕様

### 1-コマンド実行

1. **パス検証**（行96-98）: 出力先パスの存在確認、なければホームディレクトリを使用
2. **メッセージ表示**（行166-170）: セキュリティ警告メッセージを表示
3. **情報収集**（行173-202）: 各種診断情報を$hashに収集
4. **XMLエクスポート**（行206-211）: Export-ClixmlでXMLファイル出力
5. **ZIP圧縮**（行213-219）: Compress-ArchiveでZIPアーカイブ作成
6. **クリーンアップ**（行220）: 元のXMLファイルを削除

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

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

| 操作（イベント） | 対象 | 操作種別 | 概要 |
|----------------|------|---------|------|
| OS情報取得 | Win32_OperatingSystem | WMI READ | OS情報収集 |
| CPU情報取得 | Win32_Processor | WMI READ | CPU情報収集 |
| メモリ情報取得 | Win32_PhysicalMemory | WMI READ | RAM情報収集 |
| ファイル出力 | ファイルシステム | WRITE | ZIP作成 |

## メッセージ仕様

| メッセージタイプ | 条件 | メッセージ内容 |
|-----------------|------|---------------|
| Critical | 実行開始時 | "Will write the final output to: {filePathZip}..." （セキュリティ警告を含む詳細メッセージ） |
| Error | XMLエクスポート失敗 | "Failed to export dump to file." |
| Error | ZIP圧縮失敗 | "Failed to pack dump-file into a zip archive..." |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| XMLエクスポート失敗 | Stop-Functionでエラーを記録して終了 |
| ZIP圧縮失敗 | Stop-Functionでエラーを記録（手動圧縮を推奨） |
| パス未存在 | ホームディレクトリにフォールバック |

## 備考

- 新しいPowerShellセッションを開始し、最小限の手順で問題を再現してからこのコマンドを実行することを推奨
- パスワードなどの機密情報がコマンド履歴に含まれないよう注意が必要
- ZIPファイル名は `dbatools_support_pack_yyyy_MM_dd-HH_mm_ss.zip` 形式
- PowerShell Core環境ではGet-PSSnapinはスキップ
- 出力先のデフォルトはデスクトップ、存在しない場合はホームディレクトリ

---

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

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

### 推奨読解順序

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

出力されるサポートパッケージの構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | New-DbatoolsSupportPackage.ps1 | `public/New-DbatoolsSupportPackage.ps1` | 行56-82の.OUTPUTSセクション |

**読解のコツ**: 出力はFileInfoオブジェクトであり、内部にXMLシリアライズされた診断データが含まれるZIPファイルである点に注目。

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

パラメータ定義とヘルパー関数を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbatoolsSupportPackage.ps1 | `public/New-DbatoolsSupportPackage.ps1` | 行88-94のパラメータ定義 |
| 2-2 | New-DbatoolsSupportPackage.ps1 | `public/New-DbatoolsSupportPackage.ps1` | 行103-156のGet-ShellBuffer関数 |

**主要処理フロー**:
1. **行96-98**: パス存在確認とフォールバック
2. **行103-156**: コンソールバッファ取得のヘルパー関数定義

#### Step 3: 情報収集処理を理解する

各種診断情報の収集を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbatoolsSupportPackage.ps1 | `public/New-DbatoolsSupportPackage.ps1` | 行173-197の情報収集ループ |

**主要処理フロー**:
- **行174**: Get-DbatoolsLogでメッセージ取得
- **行176**: Get-DbatoolsLog -Errorsでエラー取得
- **行178**: Get-ShellBufferでコンソール内容取得
- **行180-184**: Get-DbaCmObjectでWMI情報取得
- **行186**: $PSVersionTableでPowerShellバージョン取得
- **行188**: Get-Historyでコマンド履歴取得
- **行190-195**: Get-Module、Get-PSSnapinでモジュール情報取得
- **行197**: GetAssemblies()でアセンブリ情報取得

#### Step 4: 出力処理を理解する

XMLエクスポートとZIP圧縮を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | New-DbatoolsSupportPackage.ps1 | `public/New-DbatoolsSupportPackage.ps1` | 行206-220の出力処理 |

**主要処理フロー**:
- **行207**: Export-ClixmlでXMLファイル出力
- **行214**: Compress-ArchiveでZIP作成
- **行215**: Get-ChildItemで出力ファイル情報返却
- **行220**: Remove-ItemでXMLファイル削除

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

```
New-DbatoolsSupportPackage
    |
    +-- [beginブロック] 初期化 (行95-157)
    |       |
    |       +-- パス検証 (行96-98)
    |       |       └── Test-Path / $home フォールバック
    |       |
    |       └── Get-ShellBuffer関数定義 (行103-156)
    |               └── コンソールバッファ取得ロジック
    |
    +-- セキュリティ警告表示 (行166-170)
    |       └── Write-Message -Level Critical
    |
    +-- [情報収集ループ] (行173-202)
    |       |
    |       +-- Get-DbatoolsLog (行174)
    |       |       └── dbatoolsメッセージログ
    |       |
    |       +-- Get-DbatoolsLog -Errors (行176)
    |       |       └── dbatoolsエラーログ
    |       |
    |       +-- Get-ShellBuffer (行178)
    |       |       └── コンソールバッファ内容
    |       |
    |       +-- Get-DbaCmObject (行180-184)
    |       |       └── Win32_OperatingSystem
    |       |       └── Win32_Processor
    |       |       └── Win32_PhysicalMemory
    |       |
    |       +-- $PSVersionTable (行186)
    |       |       └── PowerShellバージョン
    |       |
    |       +-- Get-History (行188)
    |       |       └── コマンド履歴
    |       |
    |       +-- Get-Module (行190)
    |       |       └── 読み込みモジュール
    |       |
    |       +-- Get-PSSnapin (行194) [Windows PSのみ]
    |       |       └── 読み込みスナップイン
    |       |
    |       └── GetAssemblies() (行197)
    |               └── 読み込みアセンブリ
    |
    +-- Export-Clixml (行207)
    |       └── XMLファイル出力
    |
    +-- Compress-Archive (行214)
    |       └── ZIP圧縮
    |
    +-- Get-ChildItem (行215)
    |       └── 出力ファイル情報
    |
    └── Remove-Item (行220)
            └── 一時XMLファイル削除
```

### データフロー図

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

Path ────────────────────────┐
                             │
                             v
                      パス検証/フォールバック
                             │
                             v
Variables ───────────────────┼──> [情報収集]
                             │          │
                             │          +── Get-DbatoolsLog (Messages)
                             │          +── Get-DbatoolsLog -Errors
                             │          +── Get-ShellBuffer (ConsoleBuffer)
                             │          +── Get-DbaCmObject (OS/CPU/RAM)
                             │          +── $PSVersionTable
                             │          +── Get-History
                             │          +── Get-Module
                             │          +── Get-PSSnapin (Windows PS)
                             │          +── GetAssemblies()
                             │          └── Get-Variable (Variables)
                             │                     │
                             │                     v
                             │            PSCustomObject ($hash)
                             │                     │
                             │                     v
                             │            Export-Clixml
                             │            (XMLファイル)
                             │                     │
                             │                     v
                             │            Compress-Archive
                             │                     │
                             │                     v
PassThru ────────────────────┴──────────> FileInfo (.zip)
                                           └── dbatools_support_pack_*.zip
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbatoolsSupportPackage.ps1 | `public/New-DbatoolsSupportPackage.ps1` | ソース | サポートパッケージ生成の実装 |
| Get-DbatoolsLog.ps1 | `public/Get-DbatoolsLog.ps1` | ソース | dbatoolsログ取得 |
| Get-DbaCmObject.ps1 | `public/Get-DbaCmObject.ps1` | ソース | WMI情報取得 |
