# 機能設計書 299-Get-DbaXEObject

## 概要

本ドキュメントは、SQL Serverインスタンスで利用可能な拡張イベントオブジェクトを取得するGet-DbaXEObject機能について記述する。

### 本機能の処理概要

Get-DbaXEObjectは、SQL Serverの動的管理ビュー（sys.dm_xe_packages、sys.dm_xe_objects）をクエリし、利用可能な拡張イベントコンポーネントを発見するコマンドレットである。イベント、アクション、ターゲット、マップ、メッセージ、タイプ、述語コンパレータ、述語ソースなどのXEビルディングブロックを一覧表示する。

**業務上の目的・背景**：拡張イベントセッションを計画・設計する際、どのイベント、アクション、ターゲットが利用可能かを把握することは重要である。SQL Serverのバージョンやエディションによって利用可能なXEオブジェクトは異なるため、事前の確認が必要である。本機能はDMVへのアクセスを簡素化し、XEセッション設計に必要な情報を提供する。

**機能の利用シーン**：
- 拡張イベントセッションの設計・計画
- 利用可能なイベント・アクション・ターゲットの調査
- SQL Serverバージョン間のXE機能比較
- トラブルシューティングセッション構築のための情報収集
- セキュリティ監査セッションの設計

**主要な処理内容**：
1. SQL Serverインスタンスへの接続（MinimumVersion=9: SQL Server 2005以上）
2. sys.dm_xe_packagesとsys.dm_xe_objectsのJOINクエリ実行
3. Typeパラメータによるフィルタリング（Event、Action、Target等）
4. オブジェクトタイプの表示名変換
5. 構造化されたPSCustomObjectの出力

**関連システム・外部連携**：なし

**権限による制御**：VIEW SERVER STATE権限が必要（DMVへのアクセス）。SQL Server 2005（バージョン9）以上が必須。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 88 | XEオブジェクト・ストア | 主機能 | XEオブジェクトの取得 |

## 機能種別

データ取得 / メタデータ検索

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | SQL Server 2005以上 |
| SqlCredential | PSCredential | No | SQL Server認証情報 | - |
| Type | string[] | No | フィルタ対象タイプ | Type/Event/Target/Action/Map/Message/PredicateComparator/PredicateSource |
| EnableException | switch | No | 例外を有効にする | - |

### 入力データソース

- sys.dm_xe_packages（XEパッケージ）
- sys.dm_xe_objects（XEオブジェクト）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピュータ名（デフォルト非表示） |
| InstanceName | string | インスタンス名（デフォルト非表示） |
| SqlInstance | string | 完全なインスタンス名 |
| PackageName | string | パッケージ名（package0、sqlserver等） |
| ObjectType | string | オブジェクトタイプ（表示名） |
| ObjectTypeRaw | string | オブジェクトタイプ（生値、デフォルト非表示） |
| TargetName | string | オブジェクト名 |
| Description | string | 説明 |

### 出力先

パイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. SQLクエリの構築（begin）
   └─ Typeパラメータ指定時: WHERE句を追加
   └─ タイプ名の変換（PredicateComparator → pred_compare等）
2. インスタンス接続（process）
3. クエリ実行
4. Select-DefaultViewで出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Type指定?}
    B -->|Yes| C[WHERE句構築]
    B -->|No| D[SQLクエリ組み立て]
    C --> E[タイプ名変換]
    E --> D
    D --> F{各インスタンスループ}
    F --> G[Connect-DbaInstance]
    G --> H[Server.Query実行]
    H --> I[Select-DefaultView]
    I --> F
    F -->|完了| J[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | バージョン要件 | SQL Server 2005以上が必須 | 接続時 |
| BR-002 | タイプ名変換 | PredicateComparator → pred_compare, PredicateSource → pred_source | Typeフィルタ時 |
| BR-003 | パッケージフィルタ | capabilities IS NULL OR capabilities & 1 = 0のパッケージのみ | 常時 |
| BR-004 | オブジェクトフィルタ | capabilities IS NULL OR capabilities & 1 = 0のオブジェクトのみ | 常時 |
| BR-005 | ソート順 | object_typeでソート | 常時 |

### 計算ロジック

オブジェクトタイプの表示名変換:
- type → Type
- event → Event
- target → Target
- pred_compare → PredicateComparator
- pred_source → PredicateSource
- action → Action
- map → Map
- message → Message

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| パッケージ取得 | sys.dm_xe_packages | SELECT | XEパッケージ情報 |
| オブジェクト取得 | sys.dm_xe_objects | SELECT | XEオブジェクト情報 |

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

#### sys.dm_xe_objects

| 操作 | 項目（カラム名） | 取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name, object_type, description | capabilities IS NULL OR capabilities & 1 = 0 | JOINでパッケージと結合 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | インスタンスに接続できない | 接続情報の確認 |
| QueryFailure | クエリエラー | DMVクエリ実行失敗 | 権限の確認 |

### リトライ仕様

リトライ処理なし。エラー発生時はStop-Functionで処理終了。

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

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

## パフォーマンス要件

特に規定なし。DMVからの読み取りのため高速。

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

- VIEW SERVER STATE権限が必要
- 出力にはSQL Serverの内部メタデータが含まれる

## 備考

- SQL Server 2005で拡張イベントが導入されたが、本格的なサポートはSQL Server 2008以降
- バージョンやエディションによって利用可能なオブジェクトが異なる
- Typeパラメータで特定のコンポーネントタイプに絞り込み可能

---

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

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

### 推奨読解順序

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

オブジェクトタイプの変換とSQLクエリの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaXEObject.ps1 | `public/Get-DbaXEObject.ps1` | オブジェクトタイプ変換（94-104行目） |

**読解のコツ**: CASE式でobject_typeを表示名に変換している点に注目。

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

beginブロックでのSQLクエリ構築を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaXEObject.ps1 | `public/Get-DbaXEObject.ps1` | beginブロック（83-115行目） |

**主要処理フロー**:
1. **84-89行目**: TypeパラメータからWHERE句を構築
2. **90-115行目**: SELECT句の構築（CASE式でタイプ変換）

#### Step 3: 実行処理を理解する

processブロックでのクエリ実行を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaXEObject.ps1 | `public/Get-DbaXEObject.ps1` | processブロック（117-131行目） |

**主要処理フロー**:
- **120行目**: Connect-DbaInstanceでMinimumVersion 9を指定
- **126行目**: Server.Query($sql)でクエリ実行
- **126行目**: Select-DefaultViewで出力プロパティを制御

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

```
Get-DbaXEObject
    │
    ├─ begin
    │      │
    │      ├─ [Type指定時]
    │      │      ├─ WHERE句構築
    │      │      └─ タイプ名変換
    │      │            ├─ PredicateComparator → pred_compare
    │      │            └─ PredicateSource → pred_source
    │      │
    │      └─ SQLクエリ組み立て
    │             ├─ SELECT句 (CASE式でタイプ変換)
    │             ├─ FROM句 (JOIN)
    │             └─ WHERE句 (capabilities フィルタ)
    │
    └─ process
           │
           └─ foreach $instance
                  │
                  ├─ Connect-DbaInstance
                  │      └─ MinimumVersion 9
                  │
                  ├─ Server.Query($sql)
                  │
                  └─ Select-DefaultView
                         └─ ExcludeProperty: ComputerName, InstanceName, ObjectTypeRaw
```

### データフロー図

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

Type Parameter ──────────────▶ WHERE句構築
                                     │
                                     ▼
sys.dm_xe_packages ──────────▶ JOIN
sys.dm_xe_objects ───────────▶       │
                                     ▼
                               CASE式タイプ変換
                                     │
                                     ▼
                               フィルタ適用
                               (capabilities)
                                     │
                                     ▼
                               PSCustomObject
                                     │
                                     ▼
                               Select-DefaultView
                                     │
                                     ▼
                                  Pipeline
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaXEObject.ps1 | `public/Get-DbaXEObject.ps1` | ソース | メイン処理 |
| Get-DbaXESession.ps1 | `public/Get-DbaXESession.ps1` | ソース | 関連機能（セッション取得） |
| Get-DbaXEStore.ps1 | `public/Get-DbaXEStore.ps1` | ソース | 関連機能（ストア取得） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続 |
