# 機能設計書 302-Get-DbaXESessionTargetFile

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `Get-DbaXESessionTargetFile` コマンドレットの機能設計を記述する。このコマンドレットは、拡張イベントセッションのターゲットファイル（.xel/.xem）の物理ファイル情報を取得する機能を提供する。

### 本機能の処理概要

`Get-DbaXESessionTargetFile` は、SQL Serverの拡張イベントセッションが出力する物理的なトレースファイル（.xel、.xem）の情報をファイルシステムから取得するコマンドレットである。SQL Server Management StudioやサードパーティのXEファイルリーダーでの分析に必要なファイルを簡単に特定できる。

**業務上の目的・背景**：拡張イベントセッションで収集されたデータを分析するには、実際のトレースファイルにアクセスする必要がある。特にリモートサーバーのXEファイルにアクセスする場合、UNCパスの解決が必要となる。本機能により、ローカル・リモート問わずXEファイルの場所を自動的に特定し、分析作業の効率化を実現する。

**機能の利用シーン**：
- XEセッションで収集されたトレースファイルの一覧を取得したい場合
- トレースファイルのサイズや最終更新日時を確認したい場合
- 複数のトレースファイルを一括で取得し、後続の分析処理に渡したい場合
- リモートサーバーのXEファイルにアクセスする必要がある場合

**主要な処理内容**：
1. Get-DbaXESessionTargetからターゲット情報を取得
2. ファイルパス（ローカルまたはUNC）を解決
3. ワイルドカードパターン（*.xel、*.xem）でファイルを検索
4. FileInfoオブジェクトとして出力

**関連システム・外部連携**：Get-DbaXESessionTarget を内部で呼び出し、ファイルターゲットの情報を取得する。ファイルシステムへのアクセスにはGet-ChildItemを使用。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 86 | XEセッションターゲット | 補助機能 | XEターゲットファイルの取得 |

## 機能種別

データ取得処理（SELECT）/ ファイルシステム操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes（ParameterSet: instance） | 接続先SQLインスタンス | - |
| SqlCredential | PSCredential | No | 代替認証資格情報 | - |
| Session | string[] | No | 対象セッション名 | - |
| Target | string[] | No | 対象ターゲット名 | - |
| InputObject | object[] | Yes（ParameterSet: piped） | パイプライン入力（Target/Sessionオブジェクト） | - |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

- Get-DbaXESessionTargetからのターゲット情報
- Microsoft.SqlServer.Management.XEvent.Session オブジェクト
- Microsoft.SqlServer.Management.XEvent.Target オブジェクト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Name | String | ファイル名（拡張子含む） |
| FullName | String | 完全ファイルパス |
| DirectoryName | String | 親ディレクトリパス |
| Length | Int64 | ファイルサイズ（バイト） |
| LastWriteTime | DateTime | 最終更新日時 |
| CreationTime | DateTime | 作成日時 |
| Attributes | FileAttributes | ファイル属性 |
| Directory | DirectoryInfo | 親ディレクトリ情報 |
| Extension | String | ファイル拡張子 |

### 出力先

PowerShellパイプライン（System.IO.FileInfoオブジェクト）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ SqlInstanceまたはInputObjectの確認
2. ターゲット情報の取得（SqlInstance指定時）
   └─ Get-DbaXESessionTarget を呼び出し
   └─ ファイルターゲットのみをフィルタリング
3. 入力オブジェクトの種類判定
   └─ Session オブジェクトの場合
   └─ Target オブジェクトの場合
4. ファイルパスの解決
   └─ ローカルホストの場合: TargetFile使用
   └─ リモートの場合: RemoteTargetFile（UNC）使用
5. ワイルドカードパターンでファイル検索
   └─ .xel → *.xel
   └─ .xem → *.xem
6. Get-ChildItemでファイル情報取得
   └─ LastWriteTimeでソート
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance指定?}
    B -->|Yes| C[Get-DbaXESessionTarget呼び出し]
    B -->|No| D[InputObjectを使用]
    C --> E[File != null でフィルタ]
    E --> F[各オブジェクトを処理]
    D --> F
    F --> G{オブジェクト種別?}
    G -->|Session| H{TargetFile存在?}
    G -->|Target| I{IsLocal?}
    G -->|その他| J[Stop-Function]
    H -->|No| K[Stop-Function: No Target File]
    H -->|Yes| L{IsLocalHost?}
    L -->|Yes| M[TargetFile使用]
    L -->|No| N[RemoteTargetFile使用]
    I -->|Yes| O[TargetFile使用]
    I -->|No| P[RemoteTargetFile使用]
    M --> Q[ワイルドカード変換]
    N --> Q
    O --> R[ワイルドカード変換]
    P --> R
    Q --> S[Get-ChildItem実行]
    R --> T[Get-ChildItem実行]
    S --> U[Sort-Object LastWriteTime]
    T --> V[ファイル出力]
    U --> W[終了]
    V --> W
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-302-01 | ローカル/リモート判定 | IsLocalHostフラグに基づきパスを選択 | 常時 |
| BR-302-02 | ワイルドカード変換 | .xel/.xemを*.xel/*.xemに変換 | ファイルパス処理時 |
| BR-302-03 | ファイルソート | 最終更新日時でソート | Sessionオブジェクト処理時 |

### 計算ロジック

- ワイルドカード変換: `$targetFile.Replace(".xel", "*.xel").Replace(".xem", "*.xem")`

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

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

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

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

データベースへの直接アクセスなし（Get-DbaXESessionTarget経由で間接的に取得）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | NoTargetFile | セッションにターゲットファイルがない | Stop-Functionで警告 |
| - | UnsupportedType | サポートされないオブジェクト型 | Stop-Functionで警告 |
| - | FileAccessError | ファイルアクセス失敗 | Stop-Functionで警告 |

### リトライ仕様

なし

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

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

## パフォーマンス要件

- ファイルシステムアクセスのレイテンシに依存
- 再帰検索（-Recurse）を使用

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

- ファイルシステムへの読み取り権限が必要
- リモートサーバーの場合は管理共有へのアクセス権限が必要
- SqlCredentialでのSQL Server認証後、ファイルアクセスは実行ユーザーの権限で行われる

## 備考

- Get-DbaXESessionTarget と組み合わせて使用
- Read-DbaXEFile と組み合わせてファイル内容を分析可能

---

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

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

### 推奨読解順序

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

FileInfoオブジェクトの構造と、入力となるSessionおよびTargetオブジェクトの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaXESessionTargetFile.ps1 | `public/Get-DbaXESessionTargetFile.ps1` | 出力型（System.IO.FileInfo）の説明（48-63行目） |

**読解のコツ**: OUTPUTSセクション（48-63行目）でFileInfoオブジェクトの標準プロパティを確認する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaXESessionTargetFile.ps1 | `public/Get-DbaXESessionTargetFile.ps1` | process ブロック（88-141行目） |

**主要処理フロー**:
1. **89行目**: Test-FunctionInterrupt で中断チェック
2. **91-99行目**: SqlInstanceからターゲット情報を取得
3. **101-140行目**: 各オブジェクトの種類に応じた処理

#### Step 3: オブジェクト種別ごとの処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaXESessionTargetFile.ps1 | `public/Get-DbaXESessionTargetFile.ps1` | Sessionオブジェクト処理（102-121行目） |
| 3-2 | Get-DbaXESessionTargetFile.ps1 | `public/Get-DbaXESessionTargetFile.ps1` | Targetオブジェクト処理（122-136行目） |

**主要処理フロー**:
- **102-121行目**: Microsoft.SqlServer.Management.XEvent.Session の処理
- **107-112行目**: ローカル/リモート判定とパス選択
- **114行目**: ワイルドカードパターン変換
- **118行目**: Get-ChildItemでファイル取得、ソート
- **122-136行目**: Microsoft.SqlServer.Management.XEvent.Target の処理

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

```
Get-DbaXESessionTargetFile
    │
    ├─ Test-FunctionInterrupt
    │
    ├─ Get-DbaXESessionTarget（SqlInstance指定時）
    │      │
    │      └─ Where-Object File -ne $null
    │
    ├─ [DbaInstance]判定
    │      └─ IsLocalHost / IsLocal プロパティ
    │
    └─ Get-ChildItem
           └─ Sort-Object LastWriteTime
```

### データフロー図

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

SqlInstance ─────────────▶ Get-DbaXESessionTarget ───▶ Target[]
      │
      ▼
Session/Target Filter ──▶ Where-Object (File != null)
      │
      ▼
InputObject ─────────────▶ 型判定（Session/Target）
      │
      │                    ┌─ Session型
      │                    │    ├─ IsLocalHost判定
      │                    │    ├─ TargetFile/RemoteTargetFile選択
      │                    │    └─ ワイルドカード変換
      │                    │
      │                    └─ Target型
      │                         ├─ IsLocal判定
      │                         ├─ TargetFile/RemoteTargetFile選択
      │                         └─ ワイルドカード変換
      │
      ▼
File Path ───────────────▶ Get-ChildItem ───────────▶ FileInfo[]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaXESessionTargetFile.ps1 | `public/Get-DbaXESessionTargetFile.ps1` | ソース | メインコマンドレット |
| Get-DbaXESessionTarget.ps1 | `public/Get-DbaXESessionTarget.ps1` | ソース | ターゲット情報取得（依存先） |
| Get-DbaXESession.ps1 | `public/Get-DbaXESession.ps1` | ソース | セッション情報取得（間接依存） |
