# 画面設計書 164-実行中ジョブ

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける実行中ジョブ取得機能（Get-DbaRunningJob）の画面設計書です。SQL Server Agentで現在実行中のジョブをリアルタイムで取得する機能を提供します。

### 本画面の処理概要

**業務上の目的・背景**：SQL Server Agentジョブの実行状況監視は、メンテナンスウィンドウの管理、パフォーマンス問題の調査、メンテナンス作業前の確認など、様々な運用シーンで必要とされます。本機能は、アイドル状態ではない（実行中の）ジョブのみを抽出し、リアルタイムの実行状態を効率的に把握できるようにします。

**画面へのアクセス方法**：PowerShellコマンドラインから `Get-DbaRunningJob` コマンドレットを実行してアクセスします。複数インスタンスの一括監視や、Get-DbaAgentJobからのパイプライン入力にも対応しています。

**主要な操作・処理内容**：
1. SQL Serverインスタンスに接続し、JobServerのジョブ情報を最新に更新
2. Get-DbaAgentJobで全ジョブ情報を取得（-IncludeExecutionオプション付き）
3. CurrentRunStatusがIdle以外のジョブをフィルタリング
4. 実行中のジョブ情報をSMO Agent.Jobオブジェクトとして出力

**画面遷移**：本機能は単独のコマンドレットとして動作します。出力されたジョブオブジェクトはStop-DbaAgentJobなどにパイプで渡すことが可能です。

**権限による表示制御**：SQL Server Agent関連の情報取得にはmsdbデータベースへのアクセス権限が必要です。SQLAgentOperatorRoleまたはsysadmin権限が推奨されます。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 146 | Get-DbaRunningJob | 主機能 | 実行中ジョブの取得 |
| 485 | Get-DbaAgentJob | 内部呼出 | ジョブ情報の取得（-IncludeExecution付き） |
| 327 | Connect-DbaInstance | 内部呼出 | SQL Serverインスタンスへの接続 |

## 画面種別

CLI（コマンドラインインターフェース）- 監視

## URL/ルーティング

PowerShellコマンド: `Get-DbaRunningJob`

## 入出力項目

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | No* | 接続先SQL Serverインスタンス |
| SqlCredential | PSCredential | No | SQL Server認証用の資格情報 |
| InputObject | Microsoft.SqlServer.Management.Smo.Agent.Job[] | No* | Get-DbaAgentJobからのパイプライン入力 |
| EnableException | switch | No | 例外を有効化 |

*SqlInstanceまたはInputObjectのいずれかが必要

### 出力項目

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

※ 出力はSMO Agent.Jobオブジェクトであり、上記以外にも多数のプロパティにアクセス可能

## 表示項目

Get-DbaAgentJobから継承したSelect-DefaultViewにより、主要プロパティのみがデフォルト表示されます。

## イベント仕様

### 1-SqlInstance指定時の実行

1. **SQL Server接続**（行104-108）: Connect-DbaInstanceでSQL Serverに接続
2. **ジョブ情報更新**（行111）: JobServer.Jobs.Refresh($true)で最新情報に更新
3. **ジョブ取得・フィルタ**（行112）: Get-DbaAgentJobで取得し、CurrentRunStatus -ne 'Idle'でフィルタリング

### 2-InputObject指定時の実行

1. **ジョブ情報更新**（行116）: 各ジョブの$job.Refresh()で最新情報に更新
2. **フィルタリング**（行117）: CurrentRunStatus -ne 'Idle'でフィルタリング

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| ジョブ情報取得 | msdb.dbo.sysjobs | SELECT | ジョブ定義の参照 |
| ジョブ状態取得 | msdb.dbo.sysjobactivity | SELECT | ジョブ実行状態の参照 |

## メッセージ仕様

| メッセージタイプ | 条件 | メッセージ内容 |
|-----------------|------|---------------|
| Error | 接続失敗時 | "Failure" - ConnectionError |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| SQL Server接続失敗 | Stop-Functionでエラーを記録し、次のインスタンスの処理を継続 |
| 実行中ジョブなし | 空の結果を返す（エラーにはならない） |

## 備考

- Refresh($true)により子オブジェクトを含む最新情報が取得される
- キャッシュされた古い情報ではなく、リアルタイムの実行状態を取得するために常にRefreshが呼ばれる
- 複数インスタンスの一括監視に最適
- Get-DbaAgentJobとの連携により、特定のジョブセットの実行状態監視も可能

---

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

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

### 推奨読解順序

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

SMO Agent.Jobオブジェクトの構造と出力形式を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaRunningJob.ps1 | `public/Get-DbaRunningJob.ps1` | 行42-75の.OUTPUTSセクションでAgent.Jobプロパティを確認 |

**読解のコツ**: CurrentRunStatusプロパティがジョブの実行状態を示す（Executing/Idle/Suspended等）。

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

Get-DbaRunningJobの主要処理フローを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaRunningJob.ps1 | `public/Get-DbaRunningJob.ps1` | 行93-101のパラメータ定義 |

**主要処理フロー**:
1. **行102**: processブロック開始
2. **行103**: SqlInstanceごとのループ処理
3. **行104-108**: Connect-DbaInstanceで接続

#### Step 3: ジョブ情報更新処理を理解する

Refreshによる最新情報取得の重要性を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaRunningJob.ps1 | `public/Get-DbaRunningJob.ps1` | 行110-112のジョブ情報更新とフィルタリング |

**主要処理フロー**:
- **行111**: $server.JobServer.Jobs.Refresh($true) - 子オブジェクト含む完全更新
- **行112**: Get-DbaAgentJob -IncludeExecution | Where-Object CurrentRunStatus -ne 'Idle'

#### Step 4: InputObject処理を理解する

パイプライン入力時の処理を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaRunningJob.ps1 | `public/Get-DbaRunningJob.ps1` | 行114-118のInputObject処理 |

**主要処理フロー**:
- **行115**: InputObjectの各ジョブをループ
- **行116**: $job.Refresh() - 個別ジョブの更新
- **行117**: CurrentRunStatus -ne 'Idle' でフィルタ

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

```
Get-DbaRunningJob
    |
    +-- [SqlInstance指定時]
    |       |
    |       +-- Connect-DbaInstance (行105)
    |       |       └── SQL Serverへの接続
    |       |
    |       +-- $server.JobServer.Jobs.Refresh($true) (行111)
    |       |       └── ジョブ情報の最新化
    |       |
    |       └── Get-DbaAgentJob -IncludeExecution (行112)
    |               └── Where-Object CurrentRunStatus -ne 'Idle'
    |
    └── [InputObject指定時]
            |
            +-- $job.Refresh() (行116)
            |       └── 個別ジョブの最新化
            |
            └── Where-Object CurrentRunStatus -ne 'Idle' (行117)
```

### データフロー図

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

SqlInstance ─────────────┐
                         │
                         └──> Connect-DbaInstance
                                    │
                                    v
                              JobServer.Jobs.Refresh($true)
                                    │
                                    v
                              Get-DbaAgentJob
                                    │
                                    v
                              CurrentRunStatus フィルタ ──────> Agent.Job オブジェクト
                                    ^                         （実行中のみ）
                                    │
InputObject ─────────────────> $job.Refresh()
                                    │
                                    v
                              CurrentRunStatus フィルタ ──────> Agent.Job オブジェクト
                                                              （実行中のみ）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaRunningJob.ps1 | `public/Get-DbaRunningJob.ps1` | ソース | 実行中ジョブ取得の実装 |
| Get-DbaAgentJob.ps1 | `public/Get-DbaAgentJob.ps1` | ソース | ジョブ情報取得（内部呼出） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
