# 画面設計書 198-データコレクターセットテンプレート

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるWindowsパフォーマンスモニターテンプレート取得機能の設計を記述する。Get-DbaPfDataCollectorSetTemplate コマンドを中心に、SQL Server監視用に設計された事前定義済みパフォーマンスモニターテンプレートを取得するための機能仕様を定義する。

### 本画面の処理概要

**業務上の目的・背景**：SQL Serverのパフォーマンス監視を設定する際、適切なカウンターの選定と構成は専門知識を要する作業である。本機能は、dbatoolsリポジトリに含まれる事前定義済みのパフォーマンスモニターテンプレートを発見・取得するためのものである。Long Running Query、PAL（Performance Analysis of Logs）構成など、SQL Serverに特化したテンプレートを提供する。テンプレートを使用することで、手動でカウンターを設定することなく、実績のある監視構成を迅速に展開できる。

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

**主要な操作・処理内容**：
1. dbatoolsモジュールのテンプレートディレクトリからXMLファイルを取得
2. メタデータファイル（collectorsets.xml）からソース情報を取得
3. 各テンプレートのXMLを解析して構成情報を抽出
4. Patternパラメータでテンプレート名・説明をフィルタリング

**画面遷移**：取得したテンプレートは `Import-DbaPfDataCollectorSetTemplate` にパイプラインで渡すことで、Data Collectorセットとして展開できる。

**権限による表示制御**：テンプレートファイルへのファイルシステムアクセス権限のみ必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 394 | Get-DbaPfDataCollectorSetTemplate | 主機能 | データコレクターセットテンプレートの取得 |
| 388 | Export-DbaPfDataCollectorSetTemplate | 補助機能 | テンプレートのエクスポート |
| 395 | Import-DbaPfDataCollectorSetTemplate | 補助機能 | テンプレートのインポート |

## 画面種別

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

## URL/ルーティング

PowerShellコマンド: `Get-DbaPfDataCollectorSetTemplate`

## 入出力項目

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| Path | string[] | No | テンプレートディレクトリパス（デフォルト: dbatools組み込みリポジトリ） |
| Pattern | string | No | テンプレート名・説明のフィルタパターン（正規表現構文） |
| Template | string[] | No | 取得対象のテンプレート名 |
| EnableException | switch | No | 例外処理を有効化 |

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

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| Name | string | テンプレート名 |
| Source | string | テンプレートソース（作成元） |
| UserAccount | string | 実行アカウント |
| Description | string | 説明 |

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

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| Path | FileInfo | テンプレートファイルパス |
| File | string | テンプレートファイル名 |

## 表示項目

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

## イベント仕様

### 1-テンプレート一覧取得

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

1. **beginブロック**:
   - メタデータファイル（collectorsets.xml）を読み込み
   - Patternのワイルドカードを正規表現に変換

2. **processブロック**:
   - 指定されたディレクトリからXMLファイル一覧を取得
   - Template指定時は名前でフィルタリング
   - 各XMLファイルを解析してDataCollectorSet情報を抽出
   - Pattern指定時は名前・説明でフィルタリング
   - Select-DefaultViewでPath、Fileを除外して出力

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

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

本機能はファイルシステムからの読み取りのみであり、データベースアクセスは行わない。

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| MSG001 | Error | Failure | XMLファイル読み取りエラー時 |

## 例外処理

| 例外種別 | 発生条件 | 処理内容 |
|---------|---------|---------|
| ファイル読み取りエラー | XMLファイルが読み取れない場合 | Stop-Functionでエラー出力、処理続行 |

## 備考

- dbatoolsモジュールの`\bin\perfmontemplates\collectorsets`ディレクトリに組み込みテンプレートが格納
- メタデータは`collectorsets.xml`ファイルで管理
- Patternパラメータはワイルドカード（*）を正規表現に変換
- テンプレートはXML形式でDataCollectorSet構成を定義
- Import-DbaPfDataCollectorSetTemplateへのパイプライン連携が主な使用パターン

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: テンプレートはXML形式で定義され、DataCollectorSetの構成情報を含む。

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

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

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

**主要処理フロー**:
1. **L77-81**: beginブロックでメタデータファイルを読み込み
2. **L78**: collectorsets.xmlからImport-Clixmlでメタデータを取得
3. **L80**: Patternのワイルドカードを正規表現に変換

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

テンプレートの取得・フィルタリング・出力処理を理解する。

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

**主要処理フロー**:
- **L85-86**: ディレクトリからXMLファイル一覧を取得
- **L88-90**: Template指定時は名前でフィルタリング
- **L92-97**: 各XMLファイルを読み込み
- **L99-125**: DataCollectorSet情報を抽出してPSCustomObjectを作成

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

```
Get-DbaPfDataCollectorSetTemplate
    |
    +-- Import-Clixml (beginブロック)
    |       └-- collectorsets.xml メタデータ読み込み
    |
    +-- Pattern変換
    |       └-- ワイルドカード → 正規表現
    |
    +-- foreach (Path)
    |       |
    |       +-- Get-ChildItem
    |       |       └-- XMLファイル一覧取得
    |       |
    |       +-- Where-Object BaseName
    |       |       └-- Template名フィルタリング
    |       |
    |       +-- foreach (file)
    |               |
    |               +-- Get-Content
    |               |       └-- XMLファイル読み込み
    |               |
    |               +-- [xml]キャスト
    |               |       └-- XML解析
    |               |
    |               +-- Pattern マッチング
    |               |       └-- 名前・説明フィルタ
    |               |
    |               └-- PSCustomObject作成
    |                       └-- Name, Source, UserAccount, Description, Path, File
    |
    └-- Select-DefaultView
            └-- File, Path を除外
```

### データフロー図

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

Path ────────────────┐
(デフォルト:         │    ┌─────────────────────┐
 dbatools組み込み)   │    │ Get-ChildItem       │
                     │    │ *.xml               │
Pattern ─────────────┼───►└──────────┬──────────┘
                     │               │
Template ────────────┘               ▼
                          ┌─────────────────────┐
                          │ XML解析             │
                          │ - DataCollectorSet  │
                          │ - メタデータ結合    │
                          └──────────┬──────────┘
                                     │
                                     ▼
                          ┌─────────────────────┐
                          │ フィルタリング       │
                          │ - Template名        │──►  PSCustomObject[]
                          │ - Pattern           │     (テンプレート一覧)
                          └─────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaPfDataCollectorSetTemplate.ps1 | `public/Get-DbaPfDataCollectorSetTemplate.ps1` | ソース | メイン関数定義 |
| Import-DbaPfDataCollectorSetTemplate.ps1 | `public/Import-DbaPfDataCollectorSetTemplate.ps1` | ソース | テンプレートインポート関数 |
| Export-DbaPfDataCollectorSetTemplate.ps1 | `public/Export-DbaPfDataCollectorSetTemplate.ps1` | ソース | テンプレートエクスポート関数 |
| collectorsets.xml | `bin/perfmontemplates/collectorsets.xml` | 設定 | テンプレートメタデータ |
| *.xml | `bin/perfmontemplates/collectorsets/*.xml` | テンプレート | 各テンプレートファイル |
