# 画面設計書 196-パフォーマンスカウンター

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける利用可能なWindowsパフォーマンスカウンター取得機能の設計を記述する。Get-DbaPfAvailableCounter コマンドを中心に、ローカルまたはリモートマシンで利用可能なパフォーマンスカウンターを高速に取得するための機能仕様を定義する。

### 本画面の処理概要

**業務上の目的・背景**：SQL Serverのパフォーマンスモニタリングを設定する際、どのパフォーマンスカウンターが利用可能かを事前に把握する必要がある。本機能は、レジストリから直接カウンター情報を読み取ることで、従来のGet-Counter方式よりも高速にカウンター一覧を取得できる。Data Collectorや監視ソリューションのセットアップ時に、利用可能なSQL Server関連カウンターを発見するために使用される。取得したカウンターはAdd-DbaPfDataCollectorCounterにパイプラインで渡すことができ、効率的な監視設定が可能である。

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

**主要な操作・処理内容**：
1. 対象コンピュータのレジストリからパフォーマンスカウンター情報を取得
2. 数値のみのエントリを除外してカウンター名を抽出
3. Patternパラメータでワイルドカードフィルタリング
4. 各カウンターにコンピュータ名と認証情報を付加して出力

**画面遷移**：本機能から取得したカウンターを `Add-DbaPfDataCollectorCounter` にパイプラインで渡すことができる。

**権限による表示制御**：リモートコンピュータの場合、レジストリへのリモートアクセス権限が必要。通常は管理者権限が必要である。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 389 | Get-DbaPfAvailableCounter | 主機能 | 利用可能パフォーマンスカウンターの取得 |
| 386 | Add-DbaPfDataCollectorCounter | 遷移先機能 | カウンターの追加 |

## 画面種別

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

## URL/ルーティング

PowerShellコマンド: `Get-DbaPfAvailableCounter`

## 入出力項目

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| ComputerName | DbaInstance[] | No | 対象コンピュータ（デフォルト: localhost） |
| Credential | PSCredential | No | 代替認証情報 |
| Pattern | string | No | カウンター名フィルタ（ワイルドカード対応） |
| EnableException | switch | No | 例外処理を有効化 |

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

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| Name | string | パフォーマンスカウンター名 |

### 出力プロパティ（追加プロパティ - Select-Object *で表示可能）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| Credential | PSCredential | 使用した認証情報（パイプライン連携用） |

## 表示項目

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

## イベント仕様

### 1-パフォーマンスカウンター一覧取得

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

1. **beginブロック**:
   - リモート実行用のスクリプトブロックを定義
   - レジストリパス `HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib\009` からカウンター情報を取得
   - 数値のみのエントリを除外、ソート、重複排除
   - Patternのワイルドカードを正規表現に変換

2. **processブロック**:
   - 各コンピュータに対してInvoke-Command2でスクリプトブロックを実行
   - Pattern指定時は結果をフィルタリング
   - Select-DefaultViewでCredentialプロパティを除外して出力

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

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

本機能はWindowsレジストリからの読み取りのみであり、データベースアクセスは行わない。

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| MSG001 | Error | Failure | リモートコンピュータへの接続失敗時 |

## 例外処理

| 例外種別 | 発生条件 | 処理内容 |
|---------|---------|---------|
| 接続エラー | リモートコンピュータへ接続できない場合 | Stop-Functionでエラー出力、処理続行 |
| 権限エラー | レジストリへのアクセス権限がない場合 | 接続時にエラーとなる |

## 備考

- レジストリベースの高速な取得方式を使用（従来のGet-Counterより高速）
- Daniel Streefkerkの手法を採用
- Patternパラメータはワイルドカード（*、?）をサポートし、内部で正規表現に変換
- 取得したカウンターはAdd-DbaPfDataCollectorCounterにパイプラインで渡せる
- Credentialプロパティは他のdbatools関数へのパイプライン連携用

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造を理解することが重要である。

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

**読解のコツ**: 出力にCredentialが含まれるのは、Add-DbaPfDataCollectorCounterへのパイプライン連携のため。

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

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

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

**主要処理フロー**:
1. **L86-98**: beginブロックでスクリプトブロックを定義
2. **L88**: レジストリパスからカウンター情報を取得
3. **L89**: 数値のみのエントリを除外、ソート、重複排除
4. **L100-101**: Patternのワイルドカードを正規表現に変換

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

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

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

**主要処理フロー**:
- **L106-115**: 各コンピュータに対してスクリプトブロックを実行
- **L109-111**: Pattern指定時はフィルタリング
- **L113-114**: Pattern未指定時は全カウンターを出力

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

```
Get-DbaPfAvailableCounter
    |
    +-- ScriptBlock定義 (beginブロック)
    |       |
    |       +-- Get-ItemProperty (レジストリ読み取り)
    |       |       └-- HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Perflib\009
    |       |
    |       +-- Where-Object
    |       |       └-- 数値のみエントリを除外
    |       |
    |       +-- Sort-Object | Get-Unique
    |       |       └-- ソート・重複排除
    |       |
    |       └-- PSCustomObject作成
    |               └-- ComputerName, Name, Credential
    |
    +-- Pattern変換
    |       └-- ワイルドカード → 正規表現
    |
    +-- foreach (ComputerName)
    |       |
    |       +-- Invoke-Command2
    |       |       └-- スクリプトブロック実行
    |       |
    |       +-- Where-Object Name -match $pattern
    |       |       └-- パターンフィルタリング
    |       |
    |       └-- Select-DefaultView
    |               └-- Credentialを除外して出力
    |
    └-- Stop-Function (エラー時)
            └-- エラー出力・処理続行
```

### データフロー図

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

ComputerName ────────┐
(デフォルト:         │
 localhost)          │    ┌─────────────────────┐
                     │    │ レジストリ読み取り   │
Credential ──────────┼───►│ Perflib\009         │
                     │    │ Counter プロパティ  │
Pattern ─────────────┘    └──────────┬──────────┘
                                     │
                                     ▼
                          ┌─────────────────────┐
                          │ フィルタリング       │
                          │ - 数値除外          │
                          │ - ソート・重複排除  │
                          │ - Patternマッチ     │
                          └──────────┬──────────┘
                                     │
                                     ▼
                          ┌─────────────────────┐
                          │ オブジェクト作成     │──►  PSCustomObject[]
                          │ - ComputerName      │     (カウンター一覧)
                          │ - Name              │
                          │ - Credential        │
                          └─────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaPfAvailableCounter.ps1 | `public/Get-DbaPfAvailableCounter.ps1` | ソース | メイン関数定義 |
| Add-DbaPfDataCollectorCounter.ps1 | `public/Add-DbaPfDataCollectorCounter.ps1` | ソース | カウンター追加関数（パイプライン連携先） |
| Get-DbaPfDataCollectorSet.ps1 | `public/Get-DbaPfDataCollectorSet.ps1` | ソース | Data Collectorセット取得関数 |
