# 機能設計書 282-Copy-DbaEndpoint

## 概要

本ドキュメントは、SQL Server エンドポイントをソースインスタンスから宛先インスタンスへコピーする Copy-DbaEndpoint コマンドの機能設計書です。

### 本機能の処理概要

Copy-DbaEndpoint は、SQL Server のユーザー定義エンドポイント（システムエンドポイントを除く）をソースサーバーから1つ以上の宛先サーバーへ移行する PowerShell コマンドです。

**業務上の目的・背景**：Service Broker、Database Mirroring、Availability Group などの高可用性機能を構成する際、複数の SQL Server インスタンス間でエンドポイント設定を統一する必要があります。本機能は、エンドポイント定義をスクリプト化して宛先サーバーに再作成することで、手動設定の手間とミスを削減し、マイグレーションや災害復旧シナリオでの構成の一貫性を確保します。

**機能の利用シーン**：
- 高可用性環境（Always On AG）の新規セットアップ時
- サーバー移行・マイグレーション時のエンドポイント複製
- 災害復旧環境の構築
- Service Broker 環境の構成展開
- Database Mirroring パートナーシップの設定

**主要な処理内容**：
1. ソース SQL Server インスタンスへの接続と認証
2. ユーザー定義エンドポイントの列挙（IsSystemObject = false のもの）
3. 各宛先インスタンスへの接続
4. エンドポイント名の重複チェック
5. Force パラメータによる既存エンドポイントの削除と再作成
6. エンドポイント定義のスクリプト化と実行
7. 処理結果のパイプライン出力

**関連システム・外部連携**：SQL Server Management Objects (SMO) を介してエンドポイントの Script() メソッドでT-SQL を生成し、宛先サーバーで実行します。

**権限による制御**：ソースおよび宛先の両方で sysadmin 権限が必要です。エンドポイントの列挙、スクリプト化、作成、削除にはこの権限レベルが要求されます。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | SSMS Server Objects > Endpoints | 参照画面 | エンドポイント確認 |
| - | PowerShell Console | 主画面 | コマンド実行 |

## 機能種別

データ移行・コピー操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Source | DbaInstanceParameter | Yes | ソース SQL Server インスタンス | 有効なインスタンス名、SQL Server 2005以降 |
| SourceSqlCredential | PSCredential | No | ソースへの代替認証情報 | - |
| Destination | DbaInstanceParameter[] | Yes | 宛先 SQL Server インスタンス（複数可） | 有効なインスタンス名、SQL Server 2005以降 |
| DestinationSqlCredential | PSCredential | No | 宛先への代替認証情報 | - |
| Endpoint | object[] | No | コピー対象エンドポイント名（ワイルドカード対応） | - |
| ExcludeEndpoint | object[] | No | 除外するエンドポイント名 | - |
| Force | switch | No | 既存エンドポイントを削除して再作成 | - |
| EnableException | switch | No | 例外スロー有効化 | - |

### 入力データソース

- PowerShell コマンドライン引数
- ソース SQL Server インスタンスのエンドポイントメタデータ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| DateTime | DbaDateTime | 操作実行日時 |
| SourceServer | string | ソースサーバー名 |
| DestinationServer | string | 宛先サーバー名 |
| Name | string | エンドポイント名 |
| Type | string | オブジェクト種別（常に "Endpoint"） |
| Status | string | 処理結果（Successful / Skipped / Failed） |
| Notes | string | 追加情報（スキップ理由、エラーメッセージ等） |

### 出力先

PowerShell パイプライン（PSCustomObject、TypeName: MigrationObject）

## 処理フロー

### 処理シーケンス

```
1. ソースサーバーへの接続
   └─ Connect-DbaInstance -MinimumVersion 9（SQL Server 2005以降）
2. ユーザー定義エンドポイントの取得
   └─ IsSystemObject = $false でフィルタリング
3. 各宛先インスタンスに対してループ
   ├─ Connect-DbaInstance で接続
   └─ 各エンドポイントに対してループ
       ├─ Endpoint / ExcludeEndpoint パラメータでフィルタリング
       ├─ 宛先に同名エンドポイントが存在するかチェック
       │   ├─ 存在 & Force なし → スキップ（Status=Skipped）
       │   └─ 存在 & Force あり → 削除して再作成
       └─ エンドポイント作成
           ├─ Script() メソッドで T-SQL 生成
           ├─ destServer.Query() で実行
           └─ 結果出力（Status=Successful / Failed）
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Connect-DbaInstance to Source]
    B --> C{接続成功?}
    C -->|No| D[Stop-Function & 終了]
    C -->|Yes| E[Get User Endpoints<br/>IsSystemObject = false]
    E --> F[Destination ループ開始]
    F --> G[Connect-DbaInstance to Destination]
    G --> H{接続成功?}
    H -->|No| I[Continue to next Destination]
    H -->|Yes| J[Endpoint ループ開始]
    J --> K{Endpoint/ExcludeEndpoint<br/>フィルタ通過?}
    K -->|No| J
    K -->|Yes| L{宛先に同名<br/>エンドポイント存在?}
    L -->|Yes| M{Force?}
    M -->|No| N[Status=Skipped 出力]
    M -->|Yes| O[Drop existing endpoint]
    O --> P{Drop成功?}
    P -->|No| Q[Status=Failed 出力]
    P -->|Yes| R[Create endpoint]
    L -->|No| R
    R --> S{Create成功?}
    S -->|Yes| T[Status=Successful 出力]
    S -->|No| Q
    N --> J
    Q --> J
    T --> J
    J -->|完了| F
    I --> F
    F -->|完了| U[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | システムエンドポイント除外 | IsSystemObject = true のエンドポイントはコピー対象外 | 常時 |
| BR-002 | 最小バージョン要件 | SQL Server 2005（バージョン9）以降が必要 | 接続時 |
| BR-003 | 重複時スキップ | 宛先に同名エンドポイントが存在する場合はスキップ | Force 未指定時 |
| BR-004 | 強制上書き | Force 指定時は既存エンドポイントを削除して再作成 | Force 指定時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| エンドポイント作成 | sys.endpoints | INSERT | CREATE ENDPOINT 実行 |
| エンドポイント削除 | sys.endpoints | DELETE | DROP ENDPOINT 実行（Force時） |

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

#### sys.endpoints

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name, endpoint_id, protocol_id, type_id 等 | ソースエンドポイントの設定をコピー | CREATE ENDPOINT |
| DELETE | name | 指定エンドポイント名 | DROP ENDPOINT（Force時） |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 接続エラー | SQL Server に接続できない | インスタンス名と認証情報を確認 |
| - | バージョンエラー | SQL Server 2000 以前 | SQL Server 2005以降を使用 |
| - | ドロップ失敗 | 既存エンドポイントの削除に失敗 | 使用中のエンドポイントを確認 |
| - | 作成失敗 | エンドポイントの作成に失敗 | ポート重複、権限不足を確認 |

### リトライ仕様

リトライは実装されていません。失敗時は Status=Failed を設定して次のエンドポイントまたは宛先の処理を続行します。

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

各エンドポイントの操作は独立して実行されます。DROP ENDPOINT と CREATE ENDPOINT は別々のトランザクションとして実行されるため、削除後に作成が失敗した場合、エンドポイントは削除されたままになります。

## パフォーマンス要件

特に定義されていません。エンドポイントの数とネットワーク遅延に依存します。

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

- sysadmin 権限が必要
- SQL Server 認証または Windows 認証を使用
- SqlCredential パラメータで資格情報を安全に受け渡し
- エンドポイントの認証設定（証明書、Kerberos等）はそのままコピーされる

## 備考

- SQL Server 2005 以降をサポート
- SupportsShouldProcess を実装（-WhatIf, -Confirm 対応）
- ConfirmImpact は Medium に設定

---

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

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

### 推奨読解順序

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

出力オブジェクトと移行ステータスの構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Copy-DbaEndpoint.ps1 | `public/Copy-DbaEndpoint.ps1` | 135-143行目: copyEndpointStatus オブジェクトの構造 |

**読解のコツ**: MigrationObject 型として出力される PSCustomObject の構造と、Select-DefaultView による表示プロパティの制御を確認します。

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

関数の開始点、パラメータ定義、begin ブロックの処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Copy-DbaEndpoint.ps1 | `public/Copy-DbaEndpoint.ps1` | パラメータ定義と初期処理 |

**主要処理フロー**:
1. **96-109行目**: パラメータ定義（Source, Destination, Endpoint 等）
2. **111-121行目**: begin ブロックでソースサーバー接続とエンドポイント取得

#### Step 3: コピー処理の実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Copy-DbaEndpoint.ps1 | `public/Copy-DbaEndpoint.ps1` | process ブロックのメインロジック |

**主要処理フロー**:
- **118行目**: ユーザー定義エンドポイントのフィルタリング（IsSystemObject = false）
- **124-129行目**: 宛先サーバーへの接続
- **145-147行目**: Endpoint/ExcludeEndpoint パラメータによるフィルタリング
- **149-171行目**: 既存エンドポイントの処理（スキップまたは削除）
- **174-186行目**: 新規エンドポイントの作成

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

```
Copy-DbaEndpoint
    │
    ├─ [begin]
    │      ├─ Connect-DbaInstance (Source)
    │      │      └─ MinimumVersion 9 (SQL 2005+)
    │      └─ Filter Endpoints (IsSystemObject = false)
    │
    └─ [process]
           └─ foreach Destination
                  ├─ Connect-DbaInstance (Destination)
                  └─ foreach Endpoint
                         ├─ Filter by Endpoint/ExcludeEndpoint
                         ├─ Check if exists on destination
                         │      ├─ [exists & !Force] Skip
                         │      └─ [exists & Force] Drop
                         └─ Create Endpoint
                                ├─ $currentEndpoint.Script()
                                └─ $destServer.Query(script)
```

### データフロー図

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

Source ────────────┐
                   │
SourceSqlCredential┼──▶ Connect-DbaInstance ──▶ serverEndpoints
                   │           │
                   │           ▼
Destination ───────┼──▶ foreach Destination
                   │           │
DestSqlCredential ─┤           ├─▶ Connect-DbaInstance
                   │           │
Endpoint ──────────┤           ├─▶ Filter endpoints
                   │           │
ExcludeEndpoint ───┤           ├─▶ Check existing
                   │           │
Force ─────────────┘           ├─▶ [Force] Drop endpoint
                               │
                               └─▶ Script() + Query()
                                          │
                                          ▼
                                   PSCustomObject ──▶ パイプライン出力
                                   (DateTime, SourceServer,
                                    DestinationServer, Name,
                                    Type, Status, Notes)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Copy-DbaEndpoint.ps1 | `public/Copy-DbaEndpoint.ps1` | ソース | メイン関数実装 |
| Copy-DbaEndpoint.Tests.ps1 | `tests/Copy-DbaEndpoint.Tests.ps1` | テスト | ユニット・統合テスト |
| Get-DbaEndpoint.ps1 | `public/Get-DbaEndpoint.ps1` | ソース | エンドポイント取得（関連） |
| New-DbaEndpoint.ps1 | `public/New-DbaEndpoint.ps1` | ソース | エンドポイント作成（関連） |
| Remove-DbaEndpoint.ps1 | `public/Remove-DbaEndpoint.ps1` | ソース | エンドポイント削除（関連） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server 接続（依存） |
