# 画面設計書 124-ディスクスペース

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるディスクスペース情報取得機能の設計仕様を定義する。SQL Serverホストマシンのディスク容量、空き領域、ファイルシステム詳細を包括的に収集し、キャパシティ監視とパフォーマンス分析を支援する。

### 本画面の処理概要

**業務上の目的・背景**：SQL Serverのキャパシティプランニングにおいて、ディスクスペースの監視は最も重要な運用タスクの一つである。データベースファイルの成長、バックアップ操作、ログファイルの拡張がディスク容量を超過すると、サービス停止につながる。本機能は、Win32_VolumeクラスをWMI経由で照会し、ディスク容量、空き領域、ブロックサイズ、ファイルシステム種別を収集する。これにより、複数サーバーの一括監視、容量アラートの設定、マイグレーション前の要件計算が可能になる。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドレットを実行してアクセスする。
```powershell
Get-DbaDiskSpace -ComputerName <コンピュータ名>
```

**主要な操作・処理内容**：
1. ターゲットコンピュータへのWMI接続
2. Win32_Volumeクラスからボリューム情報を取得（デフォルトでDriveType 2, 3のみ）
3. ExcludeDriveパラメータで指定されたドライブを除外
4. 隠しボリューム（UNCパスで始まるもの）をデフォルトでスキップ
5. Dataplat.Dbatools.Computer.DiskSpaceオブジェクトを構築して出力
6. オプションでフラグメンテーション分析を実行

**画面遷移**：本機能はCLIコマンドであり、GUI画面遷移は存在しない。関連コマンドとして`Measure-DbaDiskSpaceRequirement`でマイグレーション時のディスク要件を計算できる。

**権限による表示制御**：
- ローカルコンピュータの情報取得には管理者権限を推奨
- リモートコンピュータの操作にはWMIアクセス権限とリモート管理権限が必要

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 638 | Get-DbaDiskSpace | 主機能 | ディスクスペースの取得 |
| 645 | Measure-DbaDiskSpaceRequirement | 補助機能 | ディスクスペース要件の測定 |

## 画面種別

CLI（コマンドラインインターフェース） - 単一コマンドレット

## URL/ルーティング

PowerShellコマンドレット:
- `Get-DbaDiskSpace`
- `Measure-DbaDiskSpaceRequirement`

## 入出力項目

### Get-DbaDiskSpace パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| ComputerName | DbaInstanceParameter[] | No | $env:COMPUTERNAME | 情報を取得するコンピュータ名 |
| Credential | PSCredential | No | - | 代替資格情報 |
| Unit | string | No | GB | 表示単位（非推奨、1.0.0で削除予定） |
| SqlCredential | PSCredential | No | - | SQLインスタンス接続用資格情報 |
| ExcludeDrive | string[] | No | - | 除外するドライブ（例：'C:\'） |
| CheckFragmentation | switch | No | $false | フラグメンテーション分析を有効化 |
| Force | switch | No | $false | 全ドライブタイプと隠しボリュームを含める |
| EnableException | switch | No | $false | 例外を有効化 |

### Measure-DbaDiskSpaceRequirement パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| Source | DbaInstanceParameter | Yes | - | ソースSQL Serverインスタンス |
| Database | string | Yes | - | 分析するデータベース名 |
| SourceSqlCredential | PSCredential | No | - | ソースインスタンス用資格情報 |
| Destination | DbaInstanceParameter | Yes | - | 移行先SQL Serverインスタンス |
| DestinationDatabase | string | No | $Database | 移行先データベース名 |
| DestinationSqlCredential | PSCredential | No | - | 移行先インスタンス用資格情報 |
| Credential | PSCredential | No | - | CIM/WMI接続用資格情報 |
| EnableException | switch | No | $false | 例外を有効化 |

## 表示項目

### Get-DbaDiskSpace デフォルト表示プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| Name | string | ボリューム名（ドライブレターまたはUNCパス） |
| Label | string | ボリュームラベル |
| Capacity | DbaSize | 総容量 |
| Free | DbaSize | 空き領域 |
| PercentFree | decimal | 空き領域の割合（%） |
| BlockSize | int | ファイルシステムブロックサイズ（バイト） |

### Get-DbaDiskSpace 追加プロパティ（Select-Object *で表示）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| FileSystem | string | ファイルシステム種別（NTFS, FAT32, ReFS等） |
| Type | int | ドライブタイプ識別子 |
| DriveType | string | ドライブタイプ名（LocalDisk, RemovableDisk等） |
| IsSqlDisk | bool | SQL Serverファイルが存在するかどうか |
| Server | string | サーバー名 |
| SizeInBytes | long | 総容量（バイト） |
| FreeInBytes | long | 空き領域（バイト） |
| SizeInKB | decimal | 総容量（KB） |
| FreeInKB | decimal | 空き領域（KB） |
| SizeInMB | decimal | 総容量（MB） |
| FreeInMB | decimal | 空き領域（MB） |
| SizeInGB | decimal | 総容量（GB） |
| FreeInGB | decimal | 空き領域（GB） |
| SizeInTB | decimal | 総容量（TB） |
| FreeInTB | decimal | 空き領域（TB） |
| SizeInPB | decimal | 総容量（PB） |
| FreeInPB | decimal | 空き領域（PB） |

### Measure-DbaDiskSpaceRequirement 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| SourceSqlInstance | string | ソースSQL Serverインスタンス名 |
| SourceDatabase | string | ソースデータベース名 |
| SourceLogicalName | string | ソースファイルの論理名 |
| SourceFileName | string | ソースファイルのパス |
| SourceFileSize | DbaSize | ソースファイルサイズ |
| DestinationComputerName | string | 移行先コンピュータ名 |
| DestinationSqlInstance | string | 移行先SQL Serverインスタンス名 |
| DestinationDatabase | string | 移行先データベース名 |
| DestinationFileName | string | 移行先ファイルのパス |
| DestinationFileSize | DbaSize | 移行先ファイルサイズ |
| DifferenceSize | DbaSize | ファイルサイズの差分 |
| MountPoint | string | マウントポイント |
| FileLocation | string | ファイルの場所（Source and Destination/Only on Source/Only on Destination） |

## イベント仕様

### 1-ディスクスペース情報取得（Get-DbaDiskSpace）

指定されたコンピュータのディスクスペース情報を取得する。

**処理フロー**:
1. Forceパラメータ未指定時、DriveType 2または3のみを対象とするWHERE句を設定
2. 処理済みコンピュータをArrayListで追跡し重複を防止
3. `Get-DbaCmObject -Query "SELECT * FROM Win32_Volume$condition"`でボリューム情報取得
4. ExcludeDriveで指定されたドライブをスキップ
5. UNCパス（\\で始まる）のボリュームはForce未指定時にスキップ
6. Dataplat.Dbatools.Computer.DiskSpaceオブジェクトを構築
7. 各プロパティ（ComputerName, Name, Label, Capacity, Free, BlockSize, FileSystem, Type）を設定
8. オブジェクトをパイプラインに出力

### 2-ディスクスペース要件測定（Measure-DbaDiskSpaceRequirement）

データベースマイグレーション時のディスクスペース要件を計算する。

**処理フロー**:
1. ソースインスタンスに接続
2. 移行先インスタンスに接続
3. DestinationDatabase未指定時は$Databaseを使用
4. ソースデータベースのFileGroupsとLogFilesを取得
5. 移行先に同名データベースが存在する場合、そのファイル情報も取得
6. ソースと移行先の両方にあるファイル、ソースのみのファイル、移行先のみのファイルを比較
7. マウントポイント情報をWin32_MountPointから取得
8. PSCustomObjectを構築してファイルごとの差分情報を出力

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

本機能はSQL Serverデータベースには直接アクセスしない（Measure-DbaDiskSpaceRequirementを除く）。WMI経由でWindowsシステム情報を取得する。

### 操作別影響一覧

| 操作（イベント） | 対象リソース | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaDiskSpace | Win32_Volume | READ | ボリューム情報の読み取り |
| Measure-DbaDiskSpaceRequirement | SQL Server Database | READ | データベースファイル情報の読み取り |
| Measure-DbaDiskSpaceRequirement | Win32_MountPoint | READ | マウントポイント情報の読み取り |

## メッセージ仕様

| メッセージID | 種別 | メッセージ | 発生条件 |
|-------------|------|---------|---------|
| - | Error | "Failed to connect to $computer." | WMI接続に失敗 |
| - | Verbose | "Skipping disk: $($disk.Name)" | UNCパスのボリュームをスキップ時 |
| - | Verbose | "Processing disk: $($disk.Name)" | ボリューム処理開始時 |
| - | Verbose | "Database [$DestinationDatabase] does not exist on Destination Instance $Destination." | 移行先にデータベースが存在しない |
| - | Warning | "Path $path can't be found in any MountPoints of $computerName" | マウントポイントが見つからない |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| WMI接続失敗 | Stop-Functionでエラーを出力し、次のコンピュータの処理を継続 |
| マウントポイント取得失敗 | キャッシュに'?'を設定し、以後の問い合わせをスキップ |
| ソースインスタンス接続失敗 | Stop-Functionでエラーを出力し処理を終了 |
| 移行先インスタンス接続失敗 | Stop-Functionでエラーを出力し処理を終了 |
| ソースデータベースが存在しない | Stop-Functionでエラーを出力 |

## 備考

- DriveTypeの値:
  - 2: RemovableDisk（リムーバブルディスク）
  - 3: LocalDisk（ローカルディスク）
  - 4: NetworkDrive（ネットワークドライブ）
  - 5: CompactDisc（CD/DVD）
- デフォルトではDriveType 2と3のみが返される。Forceパラメータで全タイプを取得可能
- Unitパラメータは非推奨であり、1.0.0で削除予定。全サイズ情報は隠しプロパティとして常に利用可能
- Measure-DbaDiskSpaceRequirementはパイプライン入力をサポートし、CSVファイルやSQLテーブルからの一括処理が可能

---

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

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

### 推奨読解順序

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

出力オブジェクトのプロパティ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDiskSpace.ps1 | `public/Get-DbaDiskSpace.ps1` | 行174-184のDiskSpaceオブジェクト構築でプロパティ構造を確認 |
| 1-2 | Measure-DbaDiskSpaceRequirement.ps1 | `public/Measure-DbaDiskSpaceRequirement.ps1` | 行267-285のPSCustomObjectでマイグレーション要件の出力構造を確認 |

**読解のコツ**: Win32_VolumeクラスのプロパティがどのようにDiskSpaceオブジェクトにマッピングされているかを確認する。

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

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

**主要処理フロー（Get-DbaDiskSpace）**:
1. **139-142行**: Forceパラメータ未指定時のDriveType条件設定
2. **144-146行**: 処理済みコンピュータ追跡用ArrayList
3. **150-155行**: 重複コンピュータのスキップ
4. **157-161行**: `Get-DbaCmObject`でWin32_Volume照会
5. **163-170行**: ExcludeDriveとUNCパスのスキップ処理
6. **174-184行**: DiskSpaceオブジェクトの構築と出力

#### Step 3: Measure-DbaDiskSpaceRequirementを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Measure-DbaDiskSpaceRequirement.ps1 | `public/Measure-DbaDiskSpaceRequirement.ps1` | processブロック（行227-339） |

**主要処理フロー（Measure-DbaDiskSpaceRequirement）**:
1. **228-240行**: ソースと移行先インスタンスへの接続
2. **242-244行**: DestinationDatabaseの設定
3. **247-261行**: ソースと移行先のデータベースファイル取得
4. **263-311行**: ファイル比較とオブジェクト構築（3つのシナリオ）
5. **313-337行**: 移行先のみに存在するファイルの処理

#### Step 4: 内部依存関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaCmObject | `internal/functions/Get-DbaCmObject.ps1` | WMI/CIMオブジェクト取得 |
| 4-2 | Get-MountPoint | Measure-DbaDiskSpaceRequirement.ps1内 | 行139-147のローカル関数 |
| 4-3 | Get-MountPointFromPath | Measure-DbaDiskSpaceRequirement.ps1内 | 行148-176のローカル関数 |

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

```
Get-DbaDiskSpace
    |
    +-- Get-DbaCmObject -Query "SELECT * FROM Win32_Volume..."
    |      +-- Get-CimInstance または Get-WmiObject
    |
    +-- [Dataplat.Dbatools.Computer.DiskSpace] オブジェクト構築
    |
    +-- パイプライン出力

Measure-DbaDiskSpaceRequirement
    |
    +-- Connect-DbaInstance (Source)
    |
    +-- Connect-DbaInstance (Destination)
    |
    +-- Get-DbaDatabase (Source)
    |
    +-- Get-DbaDatabase (Destination) [存在時]
    |
    +-- Get-MountPoint (ローカル関数)
    |      +-- Get-DbaCmObject -Class Win32_MountPoint
    |
    +-- Get-MountPointFromPath (ローカル関数)
    |
    +-- Get-MountPointFromDefaultPath (ローカル関数)
    |      +-- Get-DbaDefaultPath
    |
    +-- [PSCustomObject] 出力オブジェクト構築
    |
    +-- Select-DefaultView
```

### データフロー図

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

ComputerName ──────────> Get-DbaCmObject ──────────────────>
                        (Win32_Volume)
                                |
                                v
ExcludeDrive ──────────> フィルタリング ───────────────────>
                                |
Force ─────────────────> UNCパス判定 ──────────────────────>
                                |
                                v
                        DiskSpaceオブジェクト ──────────────> 出力

[出力オブジェクト]
    ComputerName, Name, Label, Capacity, Free,
    PercentFree, BlockSize, FileSystem, DriveType

---

[Measure-DbaDiskSpaceRequirement]

Source ────────────────> Connect-DbaInstance ──────────────>
                                |
                                v
Database ──────────────> Get-DbaDatabase ──────────────────> SourceFiles
                                |
                                v
Destination ───────────> Connect-DbaInstance ──────────────>
                                |
                                v
                        Get-DbaDatabase ──────────────────> DestFiles
                                |
                                v
                        Compare-Object ────────────────────>
                                |
                                v
                        Get-MountPoint ────────────────────> MountPoint
                                |
                                v
                        PSCustomObject ────────────────────> 出力

[出力オブジェクト]
    SourceSqlInstance, SourceDatabase, SourceFileSize,
    DestinationSqlInstance, DestinationFileSize, DifferenceSize, MountPoint
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDiskSpace.ps1 | `public/Get-DbaDiskSpace.ps1` | ソース | ディスクスペース取得コマンド |
| Measure-DbaDiskSpaceRequirement.ps1 | `public/Measure-DbaDiskSpaceRequirement.ps1` | ソース | ディスク要件計算コマンド |
| Get-DbaCmObject.ps1 | `internal/functions/Get-DbaCmObject.ps1` | 内部関数 | WMI/CIMオブジェクト取得 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | 依存コマンド | データベース情報取得 |
| Get-DbaDefaultPath.ps1 | `public/Get-DbaDefaultPath.ps1` | 依存コマンド | デフォルトパス取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | 依存コマンド | SQLインスタンス接続 |
