# 機能設計書 565-Get-DbaWsfcRole

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるGet-DbaWsfcRoleコマンドレットの機能設計を定義する。本機能は、Windows Server Failover Clustering（WSFC）のロール（リソースグループ）情報を取得し、SQL Serverフェイルオーバークラスターインスタンスや可用性グループの基盤となるクラスターリソースの状態監視を実現する。

### 本機能の処理概要

**業務上の目的・背景**：SQL Server高可用性構成（FCI、Always On AG）はWSFCに依存している。クラスターロールの状態（Online、Offline、Failed等）や所有ノードを把握することは、メンテナンスウィンドウの計画、フェイルオーバー問題のトラブルシューティング、クラスター健全性監視において重要である。本機能は、WMIを通じてクラスターリソースグループ情報を取得し、SQL Server DBAがクラスター層の状態を可視化できるようにする。

**機能の利用シーン**：
- クラスター健全性のモニタリングダッシュボード作成
- メンテナンス前のクラスターロール状態確認
- フェイルオーバー発生時の所有ノード確認
- クラスター構成の棚卸しとドキュメント化
- SQL Server FCIやAGのトラブルシューティング

**主要な処理内容**：
1. Get-DbaWsfcClusterでクラスター情報を取得
2. Get-DbaCmObjectでWMI MSCluster_ResourceGroupを照会
3. 各リソースグループにState、ClusterName、ClusterFqdnを追加
4. Select-DefaultViewで出力整形

**関連システム・外部連携**：
- Windows Server Failover Clustering WMI名前空間（root\MSCluster）
- Get-DbaWsfcClusterコマンドとの連携
- Get-DbaCmObjectによるWMI/CIM照会

**権限による制御**：
- クラスターノードへのローカル管理者権限が必要
- WMI名前空間へのアクセス権限が必要

## 関連画面

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

## 機能種別

データ取得（SELECT）/ インフラ監視 / 高可用性

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | DbaInstanceParameter[] | No | クラスターノード名またはクラスター名 | デフォルト$env:COMPUTERNAME、パイプライン可 |
| Credential | PSCredential | No | 代替認証情報 | Windows認証のみ |
| EnableException | switch | No | 例外を直接スローする | デフォルトは警告メッセージ表示 |

### 入力データソース

- パイプライン入力：ComputerNameパラメータがValueFromPipelineを受け付ける
- デフォルト：ローカルコンピュータ（$env:COMPUTERNAME）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ClusterName | string | クラスター名 |
| ClusterFqdn | string | クラスターの完全修飾ドメイン名 |
| Name | string | リソースグループ（ロール）名 |
| OwnerNode | string | 現在の所有ノード名 |
| State | string | 状態（Online、Offline、Failed、Partial Online、Pending、Unknown） |

### 出力先

- PowerShellパイプライン：CimInstanceオブジェクト（拡張プロパティ付き）
- Select-DefaultViewで既定表示プロパティを設定

## 処理フロー

### 処理シーケンス

```
1. processブロックで各ComputerNameに対して処理

2. Get-DbaWsfcClusterでクラスター情報取得
   └─ ClusterName、ClusterFqdnを取得

3. Get-DbaCmObjectでMSCluster_ResourceGroup照会
   └─ WMI名前空間root\MSClusterを使用
   └─ リソースグループオブジェクト取得

4. 各ロールに対してプロパティ追加
   └─ Get-ResourceState関数でState数値を文字列に変換
   └─ ClusterName、ClusterFqdnを追加

5. Select-DefaultViewで出力整形
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[ComputerNameループ開始]
    B --> C[Get-DbaWsfcCluster実行]
    C --> D[$cluster取得]
    D --> E[Get-DbaCmObject実行]
    E --> F[MSCluster_ResourceGroup取得]
    F --> G[$roleループ開始]
    G --> H[Get-ResourceState関数でState変換]
    H --> I[Add-Member: State]
    I --> J[Add-Member: ClusterName]
    J --> K[Add-Member: ClusterFqdn]
    K --> L[Select-DefaultView]
    L --> M{次のロールあり?}
    M -->|Yes| G
    M -->|No| N{次のComputerNameあり?}
    N -->|Yes| B
    N -->|No| O[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ローカル管理者必須 | クラスターノードへのローカル管理者権限が必要 | 全操作 |
| BR-002 | State変換 | 数値状態を文字列に変換（0=Unknown等） | 出力時 |
| BR-003 | デフォルトローカル | ComputerName省略時はローカルマシン対象 | パラメータ省略時 |

### 計算ロジック

**State変換（Get-ResourceState関数）**:
- 0 → Unknown
- 1 → Online
- 2 → Offline
- 3 → Failed
- 4 → Partial Online
- 128 → Pending
- その他 → Unknown

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

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

本機能はSQL Serverデータベースへの操作は行わない。

| 操作 | 対象 | 操作種別 | 概要 |
|-----|-------------|---------|------|
| WMI照会 | root\MSCluster\MSCluster_ResourceGroup | SELECT | クラスターリソースグループ情報 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| WmiError | WMI接続エラー | WMI名前空間アクセス失敗 | 権限確認、クラスターサービス確認 |
| ClusterError | クラスター取得エラー | Get-DbaWsfcCluster失敗 | クラスター構成確認 |
| PermissionError | 権限エラー | ローカル管理者権限なし | 権限付与または昇格実行 |

### リトライ仕様

リトライ機能は実装されていない。エラー発生時はdbatools標準のエラーハンドリングに従う。

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

読み取り専用のWMI照会であり、トランザクション制御は不要。

## パフォーマンス要件

- WMI照会は軽量な操作
- クラスターリソースグループ数は通常少数（数個から数十個）
- 複数クラスター指定時は順次処理

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

- クラスターノードへのローカル管理者権限が必要
- 認証情報はPSCredentialオブジェクトを使用
- クラスター情報は機密性が高いため、出力の取り扱いに注意

## 備考

- WSFCコマンドすべてにローカル管理者権限が必要
- クラスターサービスが実行中でないと情報取得不可
- SQL Server FCI名やAG名がリソースグループ名として表示される

---

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

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

### 推奨読解順序

#### Step 1: パラメータ定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaWsfcRole.ps1 | `public/Get-DbaWsfcRole.ps1` | パラメータ定義（83-88行目） |

**読解のコツ**: ComputerNameのデフォルト値が$env:COMPUTERNAMEであることに注目。

**主要処理フロー**:
- **84-85行目**: ComputerNameはValueFromPipeline対応、デフォルト$env:COMPUTERNAME
- **86行目**: Credentialパラメータ

#### Step 2: メイン処理フローを理解する

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

**主要処理フロー**:
- **91行目**: Get-DbaWsfcClusterでクラスター情報取得
- **92行目**: Get-DbaCmObjectでMSCluster_ResourceGroup取得
- **93行目**: Add-MemberでStateプロパティ追加（Get-ResourceState関数使用）
- **94行目**: Add-MemberでClusterNameプロパティ追加
- **95行目**: Add-MemberでClusterFqdnプロパティ追加
- **96行目**: Select-DefaultViewで出力整形

#### Step 3: 依存コマンドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaWsfcCluster.ps1 | `public/Get-DbaWsfcCluster.ps1` | クラスター情報取得 |
| 3-2 | Get-DbaCmObject.ps1 | `functions/Get-DbaCmObject.ps1` | WMI/CIM照会 |

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

```
Get-DbaWsfcRole
    │
    ├─ Get-DbaWsfcCluster（クラスター情報取得）
    │      └─ $cluster.Name, $cluster.Fqdn
    │
    ├─ Get-DbaCmObject（WMI照会）
    │      └─ -Namespace root\MSCluster
    │      └─ -ClassName MSCluster_ResourceGroup
    │
    ├─ Get-ResourceState（State数値→文字列変換）
    │      └─ 0=Unknown, 1=Online, 2=Offline, 3=Failed, 4=Partial Online, 128=Pending
    │
    └─ Add-Member（プロパティ追加）
           ├─ State
           ├─ ClusterName
           └─ ClusterFqdn
           │
           └─ Select-DefaultView（出力整形）
```

### データフロー図

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

ComputerName ────────────▶ Get-DbaWsfcCluster ─────────────▶ $cluster
                                  │
                           $cluster.Name ─────────────────▶ ClusterName
                           $cluster.Fqdn ─────────────────▶ ClusterFqdn
                                  │
                           Get-DbaCmObject ───────────────▶ $role（CimInstance）
                                  │
                           Get-ResourceState ─────────────▶ State（文字列）
                                  │
                           Add-Member ────────────────────▶ 拡張$role
                                  │
                           Select-DefaultView ────────────▶ 出力オブジェクト
                           {ClusterName, ClusterFqdn, Name, OwnerNode, State}
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaWsfcRole.ps1 | `public/Get-DbaWsfcRole.ps1` | ソース | メイン機能実装 |
| Get-DbaWsfcCluster.ps1 | `public/Get-DbaWsfcCluster.ps1` | ソース | クラスター情報取得 |
| Get-DbaCmObject.ps1 | `functions/Get-DbaCmObject.ps1` | ソース | WMI/CIM照会 |
