# 機能設計書 481-Copy-DbaAgentServer

## 概要

本ドキュメントは、SQL Server Agent のサーバー全体オブジェクトと設定を別インスタンスにコピーする Copy-DbaAgentServer 関数の機能設計書である。

### 本機能の処理概要

Copy-DbaAgentServer は、SQL Server Agent の完全な構成をソースインスタンスから1つ以上の宛先インスタンスに移行するための包括的なコピー機能を提供する。ジョブ、オペレーター、アラート、スケジュール、ジョブカテゴリ、プロキシアカウントなどの Agent オブジェクトを適切な順序で作成し、サーバーレベルの Agent プロパティ（ジョブ履歴保持設定、エラーログの場所、データベースメールプロファイルなど）もコピーする。

**業務上の目的・背景**：サーバー移行、ディザスタリカバリ環境の構築、または複数環境間での Agent 構成の標準化において、手動で数十のオブジェクトを再作成する必要性を排除する。本番環境から開発/テスト環境への構成複製や、新規サーバーへの移行時に不可欠な機能である。

**機能の利用シーン**：
- SQL Server のメジャーバージョンアップグレード時のジョブ移行
- ディザスタリカバリサイトへの Agent 構成の複製
- 開発・テスト・本番環境間での Agent 設定の同期
- 新規サーバーセットアップ時の標準構成の展開

**主要な処理内容**：
1. ソースインスタンスへの接続確立と Agent オブジェクトの取得
2. ジョブカテゴリ（Job/Operator/Alert）のコピー
3. オペレーターのコピー
4. プロキシアカウントのコピー
5. 共有スケジュールのコピー
6. ジョブのコピー（アラートとの関連付けを維持するため先にコピー）
7. アラートのコピー（ジョブへの関連付けを含む）
8. サーバーレベルの Agent プロパティのコピー

**関連システム・外部連携**：ソースおよび宛先の SQL Server インスタンス間での SMO (SQL Server Management Objects) を介した通信。データベースメールプロファイルやプロキシアカウントの資格情報など、依存関係のあるオブジェクトが宛先に存在する必要がある。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 16 | Agentサーバー設定 | 補助機能 | エージェントサーバー設定のコピー |

## 機能種別

データ連携 / オブジェクト移行

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Source | DbaInstanceParameter | Yes | コピー元のSQL Serverインスタンス | sysadmin権限、SQL Server 2000以降 |
| SourceSqlCredential | PSCredential | No | ソースインスタンスへの認証資格情報 | 有効なSQL/Windows認証 |
| Destination | DbaInstanceParameter[] | Yes | コピー先のSQL Serverインスタンス（複数可） | sysadmin権限、SQL Server 2000以降 |
| DestinationSqlCredential | PSCredential | No | 宛先インスタンスへの認証資格情報 | 有効なSQL/Windows認証 |
| DisableJobsOnDestination | Switch | No | コピー後に宛先のジョブを無効化 | - |
| DisableJobsOnSource | Switch | No | コピー後にソースのジョブを無効化 | - |
| ExcludeServerProperties | Switch | No | サーバーレベルのAgent設定をスキップ | - |
| Force | Switch | No | 同名オブジェクトを上書き | - |
| EnableException | Switch | No | 例外処理を有効化 | - |

### 入力データソース

SMO を介したソース SQL Server インスタンスの JobServer オブジェクトから取得。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| DateTime | DbaDateTime | コピー操作実行時のタイムスタンプ |
| SourceServer | String | ソースSQL Serverインスタンス名 |
| DestinationServer | String | 宛先SQL Serverインスタンス名 |
| Name | String | コピーされた内容の説明（"Server level properties"） |
| Type | String | オブジェクトカテゴリ（"Agent Properties"） |
| Status | String | コピー結果（Skipped/Successful/Failed） |
| Notes | String | 失敗時のエラーメッセージ（成功時はnull） |

### 出力先

パイプライン出力として PSCustomObject (MigrationObject タイプ) を返す。

## 処理フロー

### 処理シーケンス

```
1. ソースインスタンスへの接続
   └─ Connect-DbaInstance を使用して接続確立
   └─ 失敗時は Stop-Function で処理中断

2. SMO互換性チェック
   └─ Invoke-SmoCheck でバージョン互換性を確認

3. 各宛先インスタンスに対してループ処理
   └─ 宛先への接続確立
   └─ ジョブカテゴリのコピー（Copy-DbaAgentJobCategory）
   └─ SMOオブジェクトのリフレッシュ
   └─ オペレーターのコピー（Copy-DbaAgentOperator）
   └─ プロキシのコピー（Copy-DbaAgentProxy）
   └─ スケジュールのコピー（Copy-DbaAgentSchedule）
   └─ ジョブのコピー（Copy-DbaAgentJob）
   └─ アラートのコピー（Copy-DbaAgentAlert）
   └─ サーバープロパティのコピー（T-SQLスクリプト実行）

4. 結果オブジェクトの生成と出力
   └─ MigrationObject タイプで結果を返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[ソースインスタンス接続]
    B --> C{接続成功?}
    C -->|No| D[エラー終了]
    C -->|Yes| E[SMOチェック]
    E --> F[宛先ループ開始]
    F --> G[宛先接続]
    G --> H{接続成功?}
    H -->|No| F
    H -->|Yes| I[ジョブカテゴリコピー]
    I --> J[オペレーターコピー]
    J --> K[プロキシコピー]
    K --> L[スケジュールコピー]
    L --> M[ジョブコピー]
    M --> N[アラートコピー]
    N --> O{ExcludeServerProperties?}
    O -->|Yes| P[Status: Skipped]
    O -->|No| Q[サーバープロパティコピー]
    Q --> R{コピー成功?}
    R -->|Yes| S[Status: Successful]
    R -->|No| T[Status: Failed]
    P --> U[結果出力]
    S --> U
    T --> U
    U --> V{次の宛先?}
    V -->|Yes| F
    V -->|No| W[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | コピー順序 | オブジェクトは依存関係を考慮した順序でコピーされる | 常時 |
| BR-002 | ジョブ先行コピー | アラートがジョブを参照するため、ジョブを先にコピー | 常時 |
| BR-003 | Force上書き | Forceスイッチ指定時は同名オブジェクトを削除後再作成 | Force指定時 |
| BR-004 | ジョブ無効化 | DisableJobsOnDestinationで宛先のジョブを無効化 | スイッチ指定時 |

### 計算ロジック

特になし。

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| カテゴリコピー | msdb.dbo.syscategories | INSERT | ジョブ/オペレーター/アラートカテゴリの作成 |
| オペレーターコピー | msdb.dbo.sysoperators | INSERT | オペレーター情報の作成 |
| プロキシコピー | msdb.dbo.sysproxies | INSERT | プロキシアカウントの作成 |
| スケジュールコピー | msdb.dbo.sysschedules | INSERT | 共有スケジュールの作成 |
| ジョブコピー | msdb.dbo.sysjobs | INSERT | ジョブ定義の作成 |
| アラートコピー | msdb.dbo.sysalerts | INSERT | アラート定義の作成 |
| プロパティ設定 | sp_set_sqlagent_properties | EXEC | Agentサーバー設定の変更 |

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

#### msdb.dbo.syscategories

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name, category_class | ソースからコピー | カテゴリ名が重複する場合はスキップまたは上書き |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | インスタンスへの接続失敗 | Stop-Functionで処理中断 |
| PropertyCopyFailed | プロパティコピーエラー | サーバープロパティのコピー失敗 | Status: Failedで続行 |

### リトライ仕様

特になし。各コピー関数内で個別にエラーハンドリング。

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

各コピー関数は個別にトランザクションを管理。サーバープロパティのコピーは単一のT-SQLバッチとして実行。

## パフォーマンス要件

オブジェクト数に依存。大量のジョブを持つ環境では、各コピー関数の実行後にSMOオブジェクトのリフレッシュを行うため、ネットワーク遅延の影響を受ける可能性がある。

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

- 両方のインスタンスで sysadmin 権限が必要
- プロキシアカウントの資格情報は宛先に事前に存在する必要がある
- SQL認証を使用する場合、資格情報は PSCredential オブジェクトとして安全に渡される

## 備考

- SQL Server 2000 以降をサポート
- マスターサーバー/ターゲットサーバー（MSX/TSX）の構成は未実装（TODO）
- サーバープロパティのコピーでは、errorlog_file と auto_start 設定はコメントアウトされる

---

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

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

### 推奨読解順序

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

パラメータ定義と出力オブジェクトの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Copy-DbaAgentServer.ps1 | `public/Copy-DbaAgentServer.ps1` | 99-112行目: パラメータ定義と型指定 |

**読解のコツ**: PowerShell の `[parameter(Mandatory)]` 属性と `[Switch]` 型の使用パターンに注目。

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

処理の起点となる begin ブロックと process ブロックを特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Copy-DbaAgentServer.ps1 | `public/Copy-DbaAgentServer.ps1` | 114-125行目: beginブロック、ソース接続処理 |
| 2-2 | Copy-DbaAgentServer.ps1 | `public/Copy-DbaAgentServer.ps1` | 126-214行目: processブロック、メインロジック |

**主要処理フロー**:
1. **114-121行目**: ソースインスタンスへの接続とエラーハンドリング
2. **122行目**: JobServerオブジェクトの取得
3. **128-134行目**: 各宛先インスタンスへの接続ループ
4. **136-164行目**: 各種Agentオブジェクトのコピー呼び出し

#### Step 3: 各コピー関数の呼び出し順序を理解する

依存関係を考慮したコピー順序の理解。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Copy-DbaAgentServer.ps1 | `public/Copy-DbaAgentServer.ps1` | 136行目: カテゴリコピー（最初に実行） |
| 3-2 | Copy-DbaAgentServer.ps1 | `public/Copy-DbaAgentServer.ps1` | 144行目: オペレーターコピー |
| 3-3 | Copy-DbaAgentServer.ps1 | `public/Copy-DbaAgentServer.ps1` | 152行目: プロキシコピー |
| 3-4 | Copy-DbaAgentServer.ps1 | `public/Copy-DbaAgentServer.ps1` | 155行目: スケジュールコピー |
| 3-5 | Copy-DbaAgentServer.ps1 | `public/Copy-DbaAgentServer.ps1` | 161行目: ジョブコピー（アラートより前） |
| 3-6 | Copy-DbaAgentServer.ps1 | `public/Copy-DbaAgentServer.ps1` | 163行目: アラートコピー |

**主要処理フロー**:
- **136行目**: `Copy-DbaAgentJobCategory` - ジョブ/オペレーター/アラートカテゴリを先にコピー
- **144行目**: `Copy-DbaAgentOperator` - アラートの通知先として必要
- **161行目**: `Copy-DbaAgentJob` - コメント記載あり、アラートより先にコピー

#### Step 4: サーバープロパティのコピー処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Copy-DbaAgentServer.ps1 | `public/Copy-DbaAgentServer.ps1` | 174-212行目: プロパティコピーと結果出力 |

**主要処理フロー**:
- **184-189行目**: ExcludeServerProperties時のスキップ処理
- **191-211行目**: プロパティコピーの実行とエラーハンドリング
- **194行目**: SMOのScript()メソッドでT-SQL生成
- **195-197行目**: インスタンス名置換と特定設定のコメントアウト

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

```
Copy-DbaAgentServer
    │
    ├─ Connect-DbaInstance (ソース接続)
    │
    ├─ Invoke-SmoCheck (SMO互換性チェック)
    │
    └─ [foreach 宛先インスタンス]
           │
           ├─ Connect-DbaInstance (宛先接続)
           │
           ├─ Copy-DbaAgentJobCategory
           │      └─ ジョブ/オペレーター/アラートカテゴリのコピー
           │
           ├─ Copy-DbaAgentOperator
           │      └─ オペレーターのコピー
           │
           ├─ Copy-DbaAgentProxy
           │      └─ プロキシアカウントのコピー
           │
           ├─ Copy-DbaAgentSchedule
           │      └─ 共有スケジュールのコピー
           │
           ├─ Copy-DbaAgentJob
           │      └─ ジョブ定義のコピー
           │
           ├─ Copy-DbaAgentAlert
           │      └─ アラート定義のコピー
           │
           └─ $destServer.Query($sql)
                  └─ サーバープロパティのT-SQL実行
```

### データフロー図

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

Source Instance ─────────────▶ Connect-DbaInstance ─────────────▶ SMO Server Object
                               │
                               ▼
                         Invoke-SmoCheck
                               │
                               ▼
Destination Instance(s) ────▶ Connect-DbaInstance ─────────────▶ SMO Server Object
                               │
                               ▼
                         各Copy-Dba*関数
                               │
                               ▼
                         $sourceAgent.Script()
                               │
                               ▼
                         T-SQL変換・実行 ───────────────────────▶ PSCustomObject
                                                                  (MigrationObject)
                                                                  - Status
                                                                  - Notes
                                                                  - DateTime
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Copy-DbaAgentServer.ps1 | `public/Copy-DbaAgentServer.ps1` | ソース | メイン関数 |
| Copy-DbaAgentJobCategory.ps1 | `public/Copy-DbaAgentJobCategory.ps1` | ソース | ジョブカテゴリコピー |
| Copy-DbaAgentOperator.ps1 | `public/Copy-DbaAgentOperator.ps1` | ソース | オペレーターコピー |
| Copy-DbaAgentProxy.ps1 | `public/Copy-DbaAgentProxy.ps1` | ソース | プロキシコピー |
| Copy-DbaAgentSchedule.ps1 | `public/Copy-DbaAgentSchedule.ps1` | ソース | スケジュールコピー |
| Copy-DbaAgentJob.ps1 | `public/Copy-DbaAgentJob.ps1` | ソース | ジョブコピー |
| Copy-DbaAgentAlert.ps1 | `public/Copy-DbaAgentAlert.ps1` | ソース | アラートコピー |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続 |
