# 画面設計書 187-WSFCロール

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるWindows Server Failover Cluster（WSFC）ロール情報取得機能の設計を定義する。

### 本画面の処理概要

フェイルオーバークラスター内のロール（リソースグループ）の状態と所有権情報を取得する。SQL Server Failover Cluster InstancesやAvailability Groupを制御する基盤となるクラスターロールの可視性を提供する。

**業務上の目的・背景**：データベース管理者は、メンテナンスウィンドウ中のロール健全性検証、フェイルオーバー問題のトラブルシューティング、特定のSQL Serverリソースを現在ホストしているノードの確認が必要である。この機能により、数値状態コードを読みやすいステータス値（Online、Offline、Failed、Pending）に変換して、問題のあるロールを迅速に特定できる。

**画面へのアクセス方法**：PowerShellコンソールから以下のコマンドを実行する：
```powershell
Get-DbaWsfcRole -ComputerName <クラスター名またはノード名>
```

**主要な操作・処理内容**：
1. Get-DbaWsfcClusterでクラスター情報を取得
2. WMI名前空間からMSCluster_ResourceGroupを照会
3. Get-ResourceState関数で状態値を変換
4. クラスター情報をプロパティに追加
5. 結果オブジェクトを出力

**画面遷移**：単独のCLIコマンドとして動作。内部でGet-DbaWsfcClusterを呼び出す。

**権限による表示制御**：全てのWSFCコマンドは各メンバーノードでローカル管理者権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 565 | Get-DbaWsfcRole | 主機能 | WSFCロールの取得 |

## 画面種別

コマンドラインインターフェース（CLI）

## URL/ルーティング

PowerShellコマンド:
- `Get-DbaWsfcRole`

## 入出力項目

### Get-DbaWsfcRole パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| ComputerName | DbaInstanceParameter[] | No | 対象クラスターまたはノード名（デフォルト: $env:COMPUTERNAME） |
| Credential | PSCredential | No | 代替認証用資格情報 |
| EnableException | switch | No | 例外を有効にするフラグ |

## 表示項目

### Get-DbaWsfcRole 出力（デフォルト表示）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ClusterName | string | クラスター名 |
| ClusterFqdn | string | クラスターFQDN |
| Name | string | ロール名（通常はSQL Serverインスタンス名） |
| OwnerNode | string | 現在このロールをホストしているノード |
| State | string | 状態（Online/Offline/Failed/Partial Online/Pending/Unknown） |

### 追加プロパティ（Select-Object *で取得可能）

| 項目名 | 説明 |
|--------|------|
| Caption | リソースグループの短い説明 |
| Description | 詳細コメント |
| Id | ネットワーク識別子 |
| Status | ステータス文字列（OK/Error/Degraded等） |
| AutoFailbackType | 自動フェイルバック設定（0=禁止、1=許可） |
| FailbackWindowStart | フェイルバック開始時間 |
| FailbackWindowEnd | フェイルバック終了時間 |
| FailoverPeriod | フェイルオーバー閾値適用期間 |
| FailoverThreshold | 最大フェイルオーバー試行回数 |
| PersistentState | 永続状態 |
| Priority | 優先度値 |
| AntiAffinityClassNames | 同一ノードを避けるグループ |
| GroupType | リソースグループタイプ |
| IsCore | コアグループフラグ |

## イベント仕様

### 1-ロール情報取得

1. 指定されたComputerNameに対してループ処理開始
2. Get-DbaWsfcClusterでクラスター情報取得
3. Get-DbaCmObjectでWMI名前空間（root\MSCluster）のMSCluster_ResourceGroupクラスを照会
4. Get-ResourceState関数でState値を変換（注：ソースコードではresource変数を参照しているバグの可能性あり）
5. ClusterNameとClusterFqdnをNotePropertyとして追加
6. Select-DefaultViewでデフォルト表示プロパティを設定して出力

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

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

この機能はデータベースへの更新操作を行わない。WMIクエリによる読み取り専用操作のみ。

| 操作（イベント） | 対象 | 操作種別 | 概要 |
|----------------|------|---------|------|
| ロール情報取得 | WMI root\MSCluster | SELECT（読み取り） | ロール構成情報の取得 |

## メッセージ仕様

| 種別 | メッセージ | 発生条件 |
|------|----------|---------|
| Error | (WMI接続エラー) | クラスターへの接続失敗時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| WMI接続エラー | Get-DbaCmObjectのエラーハンドリングに委譲 |
| クラスター情報取得失敗 | Get-DbaWsfcClusterのエラーハンドリングに委譲 |

## 備考

- WMI名前空間: root\MSCluster
- WMIクラス: MSCluster_ResourceGroup
- ロールとリソースグループは同一のWMIクラスを使用
- 全てのWSFCコマンドは各メンバーノードでローカル管理者権限が必要

---

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

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

### 推奨読解順序

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

WMI MSCluster_ResourceGroupクラスの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaWsfcRole.ps1 | `public/Get-DbaWsfcRole.ps1` | 出力プロパティとSelect-DefaultViewの設定（行96） |

**読解のコツ**: ロールはMSCluster_ResourceGroupを使用しており、Get-DbaWsfcResourceGroupと同じWMIクラスを照会する。

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

Get-DbaWsfcRole関数の処理フローを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaWsfcRole.ps1 | `public/Get-DbaWsfcRole.ps1` | Get-DbaWsfcCluster呼び出し、Get-DbaCmObject呼び出し |

**主要処理フロー**:
1. **行82-88**: パラメータ定義
2. **行89-90**: processブロックでComputerNameループ開始
3. **行91**: Get-DbaWsfcClusterでクラスター情報取得
4. **行92**: Get-DbaCmObjectでWMI照会（MSCluster_ResourceGroup）
5. **行93**: Get-ResourceStateでState値変換
6. **行94-95**: ClusterNameとClusterFqdnをNotePropertyとして追加
7. **行96**: Select-DefaultViewでデフォルト表示プロパティを設定

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

```
Get-DbaWsfcRole (public/Get-DbaWsfcRole.ps1)
    │
    ├─ Get-DbaWsfcCluster
    │      └─ クラスター情報取得
    │
    ├─ Get-DbaCmObject
    │      └─ WMI Query (root\MSCluster\MSCluster_ResourceGroup)
    │
    ├─ Get-ResourceState (内部関数)
    │      └─ State数値を文字列に変換
    │
    └─ Select-DefaultView
           └─ デフォルト表示プロパティ設定
```

### データフロー図

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

ComputerName ────────────▶ Get-DbaWsfcCluster
                                    │
                                    ▼
                           Cluster情報取得
                           (Name, Fqdn)
                                    │
                                    ▼
                           Get-DbaCmObject
                           Namespace: root\MSCluster
                           ClassName: MSCluster_ResourceGroup
                                    │
                                    ▼
                           Get-ResourceState
                           (State数値→文字列変換)
                                    │
                                    ▼
                           Add-Member
                           (State, ClusterName, ClusterFqdn)
                                    │
                                    ▼
                           [CimInstance]
                           ├─ ClusterName
                           ├─ ClusterFqdn
                           ├─ Name
                           ├─ OwnerNode
                           └─ State
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaWsfcRole.ps1 | `public/Get-DbaWsfcRole.ps1` | ソース | ロール情報取得メイン関数 |
| Get-DbaWsfcCluster.ps1 | `public/Get-DbaWsfcCluster.ps1` | ソース | クラスター情報取得 |
| Get-DbaCmObject.ps1 | `public/Get-DbaCmObject.ps1` | ソース | WMIオブジェクト取得汎用関数 |
