# 画面設計書 195-データコレクター

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるSQL Data Collectorコピー機能の設計を記述する。Copy-DbaDataCollector コマンドを中心に、SQL Serverインスタンス間でData Collectorのコレクションセットをコピーするための機能仕様を定義する。

### 本画面の処理概要

**業務上の目的・背景**：SQL Data Collectorは、SQL Serverのパフォーマンスモニタリングデータを収集・保存する機能である。本機能により、ソースインスタンスで構成済みのコレクションセット定義を別のSQL Serverインスタンスにコピーし、パフォーマンス監視構成を標準化できる。環境間で一貫した監視設定を維持し、手動構成のエラーを削減するために重要な機能である。特に、複数のSQL Server環境でのベースライン監視設定の展開やディザスターリカバリシナリオで有用である。

**画面へのアクセス方法**：PowerShellコマンドラインから `Copy-DbaDataCollector` コマンドを実行することでアクセスする。SourceとDestinationパラメータは必須である。

**主要な操作・処理内容**：
1. ソースSQL Serverインスタンスに接続し、Data Collectorストアを取得
2. 宛先SQL Serverインスタンスに接続し、Data Collectorストアを取得
3. 宛先でData Collectorが有効になっているか確認
4. ソースのコレクションセット（システムセットを除く）をスクリプト化
5. 宛先でコレクションセットを作成（既存の場合はスキップまたはForceで再作成）
6. ソースで実行中だったコレクションセットは宛先でも開始

**画面遷移**：本機能は `Start-DbaMigration` の一部として呼び出される場合がある。

**権限による表示制御**：ソースおよび宛先のSQL Serverでsysadmin権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 387 | Copy-DbaDataCollector | 主機能 | データコレクターのコピー |
| - | Start-DbaMigration | 遷移先機能 | 全体マイグレーションの一部として呼び出し |

## 画面種別

操作実行（マイグレーション）

## URL/ルーティング

PowerShellコマンド: `Copy-DbaDataCollector`

## 入出力項目

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| 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 | 既存のコレクションセットを上書き |
| EnableException | switch | No | 例外処理を有効化 |
| WhatIf | switch | No | 実行内容のプレビュー |
| Confirm | switch | No | 確認プロンプトの表示 |

### 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| DateTime | DbaDateTime | 操作日時 |
| SourceServer | string | ソースサーバー名 |
| DestinationServer | string | 宛先サーバー名 |
| Name | string | コレクションセット名または構成項目名 |
| Type | string | オブジェクトタイプ（Collection Set、Data Collection Server Config） |
| Status | string | 処理結果（Successful、Skipped、Failed等） |
| Notes | string | 追加情報（スキップ理由、エラー詳細等） |

## 表示項目

デフォルトビューでは以下のプロパティが表示される:
- DateTime, SourceServer, DestinationServer, Name, Type, Status, Notes

## イベント仕様

### 1-コレクションセットコピー

コマンド実行時に以下の処理フローが実行される:

1. **beginブロック**:
   - Windowsプラットフォームチェック（非Windowsは非サポート）
   - ソースSQL Serverへ接続（MinimumVersion 10）
   - CollectorConfigStoreオブジェクトを作成
   - Forceが指定されている場合、ConfirmPreferenceを'none'に設定

2. **processブロック**:
   - 宛先SQL Serverへ接続
   - 宛先のCollectorConfigStoreを取得
   - Data Collectorが無効の場合は警告して処理スキップ
   - コレクションセットをフィルタリング（システムセットを除外、名前フィルタ適用）
   - 各コレクションセットについて:
     - 既存チェック（Force指定時は削除して再作成）
     - スクリプト生成と実行
     - ソースで実行中の場合は宛先でも開始

## データベース更新仕様

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

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

### テーブル別更新項目詳細

#### syscollector_collection_sets

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | collection_set_id | 自動生成 | 新規コレクションセット |
| INSERT | name | ソースと同名 | コレクションセット名 |
| INSERT | schedule_name | ソースから転写 | スケジュール設定 |
| INSERT | collection_mode | ソースから転写 | 収集モード |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| MSG001 | Error | Copy-DbaDataCollector does not support Linux - we're still waiting for the Core SMOs from Microsoft | 非Windowsで実行時 |
| MSG002 | Verbose | Server reconfiguration not yet supported. Only Collection Set migration will be migrated at this time. | NoServerReconfigがfalseの場合 |
| MSG003 | Verbose | The Data Collector must be setup initially for Collection Sets to be migrated. | 宛先でData Collectorが無効の場合 |
| MSG004 | Verbose | Collection Set '{name}' was skipped because it already exists | 既存で、Forceなしの場合 |
| MSG005 | Verbose | Force specified. Dropping {name}. | Force指定時の削除 |
| MSG006 | Verbose | Migrating collection set {name} | コレクションセット移行時 |
| MSG007 | Verbose | Starting collection set {name} | コレクションセット開始時 |

## 例外処理

| 例外種別 | 発生条件 | 処理内容 |
|---------|---------|---------|
| 接続エラー | SQL Serverへ接続できない場合 | Stop-Functionでエラー出力、処理続行 |
| プラットフォーム非対応 | 非Windowsで実行時 | Stop-Functionで処理中断 |
| 削除エラー | コレクションセット削除失敗 | エラー記録して処理続行 |
| 作成エラー | コレクションセット作成失敗 | エラー記録して処理続行 |
| 開始エラー | コレクションセット開始失敗 | エラー記録して処理続行 |

## 備考

- SQL Server 2008以降（バージョン10以上）が必要
- Windows環境でのみサポート（PowerShell Core非対応）
- システムコレクションセットはコピー対象外
- 宛先でData Collectorがセットアップされている必要がある
- サーバー構成のコピーは未実装（NoServerReconfigは将来使用）

---

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

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

### 推奨読解順序

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

コレクションセットと出力オブジェクトの構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Copy-DbaDataCollector.ps1 | `public/Copy-DbaDataCollector.ps1` | .OUTPUTS セクションで出力オブジェクトの構造を確認（L71-84） |

**読解のコツ**: 出力オブジェクトはマイグレーション結果を表すPSCustomObjectである。

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

Copy-DbaDataCollector関数のパラメータとbeginブロックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Copy-DbaDataCollector.ps1 | `public/Copy-DbaDataCollector.ps1` | param()ブロックでパラメータ定義を確認（L106-121） |

**主要処理フロー**:
1. **L122-126**: Windowsプラットフォームチェック
2. **L127-132**: ソースSQL Serverへ接続
3. **L133-136**: CollectorConfigStoreオブジェクトを作成
4. **L139**: Force指定時のConfirmPreference設定

#### Step 3: メイン処理ロジックを理解する

コレクションセットのコピー処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Copy-DbaDataCollector.ps1 | `public/Copy-DbaDataCollector.ps1` | processブロックのメイン処理（L141-274） |

**主要処理フロー**:
- **L145-149**: 宛先SQL Serverへ接続
- **L168-170**: 宛先のCollectorConfigStoreを取得
- **L186-189**: Data Collectorが無効の場合のチェック
- **L191-197**: コレクションセットのフィルタリング
- **L200-272**: 各コレクションセットのコピー処理

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

```
Copy-DbaDataCollector
    |
    +-- Stop-Function (非Windows)
    |       └-- プラットフォームチェックエラー
    |
    +-- Connect-DbaInstance (Source)
    |       └-- ソースSQL Server接続確立
    |
    +-- New-Object CollectorConfigStore
    |       └-- ソースのコレクターストア取得
    |
    +-- foreach (Destination)
    |       |
    |       +-- Connect-DbaInstance (Destination)
    |       |       └-- 宛先SQL Server接続確立
    |       |
    |       +-- New-Object CollectorConfigStore
    |       |       └-- 宛先のコレクターストア取得
    |       |
    |       +-- Enabled チェック
    |       |       └-- Data Collector有効確認
    |       |
    |       +-- foreach (CollectionSet)
    |               |
    |               +-- 既存チェック
    |               |       └-- 存在確認・Force時は削除
    |               |
    |               +-- ScriptCreate
    |               |       └-- 作成スクリプト生成
    |               |
    |               +-- Query実行
    |               |       └-- スクリプト実行
    |               |
    |               └-- Start (IsRunning)
    |                       └-- ソースで実行中なら開始
    |
    └-- Select-DefaultView
            └-- デフォルト表示プロパティの設定
```

### データフロー図

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

Source ──────────────┐
                     │
SourceSqlCredential ─┤    ┌─────────────────────┐
                     │    │ Connect-DbaInstance │
Destination ─────────┼───►│ (Source)            │
                     │    └──────────┬──────────┘
DestinationSql       │               │
Credential ──────────┤               ▼
                     │    ┌─────────────────────┐
CollectionSet ───────┤    │ CollectorConfigStore│
                     │    │ (Source)            │
ExcludeCollectionSet ┤    └──────────┬──────────┘
                     │               │
Force ───────────────┘               ▼
                          ┌─────────────────────┐
                          │ CollectionSets      │
                          │ フィルタリング       │
                          └──────────┬──────────┘
                                     │
                                     ▼
                          ┌─────────────────────┐
                          │ 各コレクションセット │
                          │ - ScriptCreate      │──►  PSCustomObject[]
                          │ - Query実行         │     (結果オブジェクト)
                          │ - Start (条件付き)  │
                          └─────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Copy-DbaDataCollector.ps1 | `public/Copy-DbaDataCollector.ps1` | ソース | メイン関数定義 |
| Start-DbaMigration.ps1 | `public/Start-DbaMigration.ps1` | ソース | 全体マイグレーション（呼び出し元） |
