# 機能設計書 522-Stop-DbaAgentJob

## 概要

本ドキュメントは、実行中の SQL Server Agent ジョブを停止する `Stop-DbaAgentJob` コマンドの機能設計書です。

### 本機能の処理概要

実行中の SQL Server Agent ジョブを停止し、停止後のジョブオブジェクトを返す PowerShell コマンドです。SMO の Stop() メソッドを呼び出してジョブを停止します。

**業務上の目的・背景**：SQL Server Agent ジョブの実行中に問題が発生した場合（長時間実行、リソース消費過多、ブロッキング発生など）、迅速にジョブを停止する必要があります。本コマンドは PowerShell からプログラム的にジョブを停止することで、SSMS を開かずに即座に対応できます。メンテナンスウィンドウ前のジョブ停止や、トラブルシューティング時の迅速な対応に不可欠です。

**機能の利用シーン**：
- 暴走しているジョブの緊急停止
- メンテナンスウィンドウ開始前の全ジョブ停止
- パフォーマンス問題を引き起こしているジョブの停止
- ブロッキングチェーンの原因となっているジョブの停止
- CI/CD パイプラインからのジョブ制御

**主要な処理内容**：
1. SQL Server インスタンスへの接続確立
2. 指定されたジョブまたは全ジョブの取得
3. ジョブの現在のステータス確認（Idle状態はスキップ）
4. SMO の Stop() メソッド呼び出し
5. ステータス変化の確認
6. 完了待機（-Wait パラメータ使用時）
7. 停止後のジョブオブジェクト出力

**関連システム・外部連携**：SQL Server Agent サービス、SMO (SQL Server Management Objects)

**権限による制御**：SQLAgentOperatorRole 以上の権限が必要です。ジョブの所有者または sysadmin 権限を持つユーザーのみがジョブを停止できます。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | SQL Server Management Studio - SQL Server Agent Jobs | 参照画面 | GUI でのジョブ停止操作と同等の機能を提供 |

## 機能種別

システム操作 / ジョブ制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes (Instance ParameterSet) | 対象の SQL Server インスタンス | 有効なインスタンス名 |
| SqlCredential | PSCredential | No | 代替認証情報 | 有効な資格情報オブジェクト |
| Job | string[] | No | 停止するジョブ名の配列 | - |
| ExcludeJob | string[] | No | 除外するジョブ名 | - |
| InputObject | Microsoft.SqlServer.Management.Smo.Agent.Job[] | Yes (Object ParameterSet) | パイプラインからのジョブオブジェクト | 有効な Job オブジェクト |
| Wait | switch | No | ジョブ完全停止まで待機 | - |
| EnableException | switch | No | 例外をスローする | - |

### 入力データソース

- SQL Server Agent JobServer オブジェクト経由でジョブ情報を取得
- パイプラインからのジョブオブジェクト入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Name | string | ジョブ名 |
| Enabled | bool | ジョブが有効かどうか |
| CurrentRunStatus | string | 現在の実行ステータス |
| LastRunOutcome | string | 最後の実行結果 |
| LastRunDate | DateTime | 最後の実行日時 |
| NextRunDate | DateTime | 次回実行予定日時 |
| OwnerLoginName | string | ジョブ所有者 |

### 出力先

- PowerShell パイプライン出力（Microsoft.SqlServer.Management.Smo.Agent.Job オブジェクト）

## 処理フロー

### 処理シーケンス

```
1. SQL Server インスタンスへの接続
   └─ Connect-DbaInstance を使用
2. ジョブオブジェクトの収集
   └─ 全ジョブまたは指定ジョブを取得
   └─ -Job フィルター適用
   └─ -ExcludeJob 除外適用
3. 各ジョブの処理ループ
   └─ ステータス確認（Idleはスキップ）
   └─ ShouldProcess 確認
   └─ Stop() メソッド呼び出し
   └─ 初期待機（300ms）
   └─ Refresh() でステータス更新
4. ステータス変化待機ループ（最大10回）
   └─ 100ms 間隔でステータス確認
5. -Wait 指定時の完全停止待機
   └─ 3秒間隔でポーリング
6. ジョブオブジェクト出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[SQL Server 接続]
    B --> C[ジョブ収集]
    C --> D[各ジョブをループ]
    D --> E{ステータス=Idle?}
    E -->|Yes| F[スキップ・警告出力]
    E -->|No| G{ShouldProcess?}
    G -->|No| F
    G -->|Yes| H[Stop() 呼び出し]
    H --> I[300ms 待機]
    I --> J[Refresh()]
    J --> K[ステータス変化待機]
    K --> L{-Wait指定?}
    L -->|Yes| M[完全停止待機ループ]
    L -->|No| N[ジョブオブジェクト出力]
    M --> N
    F --> O{次のジョブ?}
    N --> O
    O -->|Yes| D
    O -->|No| P[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | Idle状態チェック | Idle 状態のジョブは停止対象外 | 常時 |
| BR-002 | 初期待機 | Stop() 後 300ms の初期待機 | 常時 |
| BR-003 | ステータス変化確認 | 最大10回、100ms間隔でステータス確認 | 常時 |
| BR-004 | 完全停止待機 | -Wait 指定時は 3秒間隔でポーリング | -Wait 指定時 |

### 計算ロジック

- 初期待機: 300ミリ秒（固定）
- ステータス確認ループ: 最大10回、100ms間隔
- 完全停止待機: 3秒間隔（-Wait 指定時）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ジョブ停止 | msdb.dbo.sysjobactivity | UPDATE (間接) | SMO 経由でジョブ停止 |
| ステータス確認 | msdb.dbo.sysjobactivity | SELECT (間接) | SMO 経由でステータス取得 |

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

#### msdb.dbo.sysjobs

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | job_id, name | 全ジョブまたは指定ジョブ | SMO の Jobs コレクション経由 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 接続エラー | SQL Server に接続できない | 接続情報を確認 |
| - | ステータス警告 | ジョブが既に Idle 状態 | 警告メッセージ出力、スキップ |
| - | 停止エラー | Stop() メソッドが失敗 | SMO エラーを確認 |

### リトライ仕様

ステータス変化確認で最大10回のリトライ（各100ms間隔）

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

SMO の Stop() メソッドを使用するため、SQL Server Agent サービスが内部的にトランザクション管理を行う

## パフォーマンス要件

- ジョブ停止指示自体は即座に完了
- 実際の停止完了までは現在実行中のステップに依存
- -Wait 使用時は完全停止まで待機

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

- SQLAgentOperatorRole 以上の権限が必要
- Windows 認証または SQL Server 認証をサポート
- MFA サポートは Connect-DbaInstance を経由

## 備考

- パイプライン入力で Get-DbaAgentJob と連携可能
- 実行中のジョブのみが停止対象となる
- ジョブの完全停止を確認するには -Wait パラメータを使用

---

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

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

### 推奨読解順序

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

SMO の Agent.Job オブジェクトが中心的なデータ構造です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | SMO Agent.Job | Microsoft.SqlServer.Management.Smo.Agent | Job オブジェクトの Stop() メソッドと CurrentRunStatus プロパティ |

**読解のコツ**: CurrentRunStatus が "Idle" に変わることで停止完了を確認します。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Stop-DbaAgentJob.ps1 | `public/Stop-DbaAgentJob.ps1` | 関数定義とパラメータセット |

**主要処理フロー**:
1. **94-105行目**: パラメータ定義
2. **107-123行目**: ジョブ収集とフィルタリング
3. **125-157行目**: 各ジョブの停止処理

#### Step 3: 停止ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Stop-DbaAgentJob.ps1 | `public/Stop-DbaAgentJob.ps1` | 停止処理の実装 |

**主要処理フロー**:
- **130-132行目**: Idle 状態チェック
- **135行目**: Stop() メソッド呼び出し
- **136-143行目**: 初期待機とステータス確認ループ
- **145-150行目**: -Wait 指定時の完全停止待機

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

```
Stop-DbaAgentJob
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server SMO 接続確立
    │
    ├─ $server.JobServer.Jobs
    │      └─ ジョブコレクション取得
    │
    ├─ $currentjob.Stop()
    │      └─ ジョブ停止
    │
    └─ $currentjob.Refresh()
           └─ ステータス更新
```

### データフロー図

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

SqlInstance ───▶ Connect-DbaInstance ───▶ SMO Server Object
                         │
Job/ExcludeJob ─▶ JobServer.Jobs Filter ───▶ Job Collection
                         │
                  job.Stop() ──────────────▶ Stop Signal
                         │
Wait ───────────▶ Polling Loop ─────────▶ Job Status Check
                         │
                  Job Object ──────────────▶ Pipeline Output
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Stop-DbaAgentJob.ps1 | `public/Stop-DbaAgentJob.ps1` | ソース | メイン関数定義 |
| Get-DbaAgentJob.ps1 | `public/Get-DbaAgentJob.ps1` | ソース | ジョブ情報取得（パイプライン連携） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server 接続 |
