# 機能設計書 654-Test-DbaDiskAllocation

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `Test-DbaDiskAllocation` 関数の機能設計を記述するものである。本機能はディスクのアロケーションユニットサイズ（クラスターサイズ）がSQL Serverのベストプラクティス（64KB）に準拠しているかを検証するコマンドレットである。

### 本機能の処理概要

**業務上の目的・背景**：
SQL Serverのベストプラクティスでは、データベースファイルを格納するNTFSボリュームは64KBのアロケーションユニット（クラスターサイズ）でフォーマットすることが推奨されている。不適切なアロケーションユニットサイズはデータベースI/Oパフォーマンスに悪影響を与える可能性がある。本機能は、対象サーバーの全NTFSボリュームを検査し、各ボリュームがベストプラクティスに準拠しているかを報告する。

**機能の利用シーン**：
- SQL Server環境構築時のストレージ検証
- 既存環境のストレージ構成監査
- パフォーマンス問題のトラブルシューティング
- サーバー移行前の事前チェック

**主要な処理内容**：
1. CIMセッションを使用したリモートサーバーへの接続
2. Win32_Volumeからボリューム情報の取得（NTFSのみ）
3. SQL Serverインスタンスの検出とデータベースファイルの配置ディスク特定（オプション）
4. 各ボリュームのBlockSizeが65536（64KB）かをチェック
5. 結果オブジェクトの生成と出力

**関連システム・外部連携**：
- CIM (Common Information Model) / WMI によるリモートサーバー情報取得
- Win32_Volume クラスからのボリューム情報
- Get-DbaService コマンドレットによるSQL Serverサービス検出
- Connect-DbaInstance コマンドレットによるSQL Server接続

**権限による制御**：
- CIM/WMIへのアクセス権限が必要
- NoSqlCheckを使用しない場合、SQL Serverへの接続権限も必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLI (PowerShell) | 主画面 | コマンドライン実行によるディスク検証 |

## 機能種別

データ取得処理（SELECT） / 診断処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | object[] | Yes | 対象サーバー名 | 必須、パイプライン入力可 |
| NoSqlCheck | switch | No | SQL Serverファイル配置チェックをスキップ | - |
| SqlCredential | PSCredential | No | SQL Server接続用資格情報 | - |
| Credential | PSCredential | No | Windows接続用資格情報 | - |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- PowerShellコマンドラインからのパラメータ入力
- CIM/WMI経由でのOSボリューム情報

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピュータ名（エイリアス: Server） |
| DiskName | string | ドライブ名（エイリアス: Name） |
| DiskLabel | string | ボリュームラベル（エイリアス: Label） |
| BlockSize | int | アロケーションユニットサイズ（バイト） |
| IsSqlDisk | bool | SQL Serverファイルが配置されているか（NoSqlCheck無効時のみ） |
| IsBestPractice | bool | 64KBに準拠しているか |

### 出力先

PowerShellパイプライン（1ボリュームにつき1オブジェクト）

## 処理フロー

### 処理シーケンス

```
1. 初期化処理（beginブロック）
   └─ CIMセッションオプションの設定（DCOM）

2. メイン処理（processブロック）
   └─ 各コンピュータに対して処理
       └─ ホスト名解決（Resolve-DbaComputerName）
       └─ CIMセッション作成（WSMan優先、フォールバックでDCOM）
       └─ Win32_Volumeからボリューム情報取得（NTFS限定）
       └─ SQL Serverサービス検出（NoSqlCheck無効時）
       └─ 各ボリュームの評価
           └─ SQL Serverファイル配置確認（NoSqlCheck無効時）
           └─ ベストプラクティス判定
           └─ 結果オブジェクト生成と出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[各コンピュータをループ]
    B --> C[ホスト名解決]
    C --> D{解決成功?}
    D -->|No| E[エラー: 解決失敗]
    D -->|Yes| F[CIMセッション作成WSMan]
    F --> G{接続成功?}
    G -->|No| H[CIMセッション作成DCOM]
    G -->|Yes| I[Win32_Volume取得]
    H --> J{接続成功?}
    J -->|No| K[エラー: CIM接続不可]
    J -->|Yes| I
    I --> L{NoSqlCheck?}
    L -->|Yes| M[全ボリューム処理]
    L -->|No| N[Get-DbaService実行]
    N --> O[SQL Serverインスタンス検出]
    O --> P[各ボリュームをループ]
    M --> P
    P --> Q{\\で始まる?}
    Q -->|Yes| R[スキップ]
    Q -->|No| S{NoSqlCheck?}
    S -->|No| T[sys.master_filesでファイル確認]
    S -->|Yes| U[IsSqlDiskなし]
    T --> V[BlockSize == 65536?]
    U --> V
    V -->|Yes| W[IsBestPractice = true]
    V -->|No| X[IsBestPractice = false]
    W --> Y{システムドライブ?}
    X --> Y
    Y -->|Yes| Z[IsBestPractice = false]
    Y -->|No| AA[結果オブジェクト出力]
    Z --> AA
    AA --> AB{次のボリューム?}
    AB -->|Yes| P
    AB -->|No| AC{次のコンピュータ?}
    AC -->|Yes| B
    AC -->|No| AD[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ベストプラクティスサイズ | BlockSizeが65536（64KB）であればベストプラクティス | アロケーションユニット評価時 |
| BR-002 | システムドライブ除外 | システムドライブは常にIsBestPractice = false | ドライブ評価時 |
| BR-003 | UNCパス除外 | \\で始まるパスは評価対象外 | ボリューム列挙時 |
| BR-004 | NTFS限定 | NTFSファイルシステムのボリュームのみ検査 | ボリューム取得時 |

### 計算ロジック

- ベストプラクティス判定: `$disk.BlockSize -eq 65536`
- システムドライブ判定: `$diskname -eq "$env:SystemDrive\"`

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| SQLファイル配置確認 | sys.master_files | SELECT | SQL Serverファイルの物理パス確認 |

### テーブル別操作詳細

#### sys.master_files

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | physical_name | `LIKE '$diskname%'` で対象ディスク上のファイルをカウント | NoSqlCheck無効時のみ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ホスト名解決エラー | コンピュータ名を解決できない | Stop-Function、スキップ |
| - | CIM接続エラー | WSManおよびDCOM両方で接続失敗 | Stop-Function |
| - | WMI接続エラー | Win32_Volumeへのアクセス失敗 | Stop-Function、処理終了 |
| - | SQL接続エラー | SQL Serverへの接続失敗 | Stop-Function with -Continue |

### リトライ仕様

- CIMセッション作成時、WSMan失敗でDCOMにフォールバック
- 自動リトライは実装されていない

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

読み取り専用処理のため、トランザクション管理は不要。

## パフォーマンス要件

- CIM経由のボリューム情報取得は通常数秒で完了
- 多数のSQL Serverインスタンスがある場合、ファイル配置確認に時間がかかる可能性がある

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

- CIM/WMIアクセスには管理者権限が推奨される
- Credentialパラメータによるセキュアな資格情報の受け渡し
- リモートサーバーのディスク情報を参照するため、適切なアクセス制御が必要

## 備考

- Get-DbaServiceを使用してSQL Serverインスタンスを検出
- 後方互換性のため、Server/Name/Labelのエイリアスプロパティを提供
- Select-DefaultViewで表示プロパティを制御

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Test-DbaDiskAllocation.ps1 | `public/Test-DbaDiskAllocation.ps1` | 191-198行目: IsSqlDiskありの出力定義 |
| 1-2 | Test-DbaDiskAllocation.ps1 | `public/Test-DbaDiskAllocation.ps1` | 201-207行目: IsSqlDiskなしの出力定義 |

**読解のコツ**: NoSqlCheck の有無で出力プロパティが異なる。IsSqlDisk は NoSqlCheck 無効時のみ含まれる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaDiskAllocation.ps1 | `public/Test-DbaDiskAllocation.ps1` | 94-103行目: パラメータ定義 |
| 2-2 | Test-DbaDiskAllocation.ps1 | `public/Test-DbaDiskAllocation.ps1` | 109-110行目: processブロック開始とループ |

**主要処理フロー**:
1. **111行目**: Resolve-DbaComputerName でホスト名解決
2. **117-133行目**: CIMセッション作成（WSMan優先、DCOMフォールバック）
3. **143行目**: Win32_Volume取得（NTFS限定）

#### Step 3: SQL Serverファイル配置チェックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Test-DbaDiskAllocation.ps1 | `public/Test-DbaDiskAllocation.ps1` | 149-153行目: SQL Serverサービス検出 |
| 3-2 | Test-DbaDiskAllocation.ps1 | `public/Test-DbaDiskAllocation.ps1` | 162-176行目: sys.master_filesでのファイル配置確認 |

**主要処理フロー**:
- **151行目**: Get-DbaService で SQL Server Engine サービス取得
- **169行目**: sys.master_files クエリでファイル存在確認

#### Step 4: ベストプラクティス判定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Test-DbaDiskAllocation.ps1 | `public/Test-DbaDiskAllocation.ps1` | 178-188行目: ベストプラクティス判定ロジック |

**主要処理フロー**:
- **178行目**: BlockSize == 65536 で判定
- **184-188行目**: システムドライブは強制的に false

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

```
Test-DbaDiskAllocation
    │
    ├─ begin ブロック
    │      └─ New-CimSessionOption（DCOMオプション設定）
    │
    └─ process ブロック
           ├─ Resolve-DbaComputerName
           │      └─ ホスト名解決
           │
           ├─ New-CimSession（WSMan or DCOM）
           │
           ├─ Get-CimInstance win32_volume
           │      └─ NTFSボリューム情報取得
           │
           ├─ Get-DbaService（NoSqlCheck無効時）
           │      └─ SQL Server サービス検出
           │
           ├─ Connect-DbaInstance（NoSqlCheck無効時）
           │      └─ SQL Server接続
           │
           ├─ Server.Query（sys.master_files参照）
           │      └─ ファイル配置確認
           │
           └─ ベストプラクティス判定
                  └─ 結果オブジェクト生成
```

### データフロー図

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

ComputerName ───┐
                ├──▶ Resolve-DbaComputerName
Credential ─────┤            │
                │            ▼
                │    New-CimSession
                │            │
                │            ▼
                │    Get-CimInstance win32_volume
                │    (FileSystem='NTFS')
                │            │
NoSqlCheck ─────┤            ▼
                │    ┌───────┴───────┐
                │    │ NoSqlCheck?  │
                │    └───────┬───────┘
SqlCredential ──┤    No│         │Yes
                │       ▼         │
                │    Get-DbaService │
                │       │         │
                │       ▼         │
                │    SQL Server   │
                │    ファイル確認 │
                │       │         │
                │       ▼         ▼
                │    ベストプラクティス判定
                │    (BlockSize == 65536?)
                │            │
                │            ▼
                └────────────────────────────────▶ PSCustomObject
                                                  (ボリュームごと)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Test-DbaDiskAllocation.ps1 | `public/Test-DbaDiskAllocation.ps1` | ソース | メイン機能実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
| Get-DbaService.ps1 | `public/Get-DbaService.ps1` | ソース | SQL Serverサービス検出 |
| Resolve-DbaComputerName.ps1 | `private/Resolve-DbaComputerName.ps1` | ソース | ホスト名解決処理 |
