# 画面設計書 114-ワークロードグループ

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるSQL Server Resource Governorワークロードグループ管理機能の設計仕様を記述する。

### 本画面の処理概要

本機能群は、Resource Governorのワークロードグループの作成・取得・設定・削除を行う。ワークロードグループは、リソースプール内で受信リクエストを分類し、リソースポリシー（CPU時間制限、メモリ許可、並列度など）を適用するコンテナである。

**業務上の目的・背景**：異なるタイプのワークロード（レポーティング、ETL、アプリケーショントラフィック、管理タスクなど）に対して、それぞれのリソース制約を定義することで、重要度に応じたリソース割り当てと公平なリソース使用を実現する。分類関数と組み合わせて、接続のログイン名やアプリケーション名に基づいて自動的にワークロードグループに振り分ける。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドレットを実行する。
- `Get-DbaRgWorkloadGroup` - ワークロードグループの取得
- `New-DbaRgWorkloadGroup` - ワークロードグループの作成
- `Set-DbaRgWorkloadGroup` - ワークロードグループの設定変更
- `Remove-DbaRgWorkloadGroup` - ワークロードグループの削除

**主要な操作・処理内容**：
1. 既存ワークロードグループの一覧取得と構成確認
2. カスタムワークロードグループの新規作成
3. 重要度（Importance）の設定
4. リクエストあたりのCPU時間・メモリ許可・並列度の制限設定
5. グループ内同時リクエスト数の制限設定
6. ワークロードグループの削除

**画面遷移**：本機能はコマンドラインインターフェースであり、画面遷移は存在しない。Get-DbaRgResourcePoolの出力をパイプラインでGet-DbaRgWorkloadGroupに渡すことができる。

**権限による表示制御**：参照にはVIEW SERVER STATE権限、変更にはCONTROL SERVER権限またはsysadminロールが必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 464 | Get-DbaRgWorkloadGroup | 主機能 | ワークロードグループの取得 |
| 467 | New-DbaRgWorkloadGroup | 主機能 | ワークロードグループの作成 |
| 470 | Remove-DbaRgWorkloadGroup | 主機能 | ワークロードグループの削除 |
| 473 | Set-DbaRgWorkloadGroup | 補助機能 | ワークロードグループの設定変更 |

## 画面種別

CLIコマンド群（ワークロードグループ管理）

## URL/ルーティング

```powershell
# ワークロードグループ取得
Get-DbaRgWorkloadGroup -SqlInstance <インスタンス名>

# ワークロードグループ作成
New-DbaRgWorkloadGroup -SqlInstance <インスタンス名> -WorkloadGroup <グループ名> [-ResourcePool <プール名>] [-Importance LOW|MEDIUM|HIGH] [-RequestMaximumMemoryGrantPercentage <1-100>] [-RequestMaximumCpuTimeInSeconds <値>] [-MaximumDegreeOfParallelism <0-64>] [-GroupMaximumRequests <値>]

# ワークロードグループ設定
Set-DbaRgWorkloadGroup -SqlInstance <インスタンス名> -WorkloadGroup <グループ名> -ResourcePool <プール名> ...

# ワークロードグループ削除
Remove-DbaRgWorkloadGroup -SqlInstance <インスタンス名> -WorkloadGroup <グループ名>
```

## 入出力項目

### Get-DbaRgWorkloadGroup パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|---|------|-------------|------|
| SqlInstance | DbaInstanceParameter[] | No | - | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | - | 認証資格情報 |
| InputObject | ResourcePool[] | No | - | パイプライン入力（リソースプール） |
| EnableException | switch | No | $false | 例外をスローする |

### New-DbaRgWorkloadGroup パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|---|------|-------------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | - | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | - | 認証資格情報 |
| WorkloadGroup | string[] | Yes | - | ワークロードグループ名 |
| ResourcePool | string | No | default | リソースプール名 |
| ResourcePoolType | string | No | Internal | Internal/External |
| Importance | string | No | MEDIUM | LOW/MEDIUM/HIGH |
| RequestMaximumMemoryGrantPercentage | int | No | 25 | リクエストあたり最大メモリ許可% (1-100) |
| RequestMaximumCpuTimeInSeconds | int | No | 0 | リクエストあたり最大CPU秒 (0=無制限) |
| RequestMemoryGrantTimeoutInSeconds | int | No | 0 | メモリ許可タイムアウト秒 (0=無制限) |
| MaximumDegreeOfParallelism | int | No | 0 | 最大並列度 (0=サーバー設定) |
| GroupMaximumRequests | int | No | 0 | グループ最大同時リクエスト数 (0=無制限) |
| SkipReconfigure | switch | No | $false | 再構成をスキップ |
| Force | switch | No | $false | 既存グループを削除して再作成 |
| WhatIf | switch | No | - | 実行内容をシミュレート |
| Confirm | switch | No | - | 確認プロンプトを表示 |
| EnableException | switch | No | $false | 例外をスローする |

## 表示項目

### Get-DbaRgWorkloadGroup 出力

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| Id | int | ワークロードグループID |
| Name | string | ワークロードグループ名 |
| ExternalResourcePoolName | string | 外部リソースプール名 |
| GroupMaximumRequests | int | 最大同時リクエスト数 (0=無制限) |
| Importance | string | 重要度（LOW/MEDIUM/HIGH） |
| IsSystemObject | bool | システムオブジェクトフラグ |
| MaximumDegreeOfParallelism | int | 最大並列度 |
| RequestMaximumCpuTimeInSeconds | int | リクエストあたり最大CPU秒 |
| RequestMaximumMemoryGrantPercentage | int | リクエストあたり最大メモリ% |
| RequestMemoryGrantTimeoutInSeconds | int | メモリ許可タイムアウト秒 |

### Remove-DbaRgWorkloadGroup 出力

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| Name | string | ワークロードグループ名 |
| Status | string | 処理結果（Dropped等） |
| IsRemoved | bool | 削除成功フラグ |

## イベント仕様

### 1-Get-DbaRgWorkloadGroup実行

1. SqlInstanceが指定された場合、Get-DbaRgResourcePoolを呼び出し
2. 各リソースプールのWorkloadGroupsを取得
3. ComputerName、InstanceName、SqlInstanceをNotePropertyとして追加
4. Select-DefaultViewで出力整形

### 2-New-DbaRgWorkloadGroup実行

1. Connect-DbaInstanceでSQL Serverに接続
2. ResourcePoolTypeに応じてリソースプールを取得
3. 既存ワークロードグループの存在確認
4. 既存の場合:
   - Forceあり: 既存グループを削除
   - Forceなし: エラー出力してスキップ
5. SMOで新しいWorkloadGroupオブジェクトを作成
6. プロパティを設定（Importance、RequestMaximum*、MaximumDegreeOfParallelism等）
7. $newWorkloadGroup.Create()で作成
8. SkipReconfigureでない場合、$server.ResourceGovernor.Alter()
9. Get-DbaRgWorkloadGroupで結果を出力

### 3-Set-DbaRgWorkloadGroup実行

1. WorkloadGroupまたはInputObjectからワークロードグループを取得
2. パラメータに応じてプロパティを更新
3. $wklGroup.Alter()で変更適用
4. SkipReconfigureでない場合、$server.ResourceGovernor.Alter()

### 4-Remove-DbaRgWorkloadGroup実行

1. WorkloadGroupまたはInputObjectからワークロードグループを取得
2. $wklGroup.Drop()でグループ削除
3. SkipReconfigureでない場合、$server.ResourceGovernor.Alter()
4. PSCustomObjectで結果を出力

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

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

| 操作（イベント） | 対象オブジェクト | 操作種別 | 概要 |
|----------------|-----------------|---------|------|
| New Group | sys.dm_resource_governor_workload_groups | INSERT | グループ作成 |
| Set Group | sys.dm_resource_governor_workload_groups | UPDATE | グループ設定変更 |
| Remove Group | sys.dm_resource_governor_workload_groups | DELETE | グループ削除 |
| Reconfigure | Resource Governor | EXECUTE | 設定適用 |

### SQL操作詳細

| 操作 | 実行方法 | 備考 |
|-----|---------|------|
| グループ作成 | SMO: WorkloadGroup.Create() | CREATE WORKLOAD GROUP相当 |
| グループ変更 | SMO: WorkloadGroup.Alter() | ALTER WORKLOAD GROUP相当 |
| グループ削除 | SMO: WorkloadGroup.Drop() | DROP WORKLOAD GROUP相当 |
| 再構成 | SMO: ResourceGovernor.Alter() | ALTER RESOURCE GOVERNOR RECONFIGURE相当 |

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 発生条件 |
|---------------|---------------|---------|
| エラー | Workload group {name} already exists | Forceなしで既存グループ |
| 警告 | Not reconfiguring the Resource Governor after creating a new workload group may create problems | SkipReconfigure使用時 |
| 警告 | Workload group changes will not take effect until it is reconfigured | SkipReconfigure使用時 |
| エラー | Could not remove existing workload group | 削除失敗 |
| エラー | You must pipe in a workload group or specify a WorkloadGroup | パラメータ不足 |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| グループ既存（Force=false） | Stop-Functionでエラー出力、return |
| グループ削除失敗 | Stop-Functionでエラー出力、Continue |
| グループ作成失敗 | Stop-Functionでエラー出力、Continue |
| パラメータ不足 | Stop-Functionでエラー出力、return |
| Reconfigure失敗 | Stop-Functionでエラー出力、Continue |

## 備考

- ワークロードグループはリソースプールに属する
- デフォルトのResourcePoolは"default"
- Importanceはリクエスト間のCPU優先度を制御
- RequestMaximumCpuTimeInSeconds=0は無制限（runawayクエリ対策に設定推奨）
- MaximumDegreeOfParallelism=0はサーバーのMAXDOP設定を使用
- GroupMaximumRequests=0は無制限
- 分類関数でセッションをワークロードグループに振り分ける
- システムワークロードグループ（internal、default）は変更・削除不可

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaRgWorkloadGroup.ps1 | `public/Get-DbaRgWorkloadGroup.ps1` | 出力プロパティ（行29-55）を確認 |

**読解のコツ**: Microsoft.SqlServer.Management.Smo.WorkloadGroupがベース。Parentプロパティでリソースプールへの参照を持つ。

#### Step 2: 取得処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaRgWorkloadGroup.ps1 | `public/Get-DbaRgWorkloadGroup.ps1` | 行89-103: 取得処理 |

**主要処理フロー**:
1. **行90-91**: SqlInstance指定時、Get-DbaRgResourcePoolを呼び出し
2. **行94-100**: 各プールのWorkloadGroupsを取得しNotePropertyを追加

#### Step 3: 作成処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaRgWorkloadGroup.ps1 | `public/New-DbaRgWorkloadGroup.ps1` | 行144-200: 作成処理 |

**主要処理フロー**:
1. **行152-156**: リソースプール取得（Internal/External）
2. **行158-172**: 既存グループ確認とForce処理
3. **行174-184**: SMOオブジェクト作成とプロパティ設定
4. **行186-191**: Reconfigure処理

#### Step 4: 設定処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Set-DbaRgWorkloadGroup.ps1 | `public/Set-DbaRgWorkloadGroup.ps1` | 行161-207: 設定変更処理 |

**主要処理フロー**:
1. **行168-185**: プロパティ設定（$PSBoundParameters.Keys確認）
2. **行188-194**: Alter()実行
3. **行197-204**: Reconfigure処理

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

```
Get-DbaRgWorkloadGroup
    │
    +-- Get-DbaRgResourcePool
    │       └─ リソースプール取得
    │
    +-- $pool.WorkloadGroups
    │       └─ ワークロードグループコレクション
    │
    └── Select-DefaultView
            └─ 出力プロパティ選択

New-DbaRgWorkloadGroup
    │
    +-- Connect-DbaInstance
    │
    +-- $server.ResourceGovernor.ResourcePools / ExternalResourcePools
    │       └─ リソースプール取得
    │
    +-- New-Object WorkloadGroup
    │       └─ SMOオブジェクト作成
    │
    +-- WorkloadGroup.Create()
    │
    +-- ResourceGovernor.Alter()
    │       └─ Reconfigure
    │
    └── Get-DbaRgWorkloadGroup
            └─ 結果出力

Set-DbaRgWorkloadGroup
    │
    +-- Connect-DbaInstance
    │
    +-- WorkloadGroup.Alter()
    │       └─ プロパティ変更適用
    │
    └── ResourceGovernor.Alter()
            └─ Reconfigure

Remove-DbaRgWorkloadGroup
    │
    +-- Connect-DbaInstance
    │
    +-- WorkloadGroup.Drop()
    │       └─ グループ削除
    │
    └── ResourceGovernor.Alter()
            └─ Reconfigure
```

### データフロー図

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

SqlInstance ──────────────> Get-DbaRgResourcePool ─────────────>
                            $pool.WorkloadGroups ──────────────> WorkloadGroup[]

WorkloadGroup名 ──────────> New-Object WorkloadGroup ──────────>
ResourcePool ─────────────> Create() ─────────────────────────>
Importance/CPU/Memory ────> Alter() ──────────────────────────> WorkloadGroup
MaxDOP/MaxRequests ───────>

InputObject ──────────────> プロパティ更新 ───────────────────>
設定パラメータ ───────────> Alter() ──────────────────────────> WorkloadGroup
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaRgWorkloadGroup.ps1 | `public/Get-DbaRgWorkloadGroup.ps1` | ソース | ワークロードグループ取得 |
| New-DbaRgWorkloadGroup.ps1 | `public/New-DbaRgWorkloadGroup.ps1` | ソース | ワークロードグループ作成 |
| Set-DbaRgWorkloadGroup.ps1 | `public/Set-DbaRgWorkloadGroup.ps1` | ソース | ワークロードグループ設定 |
| Remove-DbaRgWorkloadGroup.ps1 | `public/Remove-DbaRgWorkloadGroup.ps1` | ソース | ワークロードグループ削除 |
| Get-DbaRgResourcePool.ps1 | `public/Get-DbaRgResourcePool.ps1` | ソース | リソースプール取得（依存） |
