# 機能設計書 464-Get-DbaRgWorkloadGroup

## 概要

本ドキュメントは、SQL Server Resource Governorのワークロードグループ情報を取得するGet-DbaRgWorkloadGroup機能の設計を記述する。

### 本機能の処理概要

Get-DbaRgWorkloadGroupは、SQL Server Resource Governorで定義されたワークロードグループの詳細情報を取得する機能である。ワークロードグループは、CPU制限、メモリ付与、並列処理制御などの構成設定を含み、リソースプール内でのリクエストの分類と管理方法を定義する。

**業務上の目的・背景**：ワークロードグループはResource Governorの中核的な構成要素であり、受信リクエストをどのように分類し、どのようなリソースポリシーを適用するかを定義する。DBAはこの機能を使用して、現在のワークロードグループ構成を監視し、リソース割り当てポリシーを確認し、競合するワークロード間での最適なパフォーマンス分離を確保するためのトラブルシューティングを行うことができる。

**機能の利用シーン**：
- Resource Governor構成の監査・ドキュメント化時
- ワークロード間のリソース競合を分析する際
- パフォーマンスチューニング時のリソース制限設定の確認
- 複数インスタンス間でのワークロードグループ構成の比較

**主要な処理内容**：
1. SqlInstanceまたはInputObject（ResourcePoolオブジェクト）から処理対象を取得
2. 各リソースプールのWorkloadGroupsコレクションを取得
3. カスタムプロパティを追加して結果を出力

**関連システム・外部連携**：Get-DbaRgResourcePoolからパイプライン入力を受け取ることができる。SMOを使用してSQL Serverのワークロードグループ情報を取得する。

**権限による制御**：Resource Governor情報の取得にはVIEW SERVER STATE権限が推奨される。

## 関連画面

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

## 機能種別

SELECT / 情報取得

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象のSQL Serverインスタンス | ValueFromPipeline |
| SqlCredential | PSCredential | No | 代替認証情報 | - |
| InputObject | Microsoft.SqlServer.Management.Smo.ResourcePool[] | No | ResourcePoolオブジェクト | ValueFromPipeline |
| EnableException | switch | No | 例外を直接スローするかどうか | - |

### 入力データソース

- パラメータ入力（SqlInstance）
- パイプライン入力（SqlInstance、ResourcePoolオブジェクト）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | String | SQL Serverインスタンス名 |
| SqlInstance | String | 完全なSQL Serverインスタンス名 |
| Id | Int32 | ワークロードグループの一意識別子 |
| Name | String | ワークロードグループ名 |
| ExternalResourcePoolName | String | 関連付けられた外部リソースプール名（該当する場合） |
| GroupMaximumRequests | Int32 | ワークロードグループで許可される最大同時リクエスト数（0=無制限） |
| Importance | String | リソース競合時のリクエストの重要度（Low/Medium/High） |
| IsSystemObject | Boolean | システム定義ワークロードグループかどうか |
| MaximumDegreeOfParallelism | Int32 | 並列クエリ実行の最大プロセッサ数（0=無制限） |
| RequestMaximumCpuTimeInSeconds | Int32 | リクエストあたりの最大CPU時間（秒）（0=無制限） |
| RequestMaximumMemoryGrantPercentage | Int32 | リソースプールメモリの最大メモリ付与パーセンテージ |
| RequestMemoryGrantTimeoutInSeconds | Int32 | メモリ付与リクエストのタイムアウト（秒）（0=無制限） |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. SqlInstanceが指定されている場合、Get-DbaRgResourcePoolを呼び出し
   └─ ResourcePoolオブジェクトをInputObjectに追加
2. InputObjectの各ResourcePoolオブジェクトに対して繰り返し処理
3. 各プールのWorkloadGroupsコレクションを取得
4. ワークロードグループが存在する場合、カスタムプロパティを追加
   └─ ComputerName, InstanceName, SqlInstance
5. Select-DefaultViewで出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance指定?}
    B -->|Yes| C[Get-DbaRgResourcePool呼び出し]
    B -->|No| D[InputObject使用]
    C --> D
    D --> E[ResourcePoolループ開始]
    E --> F[WorkloadGroups取得]
    F --> G{グループが存在?}
    G -->|Yes| H[Add-Memberでプロパティ追加]
    G -->|No| I[次のResourcePoolへ]
    H --> J[Select-DefaultViewで出力]
    J --> I
    I --> E
    E --> K[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | パイプラインサポート | Get-DbaRgResourcePoolからの出力をパイプラインで受け取り可能 | パイプライン使用時 |
| BR-002 | 複数プール対応 | 各リソースプールに含まれる全てのワークロードグループを出力 | 常に適用 |
| BR-003 | システムオブジェクト識別 | IsSystemObjectプロパティでシステム定義とユーザー定義を区別 | 常に適用 |
| BR-004 | 階層構造 | ワークロードグループはリソースプールの子オブジェクト | 常に適用 |

### 計算ロジック

該当なし（情報取得機能のため）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 情報取得 | sys.resource_governor_workload_groups | SELECT | ワークロードグループ構成の取得（SMO経由） |

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

SMOを使用するため、直接のテーブルアクセスは行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverへの接続失敗 | 資格情報とネットワーク接続を確認 |

### リトライ仕様

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

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

読み取り専用操作のため、トランザクション管理は不要。

## パフォーマンス要件

- メタデータ取得のみのため、軽量な処理
- 通常1秒未満で完了

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

- VIEW SERVER STATE権限が推奨される
- SqlCredentialパラメータによる安全な認証情報の受け渡し

## 備考

- ワークロードグループはリソースプールに属するため、プールを指定することで特定プールのグループのみを取得可能
- Importanceプロパティは、CPU競合時のスケジューリング優先度に影響する

---

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

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

### 推奨読解順序

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

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

**読解のコツ**: 出力はMicrosoft.SqlServer.Management.Smo.WorkloadGroupクラス。ResourcePoolの子オブジェクトとして取得される。

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

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

**主要処理フロー**:
1. **90-92行目**: SqlInstance指定時はGet-DbaRgResourcePoolを呼び出してInputObjectに追加
2. **94行目**: InputObject（ResourcePool）のループ開始
3. **95行目**: $pool.WorkloadGroupsでワークロードグループコレクションを取得
4. **96-100行目**: グループが存在する場合、Add-Memberでカスタムプロパティ追加
5. **100行目**: Select-DefaultViewで出力

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaRgResourcePool.ps1 | `public/Get-DbaRgResourcePool.ps1` | ResourcePoolオブジェクトの取得方法 |
| 3-2 | Get-DbaResourceGovernor.ps1 | `public/Get-DbaResourceGovernor.ps1` | ResourceGovernorオブジェクトの取得（間接依存） |

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

```
Get-DbaRgWorkloadGroup
    │
    ├─ Get-DbaRgResourcePool (SqlInstance指定時)
    │      └─ Get-DbaResourceGovernor
    │             └─ Connect-DbaInstance
    │
    ├─ $pool.WorkloadGroups
    │
    ├─ Add-Member (カスタムプロパティ追加)
    │
    └─ Select-DefaultView (出力フォーマット)
```

### データフロー図

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

SqlInstance ─────────▶ Get-DbaRgResourcePool ───▶ ResourcePool[]
       or                        │
InputObject (pipeline) ──────────┘
                                 │
                                 ▼
                          $pool.WorkloadGroups
                                 │
                                 ▼
                        Add-Member (拡張)
                                 │
                                 ▼
                     Select-DefaultView ────▶ WorkloadGroup Objects
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaRgWorkloadGroup.ps1 | `public/Get-DbaRgWorkloadGroup.ps1` | ソース | 本機能のメイン実装 |
| Get-DbaRgResourcePool.ps1 | `public/Get-DbaRgResourcePool.ps1` | ソース | ResourcePoolオブジェクト取得 |
| Get-DbaResourceGovernor.ps1 | `public/Get-DbaResourceGovernor.ps1` | ソース | ResourceGovernorオブジェクト取得 |
| Select-DefaultView.ps1 | `private/functions/Select-DefaultView.ps1` | ソース | デフォルト表示プロパティ設定 |
