# 機能設計書 638-Get-DbaDiskSpace

## 概要

本ドキュメントは、dbatools PowerShellモジュールのGet-DbaDiskSpaceコマンドレットの機能設計書である。このコマンドは、WMIを使用してSQL Serverホストシステムのディスク領域とファイルシステム詳細を取得し、容量監視とパフォーマンス分析に必要な情報を提供する。

### 本機能の処理概要

Get-DbaDiskSpaceは、WMIを使用してWindowsディスクボリュームの情報をクエリし、データベース管理に必要なストレージ情報を収集する。容量、空き領域、ファイルシステムタイプ、オプションのフラグメンテーション分析など、包括的なディスク詳細を返す。SQL Server容量計画に不可欠であり、データベース操作に影響が出る前にディスク領域を監視するのに役立つ。

**業務上の目的・背景**：ディスク領域の不足は、データベース操作の停止やデータ損失につながる可能性がある。DBAは、バックアップ操作前の十分な領域確認、データファイルやログファイルをホストするフラグメント化されたボリュームによるパフォーマンスボトルネックの特定、ストレージ使用率のコンプライアンスドキュメント維持のために、定期的にディスク領域を監視する必要がある。このコマンドは、これらのニーズに対応する。

**機能の利用シーン**：
- SQL Server容量計画とストレージ監視
- バックアップ操作前のディスク領域確認
- パフォーマンス問題のトラブルシューティング（フラグメンテーション分析）
- ストレージ使用率レポートの作成
- 複数サーバーにまたがるディスク領域の一括監視

**主要な処理内容**：
1. 指定されたコンピュータに対してWMI接続を確立
2. Win32_Volumeクラスからディスクボリューム情報を取得
3. DriveType条件でフィルタリング（デフォルトはローカルおよびリムーバブルディスク）
4. 結果をDataplat.Dbatools.Computer.DiskSpaceオブジェクトとして出力

**関連システム・外部連携**：WMI/CIM経由でWindowsシステムに接続。SQL Serverとは直接連携しないが、SQL Serverホストのストレージ監視に使用

**権限による制御**：ターゲットシステムへのWindows管理者アクセスが必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | コマンドライン/PowerShellコンソール | 主画面 | コマンド実行および結果表示 |

## 機能種別

データ取得 / システム監視

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | DbaInstanceParameter[] | No | 対象コンピュータ。デフォルトはローカル。パイプライン入力対応 | なし |
| Credential | PSCredential | No | 接続用の代替資格情報 | なし |
| Unit | String | No | 非推奨。表示単位（Bytes/KB/MB/GB/TB/PB） | ValidateSet |
| SqlCredential | PSCredential | No | SQL Server認証用資格情報（このコマンドでは未使用） | なし |
| ExcludeDrive | string[] | No | 除外するドライブ（例：'C:\'） | なし |
| CheckFragmentation | switch | No | フラグメンテーション分析を有効化 | なし |
| Force | switch | No | 隠しボリュームを含むすべてのドライブタイプを表示 | なし |
| EnableException | switch | No | 例外を有効にして詳細なエラー情報を取得 | なし |

### 入力データソース

- WMI Win32_Volumeクラスからディスクボリューム情報を取得
- root\CIMv2ネームスペースを使用

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | コンピュータ名 |
| Name | String | ボリューム名（ドライブレターまたはUNCパス） |
| Label | String | ボリュームラベル |
| Capacity | Long | 総ディスク容量（バイト単位、内部表示はGB） |
| Free | Long | 空き領域（バイト単位、内部表示はGB） |
| PercentFree | Decimal | 空き領域の割合 |
| BlockSize | Int | ファイルシステムブロックサイズ（バイト） |
| FileSystem | String | ファイルシステムタイプ（NTFS、FAT32、ReFS等） |
| Type | Int | ドライブタイプ識別子 |
| DriveType | String | ドライブタイプ（LocalDisk、RemovableDisk等） |
| IsSqlDisk | Boolean | SQL Serverファイルが検出されたかどうか |
| Server | String | サーバー名（ComputerNameと同じ） |

### 出力先

PowerShellパイプライン（Dataplat.Dbatools.Computer.DiskSpaceオブジェクト）

## 処理フロー

### 処理シーケンス

```
1. パラメータ処理
   └─ Forceスイッチに応じてDriveType条件を設定
   └─ 処理済みコンピュータの追跡用ArrayListを初期化

2. コンピュータごとの処理ループ
   └─ 重複チェック（処理済みならスキップ）

3. WMIクエリ実行
   └─ Get-DbaCmObjectでWin32_Volumeをクエリ
   └─ 接続失敗時はStop-Function -Continue

4. ディスクごとの処理ループ
   └─ ExcludeDriveでフィルタリング
   └─ UNCパス（\\で始まる）はForce未指定時にスキップ

5. 結果オブジェクト作成
   └─ Dataplat.Dbatools.Computer.DiskSpaceオブジェクトを作成
   └─ プロパティを設定

6. 出力
   └─ オブジェクトをパイプラインに出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[条件設定]
    B --> C{Force指定?}
    C -->|Yes| D[条件なし]
    C -->|No| E[DriveType 2 or 3]
    D --> F[コンピュータループ]
    E --> F
    F --> G{処理済み?}
    G -->|Yes| H[スキップ]
    G -->|No| I[Get-DbaCmObject]
    H --> J{次のPC?}
    I --> K{成功?}
    K -->|No| L[Stop-Function -Continue]
    K -->|Yes| M[ディスクループ]
    L --> J
    M --> N{ExcludeDrive?}
    N -->|Yes| O[スキップ]
    N -->|No| P{UNCパス?}
    O --> Q{次のディスク?}
    P -->|Yes,Force未指定| R[スキップ]
    P -->|No| S[DiskSpaceオブジェクト作成]
    R --> Q
    S --> T[出力]
    T --> Q
    Q -->|Yes| M
    Q -->|No| J
    J -->|Yes| F
    J -->|No| U[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | デフォルトDriveTypeフィルタ | DriveType 2（リムーバブル）または3（ローカル）のみ表示 | Force未指定時 |
| BR-002 | UNCパススキップ | \\で始まるパスはForce未指定時にスキップ | Force未指定時 |
| BR-003 | 重複コンピュータスキップ | 同一コンピュータの重複処理を防止 | 常時 |
| BR-004 | ExcludeDriveフィルタ | 指定されたドライブを除外 | ExcludeDrive指定時 |

### 計算ロジック

本コマンドは計算を行わず、WMIから取得した値をそのまま出力。PercentFreeはDiskSpaceオブジェクト内部で計算。

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

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

データベースへの操作なし。WMI経由でOSストレージ情報を取得。

| 操作 | 対象 | 操作種別 | 概要 |
|-----|------|---------|------|
| ストレージ情報取得 | Win32_Volume | WMIクエリ | ディスクボリューム情報取得 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | WMI接続失敗 | Stop-Function -Continueで次のコンピュータへ |

### リトライ仕様

リトライ機能なし。接続エラー時は当該コンピュータをスキップして次を処理。

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

データベース操作なしのため、トランザクション管理は不要。

## パフォーマンス要件

- WMI接続のため、ネットワーク遅延の影響を受ける
- CheckFragmentationを有効にすると、各ボリュームに対して数秒〜数分のオーバーヘッドが発生
- 大量のコンピュータを処理する場合、並列処理ではないため時間がかかる

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

- ターゲットシステムへのWindows管理者アクセスが必要
- Credentialパラメータで代替資格情報をサポート
- WMI通信はデフォルトでDCOM、セキュアな環境ではファイアウォール設定が必要

## 備考

- Unitパラメータは非推奨で1.0.0で削除予定。すべてのサイズプロパティ（Bytes/KB/MB/GB/TB/PB）が同時に利用可能
- 出力オブジェクトはDataplat.Dbatools.Computer.DiskSpace型で、サイズを各単位で動的計算
- 隠しボリュームやシステムボリュームはデフォルトで除外される

---

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

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

### 推奨読解順序

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

Dataplat.Dbatools.Computer.DiskSpaceオブジェクトの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDiskSpace.ps1 | `public/Get-DbaDiskSpace.ps1` | 174-184行目のDiskSpaceオブジェクト作成 |

**読解のコツ**: Dataplat.Dbatools.Computer.DiskSpaceは.NETクラスで定義されており、CapacityとFreeから各単位のサイズを動的計算する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDiskSpace.ps1 | `public/Get-DbaDiskSpace.ps1` | 137-147行目のbeginブロック |
| 2-2 | Get-DbaDiskSpace.ps1 | `public/Get-DbaDiskSpace.ps1` | 149-186行目のprocessブロック |

**主要処理フロー**:
1. **139-142行目**: Force指定に応じたWHERE条件設定
2. **145行目**: 処理済みコンピュータ追跡用ArrayList初期化

#### Step 3: WMIクエリ実行を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDiskSpace.ps1 | `public/Get-DbaDiskSpace.ps1` | 157-161行目のGet-DbaCmObject呼び出し |

**主要処理フロー**:
- **158行目**: Win32_Volumeクエリ実行
- **159-160行目**: エラー処理

#### Step 4: フィルタリングと出力を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaDiskSpace.ps1 | `public/Get-DbaDiskSpace.ps1` | 163-185行目のディスクループ |

**主要処理フロー**:
- **164-166行目**: ExcludeDriveフィルタ
- **167-170行目**: UNCパススキップ
- **174行目**: DiskSpaceオブジェクト作成

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

```
Get-DbaDiskSpace
    │
    ├─ Get-DbaCmObject
    │      └─ WMI Win32_Volume クエリ
    │
    ├─ New-Object Dataplat.Dbatools.Computer.DiskSpace
    │      └─ 出力オブジェクト作成
    │
    ├─ Write-Message
    │      └─ Verboseログ出力
    │
    └─ Stop-Function
           └─ エラー処理
```

### データフロー図

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

ComputerName          ───▶ Get-DbaCmObject
                           (Win32_Volume)
                                 │
                                 ▼
                           フィルタリング
                           (DriveType, ExcludeDrive)
                                 │
                                 ▼
                           DiskSpaceオブジェクト    ───▶ Dataplat.Dbatools
                           作成・出力                    .Computer.DiskSpace
                                                        - Name
                                                        - Capacity
                                                        - Free
                                                        - FileSystem
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDiskSpace.ps1 | `public/Get-DbaDiskSpace.ps1` | ソース | メイン処理ロジック |
| Get-DbaCmObject.ps1 | `functions/Get-DbaCmObject.ps1` | ソース | 内部依存（WMI/CIMクエリ実行） |
| DiskSpace.cs | （.NETライブラリ） | ソース | 出力オブジェクト型定義 |
