# 通知設計書 21-Remove-DbaAgentAlertCategory

## 概要

本ドキュメントは、SQL Server Agentアラートカテゴリを削除するPowerShellコマンド `Remove-DbaAgentAlertCategory` の通知設計書です。

### 本通知の処理概要

`Remove-DbaAgentAlertCategory` は、SQL Serverインスタンスからカスタムアラートカテゴリを削除するコマンドです。このコマンドは、不要になった組織構造をクリーンアップしたり、複数環境間でアラート管理を標準化する際に使用されます。

**業務上の目的・背景**：SQL Server Agentのアラートカテゴリは、アラートを論理的にグループ化するための仕組みです。運用環境の変更、組織再編、または環境標準化プロジェクトにおいて、使用されなくなったカテゴリを削除する必要が生じます。このコマンドは、手動でSSMS（SQL Server Management Studio）を操作する代わりに、スクリプトによる一括削除を可能にし、複数サーバーへの一貫した適用を実現します。

**通知の送信タイミング**：このコマンドは通知を送信する機能ではなく、アラートカテゴリの削除操作を実行します。操作結果として、削除の成功・失敗ステータスを含むPSCustomObjectが即座にパイプラインに出力されます。

**通知の受信者**：コマンド実行者がPowerShellコンソールまたはスクリプトの出力を通じて結果を受信します。削除されたカテゴリに属していたアラートは自動的に `[Uncategorized]` カテゴリに再割り当てされます。

**通知内容の概要**：出力には以下の情報が含まれます：コンピュータ名、インスタンス名、SQL Serverインスタンス名、カテゴリ名、ステータス（"Dropped" または エラーメッセージ）、削除成否のブール値。

**期待されるアクション**：コマンド実行者は出力結果を確認し、失敗した削除操作については原因を調査して再試行するか、依存関係を解消してから再実行することが期待されます。

## 通知種別

コンソール出力 / パイプライン出力（PSCustomObject）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（即座にパイプライン出力） |
| 優先度 | 中 |
| リトライ | 無（コマンド再実行により対応） |

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

コマンド実行者のPowerShellセッションに直接出力されます。出力はパイプラインを通じて後続のコマンドに渡すことも、変数に格納することも可能です。

## 通知テンプレート

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

| 項目 | 内容 |
|-----|------|
| 出力形式 | PSCustomObject |
| 表示プロパティ | ComputerName, InstanceName, SqlInstance, Name, Status, IsRemoved |

### 出力オブジェクト構造

```powershell
[PSCustomObject]@{
    ComputerName = "サーバー名"
    InstanceName = "インスタンス名"
    SqlInstance  = "完全修飾インスタンス名"
    Name         = "削除されたカテゴリ名"
    Status       = "Dropped" または "エラーメッセージ"
    IsRemoved    = $true または $false
}
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| ComputerName | SQLサーバーのコンピュータ名 | $agentCategory.Parent.Parent.ComputerName | Yes |
| InstanceName | SQLサーバーのサービス名 | $agentCategory.Parent.Parent.ServiceName | Yes |
| SqlInstance | ドメインインスタンス名 | $agentCategory.Parent.Parent.DomainInstanceName | Yes |
| Name | アラートカテゴリ名 | $agentCategory.Name | Yes |
| Status | 削除結果ステータス | 処理結果から動的に設定 | Yes |
| IsRemoved | 削除成否フラグ | 処理結果から動的に設定 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| コマンド実行 | Remove-DbaAgentAlertCategory実行 | ShouldProcess確認後 | 各カテゴリの削除処理完了時に出力 |
| パイプライン入力 | Get-DbaAgentAlertCategoryからのパイプ | InputObject受信時 | パイプラインから受け取ったカテゴリを処理 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| WhatIf指定時 | -WhatIfパラメータ指定時は実際の削除は行わず、予定される動作のみ表示 |
| Confirm拒否時 | -Confirmで確認を求められた際にユーザーが拒否した場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[コマンド実行] --> B{SqlInstance指定?}
    B -->|Yes| C[Get-DbaAgentAlertCategory呼び出し]
    B -->|No| D[InputObjectを使用]
    C --> E[カテゴリ一覧取得]
    D --> E
    E --> F[endブロックで処理開始]
    F --> G{各カテゴリをループ}
    G --> H{ShouldProcess確認}
    H -->|Yes| I[出力オブジェクト初期化]
    H -->|No| G
    I --> J[Drop実行]
    J --> K{成功?}
    K -->|Yes| L[Status=Dropped, IsRemoved=true]
    K -->|No| M[Stop-Function呼び出し]
    M --> N[Status=エラーメッセージ, IsRemoved=false]
    L --> O[出力オブジェクト出力]
    N --> O
    O --> G
    G -->|完了| P[終了]
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| msdb.dbo.syscategories | アラートカテゴリ情報の取得 | SMO経由でアクセス |
| msdb.dbo.sysalerts | 関連アラートの確認 | カテゴリ削除時に自動再割り当て |

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

#### msdb.dbo.syscategories

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| category_id | カテゴリ識別 | SMOオブジェクト経由 |
| name | カテゴリ名表示 | SMOオブジェクト経由 |
| category_type | カテゴリ種別（アラート用=2） | アラートカテゴリのみ対象 |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| msdb.dbo.syscategories | DELETE | 指定カテゴリの削除 |
| msdb.dbo.sysalerts | UPDATE | 削除カテゴリに属するアラートを[Uncategorized]に再割り当て |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 接続エラー | SQL Serverインスタンスに接続できない | 接続情報を確認し再試行 |
| 権限エラー | sysadmin権限がない | 適切な権限を持つアカウントで再実行 |
| SMOエラー | Drop操作失敗 | エラーメッセージを確認し原因対処 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（自動リトライなし） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A（手動で再実行が必要） |

## 配信設定

### レート制限

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

### 配信時間帯

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

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

- SQL Serverインスタンスへのsysadmin権限が必要
- SqlCredentialパラメータを使用して安全に認証情報を渡すことが可能
- WhatIfパラメータを使用して、実行前に影響を確認可能
- ConfirmImpactがHighに設定されているため、デフォルトで確認プロンプトが表示される

## 備考

- 削除されたカテゴリに属していたアラートは自動的に `[Uncategorized]` カテゴリに再割り当てされる
- Get-DbaAgentAlertCategoryとパイプラインで連携し、Out-GridViewを使用した対話的な選択削除が可能
- endブロックで削除処理を行うことで、パイプライン入力時の「コレクション変更」エラーを回避

---

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

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

### 推奨読解順序

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

まず、処理対象となるアラートカテゴリオブジェクトと出力オブジェクトの構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Remove-DbaAgentAlertCategory.ps1 | `public/Remove-DbaAgentAlertCategory.ps1` | 119-126行目でPSCustomObject出力構造を確認 |

**読解のコツ**: SMOオブジェクト `Microsoft.SqlServer.Management.Smo.Agent.AlertCategory` は Parent プロパティを通じてJobServer、さらにその親としてServerオブジェクトにアクセスできます。`$agentCategory.Parent.Parent` でServerオブジェクトを参照しています。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Remove-DbaAgentAlertCategory.ps1 | `public/Remove-DbaAgentAlertCategory.ps1` | 1-98行目でfunction宣言とパラメータ定義を確認 |

**主要処理フロー**:
1. **86-98行目**: パラメータ定義（NonPipelineとPipelineの2つのParameterSet）
2. **100-102行目**: beginブロックで空配列を初期化
3. **104-113行目**: processブロックでカテゴリを収集
4. **115-139行目**: endブロックで実際の削除処理

#### Step 3: 依存コマンドを理解する

Get-DbaAgentAlertCategoryコマンドとの連携を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaAgentAlertCategory.ps1 | `public/Get-DbaAgentAlertCategory.ps1` | カテゴリ取得ロジックを確認 |

**主要処理フロー**:
- **109行目**: SqlInstance指定時にGet-DbaAgentAlertCategoryを呼び出してカテゴリを取得

#### Step 4: 削除処理の詳細を理解する

endブロックでの削除処理とエラーハンドリングを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Remove-DbaAgentAlertCategory.ps1 | `public/Remove-DbaAgentAlertCategory.ps1` | 115-139行目で削除処理とエラーハンドリングを確認 |

**主要処理フロー**:
- **117-118行目**: foreachループとShouldProcess確認
- **127-130行目**: Drop()メソッド呼び出しと成功時の処理
- **131-135行目**: catch節でのエラー処理

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

```
Remove-DbaAgentAlertCategory
    |
    +-- [beginブロック]
    |       +-- $agentCategories = @( ) 初期化
    |
    +-- [processブロック]
    |       +-- SqlInstance指定時
    |       |       +-- Get-DbaAgentAlertCategory
    |       |               +-- Connect-DbaInstance
    |       |               +-- $server.JobServer.AlertCategories
    |       +-- InputObject指定時
    |               +-- $agentCategories に追加
    |
    +-- [endブロック]
            +-- foreach ($agentCategory in $agentCategories)
                    +-- ShouldProcess確認
                    +-- PSCustomObject作成
                    +-- $agentCategory.Drop()
                    +-- 成功/失敗に応じてStatus設定
                    +-- 出力
```

### データフロー図

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

SqlInstance ──────────────────> Get-DbaAgentAlertCategory ─┐
                                                           │
Category[] ─────────────────────────────────────────────────┼────> $agentCategories
                                                           │
InputObject (Pipeline) ────────────────────────────────────┘
                                        |
                                        v
                               ┌────────────────────┐
                               │ foreach + Drop()   │
                               └────────────────────┘
                                        |
                                        v
                               PSCustomObject ────────> パイプライン出力
                               - ComputerName
                               - InstanceName
                               - SqlInstance
                               - Name
                               - Status
                               - IsRemoved
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Remove-DbaAgentAlertCategory.ps1 | `public/Remove-DbaAgentAlertCategory.ps1` | ソース | アラートカテゴリ削除の本体 |
| Get-DbaAgentAlertCategory.ps1 | `public/Get-DbaAgentAlertCategory.ps1` | ソース | カテゴリ取得（依存コマンド） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Stop-Function.ps1 | `internal/functions/Stop-Function.ps1` | ソース | エラーハンドリング共通関数 |
| Get-ErrorMessage.ps1 | `internal/functions/Get-ErrorMessage.ps1` | ソース | エラーメッセージ取得 |
