# 機能設計書 395-Import-DbaPfDataCollectorSetTemplate

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `Import-DbaPfDataCollectorSetTemplate` 関数の機能設計を記述する。この関数は、事前定義されたテンプレートからSQL Server固有のパフォーマンスカウンターを含むWindows Performance Monitor Data Collector Setsを作成するための機能を提供する。

### 本機能の処理概要

`Import-DbaPfDataCollectorSetTemplate` は、XMLテンプレートを使用してWindows Performance Monitor Data Collector Setsを作成する機能である。Performance Monitor GUIで数十のパフォーマンスカウンターを手動構成する必要を排除し、dbatools組み込みテンプレート（'Long Running Query'や'db_ola_health'など）またはカスタムXMLテンプレートファイルからCollector Setsを展開できる。

**業務上の目的・背景**：SQL Serverのパフォーマンスモニタリング設定は複雑で時間がかかる作業である。本機能により、DBAは検証済みのテンプレートを使用して迅速かつ一貫性のあるパフォーマンスモニタリング環境を構築できる。ターゲットマシン上で検出されたすべてのSQL Serverインスタンスに対して自動的にカウンターが構成される。

**機能の利用シーン**：
- SQL Serverパフォーマンスモニタリングの初期セットアップ
- 複数サーバーへの標準化されたモニタリング構成の展開
- 既存のCollector Set構成の更新または再作成
- カスタムテンプレートによる特定用途向けモニタリング設定

**主要な処理内容**：
1. テンプレートXMLファイルの読み込みと変数置換
2. Pla.DataCollectorSet COMオブジェクトを使用したCollector Set作成/更新
3. ターゲットマシン上のSQL Serverインスタンス検出
4. 検出された各インスタンス用にカウンターを自動複製

**関連システム・外部連携**：Windows Performance Logs and Alerts (Pla.DataCollectorSet COM) サービスと連携する。SQLサービスを検索してインスタンス名を検出する。

**権限による制御**：ターゲットコンピューターへのローカル管理者権限が必要。リモートコンピューターへのアクセスにはWMI/CIM権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | PowerShellコンソール | 主画面 | コマンドライン実行 |
| N/A | Windows Performance Monitor | 結果表示画面 | 作成されたCollector Set確認 |

## 機能種別

データ作成/更新処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | DbaInstanceParameter[] | No | Data Collector Setを作成するコンピューター名 | ValueFromPipeline、デフォルト: $env:COMPUTERNAME |
| Credential | PSCredential | No | 代替資格情報 | - |
| DisplayName | string | No | Collector Setの表示名 | デフォルト: テンプレート名 |
| SchedulesEnabled | switch | No | スケジュール有効化 | - |
| RootPath | string | No | ログファイルのベースディレクトリ | デフォルト: %systemdrive%\PerfLogs\Admin\[Name] |
| Segment | switch | No | ログファイルセグメンテーション有効化 | - |
| SegmentMaxDuration | int | No | セグメント最大期間（秒） | - |
| SegmentMaxSize | int | No | セグメント最大サイズ（バイト） | - |
| Subdirectory | string | No | サブディレクトリ名 | - |
| SubdirectoryFormat | int | No | サブディレクトリフォーマット | デフォルト: 3 |
| SubdirectoryFormatPattern | string | No | サブディレクトリパターン | デフォルト: yyyyMMdd\-NNNNNN |
| Task | string | No | 関連タスク名 | - |
| TaskRunAsSelf | switch | No | 自身として実行 | - |
| TaskArguments | string | No | タスク引数 | - |
| TaskUserTextArguments | string | No | ユーザーテキスト引数 | - |
| StopOnCompletion | switch | No | 完了時停止 | - |
| Path | string[] | No | カスタムテンプレートファイルパス | ValueFromPipelineByPropertyName、エイリアス: FullName |
| Template | string[] | No | dbatools組み込みテンプレート名 | タブ補完サポート |
| Instance | string[] | No | 追加のSQL Serverインスタンス名 | - |
| WhatIf | switch | No | 実行シミュレーション | - |
| Confirm | switch | No | 確認プロンプト | ConfirmImpact: Low |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- dbatools組み込みテンプレートディレクトリ: `$script:PSModuleRoot\bin\perfmontemplates\collectorsets`
- カスタムXMLテンプレートファイル
- Get-DbaPfDataCollectorSetTemplateからのパイプライン入力

## 出力仕様

### 出力データ

Get-DbaPfDataCollectorSetと同じ構造のオブジェクトを返す。

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピューター名 |
| Name | string | Data Collector Set名 |
| DisplayName | string | 表示名 |
| Description | string | 説明 |
| State | string | 状態 |
| OutputLocation | string | 出力場所 |
| ... | ... | Get-DbaPfDataCollectorSetと同等のプロパティ |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. 入力検証
   └─ PathまたはTemplateのいずれかが必要

2. テンプレートファイル準備
   ├─ Template指定時: 組み込みディレクトリからパス解決
   └─ Path指定時: 指定パスを使用

3. テンプレート内容の加工
   ├─ XMLファイル読み込み
   ├─ 変数置換（RootPath, DisplayName, SchedulesEnabled等）
   └─ 一時ファイルに保存

4. SQL Serverインスタンス検出
   └─ Invoke-Command2でリモートのSQL Serviceを検索

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

6. インスタンス用カウンター追加
   ├─ 既存のSQLカウンターを検出
   ├─ インスタンス名でカウンターパスを変換
   └─ Add-DbaPfDataCollectorCounterで追加

7. 結果出力
   └─ Get-DbaPfDataCollectorSetで最新状態を取得
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Path/Template<br>指定?}
    B -->|No| C[Stop-Function]
    B -->|Yes| D[テンプレートパス解決]
    D --> E[XMLファイル読み込み]
    E --> F[変数置換処理]
    F --> G[一時ファイル保存]
    G --> H[SQL Serverインスタンス検出]
    H --> I{Collector Set<br>存在?}
    I -->|Yes| J[ShouldProcess: 更新確認]
    I -->|No| K[ShouldProcess: 作成確認]
    J --> L[SetXml + Commit]
    K --> L
    L --> M{インスタンス<br>あり?}
    M -->|Yes| N[カウンター複製処理]
    M -->|No| O[Get-DbaPfDataCollectorSet]
    N --> O
    O --> P[パイプライン出力]
    P --> Q[終了]
    C --> Q
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | パラメーター排他 | PathまたはTemplateのいずれかが必須 | 常時 |
| BR-002 | 複数指定制限 | 複数ファイル/テンプレート時はDisplayName指定不可 | Path.Count > 1 または Template.Count > 1 |
| BR-003 | DisplayNameデフォルト | 未指定時はファイルのBaseNameを使用 | DisplayName未指定時 |
| BR-004 | インスタンスカウンター複製 | SQLServer:xxx形式をMSSQL$instance:xxxに変換 | 名前付きインスタンス存在時 |
| BR-005 | 既存Set更新 | 同名のCollector Setが存在する場合は更新 | ShouldProcess確認後 |

### 計算ロジック

- カウンターパス変換: `\SQLServer:xxx` → `\MSSQL$instance:xxx`

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 入力エラー | PathもTemplateも未指定 | Stop-Functionでエラーメッセージ |
| - | 入力エラー | 複数指定時にDisplayName指定 | Stop-Functionでエラーメッセージ |
| - | テンプレートエラー | テンプレートファイルが存在しない | Stop-Function -Continueで次へ |
| - | XML解析エラー | テンプレートが不正なXML | Stop-Function -Continueで次へ |
| - | 権限エラー | 管理者権限不足 | Test-ElevationRequirementで確認 |

### リトライ仕様

リトライ機能なし

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

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

## パフォーマンス要件

- リモートコンピューターへのInvoke-Command2実行時間に依存
- インスタンス数に応じてカウンター追加時間が増加

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

- ターゲットコンピューターへの管理者権限が必要
- Test-ElevationRequirementで権限チェックを実施
- Credentialオブジェクトは安全に処理される

## 備考

- SupportsShouldProcess対応（-WhatIf, -Confirm）
- 既存のCollector Setが存在する場合は更新確認ダイアログを表示
- 一時ファイルは処理完了後に削除される

---

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

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

### 推奨読解順序

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

入力テンプレートXMLと出力オブジェクトの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Import-DbaPfDataCollectorSetTemplate.ps1 | `public/Import-DbaPfDataCollectorSetTemplate.ps1` | 274行目のreplacementsで置換される変数を確認 |

**読解のコツ**: テンプレートXML内の`<RootPath></RootPath>`などの空タグがパラメーター値で置換される仕組みを理解する。

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

パラメーター定義と入力検証を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Import-DbaPfDataCollectorSetTemplate.ps1 | `public/Import-DbaPfDataCollectorSetTemplate.ps1` | 185-210行目のパラメーター定義、231-237行目の入力検証 |

**主要処理フロー**:
1. **185-210行目**: 多数のパラメーター定義（SupportsShouldProcess対応）
2. **231-233行目**: PathまたはTemplateの必須チェック
3. **235-237行目**: 複数指定時のDisplayName制限チェック

#### Step 3: テンプレート処理を理解する

テンプレートの読み込みと変数置換処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Import-DbaPfDataCollectorSetTemplate.ps1 | `public/Import-DbaPfDataCollectorSetTemplate.ps1` | 265-296行目のテンプレート処理 |

**主要処理フロー**:
- **271行目**: Get-Contentでテンプレート読み込み
- **274行目**: 置換対象変数のリスト定義
- **276-287行目**: 各変数の値を置換
- **290-291行目**: 一時ファイルに保存

#### Step 4: Collector Set作成処理を理解する

COMオブジェクトを使用したCollector Set作成を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Import-DbaPfDataCollectorSetTemplate.ps1 | `public/Import-DbaPfDataCollectorSetTemplate.ps1` | 215-221行目のsetscript、310-329行目の実行処理 |

**主要処理フロー**:
- **217行目**: Pla.DataCollectorSet COMオブジェクト作成
- **218行目**: SetXmlでテンプレートを設定
- **219行目**: Commitで保存（0x0003 = add or modify）

#### Step 5: インスタンスカウンター追加を理解する

SQL Serverインスタンス用カウンター複製を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | Import-DbaPfDataCollectorSetTemplate.ps1 | `public/Import-DbaPfDataCollectorSetTemplate.ps1` | 331-353行目のカウンター複製処理 |

**主要処理フロー**:
- **334行目**: 既存のSQLカウンターを検索
- **337-344行目**: SQLServer:xxx → MSSQL$instance:xxxに変換
- **351行目**: Add-DbaPfDataCollectorCounterで追加

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

```
Import-DbaPfDataCollectorSetTemplate
    │
    ├─ Test-ElevationRequirement (権限チェック)
    │
    ├─ Invoke-Command2 (インスタンス検出)
    │      └─ Get-Service -DisplayName *sql*
    │
    ├─ Invoke-Command2 (Collector Set作成)
    │      └─ COM: Pla.DataCollectorSet
    │             ├─ SetXml()
    │             └─ Commit()
    │
    ├─ Get-DbaPfDataCollectorSet (既存チェック・結果取得)
    │
    ├─ Get-DbaPfDataCollector (カウンター取得)
    │
    ├─ Get-DbaPfDataCollectorCounter (SQLカウンター検索)
    │
    └─ Add-DbaPfDataCollectorCounter (インスタンスカウンター追加)
```

### データフロー図

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

Template/Path ─────▶ テンプレート読み込み ─────▶ PSCustomObject
DisplayName                    │                    (Get-DbaPfDataCollectorSet
RootPath                       ▼                     と同じ構造)
Instance          変数置換 + 一時ファイル作成
                               │
                               ▼
                    Pla.DataCollectorSet.Commit()
                               │
                               ▼
                    インスタンスカウンター追加
                               │
                               ▼
                    Get-DbaPfDataCollectorSet
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Import-DbaPfDataCollectorSetTemplate.ps1 | `public/Import-DbaPfDataCollectorSetTemplate.ps1` | ソース | 本機能のメイン実装 |
| Get-DbaPfDataCollectorSetTemplate.ps1 | `public/Get-DbaPfDataCollectorSetTemplate.ps1` | ソース | テンプレート情報取得（パイプライン入力元） |
| Get-DbaPfDataCollectorSet.ps1 | `public/Get-DbaPfDataCollectorSet.ps1` | ソース | 作成結果の取得 |
| Add-DbaPfDataCollectorCounter.ps1 | `public/Add-DbaPfDataCollectorCounter.ps1` | ソース | インスタンスカウンター追加 |
| *.xml | `bin/perfmontemplates/collectorsets/*.xml` | テンプレート | 組み込みテンプレート |
