# 機能設計書 486-Get-DbaAgentJobCategory

## 概要

本ドキュメントは、SQL Server Agent のジョブカテゴリと使用数を取得する Get-DbaAgentJobCategory 関数の機能設計書である。

### 本機能の処理概要

Get-DbaAgentJobCategory は、1つ以上の SQL Server インスタンスから SQL Server Agent ジョブカテゴリを取得し、各カテゴリに割り当てられているジョブの数を表示する機能を提供する。ジョブカテゴリは関連するジョブをグループ化して管理を容易にし、Database Maintenance、Log Shipping、Replication などの組み込みカテゴリとカスタムカテゴリの両方を返す。

**業務上の目的・背景**：大規模な SQL Server 環境では、ジョブを適切に分類することで管理が容易になる。ジョブカテゴリの構成を確認し、カテゴリ別のジョブ数を把握することで、ジョブ管理の最適化や整理が可能となる。MSX/TSX環境では、LocalJob と MultiServerJob のカテゴリタイプを区別することが重要。

**機能の利用シーン**：
- ジョブの組織構造の確認
- カテゴリ別ジョブ数の監査
- 未使用カテゴリの特定
- MSX/TSX環境でのカテゴリタイプ確認
- 新規カテゴリ作成前の既存カテゴリ確認

**主要な処理内容**：
1. 指定されたインスタンスへの接続
2. JobCategories コレクションの取得
3. Category/CategoryType パラメータによるフィルタリング
4. 各カテゴリに属するジョブ数のカウント
5. カスタムプロパティの追加と結果出力

**関連システム・外部連携**：SQL Server Agent の JobCategories コレクションを SMO 経由で取得。ジョブ数のカウントには Jobs コレクションを使用。

**権限による制御**：msdb データベースへの読み取りアクセスが必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 10 | ジョブカテゴリ管理 | 主機能 | SQLエージェントジョブカテゴリの取得 |

## 機能種別

データ取得 / 監査・レポーティング

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | パイプライン入力可 |
| SqlCredential | PSCredential | No | 認証用資格情報 | Windows/SQL認証対応 |
| Category | string[] | No | 取得するカテゴリ名 | ValidateNotNullOrEmpty |
| CategoryType | string | No | カテゴリタイプ（LocalJob/MultiServerJob/None） | ValidateSet |
| EnableException | Switch | No | 例外処理を有効化 | - |

### 入力データソース

SMO を介した SQL Server インスタンスの JobServer.JobCategories コレクションから取得。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | SQL Serverのコンピュータ名 |
| InstanceName | String | SQL Serverインスタンス名 |
| SqlInstance | String | 完全なインスタンス名 |
| Name | String | カテゴリ名 |
| ID | Int | カテゴリID |
| CategoryType | String | カテゴリタイプ（LocalJob/MultiServerJob/None） |
| JobCount | Int | カテゴリに属するジョブ数 |

### 出力先

パイプライン出力として Microsoft.SqlServer.Management.Smo.Agent.JobCategory オブジェクトを返す。

## 処理フロー

### 処理シーケンス

```
1. 各インスタンスに対してループ処理
   └─ Connect-DbaInstance で接続
   └─ 接続失敗時は Continue で次へ

2. JobCategories の取得とフィルタリング
   └─ Category パラメータ: 完全一致フィルタ
   └─ CategoryType パラメータ: タイプフィルタ

3. 各カテゴリに対するループ処理
   └─ ジョブ数のカウント（CategoryID一致）
   └─ カスタムプロパティの追加

4. 結果の出力
   └─ Select-DefaultView で表示プロパティ設定
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[インスタンスループ開始]
    B --> C[インスタンス接続]
    C --> D{接続成功?}
    D -->|No| B
    D -->|Yes| E[JobCategories取得]
    E --> F[Category/CategoryTypeフィルタ]
    F --> G[カテゴリループ開始]
    G --> H[ジョブ数カウント]
    H --> I[カスタムプロパティ追加]
    I --> J[Select-DefaultView]
    J --> K[結果出力]
    K --> L{次のカテゴリ?}
    L -->|Yes| G
    L -->|No| M{次のインスタンス?}
    M -->|Yes| B
    M -->|No| N[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | カテゴリフィルタ | Category/CategoryType は完全一致（-in 演算子） | パラメータ指定時 |
| BR-002 | ジョブ数計算 | CategoryID一致のジョブをカウント | 常時 |
| BR-003 | CategoryTypeオプション | LocalJob/MultiServerJob/None の3つのみ | CategoryType指定時 |

### 計算ロジック

**JobCount の計算**:
```powershell
$jobCount = ($server.JobServer.Jobs | Where-Object { $_.CategoryID -eq $cat.ID }).Count
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| カテゴリ取得 | msdb.dbo.syscategories | SELECT | ジョブカテゴリ一覧の取得（SMO経由） |
| ジョブ取得 | msdb.dbo.sysjobs | SELECT | カテゴリ別ジョブ数のカウント（SMO経由） |

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

本機能は読み取り専用であり、データベースへの書き込みは行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | インスタンス接続失敗 | Continue で次のインスタンスへ |
| CategoryError | カテゴリエラー | カテゴリ取得時のエラー | Stop-Function で警告出力、Continue |

### リトライ仕様

特になし。

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

読み取り専用のため、トランザクション制御は不要。

## パフォーマンス要件

- カテゴリ数は通常少数（20未満）のため、パフォーマンス問題は発生しにくい
- ジョブ数カウントのため、各カテゴリで Jobs コレクションを走査

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

- msdb データベースへの読み取りアクセスが必要
- SQL 認証を使用する場合、資格情報は PSCredential オブジェクトとして安全に渡される

## 備考

- Category パラメータは ValidateNotNullOrEmpty 属性付き
- CategoryType は LocalJob（単一インスタンスジョブ）、MultiServerJob（MSX/TSX環境）、None（未分類）の3種類
- JobCount プロパティは動的に計算されるカスタムプロパティ
- 組み込みカテゴリ（Database Maintenance、Log Shipping など）も含めて取得

---

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

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

### 推奨読解順序

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

パラメータ定義と出力プロパティの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaAgentJobCategory.ps1 | `public/Get-DbaAgentJobCategory.ps1` | 80-90行目: パラメータ定義 |
| 1-2 | Get-DbaAgentJobCategory.ps1 | `public/Get-DbaAgentJobCategory.ps1` | 40-59行目: .OUTPUTS ドキュメント |

**読解のコツ**: CategoryType の ValidateSet（LocalJob/MultiServerJob/None）と、JobCount がカスタムプロパティであることに注目。

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

処理の起点となる process ブロックを特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaAgentJobCategory.ps1 | `public/Get-DbaAgentJobCategory.ps1` | 92-124行目: processブロック全体 |

**主要処理フロー**:
1. **94-99行目**: インスタンスへの接続
2. **101-105行目**: JobCategories の取得とフィルタリング
3. **107行目**: デフォルト表示プロパティの定義

#### Step 3: ジョブ数カウントとプロパティ追加を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaAgentJobCategory.ps1 | `public/Get-DbaAgentJobCategory.ps1` | 109-122行目: カテゴリループとプロパティ追加 |

**主要処理フロー**:
- **111行目**: ジョブ数のカウント（CategoryID一致）
- **113-116行目**: Add-Member でカスタムプロパティ追加
- **118行目**: Select-DefaultView で表示プロパティ設定

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

```
Get-DbaAgentJobCategory
    │
    └─ [process] foreach ($instance in $SqlInstance)
           │
           ├─ Connect-DbaInstance
           │      └─ インスタンス接続
           │
           ├─ $server.JobServer.JobCategories
           │      └─ カテゴリコレクション取得
           │
           ├─ Where-Object フィルタ
           │      ├─ Category: -in でフィルタ
           │      └─ CategoryType: -in でフィルタ
           │
           └─ foreach ($cat in $jobCategories)
                  │
                  ├─ $server.JobServer.Jobs | Where-Object
                  │      └─ CategoryID 一致のジョブをカウント
                  │
                  ├─ Add-Member
                  │      ├─ ComputerName
                  │      ├─ InstanceName
                  │      ├─ SqlInstance
                  │      └─ JobCount
                  │
                  └─ Select-DefaultView
                         └─ 表示プロパティ設定
```

### データフロー図

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

SqlInstance ─────────────────▶ Connect-DbaInstance ─────────────▶ SMO Server
                                │
                                ▼
Category ────────────────────▶ $server.JobServer.JobCategories
CategoryType                    │
                                ▼
                          Where-Object フィルタ (-in)
                                │
                                ▼
                          foreach カテゴリ
                                │
                                ├──▶ Jobs.Where(CategoryID) ──▶ .Count
                                │
                                ▼
                          Add-Member (JobCount)
                                │
                                ▼
                          Select-DefaultView ─────────────────────▶ JobCategory Objects
                                                                    - Name
                                                                    - ID
                                                                    - CategoryType
                                                                    - JobCount
                                                                    ...
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaAgentJobCategory.ps1 | `public/Get-DbaAgentJobCategory.ps1` | ソース | メイン関数 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続 |
| Get-DbaAgentJob.ps1 | `public/Get-DbaAgentJob.ps1` | ソース | 関連機能（ジョブ取得） |
| New-DbaAgentJobCategory.ps1 | `public/New-DbaAgentJobCategory.ps1` | ソース | 関連機能（カテゴリ作成） |
| Remove-DbaAgentJobCategory.ps1 | `public/Remove-DbaAgentJobCategory.ps1` | ソース | 関連機能（カテゴリ削除） |
| Set-DbaAgentJobCategory.ps1 | `public/Set-DbaAgentJobCategory.ps1` | ソース | 関連機能（カテゴリ変更） |
