# 機能設計書 512-Set-DbaAgentAlert

## 概要

本ドキュメントは、SQL Server Agentアラートのプロパティを変更するdbatools関数「Set-DbaAgentAlert」の機能設計書である。

### 本機能の処理概要

Set-DbaAgentAlertは、既存のSQL Agentアラートの有効/無効状態の切り替えや名前変更を行う機能を提供する。

**業務上の目的・背景**：SQL Server Agentアラートは、特定のエラーやパフォーマンス条件が発生した際に通知を行う重要な監視機能である。運用環境では、メンテナンス時にノイジーなアラートを一時的に無効化したり、環境間でアラート名を標準化したりする必要がある。本機能は、SSMSを使用せずにこれらの操作をコマンドラインから実行可能にし、複数サーバーへの一括適用を可能にする。

**機能の利用シーン**：
- メンテナンスウィンドウ中のアラート一時無効化
- 複数サーバーでのアラート設定の一括変更
- 環境間でのアラート名標準化
- 誤って発火しているアラートの緊急停止

**主要な処理内容**：
1. 対象SQL Serverインスタンスへの接続
2. 指定されたアラートの存在確認
3. アラートオブジェクトの取得とリフレッシュ
4. プロパティ変更（名前変更、有効/無効切り替え）
5. SMO Alter()メソッドによる変更のコミット
6. 更新後のアラートオブジェクトの返却

**関連システム・外部連携**：SQL Server JobServer.Alertsコレクション、SMO (SQL Server Management Objects)

**権限による制御**：sysadmin権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | SQL Server Management Studio - SQL Agent Alerts | 参照画面 | アラート一覧の確認・編集 |
| - | PowerShell Console | 主画面 | コマンド実行インターフェース |

## 機能種別

データ更新操作 (UPDATE)

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | sysadmin権限、SQL Server 2000以上 |
| SqlCredential | PSCredential | No | 代替認証資格情報 | Windows/SQL認証対応 |
| Alert | object[] | No* | 変更するアラート名 | AlertまたはInputObjectの少なくとも一方が必要 |
| NewName | string | No | 新しいアラート名 | 単一アラート変更時のみ有効 |
| Enabled | switch | No | アラートを有効化 | - |
| Disabled | switch | No | アラートを無効化 | - |
| Force | switch | No | 確認プロンプトをスキップ | - |
| InputObject | Alert[] | No* | パイプラインからのアラートオブジェクト | Get-DbaAgentAlertからの出力 |
| EnableException | switch | No | 例外処理を有効化 | - |

### 入力データソース

- Get-DbaAgentAlertコマンドからのパイプライン入力
- SQL Server JobServer.Alertsコレクション

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Name | string | アラート名 |
| IsEnabled | bool | アラートの有効状態 |
| NotificationMessage | string | アラート発火時のメッセージ |
| AlertType | string | アラートタイプ |
| Severity | int | 重大度レベル |
| DatabaseName | string | 対象データベース名 |
| EventDescriptionKeyword | string | イベント説明キーワード |
| LastOccurrenceDate | DateTime | 最終発生日時 |
| OccurrenceCount | int | 発生回数 |

### 出力先

PowerShellパイプライン（Microsoft.SqlServer.Management.Smo.Agent.Alert）

## 処理フロー

### 処理シーケンス

```
1. 初期設定
   └─ Forceフラグによる確認プロンプト制御

2. 入力検証
   └─ AlertまたはInputObjectの存在チェック

3. インスタンス接続とアラート取得
   ├─ Connect-DbaInstanceで接続
   ├─ アラート存在確認
   └─ アラートオブジェクト取得・リフレッシュ

4. 各アラートの処理
   ├─ 名前変更処理（NewName指定時）
   │   └─ Rename()メソッド呼び出し
   ├─ 有効化処理（Enabled指定時）
   │   └─ IsEnabled = $true
   └─ 無効化処理（Disabled指定時）
       └─ IsEnabled = $false

5. 変更のコミット
   └─ Alter()メソッド呼び出し

6. 結果の返却
   └─ Get-DbaAgentAlertで更新後のオブジェクト取得
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Force指定?}
    B -->|Yes| C[ConfirmPreference = none]
    B -->|No| D{InputObject/Alert指定?}
    C --> D
    D -->|No| E[エラー: アラート名必須]
    D -->|Yes| F[各インスタンスをループ]
    F --> G[Connect-DbaInstance]
    G --> H[各アラートをループ]
    H --> I{アラート存在?}
    I -->|No| J[エラー: アラート不存在]
    I -->|Yes| K[アラートオブジェクト取得]
    K --> L[InputObjectに追加]
    L --> M{次のアラート?}
    M -->|Yes| H
    M -->|No| N[各InputObjectアラートを処理]
    N --> O{NewName指定?}
    O -->|Yes| P[Rename実行]
    O -->|No| Q{Enabled指定?}
    P --> Q
    Q -->|Yes| R[IsEnabled = true]
    Q -->|No| S{Disabled指定?}
    R --> T[Alter実行]
    S -->|Yes| U[IsEnabled = false]
    S -->|No| T
    U --> T
    T --> V[Get-DbaAgentAlertで結果取得]
    V --> W{次のアラート?}
    W -->|Yes| N
    W -->|No| X[終了]
    E --> X
    J --> M
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | アラート識別子必須 | AlertまたはInputObjectの少なくとも一方が必要 | 常時 |
| BR-002 | アラート存在確認 | 指定されたアラートがインスタンスに存在する必要がある | Alert指定時 |
| BR-003 | 名前変更の排他性 | NewNameは単一アラートに対してのみ適用可能 | NewName指定時 |

### 計算ロジック

該当なし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| アラート更新 | msdb.dbo.sysalerts | UPDATE | アラートプロパティの更新 |

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

#### msdb.dbo.sysalerts

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | name | NewName指定値 | Rename()メソッド経由 |
| UPDATE | enabled | 0 or 1 | IsEnabledプロパティ経由 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Stop-Function | AlertもInputObjectも未指定 | どちらかのパラメータを指定 |
| - | ConnectionError | インスタンス接続失敗 | 接続情報を確認 |
| - | Stop-Function | アラートが存在しない | アラート名を確認 |
| - | Stop-Function | アラート取得失敗 | エラーメッセージを確認 |
| - | Stop-Function | 変更コミット失敗 | 権限を確認 |

### リトライ仕様

リトライ機能なし。エラー発生時は-Continueにより次の処理を継続。

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

SMOのAlter()メソッドによる暗黙的トランザクション。

## パフォーマンス要件

特に定義なし。

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

- sysadmin権限が必要
- SQL認証、Windows認証対応
- WhatIf/Confirmパラメータによる事前確認が可能

## 備考

- SQL Server 2000以上に対応
- 複数サーバー・複数アラートの一括変更に対応

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Microsoft.SqlServer.Management.Smo.Agent.Alert | SMO | アラートオブジェクトのプロパティ（IsEnabled, Name等） |

**読解のコツ**: SMOのAlertクラスにはRename()メソッドとAlter()メソッドがあり、名前変更とプロパティ変更は別々のメソッドで行う。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Set-DbaAgentAlert.ps1 | `public/Set-DbaAgentAlert.ps1` | 関数定義、パラメータ、processブロック構造 |

**主要処理フロー**:
1. **115-127行目**: CmdletBinding属性とパラメータ定義
2. **128-130行目**: beginブロック - Force処理
3. **131-199行目**: processブロック - メイン処理

#### Step 3: アラート変更処理の詳細を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbaAgentAlert.ps1 | `public/Set-DbaAgentAlert.ps1` | processブロック内の変更ロジック |

**主要処理フロー**:
- **135-138行目**: 入力検証
- **140-161行目**: インスタンスループとアラート取得
- **164-183行目**: アラートオプション設定
- **187-198行目**: 変更のコミットと結果取得

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

```
Set-DbaAgentAlert
    │
    ├─ Connect-DbaInstance
    │
    ├─ JobServer.Alerts[$a] (アラート取得)
    │
    ├─ Alert.Refresh() (オブジェクトリフレッシュ)
    │
    ├─ Alert.Rename() (名前変更時)
    │
    ├─ Alert.Alter() (変更コミット)
    │
    └─ Get-DbaAgentAlert (結果取得)
```

### データフロー図

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

Alert名 ─────────────▶ アラート存在確認
      │                        │
SqlInstance ──────────▶ Connect-DbaInstance
      │                        │
      ▼                        ▼
InputObject ─────────▶ アラートオブジェクト取得
                              │
                              ▼
                       プロパティ変更
                       ├─ NewName → Rename()
                       ├─ Enabled → IsEnabled = true
                       └─ Disabled → IsEnabled = false
                              │
                              ▼
                         Alter()
                              │
                              ▼
                    Get-DbaAgentAlert ───▶ [Alertオブジェクト出力]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Set-DbaAgentAlert.ps1 | `public/Set-DbaAgentAlert.ps1` | ソース | メイン関数 |
| Get-DbaAgentAlert.ps1 | `public/Get-DbaAgentAlert.ps1` | ソース | アラート取得（依存関数） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
