# 画面設計書 87-XEファイル読み取り

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける拡張イベント（Extended Events）トレースファイル読み取り機能の設計仕様を定義する。XELファイル（.xel/.xem）を解析し、構造化されたPowerShellオブジェクトとして出力するCLIを提供する。

### 本画面の処理概要

本機能は、Extended Eventsトレースファイルを解析し、収集されたイベントをPowerShellオブジェクトに変換するためのコマンドラインインターフェースを提供する。SQL Server Management Studioを使用せずに、デッドロック、パフォーマンス問題、セキュリティイベント等の分析が可能になる。

**業務上の目的・背景**：Extended Eventsセッションで収集したトレースデータは.xel/.xemファイルに保存される。本機能は、これらのバイナリファイルを解析し、PowerShellでの分析、フィルタリング、CSVエクスポート、レポート作成を可能にする。インシデント発生後の事後分析、パフォーマンス問題の調査、セキュリティ監査などに活用される。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスする：
- `Read-DbaXEFile -Path <ファイルパス>`
- `Get-ChildItem *.xel | Read-DbaXEFile`
- `Get-DbaXESession -SqlInstance <インスタンス名> | Read-DbaXEFile`

**主要な操作・処理内容**：
1. .xel/.xemファイルの解析
2. XEventオブジェクトをPSCustomObjectに変換
3. フィールドとアクションを個別プロパティとして展開
4. リモートファイルアクセス（UNC共有経由）
5. 書き込み中ファイルの自動スキップ

**画面遷移**：
- 入力元：`Get-DbaXESession`からパイプライン入力可能
- 入力元：`Get-DbaXESessionTarget`でファイルパスを特定後使用
- 入力元：`Get-ChildItem`からファイルオブジェクトをパイプライン入力

**権限による表示制御**：ファイルアクセス権限が必要。リモートファイルの場合は管理者共有（C$等）へのアクセス権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|-------------------|
| 382 | Read-DbaXEFile | 主機能 | XEファイル読み取り |
| 303 | Get-DbaXESession | 遷移元機能 | セッション取得 |
| 305 | Get-DbaXESessionTarget | 遷移元機能 | ターゲットファイルパス特定 |

## 画面種別

コマンドラインインターフェース（CLI） / 分析・参照

## URL/ルーティング

PowerShellコマンド呼び出し：
- `Read-DbaXEFile -Path <ファイルパス>`
- `Read-DbaXEFile -Path <ファイルパス> -Raw`
- `Get-ChildItem *.xel | Read-DbaXEFile`
- `Get-DbaXESession -SqlInstance <インスタンス名> -Session <セッション名> | Read-DbaXEFile`

## 入出力項目

### Read-DbaXEFile 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| Path | object[] | はい | XEファイルパス（文字列、FileInfo、Sessionオブジェクト） |
| Raw | switch | いいえ | 生のXEventオブジェクトを返す |
| EnableException | switch | いいえ | 例外処理の有効化 |

## 表示項目

### Read-DbaXEFile 出力オブジェクト（デフォルト）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| name | string | イベント名 |
| timestamp | datetime | イベント発生日時 |
| （動的プロパティ） | various | Fields/Actionsの値 |

**動的プロパティの例**：
- database_id：データベースID
- duration：実行時間
- cpu_time：CPU時間
- physical_reads：物理読み取り数
- logical_reads：論理読み取り数
- writes：書き込み数
- client_app_name：クライアントアプリケーション名
- statement：SQLステートメント

### Read-DbaXEFile 出力オブジェクト（-Raw指定時）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| （XEventオブジェクト） | Microsoft.SqlServer.XEvent.XELite.XEvent | 生のXEventオブジェクト |

## イベント仕様

### 1-XEファイル読み取り（Read-DbaXEFile）

1. Pathパラメータのタイプを判定（String/FileInfo/Session）
2. Sessionオブジェクトの場合：
   a. TargetFileの存在確認
   b. ローカル/リモート判定（IsLocalHost）
   c. リモートの場合はRemoteTargetFile（UNCパス）を使用
   d. ワイルドカード展開（*.xel/*.xem）
   e. Running状態の場合は最新ファイルをスキップ（書き込み中のため）
3. 各ファイルに対して処理：
   a. ファイル存在確認
   b. Read-XEventでファイル解析
4. Rawスイッチの場合：XEventオブジェクトをそのまま出力
5. 通常モードの場合：
   a. Fields.NameとActions.Nameからカラム名を収集
   b. アクション名の正規化（パッケージプレフィックス除去）
   c. 各イベントをPSCustomObjectに変換

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Read-DbaXEFile | なし | - | ローカルファイル読み取りのみ |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------||
| MSG001 | エラー | The session [$session] does not have an associated Target File. | TargetFileなし |
| MSG002 | エラー | $file cannot be accessed from $env:COMPUTERNAME. | ファイルアクセス不可 |
| MSG003 | エラー | The Path [$pathObject] has an unsupported file type of [$type]. | 不正な入力タイプ |
| MSG004 | エラー | Failure | ファイル読み取りエラー |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| TargetFileなし | Stop-Functionでエラーを表示し、次のパスに継続 |
| ファイルアクセス不可 | Stop-Functionでエラーを表示し、次のファイルに継続 |
| 不正な入力タイプ | Stop-Functionでエラーを表示 |
| ファイル読み取りエラー | Stop-Functionでエラーを表示し、次のファイルに継続 |

## 備考

- 対応ファイル形式：.xel（イベントファイル）、.xem（メタデータファイル）
- XELiteライブラリ（Microsoft.SqlServer.XEvent.XELite）を使用
- Get-DbaXESessionからのパイプライン入力時：
  - ローカルホストの場合はTargetFileを使用
  - リモートホストの場合はRemoteTargetFile（UNC共有）を使用
  - セッションがRunning状態の場合、書き込み中の最新ファイルをスキップ
- CSV出力のため、最初のオブジェクトに全カラムを含める設計
- アクション名は`package.action`形式から`action`部分のみを抽出

---

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

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

### 推奨読解順序

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

出力はPSCustomObject（デフォルト）またはMicrosoft.SqlServer.XEvent.XELite.XEvent（-Raw）である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Read-DbaXEFile.ps1 | `public/Read-DbaXEFile.ps1` | 出力オブジェクトの構造（26-45行目）を確認 |

**読解のコツ**: 動的プロパティはFields.Name/Actions.Nameから収集される（132-140行目）。各イベントは順序付きハッシュテーブルからPSCustomObjectに変換される（144-158行目）。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Read-DbaXEFile.ps1 | `public/Read-DbaXEFile.ps1` | param()ブロック（75-81行目）で入力パラメータを確認 |

**主要処理フロー**:
1. **89-113行目**: Pathパラメータのタイプ判定と処理
2. **115-161行目**: ファイル読み取りと変換処理

#### Step 3: 入力タイプ処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Read-DbaXEFile.ps1 | `public/Read-DbaXEFile.ps1` | 入力タイプ別処理（89-113行目） |

**入力タイプ別処理**:
- **89-90行目**: System.String → そのままファイルパスとして使用
- **91-92行目**: System.IO.FileInfo → FullNameを使用
- **93-109行目**: Microsoft.SqlServer.Management.XEvent.Session
  - **98-103行目**: ローカル/リモート判定とパス選択
  - **105行目**: ワイルドカード展開
  - **107-108行目**: Running時の最新ファイルスキップ

#### Step 4: XEvent変換処理を理解する

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

**主要処理フロー**:
- **122行目/128行目**: Read-XEventでファイル解析
- **132行目**: Fields.Nameから一意のカラム名を取得
- **134-137行目**: Actions.Nameを正規化（パッケージプレフィックス除去）
- **143-158行目**: 各イベントをPSCustomObjectに変換

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

```
Read-DbaXEFile
    │
    ├─ Test-FunctionInterrupt
    │      └─ 中断チェック
    │
    ├─ 入力タイプ判定
    │      ├─ String → ファイルパス
    │      ├─ FileInfo → FullName
    │      └─ XEvent.Session
    │             ├─ IsLocalHost判定
    │             ├─ TargetFile / RemoteTargetFile
    │             └─ Get-ChildItem (ワイルドカード展開)
    │
    ├─ Test-Path
    │      └─ ファイル存在確認
    │
    ├─ Read-XEvent (内部関数)
    │      └─ XELiteでファイル解析
    │
    └─ PSCustomObject変換
           ├─ Fields.Name/Actions.Name → カラム名収集
           └─ [ordered]@{} → [PSCustomObject]
```

### データフロー図

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

String (Path) ──────▶ ファイルパスとして使用
      │
FileInfo ───────────▶ FullName抽出
      │
XEvent.Session ─────▶ TargetFile/RemoteTargetFile
      │                       │
      │              IsLocalHost判定
      │                       │
      │              ワイルドカード展開 (*.xel)
      │                       │
      │              Running時: SkipLast 1
      │                       │
      └───────────────────────┘
                              │
                              ▼
                     Test-Path (ファイル存在確認)
                              │
                              ▼
                     Read-XEvent (XELite)
                              │
         ┌────────────────────┼────────────────────┐
         │                    │                    │
         ▼                    ▼                    ▼
       -Raw              Fields.Name          Actions.Name
         │                    │                    │
         │                    │         正規化 (プレフィックス除去)
         │                    │                    │
         │                    └────────┬───────────┘
         │                             │
         │                             ▼
         │                      カラム名収集
         │                             │
         │                             ▼
         │                    [ordered]@{hash}
         │                             │
         ▼                             ▼
   XEvent Object           PSCustomObject
   (Raw)                   (name, timestamp, 動的プロパティ)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Read-DbaXEFile.ps1 | `public/Read-DbaXEFile.ps1` | ソース | XEファイル読み取り |
| Read-XEvent.ps1 | `private/functions/Read-XEvent.ps1` | 依存 | XELiteラッパー |
| Get-DbaXESession.ps1 | `public/Get-DbaXESession.ps1` | 関連 | セッション取得 |
| Get-DbaXESessionTarget.ps1 | `public/Get-DbaXESessionTarget.ps1` | 関連 | ターゲット情報取得 |
