# 機能設計書 300-Get-DbaXESession

## 概要

本ドキュメントは、SQL Serverインスタンスから拡張イベントセッションの詳細な設定とステータス情報を取得するGet-DbaXESession機能について記述する。

### 本機能の処理概要

Get-DbaXESessionは、SQL ServerのXEStore（拡張イベントストア）からセッションの包括的な情報を取得するコマンドレットである。セッションの現在の状態、構成詳細、ターゲットファイル、メモリ設定などを含む詳細情報を返す。

**業務上の目的・背景**：拡張イベントセッションはSQL Serverの最新のイベント処理システムであり、パフォーマンス監視、トラブルシューティング、監査に使用される。複数のSQL Serverインスタンスに分散した監視設定を把握し、運用状態を確認することは運用管理上重要である。本機能は複数サーバーのXEセッション情報を一括で取得し、ターゲットファイルパスのUNC形式への変換も自動で行うため、リモート管理が容易になる。

**機能の利用シーン**：
- 複数サーバーのXEセッション状態の一括確認
- セッション設定のドキュメント化
- 監視設定の標準化状況の確認
- セッションのターゲットファイル位置の特定
- トラブルシューティング前の環境把握

**主要な処理内容**：
1. SQL Serverインスタンスへの接続（MinimumVersion=11: SQL Server 2012以上）
2. XEStoreオブジェクトの作成と接続
3. セッション一覧の取得とフィルタリング
4. ターゲットファイルパスの解決（ローカルパス→UNCパス変換）
5. 追加プロパティ（Status、Session、TargetFile、RemoteTargetFile等）の付加
6. 構造化されたSessionオブジェクトの出力

**関連システム・外部連携**：Copy-DbaXESession、Export-DbaXESession、Export-DbaXESessionTemplateなどのパイプライン入力元として使用。

**権限による制御**：VIEW SERVER STATE権限が必要。sysadmin権限推奨。SQL Server 2012（バージョン11）以上が必須。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 84 | XEセッション管理 | 主機能 | 拡張イベントセッションの取得 |

## 機能種別

データ取得 / 構成管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | SQL Server 2012以上 |
| SqlCredential | PSCredential | No | SQL Server認証情報 | - |
| Session | object[] | No | フィルタ対象セッション名（エイリアス: Sessions） | - |
| EnableException | switch | No | 例外を有効にする | - |

### 入力データソース

- Microsoft.SqlServer.Management.XEvent.XEStore.Sessions（セッションコレクション）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピュータ名（NoteProperty） |
| InstanceName | string | インスタンス名（NoteProperty） |
| SqlInstance | string | 完全なインスタンス名（NoteProperty） |
| Name | string | セッション名（SMOプロパティ） |
| Status | string | ステータス（Running/Stopped）（NoteProperty） |
| StartTime | datetime | 開始日時（SMOプロパティ） |
| AutoStart | bool | 自動開始設定（SMOプロパティ） |
| State | string | SMOオブジェクト状態（SMOプロパティ） |
| Targets | Collection | ターゲットコレクション（SMOプロパティ） |
| TargetFile | string[] | ターゲットファイルパス配列（NoteProperty） |
| Events | Collection | イベントコレクション（SMOプロパティ） |
| MaxMemory | int | 最大メモリ（KB）（SMOプロパティ） |
| MaxEventSize | int | 最大イベントサイズ（KB）（SMOプロパティ） |
| Session | string | セッション名（Nameのエイリアス）（NoteProperty） |
| RemoteTargetFile | string[] | UNC形式のターゲットファイルパス配列（NoteProperty） |
| Parent | Server | 親サーバーオブジェクト（NoteProperty） |
| Store | XEStore | XEStoreオブジェクト（NoteProperty） |

### 出力先

パイプライン（Microsoft.SqlServer.Management.XEvent.Session + NoteProperty）

## 処理フロー

### 処理シーケンス

```
1. インスタンス接続（process）
   └─ Connect-DbaInstance（MinimumVersion=11、AzureUnsupported）
   └─ SqlStoreConnection作成
   └─ XEStore作成
2. セッション取得
   └─ XEStore.Sessionsからセッション一覧取得
   └─ Sessionパラメータによるフィルタリング
3. 各セッションの処理
   └─ ステータス判定（IsRunning → "Running"/"Stopped"）
   └─ ターゲットファイルパスの解決
   └─ UNCパスへの変換（Join-AdminUnc）
   └─ NotePropertyの付加
4. Select-DefaultViewで出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{各インスタンスループ}
    B --> C[Connect-DbaInstance]
    C --> D[SqlStoreConnection作成]
    D --> E[XEStore作成]
    E --> F[Sessions取得]
    F --> G{Session フィルタ?}
    G -->|Yes| H[名前でフィルタ]
    G -->|No| I{各セッションループ}
    H --> I
    I --> J[ステータス判定]
    J --> K{ターゲットファイルあり?}
    K -->|Yes| L[ファイルパス解決]
    K -->|No| M[NoteProperty付加]
    L --> N[UNCパス変換]
    N --> M
    M --> O[Select-DefaultView]
    O --> I
    I -->|完了| B
    B -->|完了| P[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | バージョン要件 | SQL Server 2012以上が必須 | 接続時 |
| BR-002 | Azure非サポート | Azure SQL Databaseは非サポート | 接続時 |
| BR-003 | ステータス変換 | IsRunning=true→"Running", false→"Stopped" | 常時 |
| BR-004 | ファイルパス解決 | 相対パスの場合はErrorLogPathを基準に解決 | ファイル名のみ指定時 |
| BR-005 | UNCパス変換 | ローカルパスをUNC形式に変換 | 常時 |

### 計算ロジック

- Status = IsRunning ? "Running" : "Stopped"
- ファイルパス: パスにドライブ区切り文字がない場合、ErrorLogPath + ファイル名で解決
- UNCパス: \\servername\drive$\path形式に変換

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| セッション取得 | XEStore.Sessions | SELECT | セッションメタデータ |

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

SMOのXEStoreを使用。DMVへの直接アクセスはなし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | インスタンスに接続できない | 接続情報の確認 |
| AzureUnsupported | 非サポートエラー | Azure SQL Databaseに接続 | オンプレミスSQL Serverを使用 |

### リトライ仕様

リトライ処理なし。エラー発生時はStop-Functionで次のインスタンスへ継続。

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

読み取り専用操作。トランザクション制御なし。

## パフォーマンス要件

特に規定なし。SMOからのメタデータ読み取りのため高速。

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

- VIEW SERVER STATE権限が必要
- 出力にはターゲットファイルのパス情報が含まれる
- UNCパスは管理共有（$）を使用するため管理者権限が必要な場合がある

## 備考

- SQL Server 2012以上が必須（SQL Server 2008はXEStoreのサポートが限定的）
- Azure SQL Databaseは非サポート
- Copy-DbaXESession、Export-DbaXESession、Export-DbaXESessionTemplateの入力として使用可能

---

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

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

### 推奨読解順序

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

XEStoreとSessionオブジェクトの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaXESession.ps1 | `public/Get-DbaXESession.ps1` | NoteProperty付加部分（134-143行目） |

**読解のコツ**: Add-Memberで追加されるNotePropertyがデフォルト出力に含まれる点に注目。

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

processブロックでのXEStore接続とセッション取得を確認する。

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

**主要処理フロー**:
1. **102行目**: Connect-DbaInstanceでMinimumVersion 11、AzureUnsupportedを指定
2. **103-105行目**: SqlStoreConnectionとXEStoreの作成
3. **111-115行目**: セッションの取得とフィルタリング
4. **117-131行目**: ターゲットファイルパスの解決とUNC変換

#### Step 3: ファイルパス解決を理解する

ターゲットファイルのパス解決ロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaXESession.ps1 | `public/Get-DbaXESession.ps1` | ファイルパス解決部分（119-131行目） |

**主要処理フロー**:
- **119行目**: ターゲットファイルの取得
- **124-125行目**: パス区切り文字がない場合、ErrorLogPathを基準にJoin-DbaPath
- **130行目**: Join-AdminUncでUNC形式に変換

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

```
Get-DbaXESession
    │
    └─ process
           │
           └─ foreach $instance
                  │
                  ├─ Connect-DbaInstance
                  │      ├─ MinimumVersion 11
                  │      └─ AzureUnsupported
                  │
                  ├─ SqlConnectionObject.Clone()
                  │
                  ├─ New-Object SqlStoreConnection
                  │
                  ├─ New-Object XEStore
                  │
                  ├─ XEStore.Sessions
                  │      └─ [Session指定時] Where-Object Name -in
                  │
                  └─ foreach $x (session)
                         │
                         ├─ ステータス判定 (IsRunning)
                         │
                         ├─ ターゲットファイル取得
                         │      └─ Targets.TargetFields | Where-Object Name -eq Filename
                         │
                         ├─ パス解決
                         │      └─ Join-DbaPath (相対パス時)
                         │
                         ├─ UNC変換
                         │      └─ Join-AdminUnc
                         │
                         ├─ Add-Member (NoteProperty追加)
                         │      ├─ ComputerName
                         │      ├─ InstanceName
                         │      ├─ SqlInstance
                         │      ├─ Status
                         │      ├─ Session
                         │      ├─ TargetFile
                         │      ├─ RemoteTargetFile
                         │      ├─ Parent
                         │      └─ Store
                         │
                         └─ Select-DefaultView
```

### データフロー図

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

SqlInstance ─────────────────▶ Connect-DbaInstance
                                     │
                                     ▼
                              XEStore作成
                                     │
                                     ▼
                              Sessions取得
                                     │
                              ┌──────┴──────┐
                              ▼             ▼
                         [Session指定時]  [全セッション]
                              │             │
                              └──────┬──────┘
                                     ▼
                              foreach session
                                     │
                              ┌──────┴──────┐
                              ▼             ▼
                         ステータス判定  ファイルパス解決
                              │             │
                              └──────┬──────┘
                                     ▼
                              Add-Member
                              (NoteProperty)
                                     │
                                     ▼
                              Select-DefaultView
                                     │
                                     ▼
                              Session Object
                              + NoteProperties
                                     │
                                     ▼
                                  Pipeline
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaXESession.ps1 | `public/Get-DbaXESession.ps1` | ソース | メイン処理 |
| Copy-DbaXESession.ps1 | `public/Copy-DbaXESession.ps1` | ソース | パイプライン出力先 |
| Export-DbaXESession.ps1 | `public/Export-DbaXESession.ps1` | ソース | パイプライン出力先 |
| Export-DbaXESessionTemplate.ps1 | `public/Export-DbaXESessionTemplate.ps1` | ソース | パイプライン出力先 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続 |
| Join-AdminUnc.ps1 | `private/functions/` | ソース | UNCパス変換 |
