# 画面設計書：ジョブカテゴリ管理

## 1. 基本情報

| 項目 | 内容 |
|------|------|
| 画面ID | 10 |
| 画面名 | ジョブカテゴリ管理 |
| 画面種別 | CLI（コマンドラインインターフェース） |
| カテゴリ | Agent |
| 関連ファイル | public/Get-DbaAgentJobCategory.ps1, public/New-DbaAgentJobCategory.ps1, public/Remove-DbaAgentJobCategory.ps1 |

## 2. 概要・目的

ジョブカテゴリ管理は、SQL Server Agentジョブカテゴリの取得、作成、削除を行うPowerShellコマンド群です。

ジョブカテゴリは、関連するジョブをグループ化して管理やレポートを容易にするための仕組みです。SQL Serverには「Database Maintenance」「Log Shipping」「Replication」などの組み込みカテゴリがあり、DBAはカスタムカテゴリを作成することもできます。

## 3. 主要機能

### 3.1 Get-DbaAgentJobCategory

SQL Server Agentジョブカテゴリの情報を取得します。

**入力パラメータ：**

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| SqlInstance | DbaInstanceParameter[] | はい | - | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | いいえ | - | 代替認証情報 |
| Category | string[] | いいえ | - | 取得するカテゴリ名 |
| CategoryType | string | いいえ | - | カテゴリタイプ（LocalJob/MultiServerJob/None） |
| EnableException | switch | いいえ | false | 例外を有効化 |

**出力プロパティ：**

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | SQL Serverインスタンス名 |
| Name | string | カテゴリ名 |
| ID | int | カテゴリID |
| CategoryType | string | カテゴリタイプ |
| JobCount | int | 割り当てられたジョブ数 |

### 3.2 New-DbaAgentJobCategory

SQL Server Agentジョブカテゴリを作成します。

**入力パラメータ：**

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| SqlInstance | DbaInstanceParameter[] | はい | - | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | いいえ | - | 代替認証情報 |
| Category | string[] | はい | - | 作成するカテゴリ名 |
| CategoryType | string | いいえ | LocalJob | カテゴリタイプ |
| Force | switch | いいえ | false | 確認をスキップ |
| EnableException | switch | いいえ | false | 例外を有効化 |

**カテゴリタイプ：**

| 値 | 説明 |
|----|------|
| LocalJob | 単一インスタンスのジョブ（デフォルト） |
| MultiServerJob | マルチサーバー（MSX/TSX）環境のジョブ |
| None | 未分類 |

### 3.3 Remove-DbaAgentJobCategory

SQL Server Agentジョブカテゴリを削除します。

**入力パラメータ：**

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| SqlInstance | DbaInstanceParameter[] | 条件付き | - | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | いいえ | - | 代替認証情報 |
| Category | string[] | いいえ | - | 削除するカテゴリ名 |
| CategoryType | string[] | いいえ | - | カテゴリタイプでフィルタ |
| InputObject | JobCategory[] | 条件付き | - | パイプライン入力用カテゴリオブジェクト |
| EnableException | switch | いいえ | false | 例外を有効化 |

**出力プロパティ：**

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | SQL Serverインスタンス名 |
| Name | string | カテゴリ名 |
| Status | string | 操作ステータス（Dropped/エラー） |
| IsRemoved | bool | 削除成功フラグ |

## 4. 処理フロー

### 4.1 Get-DbaAgentJobCategory

```
[開始]
   ↓
[インスタンス接続]
   ├── Connect-DbaInstanceで接続
   ↓
[カテゴリ取得]
   ├── server.JobServer.JobCategories取得
   ├── Categoryパラメータでフィルタ
   ├── CategoryTypeパラメータでフィルタ
   ↓
[ジョブ数カウント]
   ├── 各カテゴリのJobCountを計算
   │     └── server.JobServer.Jobs | Where CategoryID -eq $cat.ID
   ↓
[出力プロパティ追加]
   ├── ComputerName, InstanceName, SqlInstance, JobCount追加
   ↓
[カテゴリ情報出力]
   ↓
[終了]
```

### 4.2 New-DbaAgentJobCategory

```
[開始]
   ↓
[デフォルト設定]
   ├── CategoryType未指定時は'LocalJob'に設定
   ↓
[インスタンス接続]
   ├── Connect-DbaInstanceで接続
   ↓
[カテゴリ存在確認]
   ├── [カテゴリ存在] → エラー
   ↓
[カテゴリオブジェクト作成]
   ├── New-Object Microsoft.SqlServer.Management.Smo.Agent.JobCategory
   ├── CategoryType設定
   ↓
[カテゴリ作成]
   ├── jobCategory.Create()
   ├── server.JobServer.Refresh()
   ↓
[作成結果出力]
   ├── Get-DbaAgentJobCategoryで取得
   ↓
[終了]
```

### 4.3 Remove-DbaAgentJobCategory

```
[開始]
   ↓
[カテゴリ取得]
   ├── SqlInstance指定時はGet-DbaAgentJobCategoryで取得
   ├── InputObject指定時はパイプラインから取得
   ↓
[カテゴリ削除]（endブロック）
   ├── ShouldProcess確認
   ├── jobCategory.Drop()実行
   ↓
[削除結果出力]
   ├── Status="Dropped" / エラーメッセージ
   ├── IsRemoved=true/false
   ↓
[終了]
```

## 5. バリデーションルール

### 5.1 New-DbaAgentJobCategory

| 条件 | エラーメッセージ |
|------|----------------|
| カテゴリ名重複 | "Job category $cat already exists on $instance" |

### 5.2 削除時の動作

- 削除されたカテゴリに割り当てられていたジョブは、自動的に「[Uncategorized (Local)]」カテゴリに再割り当てされます

## 6. ConfirmImpact

- **Get-DbaAgentJobCategory**: なし（読み取り専用）
- **New-DbaAgentJobCategory**: Low
- **Remove-DbaAgentJobCategory**: High

## 7. 使用例

### 7.1 全カテゴリ取得

```powershell
Get-DbaAgentJobCategory -SqlInstance sql1
```

### 7.2 特定カテゴリの取得

```powershell
Get-DbaAgentJobCategory -SqlInstance sql1 -Category 'Log Shipping'
```

### 7.3 マルチサーバージョブカテゴリの取得

```powershell
Get-DbaAgentJobCategory -SqlInstance sstad-pc -CategoryType MultiServerJob
```

### 7.4 カテゴリ作成

```powershell
New-DbaAgentJobCategory -SqlInstance sql1 -Category 'Category 1'
```

### 7.5 マルチサーバージョブカテゴリの作成

```powershell
New-DbaAgentJobCategory -SqlInstance sql1 -Category 'Category 2' -CategoryType MultiServerJob
```

### 7.6 カテゴリ削除

```powershell
Remove-DbaAgentJobCategory -SqlInstance sql1 -Category 'Category 1'
```

### 7.7 複数カテゴリの削除

```powershell
Remove-DbaAgentJobCategory -SqlInstance sql1 -Category Category1, Category2, Category3
```

### 7.8 GridViewで選択して削除

```powershell
Get-DbaAgentJobCategory -SqlInstance SRV1 | Out-GridView -Title 'Select SQL Agent job category(-ies) to drop' -OutputMode Multiple | Remove-DbaAgentJobCategory
```

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

### 8.1 理解の順序

1. **Get-DbaAgentJobCategory.ps1** - カテゴリ取得とジョブ数カウントの基本構造
2. **New-DbaAgentJobCategory.ps1** - カテゴリ作成フロー
3. **Remove-DbaAgentJobCategory.ps1** - カテゴリ削除とendブロック処理

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

```
Get-DbaAgentJobCategory
├── Connect-DbaInstance (Line 96)
├── server.JobServer.JobCategories (Line 101)
├── Where-Object (Lines 102-105) - フィルタリング
├── server.JobServer.Jobs (Line 111) - ジョブ数計算
├── Add-Member (Lines 113-116)
└── Select-DefaultView (Line 118)

New-DbaAgentJobCategory
├── Connect-DbaInstance (Line 106)
├── New-Object JobCategory (Line 118)
├── jobCategory.Create() (Line 129)
├── server.JobServer.Refresh() (Line 131)
└── Get-DbaAgentJobCategory (Line 137)

Remove-DbaAgentJobCategory
├── Get-DbaAgentJobCategory (Line 114) - SqlInstance使用時
├── ShouldProcess (Line 123)
└── jobCategory.Drop() (Line 133)
```

### 8.3 データフロー図

```
[ユーザー入力]
     │
     ├─[Get-DbaAgentJobCategory]──────────────────────────────────────┐
     │       │                                                        │
     │       └── server.JobServer.JobCategories                      │
     │                 │                                              │
     │                 ├── Category フィルタ                          │
     │                 ├── CategoryType フィルタ                      │
     │                 │                                              │
     │                 └── JobCount 計算 ─────────────────────────────┼─→ [カテゴリ情報]
     │                       └── server.JobServer.Jobs               │
     │                                                                │
     ├─[New-DbaAgentJobCategory]──────────────────────────────────────┤
     │       │                                                        │
     │       ├── New-Object JobCategory                              │
     │       │                                                        │
     │       ├── Create()                                             │
     │       │                                                        │
     │       └── Get-DbaAgentJobCategory ─────────────────────────────┼─→ [作成されたカテゴリ]
     │                                                                │
     └─[Remove-DbaAgentJobCategory]───────────────────────────────────┤
             │                                                        │
             ├── Get-DbaAgentJobCategory（SqlInstance使用時）        │
             │                                                        │
             └── Drop() ──────────────────────────────────────────────┴─→ [削除結果]
```

### 8.4 関連ファイル一覧

| ファイルパス | 役割 | 行数 |
|-------------|------|------|
| public/Get-DbaAgentJobCategory.ps1 | カテゴリ取得 | 125 |
| public/New-DbaAgentJobCategory.ps1 | カテゴリ作成 | 141 |
| public/Remove-DbaAgentJobCategory.ps1 | カテゴリ削除 | 145 |
| public/Set-DbaAgentJobCategory.ps1 | カテゴリ設定変更（関連） | - |

### 8.5 重要コードポイント

#### ジョブ数カウント（Get-DbaAgentJobCategory.ps1: Line 111）
```powershell
$jobCount = ($server.JobServer.Jobs | Where-Object { $_.CategoryID -eq $cat.ID }).Count
```

#### デフォルトCategoryType設定（New-DbaAgentJobCategory.ps1: Lines 96-99）
```powershell
if (-not $CategoryType) {
    Write-Message -Message "Setting the category type to 'LocalJob'" -Level Verbose
    $CategoryType = "LocalJob"
}
```

#### endブロックでの削除処理（Remove-DbaAgentJobCategory.ps1: Lines 120-143）
```powershell
end {
    # We have to delete in the end block to prevent "Collection was modified; enumeration operation may not execute." if directly piped from Get-DbaAgentJobCategory.
    foreach ($jobCategory in $jobCategories) {
        # ...
        $jobCategory.Drop()
    }
}
```

## 9. 権限要件

| 操作 | 必要な権限 |
|------|----------|
| Get-DbaAgentJobCategory | SQLAgentReaderRole以上 |
| New-DbaAgentJobCategory | sysadmin |
| Remove-DbaAgentJobCategory | sysadmin |

## 10. 注意事項

- カテゴリを削除しても、そのカテゴリに属していたジョブは削除されません（「[Uncategorized (Local)]」に再割り当て）
- Remove-DbaAgentJobCategoryはendブロックで削除を実行するため、Get-DbaAgentJobCategoryからの直接パイプラインでも「Collection was modified」エラーが発生しません

## 11. 関連コマンド

- Get-DbaAgentJob - ジョブ取得
- New-DbaAgentJob - ジョブ作成（カテゴリ指定可能）
- Set-DbaAgentJobCategory - カテゴリ設定変更
