# 機能設計書 307-Read-DbaXEFile

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `Read-DbaXEFile` コマンドレットの機能設計を記述する。このコマンドレットは、拡張イベント(Extended Events)のトレースファイル（.xel/.xem）を解析し、構造化されたPowerShellオブジェクトに変換する機能を提供する。

### 本機能の処理概要

`Read-DbaXEFile` は、SQL Serverの拡張イベントセッションで生成されたトレースファイル（.xel、.xem）を解析し、PowerShellオブジェクトとして出力するコマンドレットである。SQL Server Management Studioを使用せずに、キャプチャされたイベントデータを分析できる。

**業務上の目的・背景**：拡張イベントで収集されたデータを分析するには、通常SSMSやサードパーティツールが必要である。本機能により、PowerShellのパイプラインを活用してデータをフィルタリング、ソート、CSV/Excel出力、レポート生成等の後処理ができる。デッドロック、パフォーマンス問題、セキュリティイベント等のインシデント後分析に特に有用である。

**機能の利用シーン**：
- XEトレースファイルの内容をPowerShellで分析したい場合
- デッドロックや長時間クエリのイベントをCSVにエクスポートしたい場合
- 複数のトレースファイルを一括で処理したい場合
- Get-DbaXESessionからパイプラインでファイルを読み込みたい場合
- リモートサーバーのXEファイルを分析したい場合

**主要な処理内容**：
1. 入力パスの種類判定（文字列、FileInfo、Sessionオブジェクト）
2. Sessionオブジェクトの場合はローカル/リモートパス解決
3. ワイルドカードパターンでファイル検索
4. Read-XEvent関数でXEファイル読み込み
5. フィールドとアクションをプロパティとして構造化

**関連システム・外部連携**：Get-DbaXESession からのパイプライン入力をサポート。XELiteライブラリ（Read-XEvent）を使用してファイルを解析。

**権限による制御**：対象ファイルへの読み取り権限が必要。リモートサーバーの場合は管理共有へのアクセス権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 87 | XEファイル読み取り | 主機能 | XEファイルの読み取り |

## 機能種別

データ取得処理（ファイル読み取り）/ データ変換処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Path | object[] | Yes | XEファイルパス、FileInfo、またはSessionオブジェクト | - |
| Raw | switch | No | ネイティブXEventオブジェクトを出力 | - |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

- XEトレースファイル（.xel、.xem）
- Get-DbaXESessionからのSessionオブジェクト
- Get-ChildItemからのFileInfoオブジェクト

## 出力仕様

### 出力データ

#### デフォルト出力（PSCustomObject）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| name | String | イベント名 |
| timestamp | DateTime | イベント発生日時 |
| （動的プロパティ） | 各種 | イベントのフィールドとアクション |

#### Raw出力（Microsoft.SqlServer.XEvent.XELite.XEvent）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| XEventオブジェクト | XEvent | ネイティブXEventオブジェクト |

### 出力先

PowerShellパイプライン

## 処理フロー

### 処理シーケンス

```
1. 入力パスの種類判定
   └─ String: そのまま使用
   └─ FileInfo: FullNameを使用
   └─ Session: TargetFile/RemoteTargetFileを使用
2. Sessionオブジェクトの場合
   └─ ローカル/リモート判定
   └─ 実行中セッションは最新ファイルをスキップ
   └─ ワイルドカードでファイル一覧取得
3. ファイルの存在確認
4. Read-XEventでファイル読み込み
5. Raw指定時: XEventオブジェクトをそのまま出力
6. 通常時: PSCustomObjectに変換
   └─ フィールド名とアクション名を動的プロパティとして追加
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{パスの型?}
    B -->|String| C[そのまま使用]
    B -->|FileInfo| D[FullName使用]
    B -->|Session| E{TargetFile存在?}
    E -->|No| F[Stop-Function]
    E -->|Yes| G{IsLocalHost?}
    G -->|Yes| H[TargetFile使用]
    G -->|No| I[RemoteTargetFile使用]
    H --> J[ワイルドカード変換]
    I --> J
    J --> K[Get-ChildItem]
    K --> L{Status=Running?}
    L -->|Yes| M[最新ファイルスキップ]
    L -->|No| N[全ファイル対象]
    M --> O[各ファイルを処理]
    N --> O
    C --> O
    D --> O
    O --> P{ファイル存在?}
    P -->|No| Q[Stop-Function]
    P -->|Yes| R{Raw指定?}
    R -->|Yes| S[Read-XEvent出力]
    R -->|No| T[Read-XEvent]
    T --> U[カラム収集]
    U --> V[各イベントをPSCustomObjectに変換]
    V --> W[プロパティ追加]
    W --> O
    S --> O
    O --> X[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-307-01 | 実行中セッションのスキップ | Status=Running時は最新ファイルをスキップ（アクセス競合回避） | Sessionオブジェクト入力時 |
| BR-307-02 | ワイルドカード変換 | .xel/.xemを*.xel/*.xemに変換 | Sessionオブジェクト入力時 |
| BR-307-03 | アクション名正規化 | パッケージ名プレフィックスを除去 | 常時 |
| BR-307-04 | カラム収集 | 最初のイベントからユニークなカラム名を収集 | デフォルト出力時 |

### 計算ロジック

- アクション名正規化: `($action -Split '\.')[-1]`
- カラム: `@("name", "timestamp") + Fields + Actions`

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| なし | - | - | ファイルシステムのみ操作 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | NoTargetFile | SessionにTargetFileがない | Stop-Functionで継続 |
| - | UnsupportedType | サポートされないファイル型 | Stop-Functionで停止 |
| - | FileNotFound | ファイルにアクセスできない | Stop-Functionで継続 |
| - | ReadError | ファイル読み込みエラー | Stop-Functionで継続 |

### リトライ仕様

なし

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

なし（読み取り専用処理）

## パフォーマンス要件

- ファイルサイズとイベント数に比例した処理時間
- 大量のイベントを含むファイルはメモリ使用量に注意

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

- ファイルシステムへの読み取り権限が必要
- リモートサーバーの場合は管理共有へのアクセス権限が必要

## 備考

- Get-DbaXESession と組み合わせて使用可能
- CSVエクスポートやレポート生成に便利
- Rawスイッチでネイティブオブジェクトにアクセス可能

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造と、動的プロパティの生成方法を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Read-DbaXEFile.ps1 | `public/Read-DbaXEFile.ps1` | OUTPUTSセクション（27-45行目） |

**読解のコツ**: デフォルト出力はPSCustomObjectで、name/timestampは固定、他のプロパティはイベントのフィールドとアクションから動的に生成される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Read-DbaXEFile.ps1 | `public/Read-DbaXEFile.ps1` | process ブロック冒頭（82-113行目） |

**主要処理フロー**:
1. **83行目**: Test-FunctionInterrupt で中断チェック
2. **84-113行目**: 入力パスの種類に応じた処理

#### Step 3: パス種別ごとの処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Read-DbaXEFile.ps1 | `public/Read-DbaXEFile.ps1` | Stringパス処理（89-90行目） |
| 3-2 | Read-DbaXEFile.ps1 | `public/Read-DbaXEFile.ps1` | FileInfoパス処理（91-92行目） |
| 3-3 | Read-DbaXEFile.ps1 | `public/Read-DbaXEFile.ps1` | Sessionオブジェクト処理（93-110行目） |

**主要処理フロー**:
- **98-103行目**: ローカル/リモート判定とパス選択
- **105-106行目**: ワイルドカード変換とファイル取得
- **107-109行目**: 実行中セッションの最新ファイルスキップ

#### Step 4: イベント変換処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Read-DbaXEFile.ps1 | `public/Read-DbaXEFile.ps1` | Raw出力処理（120-125行目） |
| 4-2 | Read-DbaXEFile.ps1 | `public/Read-DbaXEFile.ps1` | PSCustomObject変換（126-159行目） |

**主要処理フロー**:
- **120-125行目**: Raw指定時はRead-XEventをそのまま出力
- **127-140行目**: カラム名収集（Fields + Actions）
- **143-158行目**: 各イベントをPSCustomObjectに変換

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

```
Read-DbaXEFile
    │
    ├─ Test-FunctionInterrupt
    │
    ├─ [DbaInstance]判定（Sessionオブジェクト時）
    │      └─ IsLocalHost プロパティ
    │
    ├─ Get-ChildItem（Sessionオブジェクト時）
    │      └─ Sort-Object LastWriteTime
    │      └─ Select-Object -SkipLast 1（Running時）
    │
    ├─ Test-Path
    │
    └─ Read-XEvent
           └─ Microsoft.SqlServer.XEvent.XELite
```

### データフロー図

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

String Path ─────────────▶ 直接使用
                                  │
FileInfo ────────────────▶ FullName取得
                                  │
Session Object ──────────▶ TargetFile/RemoteTargetFile
      │                          │
      ├─ IsLocalHost判定          │
      ├─ ワイルドカード変換        │
      └─ Running時スキップ         │
                                  │
                                  ▼
                          Test-Path（存在確認）
                                  │
                                  ▼
                          Read-XEvent ───────────▶ XEvent[]
                                  │
                                  ▼
       ┌────────────────────────────────────────┐
       │                                         │
       ▼                                         ▼
  Raw=True                                  Raw=False
       │                                         │
       ▼                                         ▼
  XEvent出力                           カラム名収集
                                              │
                                              ▼
                                    PSCustomObject変換 ─▶ Output
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Read-DbaXEFile.ps1 | `public/Read-DbaXEFile.ps1` | ソース | メインコマンドレット |
| Get-DbaXESession.ps1 | `public/Get-DbaXESession.ps1` | ソース | セッション取得（パイプライン入力元） |
| Read-XEvent | 内部関数/ライブラリ | ユーティリティ | XELiteによるファイル読み込み |
