# 通知設計書 15-Set-DbaAgentAlert

## 概要

本ドキュメントは、既存のSQL Serverエージェントアラートのプロパティを変更するdbatools PowerShellコマンド「Set-DbaAgentAlert」の設計仕様を記載します。

### 本通知の処理概要

Set-DbaAgentAlertは、SQL Server Agentに設定された既存のアラートの有効/無効状態や名前を変更するコマンドです。SQL Server Management Studioを使用せずに、複数サーバーのアラートを一括で管理できます。

**業務上の目的・背景**：メンテナンス期間中のアラート一時無効化、環境間でのアラート名標準化、誤って無効化されたアラートの再有効化など、日常的なアラート管理作業を効率化します。複数サーバーに対する一括操作が可能なため、大規模環境での運用負荷を軽減します。

**通知の送信タイミング**：本コマンドは「アラート設定を変更する」コマンドであり、変更後のアラートがトリガーされた際に通知が発生します。アラートを無効化（-Disabled）すると、以降はトリガーされても通知されなくなります。

**通知の受信者**：本コマンドの実行結果はコマンド実行者に返されます。変更されたアラート情報がSMO Alertオブジェクトとして出力されます。

**通知内容の概要**：変更後のアラート設定（名前、有効状態、通知メッセージ、種別、重大度など）が返されます。

**期待されるアクション**：管理者は変更結果を確認し、意図した設定変更が適用されたことを検証します。特にメンテナンス後は、無効化したアラートを再度有効化することを忘れないよう注意が必要です。

## 通知種別

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

## 送信仕様

### 基本情報

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

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

- SqlInstanceパラメータ：変更対象のSQL Serverインスタンスを指定
- Alertパラメータ：変更対象のアラート名を指定
- InputObjectパラメータ：Get-DbaAgentAlertからパイプラインで受け取ったAlertオブジェクトを処理

## 通知テンプレート

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

| 項目 | 内容 |
|-----|------|
| 出力形式 | Microsoft.SqlServer.Management.Smo.Agent.Alert |
| 確認プロンプト | ShouldProcess による確認（ConfirmImpact = 'Low'） |

### 本文テンプレート

```
アラート変更成功時の出力:
ComputerName           : {ComputerName}
SqlInstance            : {SqlInstance}
InstanceName           : {InstanceName}
Name                   : {AlertName}
IsEnabled              : {True/False}
NotificationMessage    : {Message}
AlertType              : {AlertType}
Severity               : {Severity}
DatabaseName           : {DatabaseName}
EventDescriptionKeyword: {Keyword}
LastOccurrenceDate     : {DateTime}
OccurrenceCount        : {Count}
```

### 添付ファイル

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

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| SqlInstance | SQL Serverインスタンス | パラメータ指定 | No（InputObject使用時） |
| Alert | アラート名 | パラメータ指定 | No（InputObject使用時） |
| NewName | 新しいアラート名 | パラメータ指定 | No |
| Enabled | 有効化フラグ | パラメータ指定 | No |
| Disabled | 無効化フラグ | パラメータ指定 | No |
| Force | 確認プロンプト抑制 | パラメータ指定 | No |
| InputObject | Alertオブジェクト | パイプライン入力 | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| コマンド実行 | Set-DbaAgentAlert実行 | 対象アラートが存在 | アラート設定を変更 |
| パイプライン入力 | Get-DbaAgentAlertからのパイプ | 有効なAlertオブジェクト | パイプラインで受け取ったアラートを変更 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| アラート未存在 | 指定アラートが存在しない場合はStop-Function |
| -WhatIf指定時 | 実際の変更は行わず、処理内容のみ表示 |
| ShouldProcess拒否 | ユーザーが確認プロンプトで拒否した場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[コマンド実行開始] --> B{Force指定?}
    B -->|Yes| C[ConfirmPreference = none]
    B -->|No| D[通常確認モード]
    C --> E{InputObject/Alert指定?}
    D --> E
    E -->|No| F[Stop-Function: 対象未指定]
    F --> G[終了]
    E -->|Yes| H[foreach instance in SqlInstance]
    H --> I[Connect-DbaInstance]
    I --> J{接続成功?}
    J -->|No| K[Stop-Function: 接続エラー]
    K --> H
    J -->|Yes| L[foreach alert in Alert]
    L --> M{アラート存在?}
    M -->|No| N[Stop-Function: 未存在]
    N --> L
    M -->|Yes| O[InputObjectに追加]
    O --> P[Refresh]
    P --> Q[foreach currentAlert in InputObject]
    Q --> R{NewName指定?}
    R -->|Yes| S[Rename実行]
    R -->|No| T{Enabled指定?}
    S --> T
    T -->|Yes| U[IsEnabled = true]
    T -->|No| V{Disabled指定?}
    U --> V
    V -->|Yes| W[IsEnabled = false]
    V -->|No| X[ShouldProcess確認]
    W --> X
    X --> Y{承認?}
    Y -->|Yes| Z[Alter実行]
    Y -->|No| AA[スキップ]
    Z --> AB[Get-DbaAgentAlert出力]
    AA --> AC{次のアラート?}
    AB --> AC
    AC -->|Yes| Q
    AC -->|No| AD[終了]
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| msdb.dbo.sysalerts | アラート存在確認 | SMO経由で参照 |

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

#### msdb.dbo.sysalerts

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| name | アラート存在確認 | Alert パラメータ値と比較 |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| msdb.dbo.sysalerts | UPDATE | アラート設定の更新 |

#### sysalertsテーブル

| 操作 | 項目（カラム名） | 更新値 | 備考 |
|-----|-----------------|-------|------|
| UPDATE | name | NewName | Rename実行時 |
| UPDATE | enabled | 1 or 0 | Enabled/Disabled 指定時 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 対象未指定 | Alert/InputObject両方未指定 | Stop-Function |
| 接続失敗 | SqlInstanceに接続不可 | Stop-Function -Continue |
| アラート未存在 | 指定アラートが存在しない | Stop-Function |
| Alter失敗 | SMO Alter()失敗 | Stop-Function -Continue |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

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

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

- sysadmin権限が必要
- SqlCredentialパラメータによりSQL Server認証、Windows認証、AD認証をサポート
- Forceパラメータにより確認プロンプトを抑制可能（自動化スクリプト向け）
- SQL Server 2000以上が対象

## 備考

- Rename操作は単一アラート変更時のみ有効
- Enabled/Disabledスイッチは排他的ではない（両方指定可能だが、後から処理されるDisabledが優先）
- InputObjectはパイプラインから累積的に収集される
- 変更後、Get-DbaAgentAlertで結果を取得して出力

---

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

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

### 推奨読解順序

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

まず、変更対象となるAlertオブジェクトの構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Set-DbaAgentAlert.ps1 | `public/Set-DbaAgentAlert.ps1` | 65-92行目: .OUTPUTSセクションで出力プロパティを確認 |
| 1-2 | Set-DbaAgentAlert.ps1 | `public/Set-DbaAgentAlert.ps1` | 124-125行目: InputObjectパラメータの型定義 |

**読解のコツ**: `[Microsoft.SqlServer.Management.Smo.Agent.Alert[]]`型がSMOのアラートオブジェクトであることを理解する。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Set-DbaAgentAlert.ps1 | `public/Set-DbaAgentAlert.ps1` | 115-127行目: パラメータ定義 |
| 2-2 | Set-DbaAgentAlert.ps1 | `public/Set-DbaAgentAlert.ps1` | 128-130行目: beginブロック（Force処理） |

**主要処理フロー**:
1. **129行目**: `if ($Force) { $ConfirmPreference = 'none' }` - Force指定時に確認プロンプト抑制

#### Step 3: 入力バリデーションとアラート取得を理解する

対象アラートの取得処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbaAgentAlert.ps1 | `public/Set-DbaAgentAlert.ps1` | 133-138行目: 入力バリデーション |
| 3-2 | Set-DbaAgentAlert.ps1 | `public/Set-DbaAgentAlert.ps1` | 140-161行目: アラート取得処理 |

**主要処理フロー**:
- **135-137行目**: InputObjectとAlert両方未指定の場合はエラー
- **148行目**: `$server.JobServer.Alerts.Name` でアラート存在確認
- **153行目**: `$server.JobServer.Alerts[$a]` でAlertオブジェクト取得
- **156行目**: `Refresh()` で最新状態を取得

#### Step 4: アラート変更処理を理解する

実際のアラート変更処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Set-DbaAgentAlert.ps1 | `public/Set-DbaAgentAlert.ps1` | 164-184行目: 変更処理 |
| 4-2 | Set-DbaAgentAlert.ps1 | `public/Set-DbaAgentAlert.ps1` | 186-199行目: Alter実行と出力 |

**主要処理フロー**:
- **165行目**: `$currentAlert.Parent.Parent` でサーバーオブジェクト取得
- **169-172行目**: NewName指定時はRename()実行
- **175-177行目**: Enabled指定時はIsEnabled = true
- **180-182行目**: Disabled指定時はIsEnabled = false
- **188-193行目**: ShouldProcess確認後にAlter()実行
- **197行目**: Get-DbaAgentAlertで変更結果を出力

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

```
Set-DbaAgentAlert (エントリーポイント)
    |
    +-- [beginブロック]
    |       └── Force → ConfirmPreference = 'none'
    |
    └── [processブロック]
            |
            ├── 入力バリデーション
            |       └── InputObject/Alert 必須チェック
            |
            ├── foreach ($instance in $SqlInstance)
            |       |
            |       ├── Connect-DbaInstance
            |       |
            |       └── foreach ($a in $Alert)
            |               ├── 存在チェック (Alerts.Name)
            |               ├── Alertオブジェクト取得
            |               └── Refresh()
            |
            └── foreach ($currentAlert in $InputObject)
                    |
                    ├── Rename() (NewName指定時)
                    |
                    ├── IsEnabled設定
                    |       ├── Enabled → true
                    |       └── Disabled → false
                    |
                    ├── ShouldProcess確認
                    |
                    ├── Alter()
                    |
                    └── Get-DbaAgentAlert 出力
```

### データフロー図

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

SqlInstance ────────┐
SqlCredential ──────┤
Alert ──────────────┼──▶ Connect-DbaInstance ──▶ $server
NewName ────────────┤                               │
Enabled ────────────┤                               ▼
Disabled ───────────┤                    アラート存在確認
Force ──────────────┘                               │
                                                   ▼
InputObject ─────────────────────────▶ InputObject配列
                                                   │
                                                   ▼
                                         foreach currentAlert
                                                   │
                                    ┌──────────────┼──────────────┐
                                    ▼              ▼              ▼
                              Rename()       IsEnabled設定    Alter()
                             (NewName)      (Enabled/Disabled)
                                                   │
                                                   ▼
                                         Get-DbaAgentAlert
                                                   │
                                                   ▼
                             Microsoft.SqlServer.Management.Smo.Agent.Alert
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Set-DbaAgentAlert.ps1 | `public/Set-DbaAgentAlert.ps1` | ソース | メインコマンド実装 |
| Get-DbaAgentAlert.ps1 | `public/Get-DbaAgentAlert.ps1` | ソース | 変更結果の取得（内部呼び出し） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラー処理ユーティリティ |
| Test-FunctionInterrupt.ps1 | `private/functions/Test-FunctionInterrupt.ps1` | ソース | 処理中断チェック |
| Write-Message.ps1 | `private/functions/Write-Message.ps1` | ソース | ログ出力ユーティリティ |
