# 機能設計書 294-Export-DbaXESession

## 概要

本ドキュメントは、拡張イベントセッションのT-SQL作成スクリプトを生成するExport-DbaXESession機能について記述する。

### 本機能の処理概要

Export-DbaXESessionは、SQL Serverの拡張イベントセッション定義をT-SQLスクリプトとして出力するコマンドレットである。生成されたスクリプトは、環境間の移行やデプロイメント、監視設定のドキュメント化に使用できる。

**業務上の目的・背景**：拡張イベントセッションの設定は複雑であり、同じ監視構成を複数の環境（開発、テスト、本番）で再現する必要がある。手動でのセッション再作成はエラーが発生しやすく時間もかかる。本機能はCREATE EVENT SESSIONステートメントを含む完全なT-SQLスクリプトを生成し、監視設定の一貫したデプロイメントやバージョン管理を可能にする。

**機能の利用シーン**：
- 開発環境から本番環境への監視設定デプロイ
- コンプライアンス要件のための監視設定のドキュメント化
- 複数サーバーへの標準監視設定の展開スクリプト作成
- 障害復旧用のセッション定義バックアップ
- GitやTFS等でのバージョン管理

**主要な処理内容**：
1. SQL Serverインスタンスへの接続またはパイプライン入力の受け取り
2. Get-DbaXESessionを使用したセッション情報の取得
3. ScriptCreate()メソッドによるT-SQLスクリプトの生成
4. バッチセパレータ（GO）の挿入とプレフィックスコメントの追加
5. ファイルへの出力またはコンソールへの表示

**関連システム・外部連携**：Get-DbaXESessionからのパイプライン入力をサポート。生成されたスクリプトはSSMSや他のSQL実行ツールで使用可能。

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

## 関連画面

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

## 機能種別

スクリプト生成 / データ出力

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | SQL Server 2008以上 |
| SqlCredential | PSCredential | No | SQL Server認証情報 | - |
| InputObject | Session[] | No | パイプライン入力（Get-DbaXESessionから） | Microsoft.SqlServer.Management.XEvent.Session型 |
| Session | string[] | No | 出力対象セッション名 | - |
| Path | string | No | 出力ディレクトリ。デフォルト: DbatoolsExport設定値 | - |
| FilePath | string | No | 出力ファイルパス（完全指定） | - |
| Encoding | string | No | 出力エンコーディング。デフォルト: UTF8 | ASCII/BigEndianUnicode/Byte/String/Unicode/UTF7/UTF8/Unknown |
| Passthru | switch | No | コンソールに出力 | - |
| BatchSeparator | string | No | バッチセパレータ。デフォルト: 設定値 | - |
| NoPrefix | switch | No | ヘッダコメントを除外 | - |
| NoClobber | switch | No | 既存ファイルを上書きしない | - |
| Append | switch | No | 既存ファイルに追記 | - |
| EnableException | switch | No | 例外を有効にする | - |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (Passthru時) | string | T-SQLスクリプト文字列 |
| (Path/FilePath時) | System.IO.FileInfo | 生成されたファイルの情報 |

### 出力先

- コンソール（Passthru指定時または未指定時）
- ファイルシステム（Path/FilePath指定時）

## 処理フロー

### 処理シーケンス

```
1. 初期化処理（begin）
   └─ 出力ディレクトリの検証
   └─ 実行ユーザー情報の取得
2. セッション情報の収集（process）
   └─ SqlInstance指定時: Get-DbaXESessionでセッション取得
   └─ InputObject指定時: 直接使用
   └─ SessionCollectionに蓄積
3. スクリプト生成・出力（end）
   └─ 各セッションのScriptCreate()実行
   └─ プレフィックスコメントの追加（NoPrefix未指定時）
   └─ バッチセパレータの挿入
   └─ ファイル出力またはコンソール表示
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance指定?}
    B -->|Yes| C[Get-DbaXESession呼び出し]
    B -->|No| D{InputObject?}
    D -->|Yes| E[InputObjectを使用]
    D -->|No| F[エラー: 入力なし]
    C --> G[SessionCollectionに追加]
    E --> G
    G --> H{全セッション処理完了?}
    H -->|No| B
    H -->|Yes| I{NoPrefix?}
    I -->|No| J[プレフィックス追加]
    I -->|Yes| K[スクリプト生成]
    J --> K
    K --> L{BatchSeparator?}
    L -->|Yes| M[GO挿入]
    L -->|No| N{Passthru?}
    M --> N
    N -->|Yes| O[コンソール出力]
    N -->|No| P{Path/FilePath?}
    P -->|Yes| Q[ファイル出力]
    P -->|No| O
    O --> R[終了]
    Q --> R
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ファイル命名規則 | ServerName-YYYYMMDDHHMMSS-xe.sql形式 | Path指定時 |
| BR-002 | プレフィックスコメント | 作成者、日時、dbatools情報を含む | NoPrefix未指定時 |
| BR-003 | バッチセパレータ | 各ステートメント後にGOを挿入 | BatchSeparator指定時 |
| BR-004 | NoClobber | 既存ファイル上書き防止 | NoClobber指定時 |
| BR-005 | Append | 複数サーバーの出力を1ファイルに集約 | Append指定時 |

### 計算ロジック

特になし

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

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

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

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

読み取り専用。ScriptCreate()メソッドでT-SQLスクリプトを生成。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| InputError | 入力エラー | SqlInstanceもInputObjectも未指定 | いずれかを指定 |
| FileExistsError | ファイル存在エラー | NoClobber指定時に既存ファイル | Appendを使用するか別名指定 |
| ConnectionError | 接続エラー | インスタンスに接続できない | 接続情報の確認 |

### リトライ仕様

リトライ処理なし。

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

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

## パフォーマンス要件

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

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

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

## 備考

- 複数インスタンスから1ファイルに出力する場合は-Appendを使用
- Get-DbaXESessionと組み合わせることで柔軟なフィルタリングが可能
- エンコーディングはUTF8がデフォルトで国際文字に対応

---

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

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

### 推奨読解順序

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

SessionCollectionとSessionObjectの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Export-DbaXESession.ps1 | `public/Export-DbaXESession.ps1` | SessionObject構造（167-171行目） |

**読解のコツ**: ArrayListを使用してセッション情報を蓄積し、endブロックで一括処理する。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Export-DbaXESession.ps1 | `public/Export-DbaXESession.ps1` | beginブロック（138-148行目）、processブロック（149-173行目） |

**主要処理フロー**:
1. **141行目**: SessionCollectionのArrayList初期化
2. **157-159行目**: SqlInstance指定時はGet-DbaXESessionを呼び出し
3. **165行目**: ScriptCreate()でT-SQLスクリプト取得
4. **172行目**: SessionCollectionに追加

#### Step 3: 出力処理を理解する

endブロックでのスクリプト組み立てと出力処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Export-DbaXESession.ps1 | `public/Export-DbaXESession.ps1` | endブロック（175-218行目） |

**主要処理フロー**:
- **180-184行目**: プレフィックスコメントの生成
- **186-192行目**: バッチセパレータの挿入
- **194-216行目**: 出力先の分岐（Passthru/Path/FilePath）

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

```
Export-DbaXESession
    │
    ├─ begin
    │      ├─ Test-ExportDirectory
    │      └─ ArrayList初期化
    │
    ├─ process
    │      │
    │      ├─ [SqlInstance指定時]
    │      │      └─ Get-DbaXESession
    │      │             └─ Session取得
    │      │
    │      └─ foreach $xe
    │             ├─ ScriptCreate()
    │             └─ SessionCollection.Add()
    │
    └─ end
           │
           └─ foreach $SessionObject
                  │
                  ├─ プレフィックス生成
                  │
                  ├─ バッチセパレータ挿入
                  │
                  └─ 出力処理
                         ├─ [Passthru] → コンソール
                         ├─ [Path/FilePath] → Out-File
                         └─ [その他] → コンソール
```

### データフロー図

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

SqlInstance ───────────────▶ Get-DbaXESession
        or                           │
InputObject ───────────────▶        ▼
                             ScriptCreate()
                                     │
                                     ▼
                             SessionCollection
                                     │
                                     ▼
                             プレフィックス追加
                                     │
                                     ▼
                             バッチセパレータ挿入
                                     │
                    ┌────────────────┼────────────────┐
                    ▼                ▼                ▼
              [Passthru]       [Path/FilePath]    [default]
                    │                │                │
                    ▼                ▼                ▼
               Console           .sql File        Console
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Export-DbaXESession.ps1 | `public/Export-DbaXESession.ps1` | ソース | メイン処理 |
| Get-DbaXESession.ps1 | `public/Get-DbaXESession.ps1` | ソース | セッション取得 |
| Get-ExportFilePath.ps1 | `private/functions/flowcontrol/Get-ExportFilePath.ps1` | ソース | ファイルパス生成 |
