# 機能設計書 303-Get-DbaXESessionTemplate

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `Get-DbaXESessionTemplate` コマンドレットの機能設計を記述する。このコマンドレットは、拡張イベントセッションのXMLテンプレートからメタデータを取得し、利用可能なテンプレートを発見・選択するための機能を提供する。

### 本機能の処理概要

`Get-DbaXESessionTemplate` は、dbatoolsリポジトリまたは指定されたディレクトリに格納されている拡張イベントセッションのXMLテンプレートを解析し、テンプレート名、カテゴリ、ソース、SQL Server互換性、説明などのメタデータを取得するコマンドレットである。

**業務上の目的・背景**：拡張イベントセッションをゼロから構築するのは複雑で時間がかかる。パフォーマンス、デッドロック、セキュリティ等、特定の監視シナリオに対応した検証済みのテンプレートを活用することで、監視ソリューションの構築を大幅に効率化できる。本機能により、利用可能なテンプレートを簡単に検索・発見し、Import-DbaXESessionTemplateと組み合わせて迅速にデプロイできる。

**機能の利用シーン**：
- 利用可能なXEセッションテンプレートの一覧を取得したい場合
- 特定の監視目的（パフォーマンス、デッドロック等）に適したテンプレートを検索したい場合
- テンプレートのSQL Server互換性を確認したい場合
- カスタムテンプレートを管理・検索したい場合

**主要な処理内容**：
1. 指定されたディレクトリからXMLファイルを列挙
2. 各XMLファイルをパースし、セッション情報を抽出
3. メタデータカタログ（xetemplates-metadata.xml）と照合
4. パターンマッチングまたはテンプレート名でフィルタリング
5. 構造化されたオブジェクトとして出力

**関連システム・外部連携**：dbatoolsの内蔵テンプレートリポジトリ（bin/XEtemplates）を参照。Microsoft SSMS、Jes Borland、Christian Grafe、Erin Stellato等の著名なソースからのテンプレートを含む。

**権限による制御**：ファイルシステムへの読み取り権限のみ必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 85 | XEセッションテンプレート | 主機能 | XEセッションテンプレートの取得 |

## 機能種別

データ取得処理（ファイルシステム読み取り）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Path | string[] | No | テンプレートディレクトリパス（デフォルト: bin/XEtemplates） | - |
| Pattern | string | No | 検索パターン（正規表現） | ワイルドカード*を.*に変換 |
| Template | string[] | No | 特定のテンプレート名 | - |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

- dbatoolsモジュールの内蔵テンプレートリポジトリ（bin/XEtemplates/*.xml）
- xetemplates-metadata.xml（互換性情報等のメタデータ）
- カスタム指定されたディレクトリ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Name | String | セッション名 |
| Category | String | テンプレートカテゴリ |
| Source | String | テンプレートのソース/作成者 |
| Compatibility | String | SQL Server互換性バージョン |
| Description | String | テンプレートの説明 |
| TemplateName | String | テンプレート名（非デフォルト表示） |
| Path | FileInfo | テンプレートファイルパス（非デフォルト表示） |
| File | String | ファイル名（非デフォルト表示） |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. 初期化（begin ブロック）
   └─ xetemplates-metadata.xml の読み込み
   └─ Patternのワイルドカード変換
2. テンプレートファイルの列挙
   └─ 指定ディレクトリから*.xmlを取得
   └─ Templateパラメータでフィルタリング
3. 各XMLファイルの解析
   └─ XMLコンテンツの読み込み
   └─ event_sessionsノードの抽出
4. メタデータの照合
   └─ xetemplates-metadata.xmlとの照合
5. Patternマッチング（指定時）
   └─ 名前、カテゴリ、ソース、説明でマッチ
6. 出力オブジェクトの構築
   └─ Select-DefaultViewで表示プロパティ制限
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[メタデータXML読み込み]
    B --> C[Patternのワイルドカード変換]
    C --> D[各Pathを処理]
    D --> E[Get-ChildItem *.xml]
    E --> F{Template指定?}
    F -->|Yes| G[BaseNameでフィルタ]
    F -->|No| H[全ファイル対象]
    G --> I[各XMLファイルを処理]
    H --> I
    I --> J[XMLコンテンツ読み込み]
    J --> K{読み込み成功?}
    K -->|No| L[Stop-Function]
    K -->|Yes| M[event_sessionsノード処理]
    L --> I
    M --> N[メタデータ照合]
    N --> O{Pattern指定?}
    O -->|Yes| P{パターンマッチ?}
    O -->|No| Q[PSCustomObject生成]
    P -->|Yes| Q
    P -->|No| I
    Q --> R[Select-DefaultView]
    R --> I
    I --> S{次のファイル?}
    S -->|Yes| I
    S -->|No| T[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-303-01 | ワイルドカード変換 | *を.*に、..*を.*に変換 | Pattern指定時 |
| BR-303-02 | パターンマッチ範囲 | 名前、カテゴリ、ソース、説明、テンプレート名でマッチ | Pattern指定時 |
| BR-303-03 | 互換性表示形式 | カンマを除去して表示 | 常時 |
| BR-303-04 | デフォルトパス | $script:PSModuleRoot/bin/XEtemplates | Path未指定時 |

### 計算ロジック

- パターン変換: `$Pattern.Replace("*", ".*").Replace("..*", ".*")`
- 互換性フォーマット: `$meta.Compatibility.ToString().Replace(",", "")`

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| なし | - | - | ファイルシステムのみ操作 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | XMLParseError | XMLファイルの解析失敗 | Stop-Functionで警告後継続 |

### リトライ仕様

なし

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

なし（読み取り専用処理）

## パフォーマンス要件

- テンプレートファイル数に比例した処理時間
- XMLパース処理はファイルごとに実行

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

- ファイルシステムへの読み取り権限のみ必要
- 外部からのXMLインジェクションリスクは低い（信頼できるテンプレートリポジトリを使用）

## 備考

- Import-DbaXESessionTemplateと組み合わせて使用
- Out-GridView -PassThruと組み合わせて対話的な選択が可能
- テンプレートソース: Microsoft SSMS、Jes Borland、Christian Grafe、Erin Stellato等

---

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

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

### 推奨読解順序

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

テンプレートXMLの構造とメタデータカタログの関係を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaXESessionTemplate.ps1 | `public/Get-DbaXESessionTemplate.ps1` | 出力オブジェクト構造（52-68行目） |
| 1-2 | xetemplates-metadata.xml | `bin/xetemplates-metadata.xml` | 互換性情報等のメタデータ形式 |

**読解のコツ**: 出力オブジェクトにはデフォルト表示プロパティと非表示プロパティがある。Select-DefaultView（147行目、159行目）でExcludePropertyを指定している。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaXESessionTemplate.ps1 | `public/Get-DbaXESessionTemplate.ps1` | begin ブロック（105-110行目） |
| 2-2 | Get-DbaXESessionTemplate.ps1 | `public/Get-DbaXESessionTemplate.ps1` | process ブロック（111-163行目） |

**主要処理フロー**:
1. **106-107行目**: メタデータXMLの読み込み
2. **109行目**: パターンのワイルドカード変換
3. **112-117行目**: XMLファイルの列挙とフィルタリング
4. **119-160行目**: 各ファイルの処理

#### Step 3: XMLパースとマッチングを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaXESessionTemplate.ps1 | `public/Get-DbaXESessionTemplate.ps1` | XMLパース（120-124行目） |
| 3-2 | Get-DbaXESessionTemplate.ps1 | `public/Get-DbaXESessionTemplate.ps1` | パターンマッチング（128-148行目） |

**主要処理フロー**:
- **120-124行目**: XML読み込みとエラー処理
- **127行目**: メタデータとの照合
- **128-148行目**: Patternマッチングと出力オブジェクト生成

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

```
Get-DbaXESessionTemplate
    │
    ├─ Import-Clixml（メタデータ読み込み）
    │
    ├─ Join-DbaPath
    │
    ├─ Get-ChildItem（*.xml取得）
    │
    ├─ Get-Content（XMLコンテンツ取得）
    │
    └─ Select-DefaultView
```

### データフロー図

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

Path ────────────────────▶ Get-ChildItem *.xml ─────▶ FileInfo[]
                                  │
                                  ▼
Template Filter ────────▶ Where-Object BaseName
                                  │
                                  ▼
                          Get-Content (XML)
                                  │
                                  ▼
xetemplates-metadata.xml ──▶ メタデータ照合
                                  │
                                  ▼
Pattern ─────────────────▶ 正規表現マッチング
                                  │
                                  ▼
                          PSCustomObject生成 ────────▶ Pipeline Output
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaXESessionTemplate.ps1 | `public/Get-DbaXESessionTemplate.ps1` | ソース | メインコマンドレット |
| xetemplates-metadata.xml | `bin/xetemplates-metadata.xml` | 設定 | テンプレートメタデータ |
| XEtemplates/*.xml | `bin/XEtemplates/` | テンプレート | XEセッションテンプレート |
| Import-DbaXESessionTemplate.ps1 | `public/Import-DbaXESessionTemplate.ps1` | ソース | テンプレートインポート（連携先） |
