# 画面設計書 200-データコレクターカウンター

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるWindowsパフォーマンスモニターData Collectorカウンター取得機能の設計を記述する。Get-DbaPfDataCollectorCounter コマンドを中心に、Data Collector内で収集設定されているパフォーマンスカウンターの一覧を取得するための機能仕様を定義する。

### 本画面の処理概要

**業務上の目的・背景**：パフォーマンスモニタリング構成の監査において、どのカウンターが実際に収集されているかを把握することは重要である。本機能により、Data Collector内に設定されているすべてのパフォーマンスカウンターを確認できる。SQL Serverの監視設定のトラブルシューティング、カウンター構成の検証、監視ギャップの特定に有用である。特定のカウンター（例：\SQLServer:Buffer Manager\Page life expectancy）が監視対象に含まれているかを確認する際に使用される。

**画面へのアクセス方法**：PowerShellコマンドラインから `Get-DbaPfDataCollectorCounter` コマンドを実行することでアクセスする。`Get-DbaPfDataCollector` からパイプライン入力を受け取ることも可能。

**主要な操作・処理内容**：
1. Data Collectorオブジェクトからカウンター一覧を抽出
2. 各カウンターをPSCustomObjectとして出力
3. Counterパラメータで特定のカウンターをフィルタリング
4. DataCollectorSetXmlを含めて詳細情報を保持

**画面遷移**：本機能は `Get-DbaPfDataCollector` の出力を入力として受け取る。取得したカウンター情報は `Remove-DbaPfDataCollectorCounter` で削除操作に使用可能。

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 391 | Get-DbaPfDataCollectorCounter | 主機能 | データコレクターカウンターの取得 |
| 386 | Add-DbaPfDataCollectorCounter | 主機能 | カウンターの追加 |
| 397 | Remove-DbaPfDataCollectorCounter | 主機能 | カウンターの削除 |
| 392 | Get-DbaPfDataCollectorCounterSample | 補助機能 | カウンターサンプルの取得 |
| 390 | Get-DbaPfDataCollector | 補助機能 | データコレクターの取得（入力元） |

## 画面種別

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

## URL/ルーティング

PowerShellコマンド: `Get-DbaPfDataCollectorCounter`

## 入出力項目

### 入力パラメータ

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

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

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| DataCollectorSet | string | 親コレクターセット名 |
| DataCollector | string | 親コレクター名 |
| Name | string | カウンターパス（例: \Processor(_Total)\% Processor Time） |
| FileName | string | 出力ファイル名 |

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

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| DataCollectorSetXml | string | 親セットのXML構成 |
| CounterObject | bool | オブジェクト識別フラグ |
| Credential | PSCredential | 認証情報 |

## 表示項目

デフォルトビューでは以下のプロパティが表示される:
- ComputerName, DataCollectorSet, DataCollector, Name, FileName

## イベント仕様

### 1-カウンター一覧取得

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

1. **beginブロック**:
   - コメントアウトされたカラムリスト（将来使用予定）

2. **processブロック**:
   - InputObjectからCredentialを取得（未指定時）
   - InputObjectがない場合は内部でGet-DbaPfDataCollectorを呼び出し
   - InputObjectの型チェック（DataCollectorObject必須）
   - 各コレクターのCountersプロパティを展開
   - Counter指定時はカウンター名でフィルタリング
   - 各カウンターをPSCustomObjectとして出力

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

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

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

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| MSG001 | Error | InputObject is not of the right type. Please use Get-DbaPfDataCollector. | 不正な入力オブジェクト |

## 例外処理

| 例外種別 | 発生条件 | 処理内容 |
|---------|---------|---------|
| 型エラー | InputObjectがDataCollectorObjectでない場合 | Stop-Functionでエラー出力、処理中断 |

## 備考

- Data CollectorオブジェクトのCountersプロパティからカウンター一覧を取得
- カウンターパスは\Object\Counter形式（例：\Processor(_Total)\% Processor Time）
- CounterObjectプロパティでRemove-DbaPfDataCollectorCounterへのパイプライン連携時の型識別に使用
- DataCollectorSetXmlは削除操作（Remove-DbaPfDataCollectorCounter）で必要な構成情報を保持

---

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

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

### 推奨読解順序

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

カウンターオブジェクトの構造を理解することが重要である。

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

**読解のコツ**: CounterObjectプロパティは、Remove-DbaPfDataCollectorCounterがパイプライン入力を識別するために使用される。

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

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

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

**主要処理フロー**:
1. **L105-108**: beginブロック（コメントアウトされたカラムリスト）
2. **L92-104**: 7つのパラメータ定義

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

カウンターの取得・フィルタリング・出力処理を理解する。

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

**主要処理フロー**:
- **L112-114**: InputObjectからCredentialを取得
- **L116-120**: InputObjectがない場合はGet-DbaPfDataCollectorを呼び出し
- **L122-127**: InputObjectの型チェック
- **L129-143**: 各コレクターのカウンターを展開してPSCustomObject作成

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

```
Get-DbaPfDataCollectorCounter
    |
    +-- Credential取得
    |       └-- InputObject.Credentialまたはパラメータ
    |
    +-- Get-DbaPfDataCollector (InputObjectがない場合)
    |       └-- Data Collector取得
    |
    +-- 型チェック
    |       └-- DataCollectorObject必須
    |
    +-- foreach (counterobject)
    |       |
    |       +-- foreach (countername in Counters)
    |       |       |
    |       |       +-- Counterフィルタリング
    |       |       |       └-- 名前マッチング
    |       |       |
    |       |       └-- PSCustomObject作成
    |       |               └-- ComputerName, DataCollectorSet,
    |       |                   DataCollector, Name, FileName,
    |       |                   DataCollectorSetXml, CounterObject,
    |       |                   Credential
    |       |
    |       └-- Select-DefaultView
    |               └-- CounterObject, Credential等を除外
    |
    └-- Stop-Function (型エラー時)
            └-- エラー出力・処理中断
```

### データフロー図

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

ComputerName ────────┐
                     │
Credential ──────────┤    ┌─────────────────────┐
                     │    │ Get-DbaPfData       │
CollectorSet ────────┼───►│ Collector           │
                     │    │ (内部呼び出し)       │
Collector ───────────┤    └──────────┬──────────┘
                     │               │
Counter ─────────────┤               ▼
                     │    ┌─────────────────────┐
InputObject ─────────┘    │ Countersプロパティ  │
                          │ 展開                │
                          └──────────┬──────────┘
                                     │
                                     ▼
                          ┌─────────────────────┐
                          │ フィルタリング       │
                          │ - Counter名         │──►  PSCustomObject[]
                          │ - PSCustomObject作成│     (カウンター一覧)
                          └─────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaPfDataCollectorCounter.ps1 | `public/Get-DbaPfDataCollectorCounter.ps1` | ソース | メイン関数定義 |
| Get-DbaPfDataCollector.ps1 | `public/Get-DbaPfDataCollector.ps1` | ソース | 入力元：Data Collector取得関数 |
| Add-DbaPfDataCollectorCounter.ps1 | `public/Add-DbaPfDataCollectorCounter.ps1` | ソース | カウンター追加関数 |
| Remove-DbaPfDataCollectorCounter.ps1 | `public/Remove-DbaPfDataCollectorCounter.ps1` | ソース | カウンター削除関数 |
| Get-DbaPfDataCollectorCounterSample.ps1 | `public/Get-DbaPfDataCollectorCounterSample.ps1` | ソース | カウンターサンプル取得関数 |
