# 画面設計書 85-XEセッションテンプレート

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける拡張イベント（Extended Events）セッションテンプレート管理機能の設計仕様を定義する。XEセッションテンプレートの参照、インポート、エクスポートを行うCLIを提供する。

### 本画面の処理概要

本機能は、Extended Eventsセッションの定義済みテンプレートを管理するためのコマンドラインインターフェースを提供する。テンプレートはXML形式で保存され、dbatools組み込みのテンプレートリポジトリと、ユーザー独自のテンプレートディレクトリの両方をサポートする。

**業務上の目的・背景**：Extended Eventsセッションをゼロから構築するのは複雑で時間がかかる。本機能は、Microsoft、Jes Borland、Christian Grafe、Erin Stellato等のエキスパートが作成した定義済みテンプレートを提供し、パフォーマンス監視、デッドロック追跡、セキュリティ監査などの一般的な監視シナリオを即座にセットアップできるようにする。また、既存のXEセッションをテンプレートとしてエクスポートし、SSMS（SQL Server Management Studio）で再利用可能にする機能も提供する。

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

**主要な操作・処理内容**：
1. dbatools組み込みテンプレートリポジトリの参照
2. テンプレートメタデータ（名前、カテゴリ、互換性、説明）の取得
3. パターンマッチングによるテンプレート検索
4. 既存XEセッションのXMLテンプレートへのエクスポート
5. SSMSテンプレートフォルダへの自動保存

**画面遷移**：
- 入力元：テンプレート確認後、Import-DbaXESessionTemplateでセッション作成
- 関連：`Get-DbaXESession`で既存セッション確認後エクスポート

**権限による表示制御**：Get-DbaXESessionTemplateはローカルファイル参照のみのため権限不要。Export-DbaXESessionTemplateはsysadmin権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|-------------------|
| 304 | Get-DbaXESessionTemplate | 主機能 | テンプレート情報取得 |
| 204 | Export-DbaXESessionTemplate | 主機能 | テンプレートエクスポート |
| 327 | Import-DbaXESessionTemplate | 遷移先機能 | テンプレートからセッション作成 |

## 画面種別

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

## URL/ルーティング

PowerShellコマンド呼び出し：
- `Get-DbaXESessionTemplate [-Path <テンプレートパス>] [-Pattern <検索パターン>] [-Template <テンプレート名>]`
- `Export-DbaXESessionTemplate -SqlInstance <インスタンス名> [-Session <セッション名>] [-Path <出力パス>]`
- `Get-DbaXESessionTemplate | Out-GridView -PassThru | Import-DbaXESessionTemplate -SqlInstance <インスタンス名>`

## 入出力項目

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

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| Path | string[] | いいえ | テンプレートディレクトリパス（デフォルト：dbatools組み込みリポジトリ） |
| Pattern | string | いいえ | 検索パターン（名前、カテゴリ、説明等にマッチ） |
| Template | string[] | いいえ | 特定テンプレート名 |
| EnableException | switch | いいえ | 例外処理の有効化 |

### Export-DbaXESessionTemplate 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | いいえ | 対象SQLインスタンス |
| SqlCredential | PSCredential | いいえ | 認証情報 |
| Session | object[] | いいえ | エクスポート対象セッション名 |
| Path | string | いいえ | 出力ディレクトリ（デフォルト：SSMSテンプレートフォルダ） |
| FilePath | string | いいえ | 出力ファイルパス（1セッションの場合のみ） |
| InputObject | Microsoft.SqlServer.Management.XEvent.Session[] | いいえ | パイプライン入力 |
| EnableException | switch | いいえ | 例外処理の有効化 |

## 表示項目

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

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| Name | string | セッション名 |
| Category | string | テンプレートカテゴリ |
| Source | string | テンプレート提供元 |
| Compatibility | string | 互換性のあるSQL Serverバージョン |
| Description | string | テンプレートの説明 |
| TemplateName | string | テンプレート名（非表示） |
| Path | FileInfo | テンプレートファイルパス（非表示） |
| File | string | テンプレートファイル名（非表示） |

### Export-DbaXESessionTemplate 出力オブジェクト

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| Name | string | ファイル名 |
| FullName | string | 完全パス |
| DirectoryName | string | ディレクトリパス |
| Extension | string | 拡張子（.xml） |
| Length | long | ファイルサイズ（バイト） |
| CreationTime | datetime | 作成日時 |
| LastWriteTime | datetime | 最終更新日時 |
| LastAccessTime | datetime | 最終アクセス日時 |
| Mode | string | ファイル属性 |

## イベント仕様

### 1-テンプレート一覧取得（Get-DbaXESessionTemplate）

1. xetemplates-metadata.xmlからメタデータを読み込み
2. Patternパラメータのワイルドカードを正規表現に変換
3. 指定ディレクトリ（デフォルト：$PSModuleRoot\bin\XEtemplates）からXMLファイル取得
4. Templateパラメータでファイル名フィルタリング
5. 各XMLファイルを解析しevent_sessions要素を抽出
6. メタデータとXML情報を結合
7. Patternパラメータでフィルタリング（名前、カテゴリ、ソース、説明にマッチ）
8. PSCustomObjectとして出力

### 2-テンプレートエクスポート（Export-DbaXESessionTemplate）

1. SqlInstance指定時はGet-DbaXESessionでセッション取得
2. 各セッションに対して処理
3. セッション名から不正なファイル名文字を削除
4. 出力パスの存在確認
5. FilePathが未指定の場合はPath + セッション名.xmlを生成
6. XEStore.SaveSessionToTemplate()でXMLファイル保存
7. FileInfoオブジェクトを出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaXESessionTemplate | なし | - | ローカルファイルのみ参照 |
| Export-DbaXESessionTemplate | なし | - | セッション情報読み取り後ローカルファイル出力 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------||
| MSG001 | エラー | Failure | XMLファイル解析エラー時 |
| MSG002 | エラー | Error occurred while establishing connection to {instance} | 接続エラー時 |
| MSG003 | エラー | {Path} does not exist. | 出力パス未存在時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| XMLファイル解析エラー | Stop-Functionでエラーを表示し、次のファイルに継続 |
| 接続エラー | Stop-Functionでエラーを表示し、次のインスタンスに継続 |
| 出力パス未存在 | Stop-Functionでエラーを表示し処理を停止 |

## 備考

- Get-DbaXESessionTemplateはSQL Server接続不要（ローカルファイル参照のみ）
- dbatools組み込みテンプレートは以下のソースから収集：
  - Microsoft（SSMSに含まれるテンプレート）
  - Jes Borland（"Everyday Extended Events"プレゼンテーション）
  - Christian Grafe（XE Repoスクリプト）
  - Erin Stellato（SQLskillsブログ）
  - Jonathan M. Kehayias（sp_SQLskills_ConvertTraceToExtendedEvents.sql）
- Export-DbaXESessionTemplateのデフォルト出力先は`$home\Documents\SQL Server Management Studio\Templates\XEventTemplates`
- SSMSテンプレートフォルダに保存するとSSMSのテンプレートブラウザで即座に利用可能
- Patternパラメータはワイルドカード（*）を正規表現（.*）に変換して検索
- CompatibilityはSQL Serverバージョン（2008, 2012, 2014, 2016, 2017, 2019等）のカンマ区切りリスト

---

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

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

### 推奨読解順序

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

出力はPSCustomObject（Get-DbaXESessionTemplate）またはFileInfo（Export-DbaXESessionTemplate）である。

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

**読解のコツ**: Get-DbaXESessionTemplateでは、XMLファイルの内容とメタデータXMLを組み合わせて出力オブジェクトを構築している（138-147行目、150-159行目）。

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

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

**主要処理フロー（Get-DbaXESessionTemplate）**:
1. **106-107行目**: メタデータXMLの読み込み
2. **109行目**: ワイルドカードの正規表現変換
3. **112-117行目**: XMLファイル取得とフィルタリング
4. **119-124行目**: 各XMLファイルの解析
5. **128-148行目**: パターンマッチングとオブジェクト生成

#### Step 3: テンプレートエクスポート処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Export-DbaXESessionTemplate.ps1 | `public/Export-DbaXESessionTemplate.ps1` | SaveSessionToTemplate()呼び出し（119行目） |

**主要処理フロー**:
- **100-106行目**: SqlInstance指定時のセッション取得
- **109行目**: ファイル名のサニタイズ
- **115-117行目**: ファイルパス生成
- **119行目**: XEStore.SaveSessionToTemplate()でXML保存
- **120行目**: FileInfoオブジェクト出力

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

```
Get-DbaXESessionTemplate
    │
    ├─ Import-Clixml (xetemplates-metadata.xml)
    │      └─ メタデータ読み込み
    │
    ├─ Get-ChildItem (*.xml)
    │      └─ テンプレートファイル取得
    │
    ├─ [xml](Get-Content)
    │      └─ XMLファイル解析
    │
    ├─ Where-Object (Pattern マッチング)
    │      └─ 名前、カテゴリ、ソース、説明でフィルタ
    │
    └─ Select-DefaultView
           └─ 表示プロパティ選択（Name, Category, Source, Compatibility, Description）

Export-DbaXESessionTemplate
    │
    ├─ Test-ExportDirectory
    │      └─ 出力ディレクトリ確認
    │
    ├─ Get-DbaXESession (SqlInstance指定時)
    │      └─ セッション取得
    │
    ├─ Remove-InvalidFileNameChars
    │      └─ ファイル名サニタイズ
    │
    ├─ XEStore.SaveSessionToTemplate()
    │      └─ XMLテンプレート保存
    │
    └─ Get-ChildItem
           └─ FileInfoオブジェクト出力
```

### データフロー図

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

[Get-DbaXESessionTemplate]

Path (ディレクトリ) ──────▶ Get-ChildItem (*.xml)
                                    │
                                    ▼
xetemplates-metadata.xml ──▶ Import-Clixml ──────▶ $metadata
                                    │
                                    ▼
Template ────────────────▶ Where-Object (BaseName)
                                    │
                                    ▼
                          [xml](Get-Content) ──────▶ $xml
                                    │
                                    ▼
Pattern ─────────────────▶ Pattern Matching
                                    │
                          (Name, Category, Source, Description)
                                    │
                                    ▼
                          PSCustomObject ──────────▶ 出力
                          (Name, Category, Source,
                           Compatibility, Description)

[Export-DbaXESessionTemplate]

SqlInstance ──────────────▶ Get-DbaXESession ──────▶ XEvent.Session
     │                              │
     │                              ▼
Session ─────────────────▶ Where-Object (Name)
                                    │
                                    ▼
                          Remove-InvalidFileNameChars
                                    │
                                    ▼
Path ────────────────────▶ Join-DbaPath ────────────▶ $FilePath
                                    │
                                    ▼
                          XEStore.SaveSessionToTemplate()
                                    │
                                    ▼
                          Get-ChildItem ──────────▶ FileInfo
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaXESessionTemplate.ps1 | `public/Get-DbaXESessionTemplate.ps1` | ソース | テンプレート情報取得 |
| Export-DbaXESessionTemplate.ps1 | `public/Export-DbaXESessionTemplate.ps1` | ソース | テンプレートエクスポート |
| Import-DbaXESessionTemplate.ps1 | `public/Import-DbaXESessionTemplate.ps1` | 依存 | テンプレートインポート |
| Get-DbaXESession.ps1 | `public/Get-DbaXESession.ps1` | 依存 | セッション取得 |
| xetemplates-metadata.xml | `bin/xetemplates-metadata.xml` | データ | テンプレートメタデータ |
| XEtemplates/*.xml | `bin/XEtemplates/*.xml` | データ | 組み込みテンプレートファイル |
