# 機能設計書 467-New-DbaRgWorkloadGroup

## 概要

本ドキュメントは、SQL Server Resource Governorのワークロードグループを新規作成するNew-DbaRgWorkloadGroup機能の設計を記述する。

### 本機能の処理概要

New-DbaRgWorkloadGroupは、指定されたリソースプール内にResource Governorワークロードグループを作成する機能である。CPU時間制限、メモリ付与パーセンテージ、最大並列度などの特定のリソース制限と優先度を定義できる。

**業務上の目的・背景**：ワークロードグループは、受信リクエストを分類し、リソースポリシーを適用するためのコンテナとして機能する。マルチテナント環境、混合ワークロード、またはリソース集約型クエリが重要なアプリケーションに影響を与えることを防ぐ必要があるシステムを管理するDBAにとって不可欠な機能である。レポートクエリ、ETLプロセス、アプリケーショントラフィック、管理タスクごとに、それぞれに適したリソース制約を持つ個別のワークロードグループを作成できる。

**機能の利用シーン**：
- マルチテナント環境でのワークロード分離設定
- 報告ワークロードとOLTPワークロードの優先度設定
- 長時間実行クエリのリソース制限設定
- バッチ処理の並列度制限

**主要な処理内容**：
1. 対象SQL Serverインスタンスに接続
2. 指定されたリソースプールを取得
3. 既存ワークロードグループの確認（-Force指定時は削除）
4. 新しいワークロードグループオブジェクトを作成してプロパティを設定
5. SMOのCreate()メソッドでグループを作成
6. Resource Governorを再構成して変更を適用

**関連システム・外部連携**：Get-DbaRgResourcePoolを内部的に呼び出してリソースプールを取得する。SMOを使用してResource Governorを操作する。

**権限による制御**：CONTROL SERVER権限またはsysadminロールが必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 114 | ワークロードグループ | 主機能 | ワークロードグループの作成 |

## 機能種別

INSERT / 新規作成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象のSQL Serverインスタンス | ValueFromPipeline |
| SqlCredential | PSCredential | No | 代替認証情報 | - |
| WorkloadGroup | String[] | No | 作成するワークロードグループ名 | - |
| ResourcePool | String | No | 所属リソースプール名 | デフォルト: default |
| ResourcePoolType | String | No | プールタイプ | ValidateSet: Internal, External。デフォルト: Internal |
| Importance | String | No | リクエストの重要度 | ValidateSet: LOW, MEDIUM, HIGH。デフォルト: MEDIUM |
| RequestMaximumMemoryGrantPercentage | Int | No | 最大メモリ付与パーセンテージ | ValidateRange(1, 100)。デフォルト: 25 |
| RequestMaximumCpuTimeInSeconds | Int | No | リクエストあたり最大CPU時間 | ValidateRange(0, MaxValue)。デフォルト: 0 |
| RequestMemoryGrantTimeoutInSeconds | Int | No | メモリ付与タイムアウト | ValidateRange(0, MaxValue)。デフォルト: 0 |
| MaximumDegreeOfParallelism | Int | No | 最大並列度 | ValidateRange(0, 64)。デフォルト: 0 |
| GroupMaximumRequests | Int | No | 最大同時リクエスト数 | ValidateRange(0, MaxValue)。デフォルト: 0 |
| SkipReconfigure | switch | No | 再構成をスキップ | - |
| Force | switch | No | 既存グループを削除して再作成 | - |
| EnableException | switch | No | 例外を直接スローするかどうか | - |

### 入力データソース

- パラメータ入力（コマンドライン）
- パイプライン入力（SqlInstance）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | String | SQL Serverインスタンス名 |
| SqlInstance | String | 完全なSQL Serverインスタンス名 |
| Id | Int32 | ワークロードグループの一意識別子 |
| Name | String | ワークロードグループ名 |
| ExternalResourcePoolName | String | 関連外部リソースプール名 |
| GroupMaximumRequests | Int32 | 最大同時リクエスト数 |
| Importance | String | 重要度（LOW/MEDIUM/HIGH） |
| IsSystemObject | Boolean | システム定義グループかどうか |
| MaximumDegreeOfParallelism | Int32 | 最大並列度 |
| RequestMaximumCpuTimeInSeconds | Int32 | リクエストあたり最大CPU時間 |
| RequestMaximumMemoryGrantPercentage | Int32 | 最大メモリ付与パーセンテージ |
| RequestMemoryGrantTimeoutInSeconds | Int32 | メモリ付与タイムアウト |

### 出力先

- PowerShellパイプライン（標準出力）
- Microsoft.SqlServer.Management.Smo.WorkloadGroup オブジェクト

## 処理フロー

### 処理シーケンス

```
1. 各SqlInstanceに対して繰り返し処理
   └─ Connect-DbaInstanceで接続
2. 各WorkloadGroup名に対して繰り返し処理
3. ResourcePoolTypeに基づいてリソースプールを取得
   ├─ Internal: $server.ResourceGovernor.ResourcePools
   └─ External: $server.ResourceGovernor.ExternalResourcePools
4. 既存ワークロードグループの確認
   ├─ 存在 + Force: 既存グループを削除
   └─ 存在 + not Force: エラー終了
5. 新しいWorkloadGroupオブジェクトを作成
6. プロパティを設定（Importance, RequestMaximumMemoryGrantPercentage等）
7. SMOのCreate()メソッドでグループを作成
8. Resource Governorの再構成
   ├─ SkipReconfigure: 警告を出力してスキップ
   └─ 通常: $server.ResourceGovernor.Alter()
9. Get-DbaRgWorkloadGroupで作成結果を出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[SqlInstanceループ開始]
    B --> C[Connect-DbaInstance]
    C --> D[WorkloadGroupループ開始]
    D --> E{ResourcePoolType?}
    E -->|Internal| F[ResourcePools取得]
    E -->|External| G[ExternalResourcePools取得]
    F --> H[ResourcePool選択]
    G --> H
    H --> I[既存グループ確認]
    I --> J{グループ存在?}
    J -->|Yes| K{Force指定?}
    K -->|Yes| L[既存グループ削除]
    K -->|No| M[Stop-Function: 既存エラー]
    J -->|No| N[新規WorkloadGroup作成]
    L --> N
    M --> D
    N --> O[プロパティ設定]
    O --> P[Create実行]
    P --> Q{SkipReconfigure?}
    Q -->|Yes| R[警告出力]
    Q -->|No| S[ResourceGovernor.Alter]
    R --> T[Get-DbaRgWorkloadGroup出力]
    S --> T
    T --> D
    D --> B
    B --> U[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | グループ名一意性 | ワークロードグループ名はリソースプール内で一意 | 常に適用 |
| BR-002 | デフォルトプール | ResourcePoolパラメータのデフォルトは'default' | ResourcePool未指定時 |
| BR-003 | Force動作 | -Force指定時は既存グループを削除して再作成 | 既存グループ存在時 |
| BR-004 | SkipReconfigure警告 | 再構成をスキップすると新グループは即座に有効にならない | SkipReconfigure指定時 |
| BR-005 | Importanceデフォルト | Importanceのデフォルト値はMEDIUM | Importance未指定時 |
| BR-006 | メモリ付与デフォルト | RequestMaximumMemoryGrantPercentageのデフォルトは25% | 未指定時 |

### 計算ロジック

該当なし（構成作成機能のため）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| グループ作成 | sys.resource_governor_workload_groups | INSERT | 新規ワークロードグループの登録 |
| グループ削除 | sys.resource_governor_workload_groups | DELETE | Force指定時の既存グループ削除 |
| 再構成 | - | ALTER | Resource Governor再構成 |

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

SMOのCreate()、Drop()、Alter()メソッドが内部的にT-SQLを生成・実行する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverへの接続失敗 | 資格情報とネットワーク接続を確認 |
| ResourceExists | 既存エラー | グループが既に存在し-Force未指定 | -Forceを指定するか別名を使用 |
| - | 削除失敗 | Force指定時の既存グループ削除失敗 | グループの使用状況を確認 |
| - | 作成失敗 | Create()実行時のエラー | エラーメッセージを確認 |

### リトライ仕様

リトライ処理は実装されていない。

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

SMOのCreate()による単一操作。明示的なトランザクション管理は実装されていない。

## パフォーマンス要件

- メタデータ操作のため、軽量な処理
- Resource Governor再構成に数秒かかる場合がある

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

- CONTROL SERVER権限またはsysadminロールが必要
- ShouldProcessによる確認機能を提供
- SqlCredentialパラメータによる安全な認証情報の受け渡し

## 備考

- ワークロードグループはリソースプールに所属する
- 0の値は多くのパラメータで「無制限」を意味する
- ImportanceはCPU競合時のスケジューリング優先度に影響する

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | New-DbaRgWorkloadGroup.ps1 | `public/New-DbaRgWorkloadGroup.ps1` | .OUTPUTSセクション（85-105行目）で出力オブジェクトの構造を確認 |

**読解のコツ**: 出力はMicrosoft.SqlServer.Management.Smo.WorkloadGroupクラス。リソースプールの子オブジェクトとして作成される。

#### Step 2: パラメータ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaRgWorkloadGroup.ps1 | `public/New-DbaRgWorkloadGroup.ps1` | paramブロック（118-143行目）でパラメータ定義を確認 |

**読解のコツ**: ValidateSetとValidateRangeで値を制限。各パラメータにデフォルト値が設定されている。

#### Step 3: メイン処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaRgWorkloadGroup.ps1 | `public/New-DbaRgWorkloadGroup.ps1` | processブロック（144-200行目）がメイン処理 |

**主要処理フロー**:
1. **145-150行目**: SqlInstanceループ開始、Connect-DbaInstanceで接続
2. **152-158行目**: ResourcePoolTypeに基づいてリソースプールコレクションを取得
3. **158行目**: 指定されたリソースプールを選択
4. **159-172行目**: 既存グループ確認、Force指定時は削除
5. **175-184行目**: 新しいWorkloadGroupオブジェクト作成、プロパティ設定
6. **184行目**: Create()メソッドでグループ作成
7. **186-191行目**: Resource Governor再構成（SkipReconfigureチェック）
8. **197行目**: Get-DbaRgWorkloadGroupで結果出力

#### Step 4: 依存関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaRgResourcePool.ps1 | `public/Get-DbaRgResourcePool.ps1` | リソースプール取得処理 |
| 4-2 | Get-DbaRgWorkloadGroup.ps1 | `public/Get-DbaRgWorkloadGroup.ps1` | 結果取得処理 |

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

```
New-DbaRgWorkloadGroup
    │
    ├─ Connect-DbaInstance
    │
    ├─ $server.ResourceGovernor.ResourcePools/ExternalResourcePools
    │
    ├─ $resPool.WorkloadGroups (既存確認)
    │
    ├─ $existingWorkloadGroup.Drop() (Force時)
    │
    ├─ New-Object WorkloadGroup
    │      └─ プロパティ設定
    │
    ├─ $newWorkloadGroup.Create()
    │
    ├─ $server.ResourceGovernor.Alter() (再構成)
    │
    └─ Get-DbaRgResourcePool | Get-DbaRgWorkloadGroup (結果出力)
```

### データフロー図

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

SqlInstance ─────────▶ Connect-DbaInstance
                              │
                              ▼
ResourcePool名 ────────▶ ResourcePools/ExternalResourcePools
                              │
                              ▼
WorkloadGroup名 ───────▶ 既存グループ確認
                              │
               ┌──────────────┴──────────────┐
               ▼                              ▼
        既存あり+Force              既存なし/削除済み
               │                              │
               ▼                              │
         Drop()                               │
               │                              │
               └──────────────┬───────────────┘
                              ▼
                  New-Object WorkloadGroup
                              │
                              ▼
                    プロパティ設定 + Create()
                              │
                              ▼
                   ResourceGovernor.Alter()
                              │
                              ▼
                  Get-DbaRgWorkloadGroup ────▶ WorkloadGroup Object
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaRgWorkloadGroup.ps1 | `public/New-DbaRgWorkloadGroup.ps1` | ソース | 本機能のメイン実装 |
| Get-DbaRgResourcePool.ps1 | `public/Get-DbaRgResourcePool.ps1` | ソース | リソースプール取得 |
| Get-DbaRgWorkloadGroup.ps1 | `public/Get-DbaRgWorkloadGroup.ps1` | ソース | 結果取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラーハンドリング |
