# 機能設計書 693-Get-DbaWsfcSharedVolume

## 概要

本ドキュメントは、Windows Server Failover Cluster のクラスター共有ボリューム (CSV) 情報を取得するdbatools PowerShellコマンド `Get-DbaWsfcSharedVolume` の機能設計書です。

### 本機能の処理概要

`Get-DbaWsfcSharedVolume` は、Windows Server Failover Cluster のクラスター共有ボリューム (CSV) の構成情報と運用状態を取得する機能です。CSV は SQL Server フェイルオーバークラスターインスタンス (FCI) やその他のクラスター化されたアプリケーションの共有ストレージ基盤を提供します。

**業務上の目的・背景**：クラスター環境でのストレージ健全性の監視やトラブルシューティングにおいて、CSVの状態を把握することは不可欠です。SQL Server導入前のCSV健全性確認、クラスター環境でのストレージ関連パフォーマンス問題の調査、災害復旧計画のための共有ストレージ構成のドキュメント化などに活用されます。

**機能の利用シーン**：
- SQL Server FCI導入前のCSV健全性確認
- クラスターストレージ関連の問題調査
- 共有ストレージ構成のドキュメント化
- 災害復旧計画の策定

**主要な処理内容**：
1. 指定されたコンピューター名からクラスター情報を取得 (Get-DbaWsfcCluster呼び出し)
2. WMI/CIM経由でClusterSharedVolume クラスを照会
3. クラスター名、FQDN、状態情報をオブジェクトに追加
4. 結果をパイプラインに出力

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

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

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

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ClusterName | string | Windows Server Failover Clusterの名前 |
| ClusterFqdn | string | クラスターの完全修飾ドメイン名 |
| State | string | クラスター共有ボリュームの現在の状態 (Online, Offline, Failed等) |
| (その他) | 各種 | ClusterSharedVolume WMIクラスのプロパティ |

### 出力先

PowerShellパイプライン (System.Management.ManagementObject)

## 処理フロー

### 処理シーケンス

```
1. process ブロック
   └─ ComputerName パラメータの各コンピューターに対してループ
      ├─ Get-DbaWsfcCluster を呼び出してクラスター情報を取得
      ├─ Get-DbaCmObject でClusterSharedVolumeクラスを照会
      ├─ ClusterName プロパティを追加
      ├─ ClusterFqdn プロパティを追加
      ├─ State プロパティを追加（Get-ResourceState で変換）
      └─ オブジェクトをパイプラインに出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{ComputerNameループ}
    B --> C[Get-DbaWsfcCluster呼び出し]
    C --> D[Get-DbaCmObject でClusterSharedVolume取得]
    D --> E[ClusterName追加]
    E --> F[ClusterFqdn追加]
    F --> G[State追加]
    G --> H[オブジェクト出力]
    H --> I{次のコンピューター?}
    I -->|Yes| B
    I -->|No| J[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 権限要件 | ローカル管理者権限が必要 | 常時 |
| BR-002 | 状態変換 | Get-ResourceState関数で状態を文字列に変換 | 常時 |

### 計算ロジック

状態変換はGet-ResourceState関数（共通関数）で実行されます。

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

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

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

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

## パフォーマンス要件

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

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

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

## 備考

- ソースコードにコメントがあり、開発者がCSV環境を持っていないためパススルー出力となっている
- 共有ボリュームが存在しないクラスターでは何も返されない
- 全プロパティを表示するには `Select-Object *` をパイプで連結

---

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

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

### 推奨読解順序

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

WSFC共有ボリュームの情報は、WMI ClusterSharedVolume クラスから取得されます。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ClusterSharedVolume WMIクラス | (Windows WMI) | CSV関連のプロパティ構造 |

**読解のコツ**: WMI ClusterSharedVolume クラスのプロパティは Microsoft ドキュメントで確認できます。

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

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

**主要処理フロー**:
1. **53-59行目**: パラメータ定義 (ComputerName, Credential, EnableException)
2. **60-69行目**: process ブロックでメイン処理を実行
3. **64行目**: 開発者コメント「I don't have a shared volume, so I can't see how to clean this up: Passthru」

#### 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-DbaWsfcSharedVolume
    │
    ├─ Get-DbaWsfcCluster (62行目)
    │      └─ Get-DbaCmObject (クラスター情報取得)
    │
    ├─ Get-DbaCmObject (63行目)
    │      └─ ClusterSharedVolume WMIクラス照会
    │
    └─ Get-ResourceState (67行目)
           └─ 状態コードを文字列に変換
```

### データフロー図

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

ComputerName ───▶ Get-DbaWsfcCluster ───▶ ClusterName, Fqdn
                         │
                         ▼
                  Get-DbaCmObject
                  (ClusterSharedVolume) ───▶ CSV一覧
                         │
                         ▼
                  プロパティ追加 ───▶ WMI オブジェクト
                         │           (ClusterName, ClusterFqdn,
                         ▼            State, その他CSVプロパティ)
                  パイプライン出力
```

### 関連ファイル一覧

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