# 機能設計書 387-Copy-DbaDataCollector

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるCopy-DbaDataCollector機能の設計仕様を記載する。本機能は、SQL Server Data Collectorのコレクションセットを1つのインスタンスから別のインスタンスにコピーする。

### 本機能の処理概要

本機能は、SQL Serverインスタンス間でSQL Server Data Collectorのコレクションセットをコピーし、環境全体でパフォーマンスモニタリング設定を複製できるようにする。ソースインスタンスからコレクションセット定義をスクリプト化し、すべてのコレクションアイテム、スケジュール、アップロード設定を保持した状態で宛先に再作成する。

**業務上の目的・背景**：SQL Server環境全体で一貫したパフォーマンスモニタリング構成を維持することは、ベースライン比較やトラブルシューティングにおいて重要である。手動でのData Collector設定は時間がかかり、設定ミスのリスクがある。本機能により、検証済みのモニタリング設定を他の環境に効率的に展開できる。

**機能の利用シーン**：
- 本番環境のモニタリング設定をテスト環境に複製
- 新規SQL Serverインスタンスへの標準モニタリング設定の展開
- DR環境への設定同期
- 環境間での設定標準化

**主要な処理内容**：
1. ソースインスタンスへの接続とCollectorConfigStoreの取得
2. コレクションセット定義のスクリプト化（ScriptCreate）
3. 宛先インスタンスでのData Collector有効化確認
4. 既存セットの確認と処理（-Force時は削除・再作成）
5. コレクションセットの作成と起動（ソースで実行中の場合）

**関連システム・外部連携**：SQL Server Data Collector（Management Data Warehouse）、Microsoft.SqlServer.Management.Collector名前空間。

**権限による制御**：両インスタンスでsysadminアクセスが必要。

## 関連画面

本機能はCLIベースのPowerShellコマンドレットであり、GUI画面との直接的な関連はない。

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | PowerShellコンソール | 主画面 | コマンド実行とコピー結果表示 |
| - | SQL Server Management Studio | 参照画面 | Data Collectorの確認 |

## 機能種別

マイグレーション / オブジェクトコピー

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Source | DbaInstanceParameter | Yes | コピー元SQL Serverインスタンス | - |
| SourceSqlCredential | PSCredential | No | ソースインスタンス接続用認証情報 | - |
| Destination | DbaInstanceParameter[] | Yes | コピー先SQL Serverインスタンス（複数可） | - |
| DestinationSqlCredential | PSCredential | No | 宛先インスタンス接続用認証情報 | - |
| CollectionSet | object[] | No | コピーするコレクションセット名（タブ補完対応） | - |
| ExcludeCollectionSet | object[] | No | 除外するコレクションセット名（タブ補完対応） | - |
| NoServerReconfig | switch | No | サーバー設定コピーの無効化（将来用、現在未実装） | - |
| Force | switch | No | 既存セットを削除して再作成 | - |
| WhatIf | switch | No | 実行せず影響を表示 | - |
| Confirm | switch | No | 実行前に確認を要求 | - |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- SQL Serverインスタンス：CollectorConfigStoreからコレクションセット情報を取得

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| DateTime | DbaDateTime | 操作実行日時 |
| SourceServer | string | ソースSQL Serverインスタンス名 |
| DestinationServer | string | 宛先SQL Serverインスタンス名 |
| Name | string | コレクションセット名または設定項目名 |
| Type | string | オブジェクトタイプ（"Collection Set"等） |
| Status | string | 操作結果（Successful/Skipped/Failed等） |
| Notes | string | 追加情報（スキップ理由、エラー詳細等） |

### 出力先

PowerShellパイプラインへPSCustomObjectとして出力（MigrationObject型として表示）。

## 処理フロー

### 処理シーケンス

```
1. プラットフォームチェック
   └─ Windowsのみサポート（Linux非サポート）
2. ソースインスタンス接続
   └─ Connect-DbaInstanceで接続（MinimumVersion 10）
   └─ CollectorConfigStore取得
3. 各宛先インスタンスでループ
   └─ Connect-DbaInstanceで接続
   └─ Data Collector有効化確認
4. コレクションセットのフィルタリング
   └─ システムセットを除外
   └─ CollectionSet/ExcludeCollectionSetで絞り込み
5. 各コレクションセットのコピー
   └─ 既存チェック（-Force時は削除）
   └─ ScriptCreateでスクリプト生成
   └─ 宛先で実行
6. コレクション起動
   └─ ソースで実行中の場合は宛先でも起動
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Windowsプラットフォーム?}
    B -->|No| C[エラー: Linux非サポート]
    B -->|Yes| D[ソースインスタンス接続]
    D --> E{接続成功?}
    E -->|No| F[エラー終了]
    E -->|Yes| G[CollectorConfigStore取得]
    G --> H[各宛先インスタンスでループ]
    H --> I[宛先インスタンス接続]
    I --> J{Data Collector有効?}
    J -->|No| K[警告: Data Collector未設定]
    J -->|Yes| L[コレクションセットフィルタリング]
    K --> M{次の宛先あり?}
    L --> N[各コレクションセットでループ]
    N --> O{宛先に既存?}
    O -->|Yes| P{Force指定?}
    P -->|No| Q[スキップ]
    P -->|Yes| R[既存セット削除]
    O -->|No| S[ScriptCreate実行]
    R --> S
    S --> T[宛先で作成]
    T --> U{作成成功?}
    U -->|No| V[エラー記録]
    U -->|Yes| W{ソースで実行中?}
    W -->|Yes| X[宛先でセット起動]
    W -->|No| Y[結果出力]
    X --> Y
    Q --> Y
    V --> Y
    Y --> Z{次のセットあり?}
    Z -->|Yes| N
    Z -->|No| M
    M -->|Yes| H
    M -->|No| AA[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | Windowsのみ | Linux環境では実行不可 | 常時 |
| BR-002 | SQL Server 2008以上 | MinimumVersion 10が必要 | 常時 |
| BR-003 | システムセット除外 | IsSystem=trueのセットは除外 | 常時 |
| BR-004 | Data Collector有効必須 | 宛先でData Collectorが有効である必要あり | 常時 |
| BR-005 | 自動起動 | ソースで実行中のセットは宛先でも起動 | 常時 |
| BR-006 | ConfirmImpact | Medium設定 | 常時 |

### 計算ロジック

なし（設定のコピーのみ）。

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 取得 | msdb.dbo.syscollector_collection_sets | SELECT | コレクションセット定義の取得 |
| 作成 | msdb.dbo.syscollector_collection_sets | INSERT | コレクションセットの作成 |
| 削除 | msdb.dbo.syscollector_collection_sets | DELETE | 既存セットの削除（-Force時） |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | プラットフォームエラー | Linux環境で実行 | Windows環境で実行 |
| - | 接続エラー | SQL Server接続失敗 | 認証情報・接続性を確認 |
| - | Data Collector無効 | 宛先でData Collector未設定 | Data Collectorを有効化 |
| - | 作成エラー | コレクションセット作成失敗 | エラー詳細を確認 |
| - | 起動エラー | コレクション起動失敗 | 手動で起動を試行 |

### リトライ仕様

リトライ機能は実装されていない。

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

各コレクションセットの作成は個別に処理。失敗しても他のセットの処理は継続。

## パフォーマンス要件

- コレクションセット定義のスクリプト化と実行は軽量な操作
- 複数宛先がある場合は順次処理

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

- 両インスタンスでsysadminアクセスが必要
- SqlCredentialで認証情報を安全に受け渡し

## 備考

- NoServerReconfigは将来用に予約（現在は未実装で警告を出力）
- Forceパラメータで$ConfirmPreference = 'none'に設定
- Core SMOがMicrosoftから提供されるまでLinuxサポートなし

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Copy-DbaDataCollector.ps1 | `public/Copy-DbaDataCollector.ps1` | 出力オブジェクト構造（71-85行目の.OUTPUTS） |

**読解のコツ**: MigrationObject型として表示される。Select-DefaultViewで表示制御。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Copy-DbaDataCollector.ps1 | `public/Copy-DbaDataCollector.ps1` | パラメータ定義（106-121行目） |
| 2-2 | Copy-DbaDataCollector.ps1 | `public/Copy-DbaDataCollector.ps1` | beginブロック（122-140行目） |

**主要処理フロー**:
1. **122-126行目**: Windowsプラットフォームチェック
2. **127-131行目**: Connect-DbaInstanceでソース接続
3. **133-136行目**: CollectorConfigStore取得

#### Step 3: コア処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Copy-DbaDataCollector.ps1 | `public/Copy-DbaDataCollector.ps1` | 宛先接続とData Collector確認（141-189行目） |
| 3-2 | Copy-DbaDataCollector.ps1 | `public/Copy-DbaDataCollector.ps1` | コレクションセットコピー（200-272行目） |

**主要処理フロー**:
- **145-149行目**: Connect-DbaInstanceで宛先接続
- **168-170行目**: CollectorConfigStore取得
- **186-189行目**: Data Collector有効チェック
- **191-197行目**: コレクションセットフィルタリング
- **213-238行目**: 既存チェックとForce処理
- **240-254行目**: ScriptCreateとQuery実行
- **256-270行目**: 実行中セットの起動

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

```
Copy-DbaDataCollector
    │
    ├─ Connect-DbaInstance
    │      └─ ソース/宛先SQL Server接続
    │
    ├─ Microsoft.SqlServer.Management.Collector.CollectorConfigStore
    │      ├─ CollectionSets取得
    │      ├─ ScriptCreate()
    │      └─ Start()
    │
    └─ $destServer.Query()
           └─ コレクションセット作成SQL実行
```

### データフロー図

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

Source ─────────┐
                │
Destination ────┤
                │
CollectionSet ──┼──▶ CollectorConfig ──▶ PSCustomObject
                │    Store操作          │
Credential ─────┘    ▼                  ├─ DateTime
                     ScriptCreate       ├─ SourceServer
                     ▼                  ├─ DestinationServer
                     Query実行          ├─ Name
                                        ├─ Type
                                        ├─ Status
                                        └─ Notes
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Copy-DbaDataCollector.ps1 | `public/Copy-DbaDataCollector.ps1` | ソース | メイン機能実装 |
| Copy-DbaDataCollector.Tests.ps1 | `tests/Copy-DbaDataCollector.Tests.ps1` | テスト | 単体テスト |
