# 機能設計書 399-Start-DbaPfDataCollectorSet

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `Start-DbaPfDataCollectorSet` 関数の機能設計を記述する。この関数は、ローカルまたはリモートコンピューター上のWindows Performance Monitor Data Collector Setsを開始するための機能を提供する。

### 本機能の処理概要

`Start-DbaPfDataCollectorSet` は、システムパフォーマンスデータを収集するために構成されたPerformance Monitor Data Collector Setsを開始する機能である。SQL Serverのパフォーマンストラブルシューティングにおいて、CPU、メモリ、ディスクI/O、ネットワーク統計などのOS レベルのメトリクスを収集する必要がある場合に使用される。

**業務上の目的・背景**：SQL Serverのパフォーマンス問題を診断する際、データベースレベルのメトリクスだけでなく、OSレベルのパフォーマンスカウンターも重要である。本機能により、DBAは事前に構成されたData Collector Setsを迅速に開始し、トラブルシューティングセッションを開始できる。

**機能の利用シーン**：
- パフォーマンストラブルシューティングセッションの開始
- ベースラインデータ収集の開始
- スケジュールされていないオンデマンドモニタリング
- 複数サーバーでの一斉データ収集開始

**主要な処理内容**：
1. Get-DbaPfDataCollectorSetでCollector Set情報を取得
2. Collector Setの状態確認（既に実行中またはDisabledは開始不可）
3. Pla.DataCollectorSet.Start()で開始実行

**関連システム・外部連携**：Windows Performance Logs and Alerts (Pla.DataCollectorSet COM) サービスと連携する。

**権限による制御**：ターゲットコンピューターへの管理者権限が推奨。リモートコンピューターへのアクセスにはWMI/CIM権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | PowerShellコンソール | 主画面 | コマンドライン実行 |
| N/A | Windows Performance Monitor | 参照画面 | 開始結果確認 |

## 機能種別

制御処理（状態変更）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | DbaInstance[] | No | Data Collector Setsを開始するコンピューター名 | デフォルト: $env:COMPUTERNAME |
| Credential | PSCredential | No | 代替資格情報 | - |
| CollectorSet | string[] | No | 開始対象のData Collector Set名 | エイリアス: DataCollectorSet |
| InputObject | object[] | No | Get-DbaPfDataCollectorSetからのパイプライン入力 | ValueFromPipeline |
| NoWait | switch | No | 開始完了を待たずに戻る | - |
| WhatIf | switch | No | 実行シミュレーション | - |
| Confirm | switch | No | 確認プロンプト | - |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- Get-DbaPfDataCollectorSetからのパイプライン入力
- 直接指定のCollector Set名

## 出力仕様

### 出力データ

Get-DbaPfDataCollectorSetと同じ構造のオブジェクトを返す。

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピューター名 |
| Name | string | Data Collector Set名 |
| State | string | 状態（開始後は"Running"） |
| ... | ... | Get-DbaPfDataCollectorSetと同等のプロパティ |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. NoWait処理
   └─ NoWait == $falseの場合、$wait = $true

2. InputObject/Collector Set情報の取得
   └─ InputObject未指定時はGet-DbaPfDataCollectorSetを呼び出し

3. InputObject型の検証
   └─ DataCollectorSetObjectプロパティの存在確認

4. Collector Setごとの処理
   ├─ ShouldProcess確認
   ├─ 状態確認（RunningまたはDisabledは開始不可）
   └─ Pla.DataCollectorSet.Start()実行

5. 結果出力
   └─ Get-DbaPfDataCollectorSetで最新状態を取得して返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[NoWait処理]
    B --> C{InputObject指定?}
    C -->|No| D[Get-DbaPfDataCollectorSet呼び出し]
    C -->|Yes| E{型チェック}
    D --> E
    E -->|不正| F[Stop-Function]
    E -->|正常| G[Collector Setループ]
    G --> H{ShouldProcess<br>確認?}
    H -->|No| I[スキップ]
    H -->|Yes| J{State ==<br>Running?}
    J -->|Yes| K[Stop-Function: 既に実行中]
    J -->|No| L{State ==<br>Disabled?}
    L -->|Yes| M[Stop-Function: 無効]
    L -->|No| N[Start実行]
    K --> G
    M --> G
    N --> O[Get-DbaPfDataCollectorSet]
    O --> P[パイプライン出力]
    I --> G
    P --> G
    G -->|完了| Q[終了]
    F --> Q
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 実行中Set開始禁止 | StateがRunningのCollector Setは開始不可 | State == "Running" |
| BR-002 | 無効Set開始禁止 | StateがDisabledのCollector Setは開始不可 | State == "Disabled" |
| BR-003 | 型検証 | InputObjectはGet-DbaPfDataCollectorSetからの出力であること | InputObject指定時 |
| BR-004 | 待機制御 | NoWait未指定時は開始完了まで待機 | NoWait未指定時 |

### 計算ロジック

特になし

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

本機能はデータベース操作を行わない。Windows Performance Monitor Data Collector Setを開始する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 型エラー | InputObjectがGet-DbaPfDataCollectorSetからの出力でない | Stop-Functionでエラー |
| - | 状態エラー | Collector SetがRunning状態 | Stop-Function -Continue |
| - | 状態エラー | Collector SetがDisabled状態 | Stop-Function -Continue |
| - | 開始エラー | Start()メソッドの実行失敗 | Stop-Function -Continue |

### リトライ仕様

リトライ機能なし

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

トランザクション管理なし。Pla.DataCollectorSet.Start()で即座に開始。

## パフォーマンス要件

- NoWait未指定時は開始完了まで待機
- 大量のカウンターを持つCollector Setの開始には時間がかかる場合がある

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

- ターゲットコンピューターへの適切な権限が必要
- リモートアクセスには資格情報が必要な場合がある

## 備考

- SupportsShouldProcess対応（-WhatIf, -Confirm）
- NoWaitスイッチで非同期開始が可能
- `Get-DbaPfDataCollectorSet | Start-DbaPfDataCollectorSet` のワークフローで使用可能

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造を理解する（Get-DbaPfDataCollectorSetと同じ）。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Start-DbaPfDataCollectorSet.ps1 | `public/Start-DbaPfDataCollectorSet.ps1` | 142行目のGet-DbaPfDataCollectorSet呼び出しを確認 |

**読解のコツ**: 開始後のCollector Set状態を取得するためGet-DbaPfDataCollectorSetを再呼び出ししている。

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

パラメーター定義とbeginブロックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Start-DbaPfDataCollectorSet.ps1 | `public/Start-DbaPfDataCollectorSet.ps1` | 86-96行目のパラメーター定義、97-105行目のbeginブロック |

**主要処理フロー**:
1. **94行目**: NoWaitスイッチでStart()の待機動作を制御
2. **98行目**: `$wait = $NoWait -eq $false` で待機フラグを設定

#### Step 3: 状態チェック処理を理解する

RunningまたはDisabled状態のチェックロジックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Start-DbaPfDataCollectorSet.ps1 | `public/Start-DbaPfDataCollectorSet.ps1` | 124-135行目の状態チェック |

**主要処理フロー**:
- **127行目**: Stateプロパティを取得
- **130-131行目**: Running状態の場合はStop-Function
- **133-134行目**: Disabled状態の場合はStop-Function

#### Step 4: 開始処理を理解する

COMオブジェクトを使用した開始処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Start-DbaPfDataCollectorSet.ps1 | `public/Start-DbaPfDataCollectorSet.ps1` | 100-105行目のsetscript、136-143行目の実行処理 |

**主要処理フロー**:
- **102行目**: Pla.DataCollectorSet COMオブジェクト作成
- **103行目**: Queryでコレクターセット取得
- **104行目**: Start($wait)で開始（待機パラメーター付き）

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

```
Start-DbaPfDataCollectorSet
    │
    ├─ Get-DbaPfDataCollectorSet (InputObject未指定時)
    │
    ├─ Invoke-Command2 (リモート実行)
    │      └─ COM: Pla.DataCollectorSet
    │             ├─ Query()
    │             └─ Start($wait)
    │
    └─ Get-DbaPfDataCollectorSet (結果取得)
```

### データフロー図

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

CollectorSet ─────▶ Get-DbaPfDataCollectorSet ─▶ PSCustomObject
ComputerName                   │                    (開始後の状態)
Credential                     ▼
InputObject         状態チェック
NoWait                  │
                        ▼
            Pla.DataCollectorSet.Start()
                        │
                        ▼
            Get-DbaPfDataCollectorSet (結果)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Start-DbaPfDataCollectorSet.ps1 | `public/Start-DbaPfDataCollectorSet.ps1` | ソース | 本機能のメイン実装 |
| Get-DbaPfDataCollectorSet.ps1 | `public/Get-DbaPfDataCollectorSet.ps1` | ソース | Collector Set情報取得 |
| Stop-DbaPfDataCollectorSet.ps1 | `public/Stop-DbaPfDataCollectorSet.ps1` | ソース | 逆操作（停止） |
