# 機能設計書 394-Get-DbaPfDataCollectorSetTemplate

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `Get-DbaPfDataCollectorSetTemplate` 関数の機能設計を記述する。この関数は、SQL Serverモニタリング用に設計されたWindows Performance Monitorテンプレートの情報を取得するための機能を提供する。

### 本機能の処理概要

`Get-DbaPfDataCollectorSetTemplate` は、SQL Serverパフォーマンス分析用に事前定義されたWindows Performance Monitor (PerfMon) テンプレートの情報を取得する機能である。長時間実行クエリの監視、PAL (Performance Analysis of Logs) 構成、SQL Server固有のパフォーマンスシナリオ用のカウンターセットを含むテンプレートのメタデータを解析し、名前、説明、ソース、ファイルパスなどの詳細を返す。

**業務上の目的・背景**：SQL Serverのパフォーマンスモニタリングを設定する際、どのパフォーマンスカウンターを収集すべきかを手動で決定するのは時間がかかり、専門知識が必要である。本機能により、DBAはdbatools組み込みのテンプレートを発見し、`Import-DbaPfDataCollectorSetTemplate`で展開する前に利用可能なモニタリングテンプレートを確認できる。

**機能の利用シーン**：
- 利用可能なパフォーマンスモニタリングテンプレートの発見
- テンプレートの説明と対象シナリオの確認
- カスタムテンプレートディレクトリからのテンプレート読み込み
- テンプレート選択後のImport-DbaPfDataCollectorSetTemplateへのパイプライン連携

**主要な処理内容**：
1. 指定されたディレクトリ（デフォルト: dbatools組み込みテンプレートリポジトリ）からXMLファイルを検索
2. メタデータXMLファイル (collectorsets.xml) からソース情報を読み込み
3. 各テンプレートXMLを解析し、名前、説明、ユーザーアカウント情報を抽出
4. Patternパラメーター指定時は正規表現でフィルタリング

**関連システム・外部連携**：ローカルファイルシステムのXMLテンプレートファイルを読み込む。外部システムとの連携はない。

**権限による制御**：テンプレートファイルへの読み取りアクセス権限が必要。管理者権限は不要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | PowerShellコンソール | 主画面 | コマンドライン実行 |

## 機能種別

データ取得処理 (Read-Only) / ファイル解析

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Path | string[] | No | テンプレートXMLファイルが格納されたディレクトリパス | デフォルト: $script:PSModuleRoot\bin\perfmontemplates\collectorsets |
| Pattern | string | No | テンプレート名と説明に対する正規表現フィルター | ワイルドカード(*)は.*に変換される |
| Template | string[] | No | 完全一致で取得するテンプレート名 | タブ補完サポート |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- dbatools組み込みテンプレートディレクトリ: `$script:PSModuleRoot\bin\perfmontemplates\collectorsets`
- メタデータファイル: `$script:PSModuleRoot\bin\perfmontemplates\collectorsets.xml`

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Name | string | テンプレート名 |
| Source | string | テンプレートのソース/出所 |
| UserAccount | string | テンプレート実行時のユーザーアカウント |
| Description | string | テンプレートの説明 |
| Path | FileInfo | テンプレートXMLファイルのフルパス（非表示） |
| File | string | テンプレートXMLファイル名（非表示） |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. メタデータ読み込み
   └─ collectorsets.xmlをImport-Clixmlで読み込み

2. Patternの前処理
   └─ ワイルドカード(*)を正規表現(.*)に変換

3. ディレクトリイテレーション
   ├─ 指定パスから*.xmlファイルを取得
   └─ Template指定時はBaseNameでフィルタリング

4. XMLファイル解析
   ├─ Get-ContentでXMLを読み込み
   ├─ DataCollectorSetノードを抽出
   └─ メタデータからSourceを取得

5. フィルタリングと出力
   ├─ Pattern指定時は名前/説明でマッチング
   └─ PSCustomObjectを生成してパイプライン出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[collectorsets.xml読み込み]
    B --> C[Pattern前処理]
    C --> D[ディレクトリイテレーション]
    D --> E[*.xmlファイル取得]
    E --> F{Template<br>指定?}
    F -->|Yes| G[BaseNameでフィルター]
    F -->|No| H[全ファイル処理]
    G --> H
    H --> I[XMLファイル解析]
    I --> J[DataCollectorSet抽出]
    J --> K[メタデータからSource取得]
    K --> L{Pattern<br>指定?}
    L -->|Yes| M{名前/説明<br>マッチ?}
    L -->|No| N[PSCustomObject生成]
    M -->|Yes| N
    M -->|No| H
    N --> O[パイプライン出力]
    O --> H
    H -->|完了| P[終了]
    I -->|エラー| Q[Stop-Function]
    Q --> H
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ワイルドカード変換 | Pattern内の*を.*に変換、..*は.*に正規化 | Pattern指定時 |
| BR-002 | メタデータマッチング | テンプレート名でcollectorsets.xmlからSourceを取得 | 常時 |
| BR-003 | デフォルト表示プロパティ | Path, Fileは非表示（Select-Object *で表示） | 常時 |

### 計算ロジック

特になし

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

本機能はデータベース操作を行わない。ローカルファイルシステムのみを読み取る。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | XML解析エラー | テンプレートXMLが不正な形式 | Stop-Function -Continueで次のファイルへ |

### リトライ仕様

リトライ機能なし

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

トランザクション管理なし（読み取り専用）

## パフォーマンス要件

- ファイルシステムからの読み取りのため、ディスクI/O速度に依存
- テンプレート数が少ないため処理は高速

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

- テンプレートディレクトリへの読み取り権限のみ必要
- ファイル内容の解析のみで、実行や変更は行わない

## 備考

- `Get-DbaPfDataCollectorSetTemplate | Out-GridView -PassThru | Import-DbaPfDataCollectorSetTemplate` のワークフローで使用可能
- PAL (Performance Analysis of Logs) 用テンプレートを含む
- SQL Serverバージョン別のテンプレートが利用可能

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造とメタデータファイルの形式を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaPfDataCollectorSetTemplate.ps1 | `public/Get-DbaPfDataCollectorSetTemplate.ps1` | 106-113, 116-123行目のPSCustomObject構造を確認 |

**読解のコツ**: 同じPSCustomObject構造が2箇所（Patternマッチ時と通常時）で定義されている。Select-DefaultViewでPath, Fileプロパティを除外している。

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

関数のパラメーター定義とメタデータ読み込みを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaPfDataCollectorSetTemplate.ps1 | `public/Get-DbaPfDataCollectorSetTemplate.ps1` | 70-76行目のパラメーター定義、78行目のメタデータ読み込み |

**主要処理フロー**:
1. **72行目**: Pathのデフォルト値はdbatools組み込みテンプレートディレクトリ
2. **78行目**: Import-ClixmlでXMLメタデータをオブジェクトとして読み込み
3. **80行目**: Pattern内のワイルドカードを正規表現に変換

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

XMLファイルの解析とフィルタリングロジックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaPfDataCollectorSetTemplate.ps1 | `public/Get-DbaPfDataCollectorSetTemplate.ps1` | 85-127行目のファイル処理ループ |

**主要処理フロー**:
- **86行目**: Get-ChildItemでディレクトリからXMLファイルを取得
- **88-90行目**: Template指定時のBaseNameフィルタリング
- **93-97行目**: XMLファイルの読み込みとエラーハンドリング
- **99-100行目**: DataCollectorSetノードの抽出とメタデータマッチング
- **101-114行目**: Patternマッチングとオブジェクト生成

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

```
Get-DbaPfDataCollectorSetTemplate
    │
    ├─ Import-Clixml (メタデータ読み込み)
    │      └─ collectorsets.xml
    │
    ├─ Get-ChildItem (XMLファイル取得)
    │
    ├─ Get-Content (XMLファイル読み込み)
    │      └─ [xml]キャストでXML解析
    │
    └─ Select-DefaultView (出力フォーマット)
```

### データフロー図

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

Path ─────────────────▶ Get-ChildItem ─────▶ PSCustomObject
Template                       │               - Name
Pattern                        ▼               - Source
                         Get-Content           - UserAccount
                               │               - Description
                               ▼
                         XML解析 [xml]
                               │
                               ▼
                    メタデータマッチング
                               │
                               ▼
                    Pattern フィルタリング
                               │
                               ▼
                    Select-DefaultView
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaPfDataCollectorSetTemplate.ps1 | `public/Get-DbaPfDataCollectorSetTemplate.ps1` | ソース | 本機能のメイン実装 |
| collectorsets.xml | `bin/perfmontemplates/collectorsets.xml` | メタデータ | テンプレートのソース情報 |
| *.xml | `bin/perfmontemplates/collectorsets/*.xml` | テンプレート | Performance Monitorテンプレート |
| Import-DbaPfDataCollectorSetTemplate.ps1 | `public/Import-DbaPfDataCollectorSetTemplate.ps1` | ソース | この関数の出力を消費 |
