# 画面設計書 88-XEオブジェクト・ストア

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける拡張イベント（Extended Events）オブジェクトおよびストア取得機能の設計仕様を定義する。XEオブジェクト（イベント、アクション、ターゲット等）の一覧取得とXEStoreオブジェクトの取得を行うCLIを提供する。

### 本画面の処理概要

本機能は、Extended Eventsのビルディングブロック（イベント、アクション、ターゲット等）の一覧取得と、XEセッション管理の基盤となるXEStoreオブジェクトの取得を行うためのコマンドラインインターフェースを提供する。

**業務上の目的・背景**：Extended Eventsセッションの設計時には、利用可能なイベント、アクション、ターゲットを把握する必要がある。これらのXEオブジェクトはSQL Serverのバージョンやエディションによって異なる。本機能は、sys.dm_xe_packages/sys.dm_xe_objectsを照会して利用可能なコンポーネントを表示し、適切なセッション設計を支援する。また、XEStoreオブジェクトはセッション管理のプログラミングインターフェースを提供する。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスする：
- `Get-DbaXEObject -SqlInstance <インスタンス名>`
- `Get-DbaXEObject -SqlInstance <インスタンス名> -Type Event,Action`
- `Get-DbaXEStore -SqlInstance <インスタンス名>`

**主要な操作・処理内容**：
1. XEオブジェクト（イベント、アクション、ターゲット等）の一覧取得
2. オブジェクトタイプによるフィルタリング
3. XEStoreオブジェクトの取得
4. 利用可能なパッケージ情報の取得

**画面遷移**：
- 入力元：XEセッション設計の事前調査として使用
- 関連：`New-DbaXESession`でセッション作成時に参照

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|-------------------|
| 302 | Get-DbaXEObject | 主機能 | XEオブジェクト取得 |
| 306 | Get-DbaXEStore | 主機能 | XEストア取得 |
| 356 | New-DbaXESession | 遷移先機能 | セッション作成 |

## 画面種別

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

## URL/ルーティング

PowerShellコマンド呼び出し：
- `Get-DbaXEObject -SqlInstance <インスタンス名>`
- `Get-DbaXEObject -SqlInstance <インスタンス名> -Type <タイプ>`
- `Get-DbaXEStore -SqlInstance <インスタンス名>`

## 入出力項目

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

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | はい | 対象SQLインスタンス |
| SqlCredential | PSCredential | いいえ | 認証情報 |
| Type | string[] | いいえ | フィルタリング対象タイプ |
| EnableException | switch | いいえ | 例外処理の有効化 |

**Typeパラメータの許容値**：
- Type
- Event
- Target
- Action
- Map
- Message
- PredicateComparator
- PredicateSource

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

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | はい | 対象SQLインスタンス |
| SqlCredential | PSCredential | いいえ | 認証情報 |
| EnableException | switch | いいえ | 例外処理の有効化 |

## 表示項目

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

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| PackageName | string | パッケージ名（例：package0, sqlserver） |
| ObjectType | string | オブジェクトタイプ（フレンドリー形式） |
| TargetName | string | オブジェクト名 |
| Description | string | オブジェクト説明 |
| ComputerName | string | コンピュータ名（非表示） |
| InstanceName | string | インスタンス名（非表示） |
| SqlInstance | string | 完全インスタンス名（非表示） |
| ObjectTypeRaw | string | オブジェクトタイプ（生値、非表示） |

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

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全インスタンス名 |
| ServerName | string | サーバー名 |
| Sessions | Collection | セッションコレクション |
| Packages | Collection | パッケージコレクション |
| RunningSessionCount | int | 実行中セッション数 |

## イベント仕様

### 1-XEオブジェクト取得（Get-DbaXEObject）

1. Typeパラメータが指定されている場合はWHERE句を構築
2. PredicateComparator/PredicateSourceの名前変換
3. Connect-DbaInstance（MinimumVersion 9）
4. sys.dm_xe_packages/sys.dm_xe_objectsを結合するSQLを実行
5. capabilities & 1 = 0 で内部オブジェクトを除外
6. Select-DefaultViewで出力プロパティを選択

### 2-XEストア取得（Get-DbaXEStore）

1. Connect-DbaInstance（MinimumVersion 11）
2. SqlStoreConnectionオブジェクト作成
3. XEStoreオブジェクト作成
4. Add-MemberでNotePropertyを追加
5. Select-DefaultViewで出力プロパティを選択

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaXEObject | sys.dm_xe_packages, sys.dm_xe_objects | SELECT | DMV読み取り |
| Get-DbaXEStore | なし | - | SMOオブジェクト取得 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------||
| MSG001 | エラー | Failure | 接続エラー時 |
| MSG002 | エラー | Issue collecting trace data on {server}. | クエリ実行エラー時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 接続エラー | Stop-Functionでエラーを表示し、次のインスタンスに継続 |
| クエリ実行エラー | Stop-Functionでエラーを表示 |

## 備考

- Get-DbaXEObjectはSQL Server 2005以降が必要（MinimumVersion 9）
- Get-DbaXEStoreはSQL Server 2012以降が必要（MinimumVersion 11）
- オブジェクトタイプの変換：
  - type → Type
  - event → Event
  - target → Target
  - pred_compare → PredicateComparator
  - pred_source → PredicateSource
  - action → Action
  - map → Map
  - message → Message
- capabilities & 1 = 0 で内部使用オブジェクトを除外
- パッケージ例：
  - package0：基本パッケージ（event_file, ring_buffer等）
  - sqlserver：SQL Server固有イベント
  - sqlos：OS関連イベント
  - SecAudit：セキュリティ監査イベント

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaXEObject.ps1 | `public/Get-DbaXEObject.ps1` | 出力オブジェクトの構造（37-58行目）を確認 |
| 1-2 | Get-DbaXEStore.ps1 | `public/Get-DbaXEStore.ps1` | 出力オブジェクトの構造（32-46行目）を確認 |

**読解のコツ**: Get-DbaXEObjectはT-SQL結果をそのまま出力。Get-DbaXEStoreはSMOオブジェクトにNotePropertyを追加。

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

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

**主要処理フロー（Get-DbaXEObject）**:
1. **84-89行目**: TypeパラメータからWHERE句を構築
2. **90-115行目**: T-SQLクエリを構築
3. **120行目**: Connect-DbaInstance（MinimumVersion 9）
4. **126行目**: Query()でSQLを実行

#### Step 3: T-SQLクエリを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaXEObject.ps1 | `public/Get-DbaXEObject.ps1` | T-SQLクエリ（90-115行目） |

**クエリの主要ポイント**:
- **109-110行目**: sys.dm_xe_packages/sys.dm_xe_objectsの結合
- **111行目**: パッケージのcapabilities除外
- **113行目**: オブジェクトのcapabilities除外
- **94-105行目**: object_typeのフレンドリー名変換

#### Step 4: XEStore作成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaXEStore.ps1 | `public/Get-DbaXEStore.ps1` | XEStore作成（73-80行目） |

**主要処理フロー**:
- **73行目**: SqlConnectionObjectを取得
- **74行目**: SqlStoreConnectionを作成
- **75行目**: XEStoreを作成
- **77-79行目**: NotePropertyを追加

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

```
Get-DbaXEObject
    │
    ├─ Type パラメータ処理
    │      └─ WHERE句構築
    │
    ├─ Connect-DbaInstance (MinimumVersion 9)
    │      └─ SMOサーバーオブジェクト取得
    │
    ├─ Server.Query()
    │      └─ T-SQL実行 (sys.dm_xe_packages/sys.dm_xe_objects)
    │
    └─ Select-DefaultView
           └─ 表示プロパティ選択

Get-DbaXEStore
    │
    ├─ Connect-DbaInstance (MinimumVersion 11)
    │      └─ SMOサーバーオブジェクト取得
    │
    ├─ SqlStoreConnection
    │      └─ Sfcストア接続作成
    │
    ├─ XEStore
    │      └─ Extended Eventsストア作成
    │
    ├─ Add-Member (NoteProperty追加)
    │      └─ ComputerName, InstanceName, SqlInstance
    │
    └─ Select-DefaultView
           └─ 表示プロパティ選択
```

### データフロー図

```
[Get-DbaXEObject]

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

Type ─────────────▶ WHERE句構築
                              │
                    PredicateComparator → pred_compare
                    PredicateSource → pred_source
                              │
SqlInstance ──────▶ Connect-DbaInstance ─────────▶ SMO Server
                              │
                              ▼
                     Server.Query()
                              │
         ┌────────────────────┼────────────────────┐
         │                    │                    │
         ▼                    ▼                    ▼
  sys.dm_xe_packages   sys.dm_xe_objects    CASE変換
         │                    │               (object_type)
         │                    │                    │
         └────────────────────┼────────────────────┘
                              │
                              ▼
                     Select-DefaultView
                              │
                              ▼
                     PSCustomObject
                     (PackageName, ObjectType, TargetName, Description)


[Get-DbaXEStore]

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

SqlInstance ──────▶ Connect-DbaInstance ─────────▶ SMO Server
                              │
                              ▼
                     SqlConnectionObject
                              │
                              ▼
                     SqlStoreConnection
                              │
                              ▼
                     XEStore
                              │
                              ▼
                     Add-Member (NoteProperty)
                              │
                              ▼
                     Select-DefaultView
                              │
                              ▼
                     Microsoft.SqlServer.Management.XEvent.XEStore
                     (ComputerName, SqlInstance, Sessions, Packages, RunningSessionCount)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaXEObject.ps1 | `public/Get-DbaXEObject.ps1` | ソース | XEオブジェクト取得 |
| Get-DbaXEStore.ps1 | `public/Get-DbaXEStore.ps1` | ソース | XEストア取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | 依存 | SQL Server接続 |
| New-DbaXESession.ps1 | `public/New-DbaXESession.ps1` | 関連 | セッション作成 |
