# 画面設計書 197-データコレクターセット

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるWindowsパフォーマンスモニターData Collectorセット取得機能の設計を記述する。Get-DbaPfDataCollectorSet コマンドを中心に、SQL Serverの監視とトラブルシューティングに使用されるData Collectorセットの構成詳細を取得するための機能仕様を定義する。

### 本画面の処理概要

**業務上の目的・背景**：Data Collectorセットは、SQL Serverのパフォーマンスカウンター収集を定義するWindowsパフォーマンスモニターの構成単位である。収集対象のカウンター、収集タイミング、出力先などを定義する。本機能により、既存のData Collectorセットの棚卸し、実行状態の確認、構成の監査が可能になる。SQL Server環境を継承した際の監視設定の把握や、パフォーマンスベースライン収集の確認に有用である。

**画面へのアクセス方法**：PowerShellコマンドラインから `Get-DbaPfDataCollectorSet` コマンドを実行することでアクセスする。

**主要な操作・処理内容**：
1. WindowsタスクスケジューラのPLAフォルダからData Collectorセット情報を取得
2. Pla.DataCollectorSet COMオブジェクトを使用して詳細構成を取得
3. 各セットの状態（Unknown/Disabled/Queued/Ready/Running）を判定
4. 出力パスをリモートアクセス用UNCパスに変換

**画面遷移**：本機能は `Get-DbaPfDataCollector`、`Start-DbaPfDataCollectorSet`、`Stop-DbaPfDataCollectorSet`、`Remove-DbaPfDataCollectorSet` の基盤として使用される。

**権限による表示制御**：Windowsのパフォーマンスモニター情報へのアクセス権限が必要。通常は管理者権限が必要である。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 393 | Get-DbaPfDataCollectorSet | 主機能 | データコレクターセットの取得 |
| 398 | Remove-DbaPfDataCollectorSet | 補助機能 | データコレクターセットの削除 |
| 399 | Start-DbaPfDataCollectorSet | 補助機能 | データコレクターセットの開始 |
| 400 | Stop-DbaPfDataCollectorSet | 補助機能 | データコレクターセットの停止 |
| 390 | Get-DbaPfDataCollector | 遷移先機能 | データコレクターの取得 |

## 画面種別

一覧（コマンドライン出力）

## URL/ルーティング

PowerShellコマンド: `Get-DbaPfDataCollectorSet`

## 入出力項目

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| ComputerName | DbaInstance[] | No | 対象コンピュータ（デフォルト: localhost） |
| Credential | PSCredential | No | 代替認証情報 |
| CollectorSet | string[] | No | 取得対象のコレクターセット名（エイリアス: DataCollectorSet） |
| EnableException | switch | No | 例外処理を有効化 |

### 出力プロパティ（デフォルト表示）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| Name | string | コレクターセット名 |
| DisplayName | string | 表示名 |
| Description | string | 説明 |
| State | string | 状態（Unknown/Disabled/Queued/Ready/Running） |
| Duration | int | 実行時間（秒） |
| OutputLocation | string | 出力先パス |
| LatestOutputLocation | string | 最新出力パス |
| RootPath | string | ルートパス |
| SchedulesEnabled | bool | スケジュール有効 |
| Segment | int | セグメント設定 |
| SegmentMaxDuration | int | セグメント最大時間 |
| SegmentMaxSize | int | セグメント最大サイズ |
| SerialNumber | int | シリアル番号 |
| Server | string | サーバー名 |
| StopOnCompletion | bool | 完了時停止 |
| Subdirectory | string | サブディレクトリ |
| SubdirectoryFormat | int | サブディレクトリ形式 |
| SubdirectoryFormatPattern | string | サブディレクトリパターン |
| Task | string | タスク名 |
| TaskArguments | string | タスク引数 |
| TaskRunAsSelf | bool | 自身として実行 |
| TaskUserTextArguments | string | ユーザーテキスト引数 |
| UserAccount | string | 実行アカウント |

### 出力プロパティ（追加プロパティ）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| Keywords | string | キーワード |
| DescriptionUnresolved | string | 未解決の説明 |
| DisplayNameUnresolved | string | 未解決の表示名 |
| Schedules | object | スケジュールコレクション |
| Xml | string | XML構成 |
| Security | string | セキュリティ記述子 |
| DataCollectorSetObject | bool | COMオブジェクトフラグ |
| TaskObject | object | タスクスケジューラオブジェクト |
| Credential | PSCredential | 認証情報 |
| RemoteOutputLocation | string | リモート出力パス（UNC） |
| RemoteLatestOutputLocation | string | リモート最新出力パス（UNC） |

## 表示項目

デフォルトビューでは24プロパティが表示される。Select-Object * でDataCollectorSetObjectを含む全プロパティにアクセス可能。

## イベント仕様

### 1-データコレクターセット一覧取得

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

1. **beginブロック**:
   - リモート実行用のスクリプトブロックを定義
   - タスクスケジューラからPLAフォルダのタスク一覧を取得
   - Pla.DataCollectorSet COMオブジェクトで詳細を取得
   - 状態コードを文字列に変換

2. **processブロック**:
   - 各コンピュータに対してInvoke-Command2でスクリプトブロックを実行
   - Select-DefaultViewでデフォルト表示プロパティを設定

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

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

本機能はWindowsパフォーマンスモニターからの読み取りのみであり、データベースアクセスは行わない。

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| MSG001 | Warning | Issue with getting Collector Set {name} on {computer} : {error} | コレクターセット取得エラー時 |
| MSG002 | Error | Failure | リモートコンピュータへの接続失敗時 |

## 例外処理

| 例外種別 | 発生条件 | 処理内容 |
|---------|---------|---------|
| 接続エラー | リモートコンピュータへ接続できない場合 | Stop-Functionでエラー出力、処理続行 |
| COMエラー | COMオブジェクト作成失敗時 | 警告を出力して次のセットへ |

## 備考

- Windowsのパフォーマンスログとアラート（PLA）サービスを使用
- タスクスケジューラのMicrosoft\Windows\PLAフォルダからタスク情報を取得
- 状態コード: 0=Unknown, 1=Disabled, 2=Queued, 3=Ready, 4=Running
- COMオブジェクト（Pla.DataCollectorSet、Schedule.Service）を使用
- 出力オブジェクトはDataCollectorSetObjectプロパティでCOMオブジェクト識別可能

---

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

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

### 推奨読解順序

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

Data Collectorセットオブジェクトの構造を理解することが重要である。

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

**読解のコツ**: DataCollectorSetObjectプロパティはパイプライン連携で他のdbatools関数が入力を識別するために使用される。

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

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

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

**主要処理フロー**:
1. **L114-217**: beginブロックでスクリプトブロックを定義
2. **L116-133**: タスクスケジューラからPLAフォルダのタスク一覧を取得
3. **L140-149**: 状態コードを文字列に変換
4. **L151-216**: Pla.DataCollectorSet COMオブジェクトで詳細取得

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

データコレクターセットの取得・出力処理を理解する。

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

**主要処理フロー**:
- **L227-230**: 各コンピュータに対してスクリプトブロックを実行
- **L229**: Select-DefaultViewでデフォルト表示プロパティを設定

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

```
Get-DbaPfDataCollectorSet
    |
    +-- ScriptBlock定義 (beginブロック)
    |       |
    |       +-- New-Object Schedule.Service
    |       |       └-- タスクスケジューラ接続
    |       |
    |       +-- GetFolder("Microsoft\Windows\PLA")
    |       |       └-- PLAフォルダ取得
    |       |
    |       +-- GetTasks
    |       |       └-- タスク一覧取得
    |       |
    |       +-- 状態コード変換
    |       |       └-- 0-4 → 文字列
    |       |
    |       +-- New-Object Pla.DataCollectorSet
    |       |       └-- COMオブジェクト作成
    |       |
    |       +-- Query(setname)
    |       |       └-- 詳細構成取得
    |       |
    |       └-- PSCustomObject作成
    |               └-- 全プロパティ設定
    |
    +-- foreach (ComputerName)
    |       |
    |       +-- Invoke-Command2
    |       |       └-- スクリプトブロック実行
    |       |
    |       └-- Select-DefaultView
    |               └-- デフォルト表示設定
    |
    └-- Stop-Function (エラー時)
            └-- エラー出力・処理続行
```

### データフロー図

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

ComputerName ────────┐
                     │    ┌─────────────────────┐
Credential ──────────┼───►│ タスクスケジューラ  │
                     │    │ PLAフォルダ取得     │
CollectorSet ────────┘    └──────────┬──────────┘
                                     │
                                     ▼
                          ┌─────────────────────┐
                          │ Pla.DataCollectorSet│
                          │ COMオブジェクト     │
                          │ Query実行           │
                          └──────────┬──────────┘
                                     │
                                     ▼
                          ┌─────────────────────┐
                          │ プロパティ抽出       │
                          │ - 状態変換          │──►  PSCustomObject[]
                          │ - UNCパス変換       │     (コレクターセット)
                          │ - XML構成取得       │
                          └─────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| 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` | ソース | コレクターセット削除関数 |
