# 機能設計書 397-Remove-DbaPfDataCollectorCounter

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `Remove-DbaPfDataCollectorCounter` 関数の機能設計を記述する。この関数は、Windows Performance Monitor Data Collector Setsから特定のパフォーマンスカウンターを削除するための機能を提供する。

### 本機能の処理概要

`Remove-DbaPfDataCollectorCounter` は、既存のData Collector Setsからパフォーマンスカウンターを削除する機能である。不要になったカウンターを削除することで、リソース消費を減らし、関連するメトリクスに集中したモニタリング構成を維持できる。トラブルシューティング用に追加されたカウンターの削除や、SQL Serverパフォーマンスモニタリング設定の微調整に使用される。

**業務上の目的・背景**：パフォーマンスモニタリングでは、問題調査のために一時的にカウンターを追加することがある。調査完了後、これらのカウンターを削除してモニタリングオーバーヘッドを削減する必要がある。本機能により、DBAはGUIを使用せずにPowerShellからカウンターを効率的に削除できる。

**機能の利用シーン**：
- トラブルシューティング完了後のカウンター削除
- モニタリング構成の最適化
- 不要なカウンターによるリソース消費の削減
- 標準化されたモニタリング構成への調整

**主要な処理内容**：
1. Get-DbaPfDataCollectorCounterでカウンター情報を取得
2. Data Collector SetのXML構成からCounterノードを削除
3. 変更されたXMLでCollector Setを更新

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

**権限による制御**：ターゲットコンピューターへの管理者権限が必要。ShouldProcess対応で確認プロンプトを表示。

## 関連画面

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

## 機能種別

データ削除処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | DbaInstance[] | No | Data Collector Setがあるコンピューター名 | デフォルト: $env:COMPUTERNAME |
| Credential | PSCredential | No | 代替資格情報 | - |
| CollectorSet | string[] | No | フィルタリング対象のData Collector Set名 | エイリアス: DataCollectorSet |
| Collector | string[] | No | フィルタリング対象のData Collector名 | エイリアス: DataCollector |
| Counter | object[] | Yes | 削除するカウンターパス | Mandatory、ValueFromPipelineByPropertyName、エイリアス: Name |
| InputObject | object[] | No | Get-DbaPfDataCollectorCounterからのパイプライン入力 | ValueFromPipeline |
| WhatIf | switch | No | 実行シミュレーション | - |
| Confirm | switch | No | 確認プロンプト | ConfirmImpact: High |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- Get-DbaPfDataCollectorCounterからのパイプライン入力
- 直接指定のカウンターパス

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピューター名 |
| DataCollectorSet | string | Data Collector Set名 |
| DataCollector | string | Data Collector名 |
| Name | string | 削除されたカウンターパス |
| Status | string | 操作状態（"Removed"） |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. InputObject/カウンター情報の取得
   ├─ パイプライン入力からCredentialを継承
   └─ InputObject未指定時はGet-DbaPfDataCollectorCounterを呼び出し

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

3. XML構成からカウンターノードを削除
   ├─ DataCollectorSetXmlを解析
   ├─ Counterノードを検索・削除
   └─ CounterDisplayNameノードも削除

4. ShouldProcess確認
   └─ ConfirmImpact: Highのため確認プロンプト

5. Collector Set更新
   ├─ Pla.DataCollectorSet.SetXml()
   └─ Pla.DataCollectorSet.Commit()

6. 結果出力
   └─ PSCustomObjectで操作結果を返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{InputObjectに<br>Credentialあり?}
    B -->|Yes| C[Credential継承]
    B -->|No| D{InputObject指定?}
    C --> D
    D -->|No| E[Get-DbaPfDataCollectorCounter呼び出し]
    D -->|Yes| F{型チェック}
    E --> F
    F -->|不正| G[Stop-Function]
    F -->|正常| H[Test-ElevationRequirement]
    H --> I[XML解析]
    I --> J[Counterノード検索]
    J --> K[ノード削除]
    K --> L[CounterDisplayNameノード削除]
    L --> M{ShouldProcess<br>確認?}
    M -->|Yes| N[SetXml + Commit]
    M -->|No| O[スキップ]
    N --> P[PSCustomObject生成]
    P --> Q[パイプライン出力]
    O --> Q
    Q --> R[終了]
    G --> R
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | Credential継承 | InputObjectにCredentialがある場合は継承 | InputObject.Credential存在かつCredential未指定 |
| BR-002 | 型検証 | InputObjectはGet-DbaPfDataCollectorCounterからの出力であること | InputObject指定時 |
| BR-003 | カウンターノード削除 | CounterとCounterDisplayNameの両方のノードを削除 | 常時 |
| BR-004 | 高確認レベル | ConfirmImpact: Highで削除前に確認 | ShouldProcess有効時 |

### 計算ロジック

特になし

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

本機能はデータベース操作を行わない。Windows Performance Monitor構成を更新する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 型エラー | InputObjectがGet-DbaPfDataCollectorCounterからの出力でない | Stop-Functionでエラー |
| - | 権限エラー | 管理者権限不足 | Test-ElevationRequirementで確認 |
| - | 更新エラー | Collector Setの更新失敗 | Stop-Function -Continueで次へ |

### リトライ仕様

リトライ機能なし

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

トランザクション管理なし。Pla.DataCollectorSet.Commit()で即座に反映。

## パフォーマンス要件

特定の要件なし

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

- ターゲットコンピューターへの管理者権限が必要
- Test-ElevationRequirementで権限チェックを実施
- ShouldProcess対応で誤削除を防止

## 備考

- SupportsShouldProcess対応（-WhatIf, -Confirm）
- ConfirmImpact: Highで高確認レベル
- Get-DbaPfDataCollectorCounter | Out-GridView -PassThru | Remove-DbaPfDataCollectorCounter のワークフローで使用可能

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Remove-DbaPfDataCollectorCounter.ps1 | `public/Remove-DbaPfDataCollectorCounter.ps1` | 144-150行目のPSCustomObject構造を確認 |

**読解のコツ**: 出力は5つのプロパティのみを持つシンプルなオブジェクト。Statusは常に"Removed"。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Remove-DbaPfDataCollectorCounter.ps1 | `public/Remove-DbaPfDataCollectorCounter.ps1` | 79-93行目のパラメーター定義 |

**主要処理フロー**:
1. **79行目**: SupportsShouldProcess, ConfirmImpact: Highの定義
2. **87-89行目**: CounterパラメーターはMandatory、ValueFromPipelineByPropertyName

#### Step 3: XMLノード削除処理を理解する

Data Collector Set XMLからカウンターを削除するロジックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Remove-DbaPfDataCollectorCounter.ps1 | `public/Remove-DbaPfDataCollectorCounter.ps1` | 129-138行目のXML操作 |

**主要処理フロー**:
- **129行目**: DataCollectorSetXmlを[xml]にキャスト
- **132-133行目**: Counterノードを検索して削除
- **134-135行目**: CounterDisplayNameノードも削除

#### Step 4: Collector Set更新処理を理解する

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Remove-DbaPfDataCollectorCounter.ps1 | `public/Remove-DbaPfDataCollectorCounter.ps1` | 95-101行目のsetscript、140-154行目の実行処理 |

**主要処理フロー**:
- **97行目**: Pla.DataCollectorSet COMオブジェクト作成
- **98行目**: SetXmlで更新されたXMLを設定
- **99行目**: Commit（0x0003 = add or modify）で保存

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

```
Remove-DbaPfDataCollectorCounter
    │
    ├─ Get-DbaPfDataCollectorCounter (InputObject未指定時)
    │      └─ Get-DbaPfDataCollector
    │             └─ Get-DbaPfDataCollectorSet
    │
    ├─ Test-ElevationRequirement (権限チェック)
    │
    └─ Invoke-Command2 (リモート実行)
           └─ COM: Pla.DataCollectorSet
                  ├─ SetXml()
                  └─ Commit()
```

### データフロー図

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

Counter ──────────▶ Get-DbaPfDataCollectorCounter ─▶ PSCustomObject
ComputerName                   │                      - ComputerName
CollectorSet                   ▼                      - DataCollectorSet
Collector         XML解析 + ノード削除                 - DataCollector
InputObject                    │                      - Name
                               ▼                      - Status ("Removed")
                    Pla.DataCollectorSet.Commit()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Remove-DbaPfDataCollectorCounter.ps1 | `public/Remove-DbaPfDataCollectorCounter.ps1` | ソース | 本機能のメイン実装 |
| Get-DbaPfDataCollectorCounter.ps1 | `public/Get-DbaPfDataCollectorCounter.ps1` | ソース | カウンター情報取得 |
| Add-DbaPfDataCollectorCounter.ps1 | `public/Add-DbaPfDataCollectorCounter.ps1` | ソース | カウンター追加（逆操作） |
