# 通知設計書 19-Get-DbaAgentAlertCategory

## 概要

本ドキュメントは、SQL Serverエージェントのアラートカテゴリを取得するdbatools PowerShellコマンド「Get-DbaAgentAlertCategory」の設計仕様を記載します。

### 本通知の処理概要

Get-DbaAgentAlertCategoryは、SQL Server Agentに設定されたアラートカテゴリの情報を取得するコマンドです。カテゴリごとに割り当てられているアラート数も含めて返します。

**業務上の目的・背景**：DBAはアラートを論理的にグループ化するためにカテゴリを使用します。重大度別、データベース別、責任チーム別などでアラートを整理することで、管理とトラブルシューティングが容易になります。本コマンドは、既存のカテゴリ構成を把握し、未使用カテゴリの特定や、新規アラート作成時のカテゴリ選択に役立ちます。

**通知の送信タイミング**：本コマンドは「カテゴリ情報を取得する」参照系コマンドであり、通知を送信しません。管理者がコマンドを実行した時点で即座にカテゴリ情報が返されます。

**通知の受信者**：本コマンドの実行結果はコマンド実行者（DBA、システム管理者）に返されます。取得されたカテゴリ情報はSMO AlertCategoryオブジェクトとして出力されます。

**通知内容の概要**：カテゴリの名前、ID、およびそのカテゴリに属するアラート数（AlertCount）が返されます。

**期待されるアクション**：管理者は取得したカテゴリ情報を基に、カテゴリ構成の妥当性確認、未使用カテゴリの削除検討、新規アラート作成時のカテゴリ指定などのアクションを行います。

## 通知種別

PowerShellコンソール出力 / パイプライン出力（Microsoft.SqlServer.Management.Smo.Agent.AlertCategory）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（コマンド実行と同時に結果出力） |
| 優先度 | 低（参照系コマンド、ConfirmImpact未設定） |
| リトライ | 無（失敗時はエラーメッセージ出力） |

### 送信先決定ロジック

- SqlInstanceパラメータ：取得対象のSQL Serverインスタンスを指定
- Categoryパラメータ：特定のカテゴリ名を指定してフィルタリング

## 通知テンプレート

### コンソール出力の場合

| 項目 | 内容 |
|-----|------|
| 出力形式 | Microsoft.SqlServer.Management.Smo.Agent.AlertCategory（カスタムプロパティ追加） |
| デフォルト表示 | Select-DefaultViewによる主要プロパティ表示 |

### 本文テンプレート

```
デフォルト表示プロパティ:
ComputerName : {ComputerName}
InstanceName : {InstanceName}
SqlInstance  : {SqlInstance}
Name         : {CategoryName}
ID           : {CategoryID}
AlertCount   : {Count}
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| なし | - | - | 本コマンドは添付ファイルを出力しない |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| ComputerName | SQL Serverのコンピュータ名 | $server.ComputerName | Yes |
| InstanceName | SQL Serverのインスタンス名 | $server.ServiceName | Yes |
| SqlInstance | 完全修飾インスタンス名 | $server.DomainInstanceName | Yes |
| Name | カテゴリ名 | $cat.Name | Yes |
| ID | カテゴリID | $cat.ID | Yes |
| AlertCount | アラート数 | カウント計算 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| コマンド実行 | Get-DbaAgentAlertCategory実行 | SqlInstanceに接続可能 | 指定インスタンスからカテゴリ情報を取得 |
| パイプライン入力 | SqlInstanceのパイプ入力 | 複数インスタンス指定 | 複数サーバーから一括取得 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| 接続失敗 | SqlInstanceへの接続失敗時はエラー出力して継続 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[コマンド実行開始] --> B[foreach instance in SqlInstance]
    B --> C[Connect-DbaInstance]
    C --> D{接続成功?}
    D -->|No| E[Stop-Function: 接続エラー]
    E --> B
    D -->|Yes| F[JobServer.AlertCategoriesコレクション取得]
    F --> G{Category指定あり?}
    G -->|Yes| H[名前でフィルタリング]
    G -->|No| I[全カテゴリ対象]
    H --> J[foreach cat in alertCategories]
    I --> J
    J --> K[AlertCount計算]
    K --> L[カスタムプロパティ追加]
    L --> M[Select-DefaultView出力]
    M --> N{次のカテゴリ?}
    N -->|Yes| J
    N -->|No| O{次のインスタンス?}
    O -->|Yes| B
    O -->|No| P[終了]
```

## データベース参照・更新仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| msdb.dbo.syscategories | カテゴリ情報 | SMO JobServer.AlertCategories経由 |
| msdb.dbo.sysalerts | アラート数計算 | CategoryNameでフィルタ |

### テーブル別参照項目詳細

#### msdb.dbo.syscategories

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| category_id | カテゴリID | SMO経由で全カテゴリ |
| name | カテゴリ名 | Categoryパラメータでフィルタ |
| category_class | カテゴリ種別 | AlertCategory（class=2） |

#### msdb.dbo.sysalerts

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| category_id | アラート数計算 | CategoryNameでグループ化 |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| なし | - | 本コマンドは参照専用 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 接続失敗 | SqlInstanceに接続不可 | Stop-Function -Continue で次インスタンスへ |
| カテゴリ取得失敗 | SMOエラー | Stop-Function -Continue |
| 権限不足 | 適切な権限なし | SMOからエラー返却 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | なし |
| 1日あたり上限 | なし |

### 配信時間帯

制限なし（任意のタイミングで実行可能）

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

- SQL Server Agent関連の権限が必要
- SqlCredentialパラメータによりSQL Server認証、Windows認証、AD認証をサポート
- 参照専用コマンドのため、データ変更リスクなし

## 備考

- AlertCountはカスタム計算プロパティ（SMO AlertCategoryには含まれない）
- $server.JobServer.Alerts.CategoryName でフィルタしてCount()で計算
- Test-Boundを使用したパラメータ指定チェック
- 他のdbatools Agent系コマンド（New-DbaAgentAlert, Remove-DbaAgentAlertCategoryなど）と連携可能

---

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

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

### 推奨読解順序

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

まず、出力されるAlertCategoryオブジェクトの構造と追加されるカスタムプロパティを理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaAgentAlertCategory.ps1 | `public/Get-DbaAgentAlertCategory.ps1` | 28-46行目: .OUTPUTSセクションで出力プロパティを確認 |
| 1-2 | Get-DbaAgentAlertCategory.ps1 | `public/Get-DbaAgentAlertCategory.ps1` | 93行目: デフォルト表示プロパティの定義 |

**読解のコツ**: `Microsoft.SqlServer.Management.Smo.Agent.AlertCategory`型がSMOのカテゴリオブジェクトであり、AlertCountがカスタム計算プロパティとして追加されることを理解する。

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

処理の起点となるパラメータ定義を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaAgentAlertCategory.ps1 | `public/Get-DbaAgentAlertCategory.ps1` | 70-77行目: パラメータ定義 |

**主要処理フロー**:
1. **72行目**: `[parameter(Mandatory, ValueFromPipeline)]` - SqlInstanceは必須でパイプライン入力対応
2. **75行目**: Categoryパラメータでフィルタリング

#### Step 3: 接続とカテゴリ取得を理解する

SQL Server接続とカテゴリコレクション取得を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaAgentAlertCategory.ps1 | `public/Get-DbaAgentAlertCategory.ps1` | 81-86行目: 接続処理 |
| 3-2 | Get-DbaAgentAlertCategory.ps1 | `public/Get-DbaAgentAlertCategory.ps1` | 88-91行目: カテゴリフィルタリング |

**主要処理フロー**:
- **82-85行目**: Connect-DbaInstanceによる接続とエラーハンドリング
- **88行目**: `$server.JobServer.AlertCategories` でコレクション取得
- **89-91行目**: Test-Bound + Where-Object でCategory名フィルタ

#### Step 4: AlertCount計算とカスタムプロパティ追加を理解する

出力オブジェクトの拡張処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaAgentAlertCategory.ps1 | `public/Get-DbaAgentAlertCategory.ps1` | 95-108行目: カテゴリ処理ループ |

**主要処理フロー**:
- **97行目**: AlertCount計算 - `$server.JobServer.Alerts | Where-Object { $_.CategoryName -eq $cat.Name } | Count`
- **99-102行目**: Add-Member でカスタムプロパティ追加
- **104行目**: Select-DefaultView で表示プロパティ制御

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

```
Get-DbaAgentAlertCategory (エントリーポイント)
    |
    └── [processブロック]
            |
            └── foreach ($instance in $SqlInstance)
                    |
                    ├── Connect-DbaInstance
                    |       └── SQL Server接続
                    |
                    ├── $server.JobServer.AlertCategories
                    |       └── SMOカテゴリコレクション取得
                    |
                    ├── フィルタリング (Test-Bound)
                    |       └── Category パラメータ
                    |
                    └── foreach ($cat in $alertCategories)
                            ├── AlertCount計算
                            |       └── JobServer.Alerts.CategoryName比較
                            ├── Add-Member (ComputerName)
                            ├── Add-Member (InstanceName)
                            ├── Add-Member (SqlInstance)
                            ├── Add-Member (AlertCount)
                            └── Select-DefaultView
```

### データフロー図

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

SqlInstance ────────┐
SqlCredential ──────┼──▶ Connect-DbaInstance ──▶ $server
Category ───────────┘                               │
                                                    ▼
                                     $server.JobServer.AlertCategories
                                                    │
                                                    ▼
                                     フィルタリング処理
                                     (Category指定時)
                                                    │
                                                    ▼
                                     foreach ($cat)
                                                    │
                                     ┌──────────────┼──────────────┐
                                     ▼              ▼              ▼
                              AlertCount計算   Add-Member   Select-DefaultView
                              (Alerts比較)    (4プロパティ)
                                     │              │              │
                                     └──────────────┼──────────────┘
                                                    ▼
                             Microsoft.SqlServer.Management.Smo.Agent.AlertCategory
                                    (拡張プロパティ付き)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaAgentAlertCategory.ps1 | `public/Get-DbaAgentAlertCategory.ps1` | ソース | メインコマンド実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラー処理ユーティリティ |
| Test-Bound.ps1 | `private/functions/Test-Bound.ps1` | ソース | パラメータ指定チェック |
| Select-DefaultView.ps1 | `private/functions/Select-DefaultView.ps1` | ソース | デフォルト表示プロパティ制御 |
