# 機能設計書 146-Get-DbaRunningJob

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける`Get-DbaRunningJob`コマンドレットの機能設計を定義する。本機能は、現在実行中のSQL Server Agentジョブを取得し、ジョブ実行状況のリアルタイム監視を可能にする。

### 本機能の処理概要

`Get-DbaRunningJob`は、SQL Server Agentで現在実行中（Idle状態以外）のジョブを取得するコマンドレットである。ジョブ情報をリフレッシュして最新の実行状態を取得し、アイドル状態のジョブを除外して返す。

**業務上の目的・背景**：メンテナンスウィンドウ中のジョブ実行監視、パフォーマンス問題発生時のリソース消費ジョブの特定、メンテナンス作業前のジョブ実行状況確認など、様々な運用シーンでリアルタイムのジョブ実行状況把握が必要となる。本機能は、Get-DbaAgentJobの結果からアイドル状態以外のジョブのみを抽出し、実行中ジョブの迅速な特定を支援する。

**機能の利用シーン**：
- メンテナンスウィンドウ中のジョブ実行監視
- パフォーマンス問題のトラブルシューティング
- メンテナンス作業前のジョブ実行確認
- 長時間実行ジョブの検出
- ジョブスケジュール競合の確認

**主要な処理内容**：
1. SqlInstance指定時：Connect-DbaInstanceで接続し、JobServer.Jobs.Refreshで情報更新
2. Get-DbaAgentJobで全ジョブ取得（-IncludeExecution付き）
3. CurrentRunStatusがIdle以外のジョブをフィルタリング
4. InputObject（パイプライン入力）の場合も個別にRefreshして状態確認
5. 実行中ジョブをパイプライン出力

**関連システム・外部連携**：
- SQL Server Agent（ジョブ実行エンジン）
- Get-DbaAgentJob（ジョブ情報取得）
- Connect-DbaInstance（SQL Server接続）

**権限による制御**：SQL Server Agentジョブ情報の参照には、msdbデータベースへの適切な権限（SQLAgentReaderRole以上）が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIコマンド | 主機能 | 実行中ジョブ取得 |

## 機能種別

情報取得処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | パイプライン入力対応 |
| SqlCredential | PSCredential | No | SQL Server認証用クレデンシャル | - |
| InputObject | Microsoft.SqlServer.Management.Smo.Agent.Job[] | No | Get-DbaAgentJobからのパイプライン入力 | パイプライン入力対応 |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

- SQL Server Agent JobServer.Jobs コレクション
- パイプラインからのジョブオブジェクト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverホストのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Name | string | ジョブ名 |
| CurrentRunStatus | string | 現在の実行状態（Executing, Suspended等） |
| IsEnabled | bool | ジョブが有効かどうか |
| LastRunOutcome | string | 最終実行結果（Succeeded, Failed, Cancelled等） |
| LastRunDate | datetime | 最終実行日時 |
| NextRunDate | datetime | 次回実行予定日時 |
| Owner | string | ジョブ所有者 |
| CreateDate | datetime | ジョブ作成日時 |
| Description | string | ジョブの説明 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. SqlInstanceパラメータ処理
   ├─ Connect-DbaInstanceで接続
   ├─ JobServer.Jobs.Refresh($true)で情報更新
   └─ Get-DbaAgentJob -IncludeExecutionでジョブ取得
2. ステータスフィルタリング
   └─ CurrentRunStatus -ne 'Idle'でフィルタ
3. InputObjectパラメータ処理
   ├─ 各ジョブをRefresh()で更新
   └─ CurrentRunStatus -ne 'Idle'でフィルタ
4. 結果出力
   └─ Jobオブジェクトをパイプライン出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance<br/>指定あり?}
    B -->|Yes| C[SqlInstanceループ]
    C --> D[Connect-DbaInstance]
    D --> E{接続成功?}
    E -->|No| F[Stop-Function:<br/>接続エラー]
    E -->|Yes| G[JobServer.Jobs.Refresh<br/>$true]
    G --> H[Get-DbaAgentJob<br/>-IncludeExecution]
    H --> I[Where-Object<br/>CurrentRunStatus -ne Idle]
    I --> J[結果出力]
    B -->|No| K{InputObject<br/>あり?}
    K -->|Yes| L[InputObjectループ]
    L --> M[job.Refresh]
    M --> N[Where-Object<br/>CurrentRunStatus -ne Idle]
    N --> O[結果出力]
    K -->|No| P[終了]
    J --> Q{次のInstance<br/>あり?}
    Q -->|Yes| C
    Q -->|No| K
    O --> R{次のJob<br/>あり?}
    R -->|Yes| L
    R -->|No| P
    F --> Q
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | アイドル除外 | CurrentRunStatusが'Idle'のジョブは出力しない | 常時 |
| BR-002 | 情報リフレッシュ | ジョブ情報は取得前にRefreshして最新化 | 常時 |
| BR-003 | 子オブジェクト更新 | Jobs.Refresh($true)で子オブジェクトも更新 | SqlInstance指定時 |
| BR-004 | 実行情報含む | Get-DbaAgentJobは-IncludeExecutionオプション付きで呼び出し | SqlInstance指定時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ジョブ情報取得 | msdb.dbo.sysjobs等 | SELECT | SQL Agent SMO経由でジョブ情報取得 |

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

本機能はSMO経由でのアクセスのため、直接のSQL実行は行わない。内部的にはmsdbシステムテーブルが参照される。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 接続エラー | SQL Server接続失敗 | 接続情報・ネットワーク確認 |
| - | 権限エラー | SQL Agent情報へのアクセス権限不足 | 適切な権限付与 |

### リトライ仕様

リトライは実装されていない。接続エラー時はStop-Functionで処理継続（-Continue）。

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

読み取り専用のためトランザクション制御なし。

## パフォーマンス要件

- Jobs.Refresh($true)は全ジョブ情報を更新するため、大量ジョブ環境では時間がかかる可能性
- 複数インスタンス指定時は順次処理

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

- SQL Server認証またはWindows認証でアクセス
- msdbデータベースへの参照権限が必要
- SqlCredentialパラメータで認証情報を安全に渡せる

## 備考

- CurrentRunStatusの値: Idle, Executing, Suspended, BetweenRetries, WaitingForStepToFinish, WaitingForWorkerThread, PerformingCompletionActions
- 実行中ジョブがない場合は何も返さない

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaRunningJob.ps1 | `public/Get-DbaRunningJob.ps1` | 出力はSMO Agent.Jobオブジェクト |

**読解のコツ**: 出力はMicrosoft.SqlServer.Management.Smo.Agent.Jobオブジェクトそのもの。Get-DbaAgentJobの出力と同じ形式で、Select-DefaultViewによりデフォルト表示プロパティが設定されている。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaRunningJob.ps1 | `public/Get-DbaRunningJob.ps1` | 全体処理フロー（120行） |

**主要処理フロー**:
1. **102-113行目**: SqlInstanceパラメータ処理
2. **103-108行目**: Connect-DbaInstanceで接続、エラー時Continue
3. **111行目**: JobServer.Jobs.Refresh($true)で情報更新
4. **112行目**: Get-DbaAgentJob -IncludeExecution | Where-Object
5. **114-118行目**: InputObjectパラメータ処理
6. **116行目**: 個別ジョブのRefresh()
7. **117行目**: Where-Object CurrentRunStatus -ne 'Idle'

#### Step 3: 依存機能を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaAgentJob.ps1 | `public/Get-DbaAgentJob.ps1` | ジョブ取得機能 |
| 3-2 | Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | SQL Server接続 |

**主要処理フロー**:
- Get-DbaAgentJobは-IncludeExecutionオプションでCurrentRunStatusを含むジョブ情報を取得
- Connect-DbaInstanceはSMO Serverオブジェクトを返す

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

```
Get-DbaRunningJob
    │
    ├─ Connect-DbaInstance
    │      └─ SMO Server接続
    │
    ├─ $server.JobServer.Jobs.Refresh($true)
    │      └─ 全ジョブ情報リフレッシュ
    │
    ├─ Get-DbaAgentJob -IncludeExecution
    │      └─ ジョブ一覧取得
    │
    └─ Where-Object CurrentRunStatus -ne 'Idle'
           └─ 実行中ジョブのみフィルタ
```

### データフロー図

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

SqlInstance ────▶ Connect-DbaInstance
                        │
                        ▼
                  SMO Server
                        │
                        ▼
                  JobServer.Jobs.Refresh($true)
                        │
                        ▼
                  Get-DbaAgentJob
                  -IncludeExecution
                        │
                        ▼
                  Where-Object
                  CurrentRunStatus -ne 'Idle'
                        │
                        ▼
                  [Agent.Job Object] ─────▶ パイプライン

InputObject ────▶ job.Refresh()
(Agent.Job)            │
                       ▼
                  Where-Object
                  CurrentRunStatus -ne 'Idle'
                        │
                        ▼
                  [Agent.Job Object] ─────▶ パイプライン
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaRunningJob.ps1 | `public/Get-DbaRunningJob.ps1` | ソース | メイン機能 |
| Get-DbaAgentJob.ps1 | `public/Get-DbaAgentJob.ps1` | ソース | ジョブ取得機能 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
