# 機能設計書 295-Export-DbaXESessionTemplate

## 概要

本ドキュメントは、拡張イベントセッションをSSMS用の再利用可能なXMLテンプレートとしてエクスポートするExport-DbaXESessionTemplate機能について記述する。

### 本機能の処理概要

Export-DbaXESessionTemplateは、既存の拡張イベントセッションをXMLテンプレートファイルに変換するコマンドレットである。生成されたテンプレートはSQL Server Management Studio（SSMS）のテンプレートブラウザからインポートして再利用できる。

**業務上の目的・背景**：拡張イベントセッションの設定は複雑であり、同じ監視構成を複数の環境で再利用したいケースは多い。手動でのセッション再作成やスクリプトの管理は煩雑である。本機能はセッション定義をSSMS互換のXMLテンプレート形式で保存し、GUIからの簡単なインポートを可能にする。これにより、DBAは標準化された監視テンプレートライブラリを構築できる。

**機能の利用シーン**：
- カスタム監視セッションのテンプレート化
- チーム間でのセッション設定の共有
- 組織の監視テンプレートライブラリの構築
- 複数環境への標準監視設定のデプロイ準備
- SSMSテンプレートブラウザへのセッション登録

**主要な処理内容**：
1. SQL Serverインスタンスへの接続またはパイプライン入力の受け取り
2. Get-DbaXESessionを使用したセッション情報の取得
3. XEStore.SaveSessionToTemplateによるXMLテンプレートの生成
4. 指定ディレクトリへのファイル保存

**関連システム・外部連携**：Microsoft.SqlServer.Management.XEvent.XEStoreのSaveSessionToTemplateメソッドを使用。SSMSのテンプレートブラウザと互換性のあるXML形式で出力。

**権限による制御**：VIEW SERVER STATE権限が必要（セッション情報の取得）。sysadmin権限推奨。SQL Server 2008以上が必須。

## 関連画面

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

## 機能種別

データ出力 / ファイル生成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | SQL Server 2008以上 |
| SqlCredential | PSCredential | No | SQL Server認証情報 | - |
| Session | object[] | No | エクスポート対象セッション名 | ワイルドカード対応 |
| Path | string | No | 出力ディレクトリ。デフォルト: SSMSのXEventTemplatesフォルダ | ディレクトリ存在確認 |
| FilePath | string | No | 出力ファイルパス（完全指定） | - |
| InputObject | Session[] | No | パイプライン入力（Get-DbaXESessionから） | Microsoft.SqlServer.Management.XEvent.Session型 |
| EnableException | switch | No | 例外を有効にする | - |

### 入力データソース

- SQL Server拡張イベントストアのセッション情報
- Get-DbaXESessionからのパイプライン入力

## 出力仕様

### 出力データ

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

### 出力先

- ファイルシステム（XMLファイル）
- パイプライン（System.IO.FileInfo）

## 処理フロー

### 処理シーケンス

```
1. 初期化処理（begin）
   └─ 出力ディレクトリの検証（Test-ExportDirectory）
2. セッション情報の取得（process）
   └─ SqlInstance指定時: Get-DbaXESessionでセッション取得
   └─ InputObject指定時: 直接使用
3. テンプレート生成・保存（process）
   └─ セッション名から無効な文字を除去
   └─ 出力ファイルパスの決定
   └─ XEStore.SaveSessionToTemplateでXML保存
   └─ Get-ChildItemでファイル情報を返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Test-ExportDirectory]
    B --> C{SqlInstance指定?}
    C -->|Yes| D[Get-DbaXESession呼び出し]
    C -->|No| E[InputObjectを使用]
    D --> F[InputObjectに追加]
    E --> G{各セッションループ}
    F --> G
    G --> H[セッション名クリーンアップ]
    H --> I{Path存在?}
    I -->|No| J[エラー: パス不存在]
    I -->|Yes| K{FilePath指定?}
    K -->|No| L[sessionname.xmlを生成]
    K -->|Yes| M[FilePathを使用]
    L --> N[SaveSessionToTemplate]
    M --> N
    N --> O[Get-ChildItem]
    O --> G
    G -->|完了| P[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ファイル命名 | セッション名から無効文字を除去して.xml拡張子 | FilePath未指定時 |
| BR-002 | デフォルトパス | SSMSのXEventTemplatesフォルダ | Path未指定時 |
| BR-003 | 上書き許可 | 同名ファイルは上書き | 常時（第3引数=true） |
| BR-004 | パス存在確認 | 指定パスが存在しない場合はエラー | 常時 |

### 計算ロジック

セッション名のクリーンアップ: Remove-InvalidFileNameChars関数で無効なファイル名文字を除去

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| セッション取得 | XEStore.Sessions | SELECT | セッション定義の読み取り |

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

読み取り専用。XEStore.SaveSessionToTemplateメソッドでXMLテンプレートを生成。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | インスタンスに接続できない | 接続情報の確認 |
| PathNotFoundError | パス不存在エラー | 指定パスが存在しない | パスの作成または正しいパス指定 |

### リトライ仕様

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

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

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

## パフォーマンス要件

特に規定なし。セッション数に依存した処理時間。

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

- VIEW SERVER STATE権限またはsysadmin権限が必要
- 生成されたテンプレートにはセッション設定の詳細が含まれる
- 機密性の高い監視設定のテンプレートは適切に保護すること

## 備考

- デフォルトの出力先はSSMSのテンプレートフォルダで、SSMSから直接アクセス可能
- Get-DbaXESessionと組み合わせることで特定のセッションのみをエクスポート可能
- 生成されたXMLはSSMSのImport-DbaXESessionTemplateやGUIでインポート可能

---

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

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

### 推奨読解順序

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

XESessionオブジェクトとXMLテンプレートの関係を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Export-DbaXESessionTemplate.ps1 | `public/Export-DbaXESessionTemplate.ps1` | パラメータ定義（82-92行目） |

**読解のコツ**: デフォルトのPathがSSMSのテンプレートフォルダを指している点に注目。

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

begin/processブロックの構造を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Export-DbaXESessionTemplate.ps1 | `public/Export-DbaXESessionTemplate.ps1` | processブロック（97-122行目） |

**主要処理フロー**:
1. **100-106行目**: SqlInstance指定時はGet-DbaXESessionを呼び出し
2. **109行目**: セッション名のクリーンアップ（Remove-InvalidFileNameChars）
3. **115-117行目**: FilePathの決定（未指定時はJoin-DbaPathで生成）
4. **119行目**: XEStore.SaveSessionToTemplateでXML保存
5. **120行目**: Get-ChildItemでファイル情報を返す

#### Step 3: SaveSessionToTemplateメソッドを理解する

SMOのSaveSessionToTemplateメソッドの呼び出しを確認する。

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

**主要処理フロー**:
- 第1引数: セッションオブジェクト
- 第2引数: 出力ファイルパス
- 第3引数: 上書き許可（true）

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

```
Export-DbaXESessionTemplate
    │
    ├─ begin
    │      └─ Test-ExportDirectory
    │
    └─ process
           │
           ├─ [SqlInstance指定時]
           │      └─ Get-DbaXESession
           │             └─ EnableException付き
           │
           └─ foreach $xes (InputObject)
                  │
                  ├─ Remove-InvalidFileNameChars
                  │
                  ├─ Test-Path
                  │
                  ├─ Join-DbaPath (FilePath未指定時)
                  │
                  ├─ XEStore.SaveSessionToTemplate
                  │
                  └─ Get-ChildItem
```

### データフロー図

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

SqlInstance ───────────────▶ Get-DbaXESession
        or                           │
InputObject ───────────────▶        ▼
                             Session Object
                                     │
                                     ▼
                             セッション名クリーンアップ
                                     │
                                     ▼
                             SaveSessionToTemplate ────────▶ .xml File
                                     │
                                     ▼
                             Get-ChildItem ────────────────▶ FileInfo
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Export-DbaXESessionTemplate.ps1 | `public/Export-DbaXESessionTemplate.ps1` | ソース | メイン処理 |
| Get-DbaXESession.ps1 | `public/Get-DbaXESession.ps1` | ソース | セッション取得 |
| Import-DbaXESessionTemplate.ps1 | `public/Import-DbaXESessionTemplate.ps1` | ソース | 対となるインポート機能 |
| Remove-InvalidFileNameChars.ps1 | `private/functions/` | ソース | ファイル名クリーンアップ |
