# 機能設計書 496-New-DbaAgentAlert

## 概要

本ドキュメントは、SQL Server Agent アラートの作成機能 `New-DbaAgentAlert` の設計仕様を記載する。

### 本機能の処理概要

SQL Server Agent アラートを新規作成する機能である。特定のエラー重大度、メッセージID、パフォーマンス条件、またはWMIイベントを監視し、オペレーターへの通知やジョブの自動実行を設定できる。

**業務上の目的・背景**：SQL Server の監視において、特定のエラー条件や性能問題を検知した際の自動通知は運用品質向上に不可欠である。SSMS を使用した手動設定は複数インスタンスへの展開が非効率であり、本機能により PowerShell からアラートの一括作成・標準化が可能となる。重大度ベース、メッセージIDベース、パフォーマンス条件ベース、WMIイベントベースの4種類のアラートをサポートする。

**機能の利用シーン**：
- カスタムアラートの作成（特定のエラー監視）
- パフォーマンス監視アラートの設定
- WMI イベント監視の設定
- 複数インスタンスへのアラート一括展開
- 自動化スクリプトでのアラート管理

**主要な処理内容**：
1. 対象 SQL Server インスタンスへの接続
2. アラートの重複チェック
3. SMO Alert オブジェクトの作成と設定
4. オペレーター通知の設定（指定時）
5. アラートの保存と結果出力

**関連システム・外部連携**：SQL Server Agent アラートシステム、Database Mail（通知用）、WMI（WMIイベント監視時）、パフォーマンスカウンター（パフォーマンス条件監視時）。

**権限による制御**：SQL Server への sysadmin 権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 12 | Agentアラート管理 | 主画面 | SQLエージェントアラートの新規作成 |

## 機能種別

データ作成（INSERT）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQLServerインスタンス | 必須 |
| SqlCredential | PSCredential | No | 代替認証情報 | - |
| Alert | string | Yes | アラート名 | 必須、インスタンス内で一意 |
| Category | string | No | アラートカテゴリ | - |
| Database | string | No | 対象データベース限定 | - |
| Operator | string[] | No | 通知先オペレーター | - |
| DelayBetweenResponses | int | No | 通知間隔（秒） | デフォルト60 |
| Disabled | switch | No | 無効状態で作成 | - |
| EventDescriptionKeyword | string | No | イベント説明フィルタキーワード | - |
| EventSource | string | No | イベントソース | - |
| JobId | string | No | 応答ジョブID | GUID形式、デフォルト00000000-0000-0000-0000-000000000000 |
| Severity | int | No | 重大度レベル（0-25） | 重大度アラート用 |
| MessageId | int | No | メッセージID | メッセージIDアラート用 |
| NotificationMessage | string | No | カスタム通知メッセージ | - |
| PerformanceCondition | string | No | パフォーマンス条件 | パフォーマンスアラート用 |
| WmiEventNamespace | string | No | WMI名前空間 | WMIアラート用 |
| WmiEventQuery | string | No | WMIクエリ | WMIアラート用 |
| NotifyMethod | string | No | 通知方法 | None/NotifyEmail/Pager/NetSend/NotifyAll、デフォルトNotifyAll |
| EnableException | switch | No | 例外処理の制御フラグ | - |

### 入力データソース

- ユーザー指定のパラメータ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピューター名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Name | string | アラート名 |
| ID | int | アラートID |
| JobName | string | 応答ジョブ名 |
| AlertType | enum | アラートタイプ |
| CategoryName | string | カテゴリ名 |
| Severity | int | 重大度レベル |
| MessageId | int | メッセージID |
| IsEnabled | bool | 有効フラグ |
| DelayBetweenResponses | int | 通知間隔 |

### 出力先

PowerShell パイプラインへの出力（`Microsoft.SqlServer.Management.Smo.Agent.Alert` オブジェクト、Get-DbaAgentAlert 経由）

## 処理フロー

### 処理シーケンス

```
1. パラメータ処理
   └─ NotifyMethod による IncludeEventDescription 設定
2. インスタンスループ開始
   └─ 各 SqlInstance に対して処理
3. SQL Server 接続
   └─ Connect-DbaInstance で接続確立
4. アラート名ループ
   └─ 各 Alert 名に対して処理
5. 重複チェック
   └─ 同名アラートの存在確認
6. SMO Alert オブジェクト作成
   └─ New-Object Microsoft.SqlServer.Management.Smo.Agent.Alert
7. プロパティ設定
   └─ 各パラメータに基づくプロパティ設定
8. アラート作成
   └─ $newalert.Create()
9. オペレーター通知設定
   └─ AddNotification でオペレーター追加
10. 結果出力
    └─ Get-DbaAgentAlert で出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[パラメータ処理]
    B --> C{SqlInstance ループ}
    C --> D[Connect-DbaInstance]
    D --> E{接続成功?}
    E -->|No| F[Stop-Function]
    F --> C
    E -->|Yes| G{Alert 名ループ}
    G --> H{同名アラート存在?}
    H -->|Yes| I[Stop-Function でスキップ]
    I --> G
    H -->|No| J[SMO Alert オブジェクト作成]
    J --> K{AG リスナー経由?}
    K -->|Yes| L[Stop-Function]
    K -->|No| M[プロパティ設定ループ]
    M --> N[newalert.Create]
    N --> O{Operator 指定?}
    O -->|Yes| P[AddNotification]
    O -->|No| Q[JobServer.Refresh]
    P --> Q
    Q --> R[Get-DbaAgentAlert]
    R --> G
    G -->|終了| C
    C -->|終了| S[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-496-01 | アラート名一意性 | 同名アラートが存在する場合は作成をスキップ | 常時 |
| BR-496-02 | アラートタイプ選択 | MessageId > 0 かつ Severity 未指定の場合、Severity = 0 | MessageId 指定時 |
| BR-496-03 | AG リスナー制限 | 可用性グループリスナー経由ではアラート作成不可 | AG リスナー接続時 |
| BR-496-04 | NotifyMethod デフォルト | 指定なしの場合は NotifyAll | 常時 |
| BR-496-05 | DelayBetweenResponses デフォルト | 指定なしの場合は 60 秒 | 常時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| アラート作成 | msdb.dbo.sysalerts | INSERT | アラートの作成 |
| 通知設定 | msdb.dbo.sysnotifications | INSERT | オペレーター通知設定 |

### テーブル別操作詳細

#### msdb.dbo.sysalerts

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name, severity, message_id, enabled, category_id, delay_between_responses など | SMO Alert.Create() 経由 | |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Server への接続失敗 | Stop-Function で Continue |
| AlertExists | 重複エラー | 同名アラートが存在 | Stop-Function で Continue |
| AGListener | AG制限 | AGリスナー経由での接続 | Stop-Function で Continue |
| NotificationError | 通知設定エラー | オペレーター通知追加失敗 | Stop-Function で Continue |

### リトライ仕様

リトライ処理は実装されていない。

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

各アラートは個別に作成される。SMO の Create() メソッドで内部的にトランザクション管理。

## パフォーマンス要件

- 各インスタンスへの接続は順次処理
- アラート作成は SMO の Create() メソッドを使用

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

- SQL Server への接続には SqlCredential による認証情報指定が可能
- sysadmin 権限が必要
- ShouldProcess（WhatIf/Confirm）をサポート

## 備考

- 4種類のアラートタイプをサポート:
  - 重大度アラート（Severity パラメータ）
  - メッセージIDアラート（MessageId パラメータ）
  - パフォーマンス条件アラート（PerformanceCondition パラメータ）
  - WMIイベントアラート（WmiEventNamespace, WmiEventQuery パラメータ）

---

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

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

### 推奨読解順序

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

SMO の Alert オブジェクト構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | New-DbaAgentAlert.ps1 | `public/New-DbaAgentAlert.ps1` | 227行目の list 配列（設定可能プロパティ一覧） |

**読解のコツ**: list 配列に含まれるプロパティ名が SMO Alert オブジェクトの設定可能なプロパティに対応。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaAgentAlert.ps1 | `public/New-DbaAgentAlert.ps1` | 160-185行目のパラメータ定義、186行目の process ブロック開始 |

**主要処理フロー**:
1. **187-193行目**: NotifyMethod による IncludeEventDescription 設定
2. **199-201行目**: MessageId > 0 かつ Severity 未指定時の処理
3. **203-208行目**: Connect-DbaInstance で接続
4. **210-256行目**: アラート作成メインロジック

#### Step 3: アラート作成処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaAgentAlert.ps1 | `public/New-DbaAgentAlert.ps1` | 214-254行目のアラート作成処理 |

**主要処理フロー**:
- **217-226行目**: SMO Alert オブジェクト作成（AG リスナーエラー処理含む）
- **227行目**: 設定可能プロパティのリスト定義
- **229-235行目**: 変数からプロパティへの動的設定
- **237行目**: newalert.Create() でアラート作成
- **239-248行目**: オペレーター通知の追加

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

```
New-DbaAgentAlert
    │
    ├─ Connect-DbaInstance
    │      └─ SMO 接続確立
    │
    ├─ Stop-Function
    │      └─ エラー処理
    │
    ├─ New-Object Microsoft.SqlServer.Management.Smo.Agent.Alert
    │      └─ SMO Alert オブジェクト作成
    │
    ├─ Get-Variable
    │      └─ パラメータ変数の動的取得
    │
    ├─ Alert.Create()
    │      └─ アラート作成
    │
    ├─ Alert.AddNotification()
    │      └─ オペレーター通知追加
    │
    ├─ Alert.Alter()
    │      └─ 変更の保存
    │
    ├─ JobServer.Refresh()
    │      └─ コレクションのリフレッシュ
    │
    └─ Get-DbaAgentAlert
           └─ 作成したアラートの取得・出力
```

### データフロー図

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

SqlInstance ─────────────┬─► Connect-DbaInstance ──────────────► SMO Server
SqlCredential ───────────┘                                              │
                                                                        ▼
Alert ───────────────────────► アラート重複チェック                     │
                                        │                               │
                                   存在する?                            │
                                   │      │                             │
                                 Yes      No                            │
                                   │      │                             │
                             スキップ     ▼                             │
                                    New-Object Alert                    │
                                         │                              │
Severity ────────────────────────────────┤                              │
MessageId ───────────────────────────────┤                              │
PerformanceCondition ────────────────────┤                              │
WmiEventNamespace ───────────────────────┤                              │
WmiEventQuery ───────────────────────────┤                              │
Category ────────────────────────────────┤                              │
Database ────────────────────────────────┤                              │
DelayBetweenResponses ───────────────────┤                              │
NotifyMethod ────────────────────────────┘                              │
                                         │                              │
                                         ▼                              │
                                  Alert.Create()                        │
                                         │                              │
Operator ────────────────────────► AddNotification()                    │
                                         │                              │
                                         ▼                              │
                                  Alert.Alter()                         │
                                         │                              │
                                         ▼                              │
                                Get-DbaAgentAlert ──────────► Alert オブジェクト
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaAgentAlert.ps1 | `public/New-DbaAgentAlert.ps1` | ソース | メイン機能実装 |
| Get-DbaAgentAlert.ps1 | `public/Get-DbaAgentAlert.ps1` | ソース | アラート取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server 接続 |
| Stop-Function.ps1 | `internal/functions/Stop-Function.ps1` | ソース | エラー処理 |
