# 画面設計書 86-XEセッションターゲット

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける拡張イベント（Extended Events）セッションターゲット取得機能の設計仕様を定義する。XEセッションに設定されたターゲット（イベントファイル、リングバッファ等）の構成と場所を取得するCLIを提供する。

### 本画面の処理概要

本機能は、Extended Eventsセッションのターゲット情報を取得するためのコマンドラインインターフェースを提供する。ターゲットはXEセッションが収集したイベントデータを出力する先であり、イベントファイル（.xel）、リングバッファ、イベントカウンター等がある。

**業務上の目的・背景**：Extended Eventsセッションのトラブルシューティングでは、ターゲット構成の確認が重要である。本機能は、ターゲットファイルの場所（ローカルパスとUNCパス）、ターゲットタイプ、構成パラメータを一覧表示し、DBAがXEログファイルを迅速に特定し、ターゲット構成の問題を診断できるようにする。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスする：
- `Get-DbaXESessionTarget -SqlInstance <インスタンス名>`
- `Get-DbaXESessionTarget -SqlInstance <インスタンス名> -Session <セッション名>`
- `Get-DbaXESession -SqlInstance <インスタンス名> | Get-DbaXESessionTarget`

**主要な操作・処理内容**：
1. XEセッションのターゲット一覧取得
2. ターゲットファイルパスの解決（相対パス→絶対パス）
3. UNCパスへの変換（リモートアクセス用）
4. ターゲット構成パラメータの取得
5. セッション状態（Running/Stopped）の表示

**画面遷移**：
- 入力元：`Get-DbaXESession`からパイプライン入力可能
- 関連：`Read-DbaXEFile`でターゲットファイルの内容を読み取り

**権限による表示制御**：sysadmin権限が必要。

## 関連機能

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

## 画面種別

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

## URL/ルーティング

PowerShellコマンド呼び出し：
- `Get-DbaXESessionTarget -SqlInstance <インスタンス名>`
- `Get-DbaXESessionTarget -SqlInstance <インスタンス名> -Session <セッション名>`
- `Get-DbaXESessionTarget -SqlInstance <インスタンス名> -Session <セッション名> -Target <ターゲット名>`
- `Get-DbaXESession -SqlInstance <インスタンス名> | Get-DbaXESessionTarget`

## 入出力項目

### Get-DbaXESessionTarget 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | はい* | 対象SQLインスタンス（InputObjectと排他） |
| SqlCredential | PSCredential | いいえ | 認証情報 |
| Session | string[] | いいえ | フィルタリング対象セッション名 |
| Target | string[] | いいえ | フィルタリング対象ターゲット名 |
| InputObject | Microsoft.SqlServer.Management.XEvent.Session[] | はい* | パイプライン入力（SqlInstanceと排他） |
| EnableException | switch | いいえ | 例外処理の有効化 |

## 表示項目

### Get-DbaXESessionTarget 出力オブジェクト

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全インスタンス名 |
| Session | string | セッション名 |
| SessionStatus | string | セッション状態（Running/Stopped） |
| Name | string | ターゲット名（例：package0.event_file） |
| ID | int | ターゲットID |
| Field | Collection | ターゲットフィールド構成 |
| PackageName | string | パッケージ名 |
| File | string[] | ターゲットファイルパス |
| Description | string | ターゲット説明 |
| ScriptName | string | スクリプト用ターゲット名 |
| TargetFile | string[] | ローカルターゲットファイルパス（非表示） |
| RemoteTargetFile | string[] | UNCターゲットファイルパス（非表示） |

## イベント仕様

### 1-ターゲット情報取得（Get-DbaXESessionTarget）

1. SqlInstance指定時はGet-DbaXESessionでセッション取得
2. 各セッションのTargetsコレクションを反復処理
3. Sessionパラメータでセッション名フィルタリング
4. Targetパラメータでターゲット名フィルタリング
5. TargetFieldsからFilenameフィールドを抽出
6. 相対パスの場合はErrorLogPathを基準に絶対パスを解決
7. Join-AdminUncでUNCパスを生成
8. Add-MemberでNotePropertyを追加
9. Select-DefaultViewで出力プロパティを選択

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaXESessionTarget | なし | - | 読み取り専用操作 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------||
| MSG001 | エラー | Failure | 接続エラー時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 接続エラー | Get-DbaXESessionで処理（Stop-Functionでエラーを表示し継続） |

## 備考

- ターゲットタイプの例：
  - `package0.event_file`：イベントファイルターゲット（.xelファイル）
  - `package0.ring_buffer`：リングバッファターゲット（メモリ内）
  - `package0.event_counter`：イベントカウンターターゲット
  - `package0.histogram`：ヒストグラムターゲット
  - `package0.pair_matching`：ペアマッチングターゲット
- ファイルパス解決：相対パス指定の場合、ErrorLogPathを基準に絶対パスに変換
- UNCパス生成：Join-AdminUncで`\\ComputerName\c$\path`形式に変換
- パイプライン入力をサポートし、Get-DbaXESessionからの出力を直接受け取り可能
- TargetFieldsプロパティには、各ターゲットの詳細な構成パラメータが含まれる

---

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

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

### 推奨読解順序

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

出力はMicrosoft.SqlServer.Management.XEvent.Targetオブジェクト（拡張済み）である。

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

**読解のコツ**: Add-MemberでNotePropertyを追加し（146-152行目）、Select-DefaultViewで表示プロパティを制御している（154行目）。

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

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

**主要処理フロー**:
1. **163-165行目**: SqlInstance指定時はGet-DbaXESessionでセッション取得
2. **166行目**: Get-Target内部関数を呼び出し

#### Step 3: ターゲット処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaXESessionTarget.ps1 | `public/Get-DbaXESessionTarget.ps1` | Get-Target内部関数（109-157行目） |

**主要処理フロー**:
- **124行目**: Sessionパラメータでフィルタリング
- **125行目**: セッション状態（Running/Stopped）を判定
- **128-129行目**: Targetsコレクションを反復し、Targetパラメータでフィルタリング
- **131行目**: TargetFieldsからFilenameを抽出
- **135-144行目**: 相対パスを絶対パスに変換し、UNCパスを生成
- **146-152行目**: NotePropertyを追加
- **154行目**: Select-DefaultViewで出力プロパティを選択

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

```
Get-DbaXESessionTarget
    │
    ├─ Get-DbaXESession (SqlInstance指定時)
    │      └─ セッション取得
    │
    └─ Get-Target (内部関数)
           │
           ├─ Session.Targets
           │      └─ ターゲットコレクション取得
           │
           ├─ TargetFields (Filename抽出)
           │      └─ ファイルパス取得
           │
           ├─ ErrorLogPath
           │      └─ 相対パス解決の基準
           │
           ├─ Join-AdminUnc
           │      └─ UNCパス生成
           │
           ├─ Add-Member (NoteProperty追加)
           │      └─ ComputerName, Session, TargetFile等
           │
           └─ Select-DefaultView
                  └─ 表示プロパティ選択
```

### データフロー図

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

SqlInstance ───────▶ Get-DbaXESession ─────────▶ Session Collection
      │                       │
      │                       ▼
      └────────────▶ Get-Target (内部関数)
                              │
Session ─────────▶ Where-Object (Name) ──────▶ フィルタリング
                              │
Target ──────────▶ Where-Object (Name) ──────▶ フィルタリング
                              │
                              ▼
                     Session.Targets
                              │
                              ▼
                     TargetFields (Filename)
                              │
         ┌────────────────────┼────────────────────┐
         │                    │                    │
         ▼                    ▼                    ▼
   相対パス判定        ErrorLogPath取得      Join-AdminUnc
         │                    │                    │
         └────────────────────┼────────────────────┘
                              │
                              ▼
                     Add-Member (NoteProperty)
                              │
                     ・ComputerName
                     ・InstanceName
                     ・Session
                     ・SessionStatus
                     ・TargetFile
                     ・RemoteTargetFile
                              │
                              ▼
                     Select-DefaultView
                              │
                              ▼
                     Microsoft.SqlServer.Management.XEvent.Target
                     (Extended)
```

### 関連ファイル一覧

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