# 機能設計書 305-Import-DbaXESessionTemplate

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `Import-DbaXESessionTemplate` コマンドレットの機能設計を記述する。このコマンドレットは、XMLテンプレートから拡張イベント(Extended Events)セッションをSQL Serverインスタンスに作成する機能を提供する。

### 本機能の処理概要

`Import-DbaXESessionTemplate` は、dbatoolsリポジトリまたはカスタムXMLテンプレートファイルから拡張イベントセッションを作成するコマンドレットである。パフォーマンストラブルシューティング、セキュリティ監査、ヘルス監視等の一般的な監視シナリオに対応した事前定義テンプレートを提供し、XEセッションのデプロイを簡素化する。

**業務上の目的・背景**：拡張イベントセッションの構築は複雑で時間がかかる作業である。検証済みのテンプレートを使用することで、一貫性のある監視構成を迅速にデプロイできる。本機能により、インデックスページスプリット、クエリ待機統計、デッドロック監視、IOエラー、データベースヘルスチェック等の一般的な監視シナリオを簡単に実装できる。

**機能の利用シーン**：
- 事前定義されたXEテンプレートを本番環境にデプロイしたい場合
- 複数のSQL Serverインスタンスに同一の監視構成を展開したい場合
- カスタムXEテンプレートをインポートしたい場合
- トレースファイルの出力先をカスタマイズしたい場合
- サーバー再起動後も自動開始するセッションを構成したい場合

**主要な処理内容**：
1. テンプレートXMLの読み込み（ビルトインまたはカスタム）
2. ターゲットファイルパスの置換（オプション）
3. SQL Serverバージョン互換性チェック
4. 既存セッションの存在確認
5. XEStoreを使用したセッション作成
6. StartUpState設定とセッション開始（オプション）

**関連システム・外部連携**：Get-DbaXESessionTemplate でテンプレートを発見、Get-DbaXESession で作成済みセッションを確認、Start-DbaXESession でセッションを開始。

**権限による制御**：sysadmin権限が必要。SQL Server 2012以降をサポート。

## 関連画面

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

## 機能種別

データ作成処理（CREATE）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 接続先SQLインスタンス | SQL Server 2012以降 |
| SqlCredential | PSCredential | No | 代替認証資格情報 | - |
| Name | string | No | カスタムセッション名 | 複数テンプレート時は使用不可 |
| Path | string[] | No | カスタムテンプレートファイルパス | - |
| Template | string[] | No | ビルトインテンプレート名 | - |
| TargetFilePath | string | No | トレースファイル出力先ディレクトリ | - |
| TargetFileMetadataPath | string | No | メタデータファイル出力先ディレクトリ | - |
| StartUpState | string | No | 開始状態（On/Off、デフォルト: Off） | ValidateSet: On, Off |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | SQLインスタンスのコンピューター名 |
| InstanceName | String | SQLインスタンス名 |
| SqlInstance | String | 完全修飾インスタンス名 |
| Name | String | セッション名 |
| Status | String | セッションステータス |
| StartTime | DateTime | セッション開始日時 |
| AutoStart | Boolean | 自動開始設定 |
| State | String | SMOオブジェクト状態 |
| Targets | Collection | ターゲットコレクション |
| TargetFile | String[] | ターゲットファイルパス |
| Events | Collection | イベントコレクション |
| MaxMemory | Int | 最大メモリ（MB） |
| MaxEventSize | Int | 最大イベントサイズ（MB） |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 初期化（begin ブロック）
   └─ xetemplates-metadata.xml の読み込み
2. パラメータ検証
   └─ PathまたはTemplateの必須チェック
   └─ 複数テンプレート時のName使用禁止チェック
3. SQL Serverインスタンスへの接続
   └─ Connect-DbaInstance（MinimumVersion 11）
4. XEStoreの初期化
5. テンプレートパスの解決
   └─ ビルトインテンプレートのパス構築
6. テンプレートファイルの処理
   └─ TargetFilePath置換処理（オプション）
   └─ XMLコンテンツの読み込み
7. バリデーション
   └─ event_sessionsノードの存在確認
   └─ SQL Serverバージョン互換性チェック
   └─ 既存セッションの存在確認
8. セッション作成
   └─ CreateSessionFromTemplate
   └─ session.Create()
9. StartUpState処理（On指定時）
   └─ AutoStart設定
   └─ セッション開始
10. 出力
    └─ Get-DbaXESession でセッション取得
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Path/Template指定?}
    B -->|No| C[Stop-Function]
    B -->|Yes| D{複数テンプレート+Name?}
    D -->|Yes| E[Stop-Function]
    D -->|No| F[各インスタンスを処理]
    F --> G[Connect-DbaInstance]
    G --> H[XEStore初期化]
    H --> I[テンプレートパス解決]
    I --> J[各ファイルを処理]
    J --> K{TargetFilePath指定?}
    K -->|Yes| L[パス置換処理]
    K -->|No| M[XMLコンテンツ読み込み]
    L --> M
    M --> N{event_sessions存在?}
    N -->|No| O[Stop-Function]
    N -->|Yes| P[バージョン互換性チェック]
    P --> Q{互換?}
    Q -->|No| R[Stop-Function]
    Q -->|Yes| S{既存セッション?}
    S -->|Yes| T[Stop-Function]
    S -->|No| U[CreateSessionFromTemplate]
    U --> V[session.Create]
    V --> W{StartUpState=On?}
    W -->|Yes| X[AutoStart設定]
    W -->|No| Y[Get-DbaXESession]
    X --> Z[Start-DbaXESession]
    Z --> Y
    Y --> J
    J --> AA[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-305-01 | パラメータ必須 | PathまたはTemplateのいずれかが必須 | 常時 |
| BR-305-02 | 複数テンプレート時Name禁止 | 複数テンプレート指定時はNameパラメータ使用不可 | Path/Templateが複数の場合 |
| BR-305-03 | デフォルトセッション名 | Name未指定時はテンプレートファイル名を使用 | Name未指定時 |
| BR-305-04 | バージョン互換性 | テンプレートのCompatibilityに基づき互換性チェック | 常時 |
| BR-305-05 | 既存セッションチェック | 同名セッションが存在する場合はエラー | 常時 |
| BR-305-06 | StartUpState処理 | On指定時はAutoStart設定とセッション開始 | StartUpState=On |

### 計算ロジック

- テンプレートパス: `Join-DbaPath $script:PSModuleRoot "bin" "XEtemplates" "$file.xml"`

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 作成 | XEセッション | CREATE | 拡張イベントセッション作成 |

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

#### 拡張イベントセッション

| 操作 | 項目 | 更新値・取得条件 | 備考 |
|-----|-----|-----------------|------|
| CREATE | セッション定義 | テンプレートXMLに基づく | SMO経由 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ParameterError | PathもTemplateも未指定 | Stop-Functionでエラー |
| - | ParameterError | 複数テンプレート+Name指定 | Stop-Functionでエラー |
| - | ConnectionError | SQL接続失敗 | Stop-Functionで継続 |
| - | InvalidTemplate | テンプレートパスが無効 | Stop-Functionで継続 |
| - | InvalidXML | event_sessionsノードなし | Stop-Functionで継続 |
| - | VersionError | SQL Serverバージョン非互換 | Stop-Functionで継続 |
| - | ExistingSession | 同名セッション既存 | Stop-Functionで継続 |

### リトライ仕様

なし

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

なし（SMO経由でセッション作成）

## パフォーマンス要件

- テンプレート数およびインスタンス数に比例した処理時間

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

- sysadmin権限が必要
- TargetFilePath/TargetFileMetadataPathのディレクトリ作成権限が必要

## 備考

- Get-DbaXESessionTemplate と組み合わせて使用
- Start-DbaXESession と組み合わせてセッション開始
- SQL Server 2012以降が必要

---

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

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

### 推奨読解順序

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

テンプレートXML構造と出力Sessionオブジェクトを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Import-DbaXESessionTemplate.ps1 | `public/Import-DbaXESessionTemplate.ps1` | 出力型とプロパティ（63-91行目） |

**読解のコツ**: 出力はMicrosoft.SqlServer.Management.XEvent.Sessionオブジェクト。StartUpState=On時は開始されたセッションが返される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Import-DbaXESessionTemplate.ps1 | `public/Import-DbaXESessionTemplate.ps1` | begin ブロック（135-138行目） |
| 2-2 | Import-DbaXESessionTemplate.ps1 | `public/Import-DbaXESessionTemplate.ps1` | process ブロック冒頭（139-147行目） |

**主要処理フロー**:
1. **136-137行目**: メタデータXMLの読み込み
2. **140-142行目**: PathとTemplateの必須チェック
3. **144-147行目**: 複数テンプレート+Name の禁止チェック

#### Step 3: セッション作成処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Import-DbaXESessionTemplate.ps1 | `public/Import-DbaXESessionTemplate.ps1` | テンプレート処理（160-167行目） |
| 3-2 | Import-DbaXESessionTemplate.ps1 | `public/Import-DbaXESessionTemplate.ps1` | セッション作成（245-264行目） |

**主要処理フロー**:
- **160-167行目**: ビルトインテンプレートパスの構築
- **171-219行目**: TargetFilePath置換処理
- **221-223行目**: event_sessionsノード検証
- **225-243行目**: バージョン互換性と既存セッションチェック
- **245-264行目**: セッション作成とStartUpState処理

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

```
Import-DbaXESessionTemplate
    │
    ├─ Import-Clixml（メタデータ読み込み）
    │
    ├─ Test-Bound（パラメータチェック）
    │
    ├─ Connect-DbaInstance
    │      └─ -MinimumVersion 11
    │
    ├─ New-Object XEStore
    │
    ├─ Join-DbaPath（テンプレートパス構築）
    │
    ├─ Get-Content（XMLコンテンツ取得）
    │
    ├─ Test-HostOSLinux（パス区切り判定）
    │
    ├─ Test-DbaPath / New-DbaDirectory
    │
    ├─ Get-DbaXESession（既存セッションチェック）
    │
    ├─ $store.CreateSessionFromTemplate
    │
    ├─ $session.Create
    │
    └─ Start-DbaXESession（StartUpState=On時）
```

### データフロー図

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

Template/Path ────────────▶ テンプレートパス解決
                                  │
                                  ▼
TargetFilePath ───────────▶ パス置換処理
                                  │
                                  ▼
                          XMLコンテンツ読み込み
                                  │
                                  ▼
xetemplates-metadata.xml ─▶ バージョン互換性チェック
                                  │
                                  ▼
SqlInstance ──────────────▶ Connect-DbaInstance ────▶ Server
                                  │
                                  ▼
                          既存セッションチェック
                                  │
                                  ▼
                          CreateSessionFromTemplate
                                  │
                                  ▼
                          session.Create() ─────────▶ Session Object
                                  │
                                  ▼
StartUpState=On ──────────▶ Start-DbaXESession ─────▶ Running Session
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Import-DbaXESessionTemplate.ps1 | `public/Import-DbaXESessionTemplate.ps1` | ソース | メインコマンドレット |
| Get-DbaXESessionTemplate.ps1 | `public/Get-DbaXESessionTemplate.ps1` | ソース | テンプレート発見（連携元） |
| Get-DbaXESession.ps1 | `public/Get-DbaXESession.ps1` | ソース | セッション確認（依存先） |
| Start-DbaXESession.ps1 | `public/Start-DbaXESession.ps1` | ソース | セッション開始（依存先） |
| xetemplates-metadata.xml | `bin/xetemplates-metadata.xml` | 設定 | 互換性メタデータ |
| XEtemplates/*.xml | `bin/XEtemplates/` | テンプレート | ビルトインテンプレート |
