# 機能設計書 691-Get-DbaWsfcResourceGroup

## 概要

本ドキュメントは、Windows Server Failover Cluster (WSFC) のリソースグループ情報を取得するdbatools PowerShellコマンド `Get-DbaWsfcResourceGroup` の機能設計書です。

### 本機能の処理概要

`Get-DbaWsfcResourceGroup` は、Windows Server Failover Cluster からリソースグループのステータスと所有者情報を取得する機能です。SQL Server フェイルオーバークラスターインスタンス (FCI) や可用性グループ (AG) をホストするクラスター環境において、リソースグループの健全性を監視・トラブルシューティングするために使用されます。

**業務上の目的・背景**：SQL Server の高可用性環境では、Windows Server Failover Cluster がSQL Serverサービスとリソースを制御するリソースグループを管理しています。メンテナンス中のリソースグループの健全性確認、フェイルオーバー問題のトラブルシューティング、特定のSQL Serverリソースを現在ホストしているノードの確認など、クラスター管理の可視性を提供することで運用効率を向上させます。

**機能の利用シーン**：
- メンテナンスウィンドウでのリソースグループ健全性の事前確認
- フェイルオーバー発生時の問題調査とトラブルシューティング
- 特定のSQL Serverリソースが現在どのノードで実行されているかの確認
- クラスター構成のドキュメント化と監査

**主要な処理内容**：
1. 指定されたコンピューター名からクラスター情報を取得 (Get-DbaWsfcCluster呼び出し)
2. WMI/CIM経由でMSCluster_ResourceGroupクラスを照会
3. リソースグループ名によるフィルタリング (Nameパラメータ指定時)
4. 状態コードを読みやすい文字列 (Online, Offline, Failed, Unknown) に変換
5. クラスター名とFQDN情報をオブジェクトに追加
6. 既定の表示プロパティでフォーマットして出力

**関連システム・外部連携**：Windows Server Failover Clustering (WSFC) サービス、WMI/CIM (root\MSCluster名前空間)

**権限による制御**：各メンバーノードでのローカル管理者権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | コマンドライン | 主画面 | PowerShellコンソールからの直接実行 |

## 機能種別

データ取得 / クラスター監視

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | DbaInstanceParameter[] | No | クエリ対象のWSFCクラスターまたはノード名。パイプライン入力対応 | 指定なしの場合は$env:COMPUTERNAME |
| Credential | PSCredential | No | 代替資格情報でクラスターにログイン | なし |
| Name | string[] | No | 取得するリソースグループ名のフィルター。複数指定可 | なし |
| EnableException | switch | No | 例外を有効にし、try/catchでのキャッチを可能にする | なし |

### 入力データソース

- Windows Server Failover Cluster WMI名前空間 (root\MSCluster)
- MSCluster_ResourceGroup WMIクラス

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ClusterName | string | Windows Server Failover Clusterの名前 |
| ClusterFqdn | string | クラスターの完全修飾ドメイン名 |
| Name | string | リソースグループの名前 |
| State | string | 現在のリソースグループ状態 (Online, Offline, Failed, Unknown) |
| PersistentState | uint32 | リソースグループの永続的状態 |
| OwnerNode | string | このリソースグループを現在所有しているクラスターノード |

### 出力先

PowerShellパイプライン (Microsoft.Management.Infrastructure.CimInstance#root/MSCluster/MSCluster_ResourceGroup)

## 処理フロー

### 処理シーケンス

```
1. begin ブロック
   └─ Get-ResourceGroupState 内部関数を定義（状態コードを文字列に変換）

2. process ブロック
   └─ ComputerName パラメータの各コンピューターに対してループ
      ├─ Get-DbaWsfcCluster を呼び出してクラスター情報を取得
      ├─ Get-DbaCmObject でMSCluster_ResourceGroupクラスを照会
      ├─ Name パラメータが指定されている場合、結果をフィルタリング
      └─ 各リソースグループに対してループ
         ├─ State プロパティを読みやすい文字列に変換して追加
         ├─ ClusterName プロパティを追加
         ├─ ClusterFqdn プロパティを追加
         └─ Select-DefaultView で既定表示プロパティを設定して出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Get-ResourceGroupState関数定義]
    B --> C{ComputerNameループ}
    C --> D[Get-DbaWsfcCluster呼び出し]
    D --> E[Get-DbaCmObject でMSCluster_ResourceGroup取得]
    E --> F{Nameパラメータ指定?}
    F -->|Yes| G[名前でフィルタリング]
    F -->|No| H{リソースグループループ}
    G --> H
    H --> I[State を文字列に変換]
    I --> J[ClusterName追加]
    J --> K[ClusterFqdn追加]
    K --> L[Select-DefaultViewで出力]
    L --> M{次のリソースグループ?}
    M -->|Yes| H
    M -->|No| N{次のコンピューター?}
    N -->|Yes| C
    N -->|No| O[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 状態コード変換 | 数値状態コードを可読文字列に変換: -1=Unknown, 0=Online, 1=Offline, 2=Failed | 常時 |
| BR-002 | 名前フィルタリング | Nameパラメータ指定時、完全一致でフィルタリング | Nameパラメータ指定時 |
| BR-003 | 権限要件 | ローカル管理者権限が必要 | 常時 |

### 計算ロジック

状態コード変換ロジック:
```powershell
switch ($state) {
    -1 { "Unknown" }
    0 { "Online" }
    1 { "Offline" }
    2 { "Failed" }
    default { $state }
}
```

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

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

本機能はデータベースを直接操作せず、WMI/CIM経由でWindows Server Failover Clusterのメタデータを読み取り専用で取得します。

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| N/A | N/A | SELECT (WMI) | MSCluster_ResourceGroup WMIクラスからの読み取り |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | 接続エラー | 対象コンピューターに接続できない場合 | コンピューター名の確認、ネットワーク接続確認 |
| N/A | 権限エラー | ローカル管理者権限がない場合 | 適切な資格情報でCredentialパラメータを使用 |
| N/A | WMIエラー | WSFCサービスが実行されていない場合 | クラスターサービスの起動状態を確認 |

### リトライ仕様

明示的なリトライ機能は実装されていません。Get-DbaCmObjectの接続フォールバック機能に依存しています。

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

読み取り専用操作のため、トランザクション制御は適用されません。

## パフォーマンス要件

特定のパフォーマンス要件は定義されていません。WMIクエリのレスポンス時間はネットワーク状況とクラスターの負荷状態に依存します。

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

- 各メンバーノードでのローカル管理者権限が必要
- Credentialパラメータによる代替資格情報のサポート
- WMI/CIM経由の安全な通信

## 備考

- このコマンドはSQL Server固有ではなく、WSFCリソースグループ全般を取得します
- SQL Server関連のリソースグループには "SQL Server (MSSQLSERVER)" や可用性グループ名が含まれます
- 全プロパティを表示するには `Select-Object *` をパイプで連結

---

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

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

### 推奨読解順序

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

WSFCリソースグループの情報は、WMI MSCluster_ResourceGroup クラスから取得されます。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | MSCluster_ResourceGroup WMIクラス | (Windows WMI) | Name, State, PersistentState, OwnerNode などのプロパティ構造 |

**読解のコツ**: WMI MSCluster_ResourceGroup クラスのプロパティは Microsoft ドキュメントで確認できます。State プロパティは数値で、-1, 0, 1, 2 の値を取ります。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaWsfcResourceGroup.ps1 | `public/Get-DbaWsfcResourceGroup.ps1` | メイン関数の構造、パラメータ定義 |

**主要処理フロー**:
1. **77-83行目**: パラメータ定義 (ComputerName, Credential, Name, EnableException)
2. **84-93行目**: begin ブロックで Get-ResourceGroupState 内部関数を定義
3. **95-109行目**: process ブロックでメイン処理を実行

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaWsfcCluster.ps1 | `public/Get-DbaWsfcCluster.ps1` | クラスター情報取得の仕組み |
| 3-2 | Get-DbaCmObject.ps1 | `public/Get-DbaCmObject.ps1` | WMI/CIMクエリの実行方法 |

**主要処理フロー**:
- **Get-DbaWsfcCluster**: クラスター名とFQDNを取得
- **Get-DbaCmObject**: WMI名前空間からオブジェクトを取得

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

```
Get-DbaWsfcResourceGroup
    │
    ├─ Get-DbaWsfcCluster (97行目)
    │      └─ Get-DbaCmObject (クラスター情報取得)
    │
    ├─ Get-DbaCmObject (98行目)
    │      └─ MSCluster_ResourceGroup WMIクラス照会
    │
    ├─ Get-ResourceGroupState (内部関数, 85-93行目)
    │      └─ 状態コードを文字列に変換
    │
    └─ Select-DefaultView (106行目)
           └─ 既定表示プロパティの設定
```

### データフロー図

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

ComputerName ───▶ Get-DbaWsfcCluster ───▶ ClusterName, Fqdn
                         │
                         ▼
                  Get-DbaCmObject
                  (MSCluster_ResourceGroup) ───▶ リソースグループ一覧
                         │
                         ▼
                  フィルタリング (Name パラメータ)
                         │
                         ▼
                  プロパティ追加・変換 ───▶ CimInstance オブジェクト
                         │                  (ClusterName, ClusterFqdn,
                         ▼                   Name, State, PersistentState,
                  Select-DefaultView         OwnerNode)
                         │
                         ▼
                  パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaWsfcResourceGroup.ps1 | `public/Get-DbaWsfcResourceGroup.ps1` | ソース | メイン機能実装 |
| Get-DbaWsfcCluster.ps1 | `public/Get-DbaWsfcCluster.ps1` | ソース | クラスター情報取得 |
| Get-DbaCmObject.ps1 | `public/Get-DbaCmObject.ps1` | ソース | WMI/CIMオブジェクト取得 |
| Get-DbaWsfcResourceGroup.Tests.ps1 | `tests/Get-DbaWsfcResourceGroup.Tests.ps1` | テスト | ユニットテスト |
