# 機能設計書 357-Copy-DbaCustomError

## 概要

本ドキュメントは、SQL Serverカスタムエラーメッセージを移行する `Copy-DbaCustomError` コマンドの機能設計書である。

### 本機能の処理概要

本機能は、ソースサーバーのsys.messagesカタログからユーザー定義エラーメッセージを取得し、デスティネーションサーバーにコピーする。言語ごとの翻訳を含むすべてのカスタムエラーを移行対象とする。

**業務上の目的・背景**：カスタムエラーメッセージ（sp_addmessageで作成されたメッセージ）は、アプリケーション固有のエラーハンドリングに使用される。サーバー移行や環境の標準化において、これらのカスタムエラーも一緒に移行する必要がある。本機能により、複数言語の翻訳を含むカスタムエラーを一括でコピーでき、移行作業を効率化する。

**機能の利用シーン**：
- サーバー移行時のカスタムエラー移行
- 開発環境から本番環境へのエラー定義の展開
- 複数サーバー間でのエラー定義の標準化
- DR環境構築時のエラー定義同期

**主要な処理内容**：
1. ソースサーバーへの接続とカスタムエラー取得
2. 英語（us_english）バージョンを先に処理（SQL Server要件）
3. 既存エラーの存在チェック
4. -Force指定時は既存エラーを削除して再作成
5. Script()メソッドでSQLを生成し、デスティネーションで実行

**関連システム・外部連携**：sys.messages、sp_addmessage、sp_dropmessage

**権限による制御**：sysadmin権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | PowerShellコンソール | 主画面 | コマンド実行および結果表示 |

## 機能種別

データ移行 / オブジェクトコピー

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Source | DbaInstanceParameter | Yes | ソースSQL Serverインスタンス | - |
| SourceSqlCredential | PSCredential | No | ソース認証情報 | - |
| Destination | DbaInstanceParameter[] | Yes | デスティネーションインスタンス（複数可） | - |
| DestinationSqlCredential | PSCredential | No | デスティネーション認証情報 | - |
| CustomError | Object[] | No | コピー対象のエラーID | - |
| ExcludeCustomError | Object[] | No | 除外するエラーID | - |
| Force | Switch | No | 既存エラーを上書き | - |
| EnableException | Switch | No | 例外制御 | - |
| WhatIf | Switch | No | 実行シミュレーション | - |
| Confirm | Switch | No | 実行確認 | - |

### 入力データソース

- ソースサーバーの UserDefinedMessages コレクション（SMO）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| DateTime | DbaDateTime | 操作日時 |
| SourceServer | String | ソースサーバー名 |
| DestinationServer | String | デスティネーションサーバー名 |
| Name | String | カスタムエラーID |
| Type | String | オブジェクトタイプ（"Custom error"） |
| Status | String | 結果（Successful / Skipped / Failed） |
| Notes | String | 追加情報 |

### 出力先

- PowerShellパイプライン（PSCustomObject / MigrationObject）

## 処理フロー

### 処理シーケンス

```
1. ソースサーバー接続
   └─ Connect-DbaInstance (MinimumVersion 9)

2. カスタムエラー取得
   ├─ 英語(us_english)を先頭にソート
   └─ その他の言語を追加

3. デスティネーションループ開始
   └─ 各デスティネーションに対して以下を実行

4. デスティネーションサーバー接続
   └─ Connect-DbaInstance (MinimumVersion 9)

5. カスタムエラーループ開始
   └─ 各カスタムエラーに対して以下を実行

6. フィルタチェック
   └─ CustomError/ExcludeCustomError パラメータ適用

7. 既存チェック
   ├─ 存在しない場合: コピー実行
   ├─ 存在 + Force なし: スキップ
   └─ 存在 + Force: 削除して再作成

8. エラーコピー実行
   └─ Script() でSQL生成、Query() で実行

9. 結果出力
   └─ MigrationObject として出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[ソースサーバー接続]
    B --> C[カスタムエラー取得]
    C --> D[英語を先頭にソート]
    D --> E[デスティネーションループ]
    E --> F[デスティネーション接続]
    F --> G[カスタムエラーループ]
    G --> H{フィルタ通過?}
    H -->|No| I[スキップ]
    H -->|Yes| J{既存あり?}
    J -->|No| K[コピー実行]
    J -->|Yes| L{-Force?}
    L -->|No| M[Skipped出力]
    L -->|Yes| N[既存削除]
    N --> K
    K --> O{成功?}
    O -->|Yes| P[Successful出力]
    O -->|No| Q[Failed出力]
    P --> R{次のエラー?}
    Q --> R
    M --> R
    I --> R
    R -->|Yes| G
    R -->|No| S{次のデスティネーション?}
    S -->|Yes| E
    S -->|No| T[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 英語優先 | us_englishバージョンを最初にコピー | SQL Server要件 |
| BR-002 | 英語削除で全言語削除 | 英語版を削除すると全翻訳も削除される | -Force時 |
| BR-003 | SQL Server 2005以上 | MinimumVersion 9 | 常時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 取得 | sys.messages | SELECT (SMO経由) | カスタムエラー取得 |
| 追加 | sys.messages | INSERT (sp_addmessage経由) | カスタムエラー追加 |
| 削除 | sys.messages | DELETE (sp_dropmessage経由) | 既存エラー削除 |

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

#### sys.messages (SMO UserDefinedMessages)

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | message_id, language_id, text, severity, is_event_logged | is_system_object = 0 | ユーザー定義のみ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | インスタンス接続失敗 | Stop-Function、continue |
| DropFailed | 削除エラー | 既存エラー削除失敗 | Failed出力、continue |
| CreateFailed | 作成エラー | エラーコピー失敗 | Failed出力、continue |

### リトライ仕様

リトライ処理なし。

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

各エラーは個別に処理。部分的な移行が可能。

## パフォーマンス要件

- カスタムエラー数に比例した処理時間

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

- sysadmin権限が必要

## 備考

- SupportsShouldProcess対応（WhatIf/Confirm）
- 複数デスティネーション対応

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Copy-DbaCustomError.ps1 | `public/Copy-DbaCustomError.ps1` | UserDefinedMessagesコレクション（127-128行目） |

**読解のコツ**: SMO UserDefinedMessage オブジェクトのプロパティを理解する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Copy-DbaCustomError.ps1 | `public/Copy-DbaCustomError.ps1` | 関数全体の処理フロー |

**主要処理フロー**:
1. **104-118行目**: パラメータ定義
2. **120-131行目**: ソース接続とカスタムエラー取得
3. **127-128行目**: 英語優先ソート
4. **143-185行目**: 既存チェックと削除/コピー処理
5. **187-202行目**: コピー実行とエラーハンドリング

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

```
Copy-DbaCustomError
    │
    ├─ Connect-DbaInstance (Source, MinimumVersion 9)
    │
    ├─ $sourceServer.UserDefinedMessages
    │      └─ 英語優先ソート
    │
    ├─ Connect-DbaInstance (Destination, MinimumVersion 9)
    │
    ├─ $destServer.UserDefinedMessages[$id, $lang].Drop()
    │      └─ -Force時の既存削除
    │
    └─ $destServer.Query($currentCustomError.Script())
           └─ カスタムエラー作成
```

### データフロー図

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

Source ───▶ Connect-DbaInstance
                 │
                 ▼
          UserDefinedMessages取得
                 │
                 ▼
          英語優先ソート
                 │
                 ▼
Destination ───▶ Connect-DbaInstance
                 │
                 ▼
          既存チェック
                 │
          ┌──────┴──────┐
          ▼             ▼
       存在しない     存在する
          │             │
          │        ┌────┴────┐
          │        ▼         ▼
          │     -Force    Force無し
          │        │         │
          │      Drop()    Skipped
          │        │         │
          └────┬───┘         │
               ▼             │
          Script()→Query()   │
               │             │
               ▼             ▼
          Successful    MigrationObject出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Copy-DbaCustomError.ps1 | `public/Copy-DbaCustomError.ps1` | ソース | メイン関数 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
