# 画面設計書 125-ディスクテスト

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるディスクテスト機能の設計仕様を定義する。SQL Serverホストマシンのディスクパーティションアライメント、アロケーションユニットサイズ、I/Oパフォーマンスを検証し、ストレージ構成の最適化を支援する。

### 本画面の処理概要

**業務上の目的・背景**：SQL ServerのI/Oパフォーマンスは、基盤となるストレージ構成に大きく依存する。パーティションのアライメント不良、不適切なアロケーションユニットサイズ、ストレージのボトルネックは、データベースパフォーマンスに重大な悪影響を与える。本機能群は、ディスクパーティションの開始オフセットがストライプユニットサイズと適切にアラインされているか、NTFSボリュームが64KBアロケーションユニットでフォーマットされているか、sys.dm_io_virtual_file_statsを通じてI/Oレイテンシが許容範囲内かを検証する。

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

**主要な操作・処理内容**：
1. **Test-DbaDiskAlignment**: CIMを通じてWin32_DiskPartitionを照会し、パーティションオフセットを取得。5つの一般的なストライプサイズ（64KB〜1024KB）に対してアライメントを検証
2. **Test-DbaDiskAllocation**: Win32_Volumeを照会し、NTFSボリュームのブロックサイズが64KB（65536バイト）のベストプラクティスに従っているか確認
3. **Test-DbaDiskSpeed**: sys.dm_io_virtual_file_statsをクエリし、読み取り/書き込みレイテンシを測定してパフォーマンス評価を提供

**画面遷移**：本機能はCLIコマンドであり、GUI画面遷移は存在しない。関連コマンドとして`Get-DbaDiskSpace`でディスク容量を確認できる。

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 653 | Test-DbaDiskAlignment | 主機能 | ディスクアライメントのテスト |
| 654 | Test-DbaDiskAllocation | 補助機能 | ディスクアロケーションのテスト |
| 655 | Test-DbaDiskSpeed | 補助機能 | ディスク速度のテスト |

## 画面種別

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

## URL/ルーティング

PowerShellコマンドレット:
- `Test-DbaDiskAlignment`
- `Test-DbaDiskAllocation`
- `Test-DbaDiskSpeed`

## 入出力項目

### Test-DbaDiskAlignment パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| ComputerName | DbaInstanceParameter[] | Yes | - | テスト対象のコンピュータ名 |
| Credential | PSCredential | No | - | 代替Windows資格情報 |
| SqlCredential | PSCredential | No | - | SQL Server接続用資格情報 |
| NoSqlCheck | switch | No | $false | SQL Serverファイルを含むディスクのみの制限を解除 |
| EnableException | switch | No | $false | 例外を有効化 |

### Test-DbaDiskAllocation パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| ComputerName | object[] | Yes | - | テスト対象のコンピュータ名 |
| NoSqlCheck | switch | No | $false | SQL Serverファイルを含むディスクのみの制限を解除 |
| SqlCredential | PSCredential | No | - | SQL Server接続用資格情報 |
| Credential | PSCredential | No | - | 代替Windows資格情報 |
| EnableException | switch | No | $false | 例外を有効化 |

### Test-DbaDiskSpeed パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| SqlInstance | DbaInstance[] | Yes | - | テスト対象のSQL Serverインスタンス |
| SqlCredential | PSCredential | No | - | SQL Server接続用資格情報 |
| Database | object[] | No | - | 対象データベース |
| ExcludeDatabase | object[] | No | - | 除外データベース |
| AggregateBy | string | No | File | 集計レベル（File/Database/Disk） |
| EnableException | switch | No | $false | 例外を有効化 |

## 表示項目

### Test-DbaDiskAlignment 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| Name | string | パーティション名またはドライブレター |
| PartitionSize | DbaSize | パーティションサイズ |
| PartitionType | string | パーティションタイプ |
| TestingStripeSize | DbaSize | テスト中のストライプサイズ（64KB〜1024KB） |
| OffsetModuluCalculation | DbaSize | オフセット % ストライプサイズの結果 |
| StartingOffset | DbaSize | パーティション開始オフセット |
| IsOffsetBestPractice | bool | オフセットがベストプラクティスか |
| IsBestPractice | bool | テストしたストライプサイズにアラインしているか |
| NumberOfBlocks | long | パーティション内のブロック数 |
| BootPartition | bool | ブートパーティションか |
| PartitionBlockSize | int | パーティションのブロックサイズ |
| IsDynamicDisk | bool | ダイナミックディスクか |

### Test-DbaDiskAllocation 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| DiskName | string | ディスク名 |
| DiskLabel | string | ディスクラベル |
| BlockSize | int | アロケーションユニットサイズ（バイト） |
| IsSqlDisk | bool | SQL Serverファイルが存在するか |
| IsBestPractice | bool | 64KBアロケーションユニットか |

### Test-DbaDiskSpeed 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | SQL Serverインスタンス名 |
| Database | string | データベース名（File/Database集計時） |
| SizeGB | decimal | ファイルサイズ（GB、File集計時） |
| FileName | string | ファイル名（File集計時） |
| FileID | int | ファイルID（File集計時） |
| FileType | string | ファイルタイプ（Data/Log） |
| DiskLocation | string | ディスク位置（Disk集計時） |
| Reads | long | 読み取り操作数 |
| AverageReadStall | int | 平均読み取りレイテンシ（ms） |
| ReadPerformance | string | 読み取りパフォーマンス評価 |
| Writes | long | 書き込み操作数 |
| AverageWriteStall | int | 平均書き込みレイテンシ（ms） |
| WritePerformance | string | 書き込みパフォーマンス評価 |
| Avg Overall Latency | int | 平均全体レイテンシ（ms） |
| Avg Bytes/Read | long | 平均読み取りバイト数 |
| Avg Bytes/Write | long | 平均書き込みバイト数 |
| Avg Bytes/Transfer | long | 平均転送バイト数 |

## イベント仕様

### 1-ディスクアライメントテスト（Test-DbaDiskAlignment）

パーティションのアライメント状態を検証する。

**処理フロー**:
1. `Resolve-DbaNetworkName`でコンピュータ名を解決
2. WSMan経由でCimSessionを作成、失敗時はDCOMにフォールバック
3. `Get-CimInstance -ClassName Win32_DiskPartition`でパーティション情報取得
4. `ASSOCIATORS OF`クエリでWin32_LogicalDiskToPartitionを取得
5. NoSqlCheck未指定時、`Win32_Service`からSQL Serverインスタンスを検出
6. SQL Serverインスタンスに接続し、sys.master_filesをクエリしてSQLディスクを判定
7. 各パーティションに対して5つのストライプサイズ（64, 128, 256, 512, 1024KB）でアライメント検証
8. ダイナミックディスク（Logical Disk Manager）の場合は警告を出力
9. PSCustomObjectを構築して出力

### 2-ディスクアロケーションテスト（Test-DbaDiskAllocation）

アロケーションユニットサイズのベストプラクティス準拠を検証する。

**処理フロー**:
1. `Resolve-DbaComputerName`でコンピュータ名を解決
2. WSMan経由でCimSessionを作成、失敗時はDCOMにフォールバック
3. `Get-CimInstance -ClassName win32_volume -Filter "FileSystem='NTFS'"`でNTFSボリューム取得
4. NoSqlCheck未指定時、`Get-DbaService`でSQL Serverインスタンスを検出
5. 各ディスクに対してsys.master_filesをクエリしてSQLディスクを判定
6. BlockSizeが65536（64KB）かどうかでベストプラクティス判定
7. システムドライブはベストプラクティス対象外として除外
8. PSCustomObjectを構築してSelect-DefaultViewで出力

### 3-ディスク速度テスト（Test-DbaDiskSpeed）

I/Oパフォーマンス統計を取得・分析する。

**処理フロー**:
1. `Connect-DbaInstance -MinimumVersion 9`でSQL Server 2005以降に接続
2. AggregateByパラメータに応じてSQLクエリを構築
3. sys.dm_io_virtual_file_statsとsys.master_filesをジョイン
4. ホストプラットフォーム（Windows/Linux）に応じてパス処理を分岐
5. 読み取り/書き込みレイテンシに基づいてパフォーマンス評価を計算
   - < 10ms: Very Good
   - < 20ms: OK
   - < 50ms: Slow, Needs Attention
   - >= 50ms: Serious I/O Bottleneck
6. 結果をパイプラインに出力

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

本機能はSQL Serverデータベースの更新は行わない。読み取り専用の診断機能である。

### 操作別影響一覧

| 操作（イベント） | 対象リソース | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Test-DbaDiskAlignment | Win32_DiskPartition | READ | パーティション情報の読み取り |
| Test-DbaDiskAlignment | Win32_LogicalDiskToPartition | READ | ディスクマッピングの読み取り |
| Test-DbaDiskAlignment | sys.master_files | READ | SQLファイル情報の読み取り |
| Test-DbaDiskAllocation | Win32_Volume | READ | ボリューム情報の読み取り |
| Test-DbaDiskAllocation | sys.master_files | READ | SQLファイル情報の読み取り |
| Test-DbaDiskSpeed | sys.dm_io_virtual_file_stats | READ | I/O統計の読み取り |
| Test-DbaDiskSpeed | sys.master_files | READ | ファイル情報の読み取り |

## メッセージ仕様

| メッセージID | 種別 | メッセージ | 発生条件 |
|-------------|------|---------|---------|
| - | Error | "Can't get disk alignment info for $ComputerName. Unsupported operating system." | 名前空間エラー発生時 |
| - | Error | "Can't connect to CIM on $ComputerName." | CIM接続失敗 |
| - | Error | "Couldn't resolve hostname. Skipping." | 名前解決失敗 |
| - | Error | "Can't create CimSession on $computer." | CimSession作成失敗 |
| - | Warning | "Disk is dynamic, all Offset calculations should be suspect..." | ダイナミックディスク検出時 |
| - | Verbose | "Creating CimSession on $computer over WSMan" | CimSession作成開始 |
| - | Verbose | "Creating CimSession on $fullComputerName over DCOM." | WSMan失敗後のDCOMフォールバック |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| CIM接続失敗 | Stop-Functionでエラーを出力し、次のコンピュータの処理を継続 |
| SQL Server接続失敗 | Stop-Functionでエラーを出力し、次のインスタンスの処理を継続 |
| 名前解決失敗 | Stop-Functionでエラーを出力し、次のコンピュータの処理を継続 |
| 名前空間エラー（非サポートOS） | Stop-Functionでエラーを出力して終了 |

## 備考

- Test-DbaDiskAlignmentは各パーティションに対して5つのオブジェクトを返す（5つのストライプサイズに対するテスト結果）
- ダイナミックディスクの場合、アライメント計算の信頼性が低下する可能性がある
- Windows Server 2008以降は通常1MBオフセットで自動的にアラインされる
- 64KBアロケーションユニットはSQL Serverのベストプラクティスだが、システムドライブには推奨されない
- Test-DbaDiskSpeedはSQL Server 2005（バージョン9）以降が必要

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Test-DbaDiskAlignment.ps1 | `public/Test-DbaDiskAlignment.ps1` | 行270-284のPSCustomObjectで出力構造を確認 |
| 1-2 | Test-DbaDiskAllocation.ps1 | `public/Test-DbaDiskAllocation.ps1` | 行191-208のPSCustomObjectで出力構造を確認 |
| 1-3 | Test-DbaDiskSpeed.ps1 | `public/Test-DbaDiskSpeed.ps1` | 行145-190のSELECT文で出力プロパティを確認 |

**読解のコツ**: Test-DbaDiskAlignmentは1パーティションあたり5オブジェクトを返す点に注意。

#### Step 2: エントリーポイントを理解する（Test-DbaDiskAlignment）

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaDiskAlignment.ps1 | `public/Test-DbaDiskAlignment.ps1` | processブロック（行290-337） |

**主要処理フロー**:
1. **294-299行**: コンピュータ名の解決
2. **305-326行**: CimSession作成（WSMan→DCOMフォールバック）
3. **332-336行**: Get-DiskAlignment内部関数の呼び出し
4. **118-287行**: Get-DiskAlignment関数（beginブロック内に定義）
5. **136-146行**: Win32_DiskPartitionの取得
6. **149-166行**: パーティションとディスクのマッピング
7. **176-193行**: SQL Serverインスタンスの検出
8. **196-229行**: SQLディスクの判定
9. **232-286行**: アライメント計算とオブジェクト出力

#### Step 3: Test-DbaDiskAllocationを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Test-DbaDiskAllocation.ps1 | `public/Test-DbaDiskAllocation.ps1` | processブロック（行109-217） |

**主要処理フロー**:
1. **110-115行**: コンピュータ名の解決
2. **117-137行**: CimSession作成
3. **141-147行**: Win32_Volumeの取得（NTFSのみ）
4. **149-153行**: SQL Serverインスタンスの検出
5. **162-175行**: sys.master_filesでSQLディスク判定
6. **178-188行**: ベストプラクティス判定（65536バイト）
7. **190-214行**: 出力オブジェクト構築

#### Step 4: Test-DbaDiskSpeedを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Test-DbaDiskSpeed.ps1 | `public/Test-DbaDiskSpeed.ps1` | processブロック（行238-276） |

**主要処理フロー**:
1. **140-236行**: beginブロックでSQLクエリを動的構築
2. **241-244行**: SQL Server接続（MinimumVersion 9）
3. **249-272行**: AggregateByに応じたSQLの調整
4. **275行**: クエリ実行と結果出力

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

```
Test-DbaDiskAlignment
    |
    +-- Resolve-DbaNetworkName
    |
    +-- New-CimSession (WSMan)
    |      +-- [失敗時] New-CimSession (DCOM)
    |
    +-- Get-DiskAlignment (内部関数)
           |
           +-- Get-CimInstance -ClassName Win32_DiskPartition
           |
           +-- Get-CimInstance -Query "ASSOCIATORS OF..."
           |
           +-- Get-CimInstance -ClassName Win32_Service
           |      +-- SQL Serverインスタンス検出
           |
           +-- Connect-DbaInstance
           |      +-- $server.Query("SELECT...FROM sys.master_files")
           |
           +-- [PSCustomObject] 出力 (5オブジェクト/パーティション)

Test-DbaDiskAllocation
    |
    +-- Resolve-DbaComputerName
    |
    +-- New-CimSession (WSMan)
    |      +-- [失敗時] New-CimSession (DCOM)
    |
    +-- Get-CimInstance -ClassName win32_volume (NTFS)
    |
    +-- Get-DbaService -Type Engine
    |
    +-- Connect-DbaInstance
    |      +-- $server.Query("SELECT...FROM sys.master_files")
    |
    +-- [PSCustomObject] 出力
    |
    +-- Select-DefaultView

Test-DbaDiskSpeed
    |
    +-- Connect-DbaInstance -MinimumVersion 9
    |
    +-- $server.Query(動的構築SQLクエリ)
           |
           +-- sys.dm_io_virtual_file_stats
           +-- sys.master_files
```

### データフロー図

```
[Test-DbaDiskAlignment]

ComputerName ──────────> Resolve-DbaNetworkName ──────────>
                                |
                                v
                        New-CimSession ───────────────────>
                                |
                                v
                        Win32_DiskPartition ──────────────> パーティション情報
                                |
                                v
NoSqlCheck ────────────> SQL Server検出 ──────────────────>
                                |
                                v
                        sys.master_files ─────────────────> SQLディスク判定
                                |
                                v
                        アライメント計算 ─────────────────> 5ストライプサイズ
                                |
                                v
                        PSCustomObject ───────────────────> 出力 (5件/パーティション)

---

[Test-DbaDiskSpeed]

SqlInstance ───────────> Connect-DbaInstance ─────────────>
                                |
                                v
AggregateBy ───────────> SQL動的構築 ─────────────────────>
                        (File/Database/Disk)
                                |
                                v
Database ──────────────> WHERE句追加 ─────────────────────>
ExcludeDatabase
                                |
                                v
                        sys.dm_io_virtual_file_stats ─────>
                        + sys.master_files
                                |
                                v
                        パフォーマンス評価 ────────────────> ReadPerformance
                        (< 10ms: Very Good)                  WritePerformance
                        (< 20ms: OK)
                        (< 50ms: Slow)
                        (>= 50ms: Bottleneck)
                                |
                                v
                        結果出力 ─────────────────────────> 出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Test-DbaDiskAlignment.ps1 | `public/Test-DbaDiskAlignment.ps1` | ソース | ディスクアライメントテスト |
| Test-DbaDiskAllocation.ps1 | `public/Test-DbaDiskAllocation.ps1` | ソース | アロケーションユニットテスト |
| Test-DbaDiskSpeed.ps1 | `public/Test-DbaDiskSpeed.ps1` | ソース | I/Oパフォーマンステスト |
| Resolve-DbaNetworkName.ps1 | `internal/functions/Resolve-DbaNetworkName.ps1` | 内部関数 | ネットワーク名解決 |
| Resolve-DbaComputerName.ps1 | `internal/functions/Resolve-DbaComputerName.ps1` | 内部関数 | コンピュータ名解決 |
| Get-DbaService.ps1 | `public/Get-DbaService.ps1` | 依存コマンド | SQL Serverサービス取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | 依存コマンド | SQLインスタンス接続 |
