# 機能設計書 393-Get-DbaPfDataCollectorSet

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `Get-DbaPfDataCollectorSet` 関数の機能設計を記述する。この関数は、Windows Performance Monitor Data Collector Setsの詳細情報を取得するための機能を提供する。

### 本機能の処理概要

`Get-DbaPfDataCollectorSet` は、Windows Performance Monitor Data Collector Setsの詳細情報を取得する機能である。Data Collector Setsは、SQL Serverのモニタリングとトラブルシューティングに使用されるパフォーマンスカウンターの収集設定を定義する。この関数は、既存のCollector Setsをインベントリし、状態（実行中、停止、スケジュール済み）を確認し、出力場所やスケジュールを含む構成をレビューするのに役立つ。

**業務上の目的・背景**：SQL Server環境を引き継いだ際や、既存のパフォーマンスモニタリング設定を監査する際に、どのようなData Collector Setsが構成されているかを把握する必要がある。本機能により、DBAは複数のSQL Serverホストにわたってパフォーマンスモニタリング構成を効率的に確認できる。

**機能の利用シーン**：
- 既存のパフォーマンスモニタリング設定のインベントリ作成
- Data Collector Setsの状態（Running, Stopped, Ready等）確認
- 出力ファイルの保存場所とスケジュール設定の確認
- 複数サーバー間でのモニタリング構成の比較

**主要な処理内容**：
1. 指定されたコンピューターに接続し、Task Schedulerサービスを通じてPLAタスクを取得
2. Pla.DataCollectorSet COMオブジェクトを使用してCollector Set構成をクエリ
3. 状態、出力場所、スケジュール設定を含む詳細情報を取得
4. 構造化されたオブジェクトとしてパイプラインに出力

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

**権限による制御**：ローカルコンピューターでの実行には管理者権限が推奨。リモートコンピューターへのアクセスにはWMI/CIM権限およびTask Schedulerへのアクセス権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | PowerShellコンソール | 主画面 | コマンドライン実行 |
| N/A | Windows Performance Monitor | 参照画面 | Data Collector Set構成確認 |
| N/A | Task Scheduler | 参照画面 | PLAタスク確認 |

## 機能種別

データ取得処理 (Read-Only)

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | DbaInstance[] | No | Data Collector Setsをインベントリするコンピューター名 | ValueFromPipeline、デフォルト: $env:COMPUTERNAME |
| Credential | PSCredential | No | 代替資格情報 | Get-Credentialで生成 |
| CollectorSet | string[] | No | 特定のData Collector Set名でフィルタリング | エイリアス: DataCollectorSet |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- Windows Task Scheduler (Microsoft\Windows\PLA フォルダー)
- Windows Performance Logs and Alerts (PLA) サービス

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピューター名 |
| Name | string | Data Collector Set名 |
| DisplayName | string | 表示名 |
| Description | string | 説明 |
| State | string | 状態 (Unknown/Disabled/Queued/Ready/Running) |
| Duration | int | 実行期間（秒） |
| OutputLocation | string | 出力ファイルパス |
| LatestOutputLocation | string | 最新出力ファイルパス |
| RemoteOutputLocation | string | リモートUNCパス |
| RemoteLatestOutputLocation | string | リモート最新出力UNCパス |
| RootPath | string | ルートディレクトリパス |
| SchedulesEnabled | bool | スケジュール有効フラグ |
| Segment | bool | セグメント構成 |
| SegmentMaxDuration | int | セグメント最大期間（秒） |
| SegmentMaxSize | int | セグメント最大サイズ（MB） |
| SerialNumber | int | シリアル番号 |
| Server | string | サーバー名 |
| StopOnCompletion | bool | 完了時停止フラグ |
| Subdirectory | string | サブディレクトリ |
| SubdirectoryFormat | int | サブディレクトリフォーマット |
| SubdirectoryFormatPattern | string | サブディレクトリパターン |
| Task | string | 関連タスク名 |
| TaskArguments | string | タスク引数 |
| TaskRunAsSelf | bool | 自身として実行フラグ |
| TaskUserTextArguments | string | ユーザーテキスト引数 |
| UserAccount | string | 実行ユーザーアカウント |
| Xml | string | XML構成（非表示） |
| Security | string | セキュリティ記述子（非表示） |
| DataCollectorSetObject | bool | オブジェクトフラグ（非表示） |
| TaskObject | object | タスクオブジェクト参照（非表示） |
| Credential | PSCredential | 使用資格情報（非表示） |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. スクリプトブロック定義
   └─ Task SchedulerとPLA COMオブジェクトを使用するリモート実行スクリプト

2. コンピューターごとの処理
   ├─ Invoke-Command2でリモート実行
   ├─ Schedule.ServiceでPLAタスクを取得
   ├─ タスクごとにPla.DataCollectorSet.Queryで詳細取得
   └─ 状態マッピング (0:Unknown, 1:Disabled, 2:Queued, 3:Ready, 4:Running)

3. 出力オブジェクト生成
   └─ Select-DefaultViewで表示プロパティを制御
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[スクリプトブロック定義]
    B --> C[ComputerNameイテレーション]
    C --> D[Invoke-Command2実行]
    D --> E[Schedule.Service接続]
    E --> F[PLAフォルダーからタスク取得]
    F --> G{CollectorSet<br>フィルター?}
    G -->|Yes| H[タスクをフィルタリング]
    G -->|No| I[全タスク処理]
    H --> I
    I --> J[Pla.DataCollectorSet.Query]
    J --> K[状態をマッピング]
    K --> L[PSCustomObject生成]
    L --> M[出力パスをUNCに変換]
    M --> N[パイプライン出力]
    N --> C
    C -->|完了| O[終了]
    D -->|エラー| P[Stop-Function]
    P --> C
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 状態マッピング | Task.Stateを文字列に変換（0:Unknown, 1:Disabled, 2:Queued, 3:Ready, 4:Running） | 常時 |
| BR-002 | UNCパス変換 | ローカルパスをリモートアクセス用UNCパスに変換 | OutputLocation存在時 |
| BR-003 | CollectorSetフィルター | CollectorSet指定時は名前でフィルタリング | CollectorSetパラメーター指定時 |

### 計算ロジック

- UNCパス変換: `\\$env:COMPUTERNAME\$dir` (ドライブレターを$記号に置換)

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

本機能はデータベース操作を行わない。Windows Performance Monitor構成のみを読み取る。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 接続エラー | リモートコンピューターへの接続失敗 | Stop-Functionで処理継続 |
| - | クエリエラー | Collector Setのクエリ失敗 | Write-Warningで警告、次のSetへ継続 |

### リトライ仕様

リトライ機能なし

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

トランザクション管理なし（読み取り専用）

## パフォーマンス要件

- リモートコンピューターへのInvoke-Command2実行時間に依存
- 多数のCollector Setsがある場合は処理時間が増加

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

- リモートアクセスには適切な資格情報が必要
- Task SchedulerとPLAサービスへのアクセス権限が必要
- Credentialオブジェクトは出力に含まれるが非表示プロパティ

## 備考

- 出力の全プロパティを表示するには `Select-Object *` を使用
- 他のDbaPfDataCollector系関数のベースとなる関数
- DataCollectorSetObjectプロパティは他の関数での型チェックに使用

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造と、COMオブジェクトから取得するプロパティを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaPfDataCollectorSet.ps1 | `public/Get-DbaPfDataCollectorSet.ps1` | 173-210行目のPSCustomObject構造を確認 |

**読解のコツ**: Pla.DataCollectorSet COMオブジェクトのプロパティをそのままPSCustomObjectにマッピングしている。状態は数値から文字列への変換が行われている（143-149行目）。

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

関数のパラメーター定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaPfDataCollectorSet.ps1 | `public/Get-DbaPfDataCollectorSet.ps1` | 103-111行目のパラメーター定義 |

**主要処理フロー**:
1. **105-106行目**: ComputerNameはValueFromPipelineをサポート
2. **108-109行目**: CollectorSetエイリアスはDataCollectorSet

#### Step 3: スクリプトブロック定義を理解する

リモート実行されるスクリプトブロックのロジックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaPfDataCollectorSet.ps1 | `public/Get-DbaPfDataCollectorSet.ps1` | 114-217行目のsetscript定義 |

**主要処理フロー**:
- **116-117行目**: Schedule.Service COMオブジェクト作成と接続
- **118行目**: Microsoft\Windows\PLAフォルダーを取得
- **121-133行目**: タスク一覧を取得（do-whileループ）
- **140行目**: Pla.DataCollectorSet COMオブジェクト作成
- **153行目**: Queryメソッドで詳細情報を取得

#### Step 4: 出力処理を理解する

データ取得後の出力処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaPfDataCollectorSet.ps1 | `public/Get-DbaPfDataCollectorSet.ps1` | 219-233行目の出力処理 |

**主要処理フロー**:
- **227-229行目**: Invoke-Command2でリモート実行
- **229行目**: Select-DefaultViewで表示プロパティを制御

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

```
Get-DbaPfDataCollectorSet
    │
    └─ Invoke-Command2 (リモート実行)
           │
           ├─ COM: Schedule.Service
           │      └─ GetFolder("Microsoft\Windows\PLA")
           │             └─ GetTasks()
           │
           └─ COM: Pla.DataCollectorSet
                  └─ Query(setname, null)
```

### データフロー図

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

ComputerName ─────▶ Invoke-Command2 ─────▶ PSCustomObject
CollectorSet              │                  - Name
Credential                │                  - State
                          ▼                  - OutputLocation
                   Schedule.Service          - SchedulesEnabled
                          │                  - Xml
                          ▼                  - DataCollectorSetObject
                   Pla.DataCollectorSet
                          │
                          ▼
                   Select-DefaultView
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaPfDataCollectorSet.ps1 | `public/Get-DbaPfDataCollectorSet.ps1` | ソース | 本機能のメイン実装 |
| Get-DbaPfDataCollector.ps1 | `public/Get-DbaPfDataCollector.ps1` | ソース | この関数の出力を消費 |
| Start-DbaPfDataCollectorSet.ps1 | `public/Start-DbaPfDataCollectorSet.ps1` | ソース | この関数の出力を消費 |
| Stop-DbaPfDataCollectorSet.ps1 | `public/Stop-DbaPfDataCollectorSet.ps1` | ソース | この関数の出力を消費 |
| Remove-DbaPfDataCollectorSet.ps1 | `public/Remove-DbaPfDataCollectorSet.ps1` | ソース | この関数の出力を消費 |
