# 機能設計書 291-Copy-DbaXESession

## 概要

本ドキュメントは、SQL Serverの拡張イベント（Extended Events）セッションを別のインスタンスにコピーするCopy-DbaXESession機能について記述する。

### 本機能の処理概要

Copy-DbaXESessionは、SQL Serverインスタンス間でカスタム拡張イベントセッションを移行するためのコマンドレットである。ソースサーバーからセッション定義をスクリプト化し、宛先サーバーで再作成することで、監視設定の一貫性を保ちながらサーバー間でのセッション移行を実現する。

**業務上の目的・背景**：SQL Serverの運用において、拡張イベントセッションは性能監視、トラブルシューティング、監査などの重要な機能を担っている。サーバーの移行、災害復旧環境の構築、または複数環境での監視設定の標準化を行う際に、手動でセッションを再作成するのは時間がかかりエラーが発生しやすい。本機能はこの課題を解決し、セッション定義の一貫した移行を自動化する。

**機能の利用シーン**：
- 本番サーバーから災害復旧サーバーへの監視設定の複製
- 開発環境から本番環境への監視セッションの展開
- SQL Serverの移行プロジェクトにおける設定移行
- 複数サーバーへの標準監視設定の一括展開

**主要な処理内容**：
1. ソースSQL Serverインスタンスへの接続とXEStore（拡張イベントストア）の取得
2. システムセッション（AlwaysOn_health、system_health）を除外したセッションリストの取得
3. フィルタ条件（XeSession、ExcludeXeSession）に基づくセッションの絞り込み
4. 宛先インスタンスへの接続と既存セッションの存在確認
5. セッション定義のスクリプト生成（ScriptCreate）と宛先での実行
6. ソースでセッションが実行中の場合、宛先でもセッションを開始

**関連システム・外部連携**：Microsoft.SqlServer.Management.XEvent名前空間のXEStoreクラスを使用してセッション管理を行う。SMO（SQL Server Management Objects）を介した接続を使用。

**権限による制御**：ソースおよび宛先の両方のSQL Serverインスタンスでsysadmin権限が必要。SQL Server 2012（バージョン11）以上が必須。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 84 | XEセッション管理 | 補助機能 | 拡張イベントセッションのコピー |

## 機能種別

データ連携 / マイグレーション

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Source | DbaInstanceParameter | Yes | コピー元SQL Serverインスタンス | SQL Server 2012以上 |
| Destination | DbaInstanceParameter[] | Yes | コピー先SQL Serverインスタンス（複数指定可能） | SQL Server 2012以上 |
| SourceSqlCredential | PSCredential | No | ソースインスタンスへの認証情報 | - |
| DestinationSqlCredential | PSCredential | No | 宛先インスタンスへの認証情報 | - |
| XeSession | object[] | No | コピーするセッション名の配列 | - |
| ExcludeXeSession | object[] | No | 除外するセッション名の配列 | - |
| Force | switch | No | 既存セッションを削除して再作成 | - |
| EnableException | switch | No | 例外を有効にする | - |
| WhatIf | switch | No | 実行内容のプレビュー | - |
| Confirm | switch | No | 確認プロンプトの表示 | - |

### 入力データソース

- ソースSQL Serverの拡張イベントストア（XEStore）からセッション定義を取得

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| DateTime | DbaDateTime | 操作実行日時 |
| SourceServer | string | コピー元サーバー名 |
| DestinationServer | string | コピー先サーバー名 |
| Name | string | セッション名 |
| Type | string | オブジェクトタイプ（常に"Extended Event"） |
| Status | string | 結果ステータス（Successful/Skipped/Failed） |
| Notes | string | 追加情報（エラーメッセージまたは"Already exists on destination"） |

### 出力先

パイプラインへのPSCustomObject出力（TypeName: MigrationObject）

## 処理フロー

### 処理シーケンス

```
1. ソースインスタンスへの接続
   └─ Connect-DbaInstanceで接続、MinimumVersion=11を指定
2. XEStoreオブジェクトの作成
   └─ SqlStoreConnectionを介してXEStoreを初期化
3. セッションリストの取得とフィルタリング
   └─ AlwaysOn_health、system_healthを除外
   └─ XeSession/ExcludeXeSessionパラメータでフィルタ
4. 宛先インスタンスのループ処理
   └─ 各宛先に接続してXEStoreを作成
5. セッションごとの処理
   └─ 既存セッションの確認
   └─ Force指定時は既存セッションを削除
   └─ セッション定義のスクリプト生成と実行
   └─ ソースで実行中の場合は宛先でも開始
6. 結果オブジェクトの出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[ソースインスタンス接続]
    B --> C[XEStore取得]
    C --> D[セッションリスト取得・フィルタ]
    D --> E{宛先インスタンスループ}
    E --> F[宛先に接続]
    F --> G{セッションループ}
    G --> H{宛先に既存セッション?}
    H -->|Yes| I{Force指定?}
    I -->|No| J[スキップ・結果出力]
    I -->|Yes| K[既存セッション削除]
    K --> L[セッション作成]
    H -->|No| L
    L --> M{ソースで実行中?}
    M -->|Yes| N[宛先でセッション開始]
    M -->|No| O[成功結果出力]
    N --> O
    J --> G
    O --> G
    G -->|完了| E
    E -->|完了| P[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | システムセッション除外 | AlwaysOn_healthとsystem_healthはコピー対象外 | 常時 |
| BR-002 | 既存セッション処理 | 既存セッションはForceなしでスキップ | Force未指定時 |
| BR-003 | 実行状態の継承 | ソースで実行中のセッションは宛先でも開始 | セッション作成成功時 |
| BR-004 | バージョン要件 | SQL Server 2012以上が必須 | 接続時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| セッション取得 | sys.dm_xe_sessions | SELECT | ソースのセッション情報取得 |
| セッション作成 | Extended Events | DDL | CREATE EVENT SESSION実行 |
| セッション削除 | Extended Events | DDL | DROP EVENT SESSION実行（Force時） |
| セッション開始 | Extended Events | DDL | ALTER EVENT SESSION STATE=START |

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

#### Extended Events システム

| 操作 | 項目 | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | XEStore.Sessions | システムセッション以外 | フィルタ適用 |
| DDL | ScriptCreate() | セッション定義の完全スクリプト | XML形式の定義を含む |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | インスタンスに接続できない | 接続情報の確認 |
| DropError | 削除エラー | 既存セッションの削除に失敗 | セッションの状態確認 |
| CreateError | 作成エラー | セッション作成に失敗 | スクリプト内容の確認 |

### リトライ仕様

リトライ処理なし。エラー発生時は次のセッション処理へ継続。

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

DDL操作は個別に実行される。トランザクション制御なし。

## パフォーマンス要件

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

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

- ソースおよび宛先でsysadmin権限が必要
- SQL認証使用時はPSCredentialで資格情報を安全に渡す
- 監査セッションのコピーは監査要件の確認が必要

## 備考

- SQL Server 2008以降で拡張イベントは利用可能だが、本機能はSQL Server 2012以上が必要
- コピー元とコピー先でSQL Serverバージョンが異なる場合、一部のイベントやアクションが利用できない可能性がある

---

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

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

### 推奨読解順序

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

まず、XEStore（拡張イベントストア）とセッションオブジェクトの構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Copy-DbaXESession.ps1 | `public/Copy-DbaXESession.ps1` | 出力オブジェクト構造（152-160行目）とMigrationObject型 |

**読解のコツ**: PowerShellのPSCustomObjectとSelect-DefaultViewによる出力プロパティの制御に注目する。

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

処理の起点となるbeginブロックとprocessブロックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Copy-DbaXESession.ps1 | `public/Copy-DbaXESession.ps1` | beginブロック（114-135行目）でソース接続とセッション取得 |

**主要処理フロー**:
1. **116行目**: Connect-DbaInstanceでMinimumVersion 11を指定してソース接続
2. **118-120行目**: SqlStoreConnectionとXEStoreオブジェクトの作成
3. **126-132行目**: セッションフィルタリング（システムセッション除外、XeSession/ExcludeXeSession適用）

#### Step 3: 宛先処理ループを理解する

processブロックで宛先ごとの処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Copy-DbaXESession.ps1 | `public/Copy-DbaXESession.ps1` | processブロック（136-216行目）の宛先ループ |

**主要処理フロー**:
- **138-146行目**: 宛先インスタンスへの接続とXEStore作成
- **149-214行目**: セッションごとの処理ループ
- **162-188行目**: 既存セッション確認とForce処理
- **191-212行目**: セッション作成と開始処理

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

```
Copy-DbaXESession
    │
    ├─ Connect-DbaInstance (ソース接続)
    │      └─ MinimumVersion 11 チェック
    │
    ├─ New-Object XEStore (ソースXEStore)
    │
    ├─ foreach $Destination
    │      │
    │      ├─ Connect-DbaInstance (宛先接続)
    │      │
    │      ├─ New-Object XEStore (宛先XEStore)
    │      │
    │      └─ foreach $session
    │             │
    │             ├─ 既存セッション確認
    │             │
    │             ├─ [Force時] Session.Drop()
    │             │
    │             ├─ Session.ScriptCreate()
    │             │
    │             ├─ Server.Query($sql)
    │             │
    │             └─ [実行中時] Session.Start()
    │
    └─ Select-DefaultView (出力整形)
```

### データフロー図

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

Source Instance ──────▶ Connect-DbaInstance ──────▶ XEStore
                              │
                              ▼
                        セッションリスト取得
                              │
                              ▼
                        フィルタリング
                        (システムセッション除外)
                              │
                              ▼
Destination Instance ─▶ Connect-DbaInstance ──────▶ XEStore
                              │
                              ▼
                        既存確認 & 作成
                              │
                              ▼
                        ScriptCreate → Query
                              │
                              ▼
                        PSCustomObject ──────────▶ Pipeline
                        (MigrationObject)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Copy-DbaXESession.ps1 | `public/Copy-DbaXESession.ps1` | ソース | メイン処理 |
| Copy-DbaXESession.Tests.ps1 | `tests/Copy-DbaXESession.Tests.ps1` | テスト | Pesterテスト |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続 |
| Get-DbaXESession.ps1 | `public/Get-DbaXESession.ps1` | ソース | 関連機能（セッション取得） |
