# 機能設計書 196-New-DbatoolsSupportPackage

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける`New-DbatoolsSupportPackage`機能の設計仕様を記載する。この機能は、dbatoolsモジュールの問題やバグのトラブルシューティング用の包括的な診断パッケージを作成する。

### 本機能の処理概要

**業務上の目的・背景**：dbatoolsコマンドで問題が発生した際、開発チームが効果的にデバッグを行うためには、環境情報、実行履歴、エラーログなど多岐にわたる情報が必要となる。本機能は、これらの診断情報を自動的に収集し、ZIPアーカイブとして出力することで、ユーザーがバグレポートを効率的に提出できるようにする。

**機能の利用シーン**：
- dbatoolsコマンドでエラーが発生した際のバグレポート作成
- 予期しない動作の原因調査
- 環境固有の問題のトラブルシューティング
- 開発チームへの問題報告

**主要な処理内容**：
1. dbatoolsログメッセージの収集（Get-DbatoolsLog）
2. dbatoolsエラーログの収集（Get-DbatoolsLog -Errors）
3. コンソールバッファの取得（表示中の内容）
4. OS情報の収集（Win32_OperatingSystem）
5. CPU情報の収集（Win32_Processor）
6. メモリ情報の収集（Win32_PhysicalMemory）
7. PowerShellバージョン情報の収集（$PSVersionTable）
8. コマンド履歴の収集（Get-History）
9. ロード済みモジュール一覧の収集（Get-Module）
10. Snapin一覧の収集（Windows PowerShellのみ）
11. ロード済みアセンブリ一覧の収集
12. 指定変数の収集（オプション）
13. XMLファイルへのエクスポート
14. ZIPアーカイブ作成
15. 一時XMLファイルの削除

**関連システム・外部連携**：WMI/CIM（システム情報取得）、PowerShellランタイム。

**権限による制御**：システム情報取得のための適切な権限が必要。出力先への書き込み権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 169 | サポートパッケージ | 主機能 | dbatoolsサポートパッケージの作成 |

## 機能種別

帳票出力 / 診断ツール

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Path | string | No | 出力先ディレクトリ（デフォルト: デスクトップ） | - |
| Variables | string[] | No | 追加で含める変数名 | - |
| PassThru | switch | No | FileInfoオブジェクトを返す | - |
| EnableException | switch | No | 例外をスローするかどうか | - |

### 入力データソース

- PowerShellセッション情報
- WMI/CIMデータ
- dbatoolsログデータ
- コンソールバッファ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| FileInfo | System.IO.FileInfo | 作成されたZIPファイルの情報 |

### ZIPファイルの内容

| データ項目 | 説明 |
|-----------|------|
| Messages | dbatoolsログメッセージ |
| Errors | dbatoolsエラーログ |
| ConsoleBuffer | コンソール表示内容 |
| OperatingSystem | OS情報 |
| CPU | CPU情報 |
| Ram | メモリ情報 |
| PSVersion | PowerShellバージョン |
| History | コマンド履歴 |
| Modules | ロード済みモジュール |
| SnapIns | ロード済みSnapin（Windows PowerShellのみ） |
| Assemblies | ロード済みアセンブリ |
| Variables | 指定された変数（オプション） |

### 出力先

デフォルトはデスクトップ。存在しない場合はホームディレクトリ。ファイル名は `dbatools_support_pack_yyyy_MM_dd-HH_mm_ss.zip`。

## 処理フロー

### 処理シーケンス

```
1. beginブロック
   ├─ Pathの存在確認（なければ$homeに変更）
   └─ Get-ShellBufferヘルパー関数定義
2. processブロック
   ├─ ShouldProcess確認
   ├─ ファイルパス生成
   ├─ 警告メッセージ出力
   └─ データ収集ループ
       ├─ Get-DbatoolsLog（メッセージ）
       ├─ Get-DbatoolsLog -Errors（エラー）
       ├─ Get-ShellBuffer（コンソールバッファ）
       ├─ Get-DbaCmObject Win32_OperatingSystem
       ├─ Get-DbaCmObject Win32_Processor
       ├─ Get-DbaCmObject Win32_PhysicalMemory
       ├─ $PSVersionTable
       ├─ Get-History
       ├─ Get-Module
       ├─ Get-PSSnapin（非Coreのみ）
       ├─ AppDomain.GetAssemblies()
       └─ Get-Variable（Variables指定時）
3. XMLエクスポート
   └─ Export-Clixml
4. ZIPアーカイブ作成
   └─ Compress-Archive
5. 一時ファイル削除
   └─ Remove-Item
6. endブロック
   └─ 終了メッセージ
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Path存在?}
    B -->|No| C[Path = home]
    B -->|Yes| D{ShouldProcess確認}
    C --> D
    D -->|No| E[終了]
    D -->|Yes| F[ファイルパス生成]
    F --> G[警告メッセージ出力]
    G --> H[データ収集開始]
    H --> I[dbatoolsログ収集]
    I --> J[コンソールバッファ取得]
    J --> K[OS/CPU/RAM情報収集]
    K --> L[PowerShell情報収集]
    L --> M[モジュール/Snapin情報収集]
    M --> N[アセンブリ情報収集]
    N --> O{Variables指定?}
    O -->|Yes| P[変数情報収集]
    O -->|No| Q[Export-Clixml]
    P --> Q
    Q --> R{エクスポート成功?}
    R -->|No| S[Stop-Function 終了]
    R -->|Yes| T[Compress-Archive]
    T --> U{アーカイブ成功?}
    U -->|No| V[Stop-Function 終了]
    U -->|Yes| W[XMLファイル削除]
    W --> X[FileInfo返却]
    X --> Y[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | デフォルトパス | デスクトップが存在しない場合はホームディレクトリ | 常時 |
| BR-002 | Core非対応 | PSSnapinはPowerShell Coreでは取得しない | PSEdition = Core |
| BR-003 | タイムスタンプ命名 | ファイル名にタイムスタンプを含める | 常時 |
| BR-004 | ShouldProcess | 確認なしでは実行しない | 常時 |

### 計算ロジック

特に計算処理はない。

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

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

データベース操作はない。

### テーブル別操作詳細

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Stop-Function | XMLエクスポート失敗 | 出力先権限を確認 |
| - | Stop-Function | ZIPアーカイブ作成失敗 | 手動でZIP化を推奨 |

### リトライ仕様

本機能にリトライ機能はない。

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

ファイル操作のため、データベーストランザクションは関与しない。

## パフォーマンス要件

特になし。診断情報収集のため、多少の処理時間は許容される。

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

- コンソールバッファにはパスワード等の機密情報が含まれる可能性があるため注意
- 新しいセッションで問題を再現してから実行することを推奨
- 指定変数には機密情報を含めないよう注意

## 備考

- 出力されるZIPファイルには機密情報が含まれる可能性があるため、提出前に内容を確認することを推奨
- PowerShell Coreでは一部の情報（Snapin）が収集されない
- 大きなコンソールバッファを持つセッションでは出力ファイルが大きくなる可能性がある

---

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

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

### 推奨読解順序

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

収集されるデータの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | New-DbatoolsSupportPackage.ps1 | `public/New-DbatoolsSupportPackage.ps1` | $hash変数の構造（172行目以降） |

**読解のコツ**: $hashハッシュテーブルに各種診断情報がキーと値で格納される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbatoolsSupportPackage.ps1 | `public/New-DbatoolsSupportPackage.ps1` | 関数定義とパラメータ構造 |

**主要処理フロー**:
1. **88-94行目**: param()ブロック
2. **95-157行目**: beginブロック（Get-ShellBuffer定義含む）
3. **159-221行目**: processブロック（メインロジック）
4. **223-225行目**: endブロック

#### Step 3: Get-ShellBufferヘルパー関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbatoolsSupportPackage.ps1 | `public/New-DbatoolsSupportPackage.ps1` | コンソールバッファ取得ロジック |

**主要処理フロー**:
- **103-156行目**: Get-ShellBuffer関数
- **108-113行目**: バッファ範囲定義
- **116行目**: GetBufferContents呼び出し
- **118-131行目**: バッファを文字列配列に変換
- **133-148行目**: 空行トリミング

#### Step 4: データ収集処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | New-DbatoolsSupportPackage.ps1 | `public/New-DbatoolsSupportPackage.ps1` | 各種データ収集 |

**主要処理フロー**:
- **173-176行目**: dbatoolsログ収集
- **177-178行目**: コンソールバッファ取得
- **179-186行目**: システム情報収集（WMI）
- **187-194行目**: PowerShell情報収集
- **196-197行目**: アセンブリ情報収集
- **199-202行目**: 変数情報収集（オプション）

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

```
New-DbatoolsSupportPackage
    │
    ├─ Get-ShellBuffer (内部関数)
    │      └─ $host.ui.rawui.GetBufferContents()
    │
    ├─ Get-DbatoolsLog
    │      └─ dbatoolsログメッセージ取得
    │
    ├─ Get-DbaCmObject
    │      ├─ Win32_OperatingSystem
    │      ├─ Win32_Processor
    │      └─ Win32_PhysicalMemory
    │
    ├─ Get-History
    │      └─ コマンド履歴取得
    │
    ├─ Get-Module
    │      └─ ロード済みモジュール取得
    │
    ├─ Get-PSSnapin (非Core)
    │      └─ ロード済みSnapin取得
    │
    ├─ Export-Clixml
    │      └─ XMLエクスポート
    │
    ├─ Compress-Archive
    │      └─ ZIPアーカイブ作成
    │
    └─ Remove-Item
           └─ 一時XMLファイル削除
```

### データフロー図

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

Path ──────────────────────┐
                           │
Variables ─────────────────┼──▶ New-DbatoolsSupportPackage
                           │           │
                           │           ├─ Get-ShellBuffer
                           │           ├─ Get-DbatoolsLog
                           │           ├─ Get-DbaCmObject
                           │           ├─ Get-History
                           │           ├─ Get-Module
                           │           └─ Get-Variable
                           │                  │
                           │                  ▼
                           │           $hash (ハッシュテーブル)
                           │                  │
                           │                  ▼
                           │           Export-Clixml → .xml
                           │                  │
                           │                  ▼
                           └───────▶ Compress-Archive ──────────▶ .zip ファイル
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbatoolsSupportPackage.ps1 | `public/New-DbatoolsSupportPackage.ps1` | ソース | メイン関数定義 |
| Get-DbatoolsLog.ps1 | `public/Get-DbatoolsLog.ps1` | ソース | ログ取得 |
| Get-DbaCmObject.ps1 | `public/Get-DbaCmObject.ps1` | ソース | WMI/CIM情報取得 |
