# 機能設計書 506-Remove-DbaAgentJob

## 概要

本ドキュメントは、SQL Server Agent ジョブを削除する `Remove-DbaAgentJob` コマンドの機能設計書である。

### 本機能の処理概要

**業務上の目的・背景**：SQL Server Agent ジョブは自動化タスクの中核を担うが、アプリケーションの廃止、テスト環境のクリーンアップ、サーバー統合などで不要になることがある。本コマンドは、システムストアドプロシージャ sp_delete_job を使用してジョブを削除し、オプションでジョブ履歴や未使用スケジュールの保持を選択できる。複数インスタンスへの一括削除やパイプラインを通じた選択的削除をサポートする。

**機能の利用シーン**：アプリケーション廃止に伴うジョブの削除、テスト環境のジョブクリーンアップ、サーバー統合プロジェクトでの obsolete ジョブ削除、コンプライアンス要件のため履歴を保持しながらのジョブ削除などに利用される。

**主要な処理内容**：
1. 対象インスタンスへの接続（Connect-DbaInstance 使用）
2. 指定されたジョブの存在確認
3. パイプライン入力またはパラメータ指定によるジョブオブジェクト収集
4. ShouldProcess による削除確認
5. sp_delete_job を使用したジョブ削除（履歴・スケジュール保持オプション付き）
6. Tepp キャッシュからのジョブ名削除
7. 削除結果のステータスオブジェクト出力

**関連システム・外部連携**：SQL Server Agent サービス、msdb データベース

**権限による制御**：対象インスタンスで sysadmin 権限または SQLAgentOperatorRole が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 8 | Agentジョブ管理 | 主画面 | SQLエージェントジョブの削除 |

## 機能種別

CRUD操作（Delete）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | 接続可能なインスタンス名 |
| SqlCredential | PSCredential | No | 代替認証情報 | - |
| Job | object[] | No | 削除するジョブ名 | 存在するジョブ名 |
| KeepHistory | switch | No | ジョブ履歴を保持 | - |
| KeepUnusedSchedule | switch | No | 未使用スケジュールを保持 | - |
| InputObject | Job[] | No | パイプライン入力用ジョブオブジェクト | SMO Jobオブジェクト |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

PowerShell コマンドラインからのパラメータ入力、または Get-DbaAgentJob からのパイプライン入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Name | string | 削除されたジョブ名 |
| Status | string | 削除結果（"Dropped" または "Failed. {エラーメッセージ}"） |

### 出力先

PowerShell パイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. processブロック
   ├─ Job パラメータの null/空チェック
   │   └─ null/空/空白のみの場合はスキップ
   ├─ 各 SqlInstance に対するループ
   │   ├─ インスタンス接続
   │   └─ 各 Job 名に対するループ
   │       ├─ ジョブ存在確認
   │       └─ 存在すれば InputObject に追加
   └─ 各 InputObject（ジョブ）に対するループ
       ├─ ShouldProcess による確認
       ├─ KeepHistory/KeepUnusedSchedule に応じたフラグ設定
       ├─ sp_delete_job 実行
       ├─ JobServer.Jobs.Refresh()
       ├─ Tepp キャッシュからの削除
       └─ 結果オブジェクト出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Job パラメータ有効?}
    B -->|No| C[スキップ]
    B -->|Yes| D[インスタンス接続]
    D --> E{ジョブ存在?}
    E -->|No| F[エラー出力、次へ]
    E -->|Yes| G[InputObjectに追加]
    G --> H{ShouldProcess確認}
    F --> H
    C --> H
    H -->|No| I{次のジョブ?}
    H -->|Yes| J{KeepHistory?}
    J -->|Yes| K[dropHistory=0]
    J -->|No| L[dropHistory=1]
    K --> M{KeepUnusedSchedule?}
    L --> M
    M -->|Yes| N[dropSchedule=0]
    M -->|No| O[dropSchedule=1]
    N --> P[sp_delete_job実行]
    O --> P
    P --> Q{成功?}
    Q -->|Yes| R[Status=Dropped]
    Q -->|No| S[Status=Failed]
    R --> T[結果出力]
    S --> T
    T --> I
    I -->|Yes| H
    I -->|No| U[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-506-01 | 履歴保持オプション | KeepHistory 指定時、sysjobhistory テーブルのレコードを保持 | KeepHistory 指定時 |
| BR-506-02 | スケジュール保持オプション | KeepUnusedSchedule 指定時、他のジョブで使用されていないスケジュールを保持 | KeepUnusedSchedule 指定時 |
| BR-506-03 | ジョブ存在確認 | 指定されたジョブが存在しない場合、エラーメッセージを出力して処理継続 | 常時 |
| BR-506-04 | 確認プロンプト | ConfirmImpact が High のため、削除前に確認プロンプトを表示 | 常時 |
| BR-506-05 | null/空チェック | Job パラメータが null/空/空白のみの場合はスキップ（未初期化変数対策） | Job パラメータ指定時 |

### 計算ロジック

**sp_delete_job パラメータ設定**：
- @delete_history: KeepHistory 指定時 = 0、未指定時 = 1
- @delete_unused_schedule: KeepUnusedSchedule 指定時 = 0、未指定時 = 1

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ジョブ削除 | msdb.dbo.sysjobs | DELETE | sp_delete_job 経由でジョブレコード削除 |
| ジョブステップ削除 | msdb.dbo.sysjobsteps | DELETE | ジョブ削除時に自動削除 |
| ジョブスケジュール削除 | msdb.dbo.sysjobschedules | DELETE | ジョブ-スケジュール関連付け削除 |
| スケジュール削除 | msdb.dbo.sysschedules | DELETE | 未使用スケジュール削除（KeepUnusedSchedule未指定時） |
| ジョブ履歴削除 | msdb.dbo.sysjobhistory | DELETE | ジョブ履歴削除（KeepHistory未指定時） |

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

#### msdb.dbo.sysjobs

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | job_id | sp_delete_job @job_name で指定 | ジョブ本体削除 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 接続エラー | インスタンスへの接続失敗 | Stop-Function で処理継続 |
| - | 存在エラー | 指定ジョブが存在しない | Stop-Function で処理継続 |
| - | 削除エラー | sp_delete_job 実行失敗 | Status に "Failed. {エラー}" を設定 |

### リトライ仕様

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

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

sp_delete_job システムストアドプロシージャによる暗黙的トランザクション。

## パフォーマンス要件

特に定義されていない。

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

- 対象インスタンスへの sysadmin 権限または SQLAgentOperatorRole が必要
- ジョブ名はシングルクォートをエスケープして SQL インジェクションを防止

## 備考

- sp_delete_job を直接使用（SMO の Drop() メソッドではなく）
- Get-DbaAgentJob からのパイプライン入力をサポート
- 複数インスタンスへの一括削除をサポート

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造とパラメータを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Remove-DbaAgentJob.ps1 | `public/Remove-DbaAgentJob.ps1` | 88-98行目: パラメータ定義 |

**読解のコツ**: KeepHistory と KeepUnusedSchedule が sp_delete_job のオプションに対応する。

#### Step 2: ジョブ収集処理を理解する

process ブロックでのジョブオブジェクト収集。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Remove-DbaAgentJob.ps1 | `public/Remove-DbaAgentJob.ps1` | 99-121行目: ジョブ収集処理 |

**主要処理フロー**:
1. **101-106行目**: Job パラメータの null/空チェック（未初期化変数対策）
2. **108-120行目**: SqlInstance ループでジョブ存在確認と InputObject 追加

#### Step 3: 削除処理を理解する

sp_delete_job を使用した削除処理。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Remove-DbaAgentJob.ps1 | `public/Remove-DbaAgentJob.ps1` | 122-163行目: 削除処理ループ |

**主要処理フロー**:
- **128-137行目**: KeepHistory/KeepUnusedSchedule に応じたフラグ設定
- **139行目**: sp_delete_job クエリ構築（シングルクォートエスケープ付き）
- **140行目**: ExecuteNonQuery で実行
- **141行目**: JobServer.Jobs.Refresh()
- **142行目**: Tepp キャッシュからの削除

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

```
Remove-DbaAgentJob
    │
    ├─ Connect-DbaInstance (110行目)
    │      └─ SQL Server インスタンスへの接続確立
    │
    ├─ $server.Databases['msdb'].ExecuteNonQuery() (140行目)
    │      └─ sp_delete_job ストアドプロシージャ実行
    │
    ├─ $server.JobServer.Jobs.Refresh() (141行目)
    │      └─ ジョブコレクションの更新
    │
    └─ Remove-TeppCacheItem (142行目)
           └─ タブ補完キャッシュからの削除
```

### データフロー図

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

SqlInstance ──┬──▶ Connect-DbaInstance ──▶ Server オブジェクト
Job ──────────┘           │
                          ▼
              ジョブ存在確認
                          │
InputObject ─────────────▶│
                          ▼
              sp_delete_job 構築
              @job_name = '{ジョブ名}'
              @delete_history = {0|1}
              @delete_unused_schedule = {0|1}
                          │
                          ▼
              ExecuteNonQuery 実行
                          │
                          ▼
              PSCustomObject出力
              (ComputerName, InstanceName,
               SqlInstance, Name, Status)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Remove-DbaAgentJob.ps1 | `public/Remove-DbaAgentJob.ps1` | ソース | メインコマンド実装 |
| Get-DbaAgentJob.ps1 | `public/Get-DbaAgentJob.ps1` | ソース | ジョブ取得（パイプライン入力用） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続 |
