# 画面設計書 252-データファイル情報

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `Get-DbaDbDetachedFileInfo` コマンドに関する画面設計書です。このコマンドは、デタッチされたSQL Serverデータベースファイル（MDF）からメタデータとファイル構造を読み取ります。

### 本画面の処理概要

**業務上の目的・背景**：マイグレーション計画、バックアップ検証、災害復旧シナリオにおいて、デタッチされたデータベースファイルの内容を事前に確認する必要があります。このコマンドを使用することで、データベースをアタッチするリスクなしに、MDFファイルからデータベース名、SQL Serverバージョン、照合順序、関連ファイル一覧などの重要な情報を取得できます。異なるSQL Serverバージョン間でのデータベース移行前の互換性確認に特に有用です。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから `Get-DbaDbDetachedFileInfo` コマンドを実行します。MDFファイルのパスをパイプラインで渡すことも可能です。

**主要な操作・処理内容**：
1. 指定されたSQL Serverインスタンスへの接続を確立
2. MDFファイルへのアクセス権限を検証
3. SMOの `DetachedDatabaseInfo` メソッドでファイルヘッダーを読み取り
4. 内部バージョン番号をSQL Serverバージョン名にマッピング
5. 照合順序IDを照合順序名に変換
6. データファイルとログファイルの一覧を列挙
7. 結果をPSCustomObjectとして出力

**画面遷移**：CLIコマンドのため画面遷移はありません。出力結果は `Mount-DbaDatabase` などのコマンドにパイプラインで渡すことができます。

**権限による表示制御**：SQL Serverサービスアカウントがファイルパスにアクセスできる必要があります。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 632 | Get-DbaDbDetachedFileInfo | 主機能 | デタッチされたデータベースファイル情報の取得 |
| 181 | Mount-DbaDatabase | 遷移先機能 | 取得した情報を基にデータベースをアタッチ |
| 81 | Dismount-DbaDatabase | 関連機能 | データベースのデタッチ操作 |

## 画面種別

情報取得・表示（CLIコマンド）

## URL/ルーティング

該当なし（PowerShell CLIコマンド）

## 入出力項目

### 入力パラメーター

| パラメーター名 | 型 | 必須 | 説明 |
|---------------|---|-----|------|
| SqlInstance | DbaInstanceParameter | Yes | ファイル解析に使用するSQL Serverインスタンス |
| SqlCredential | PSCredential | No | 代替認証情報 |
| Path | string[] | Yes | 解析対象のMDFファイルパス（パイプライン入力対応、エイリアス: Mdf, FilePath, FullName） |
| EnableException | switch | No | 例外を直接スローするかどうか |

### 出力項目

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| ComputerName | string | ファイル読み取りに使用したSQL Serverのコンピューター名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| Name | string | デタッチされたデータベースの元のデータベース名 |
| Version | string | SQL Serverバージョン名（例: "SQL Server 2019"） |
| ExactVersion | int | MDFファイルヘッダーからの内部バージョン番号 |
| Collation | string | データベースの照合順序名（解決できない場合は照合順序ID） |
| DataFiles | StringCollection | データファイルパスのコレクション |
| LogFiles | StringCollection | ログファイルパスのコレクション |

## 表示項目

CLIコマンドのため、表示項目は出力オブジェクトのプロパティに依存します。

## イベント仕様

### 1-コマンド実行

コマンド実行時に以下の処理が行われます：

1. `Connect-DbaInstance` でSQL Serverに接続
2. `Test-DbaPath` でファイルアクセス権限を確認
3. `$server.DetachedDatabaseInfo($filepath)` でメタデータ取得
4. 内部バージョン番号のマッピング処理（switch文）
5. `fn_helpcollations()` で照合順序名を解決
6. `EnumDetachedDatabaseFiles` / `EnumDetachedLogFiles` でファイル一覧取得
7. PSCustomObjectを出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 照合順序解決 | fn_helpcollations | SELECT | 照合順序IDから名前への変換 |

### テーブル別更新項目詳細

このコマンドは読み取り専用であり、データベースの更新は行いません。

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|--------------|------|---------------|
| エラー | ファイルアクセス不可 | "$servername cannot access the file $filepath. Does the file exist and does the service account ($serviceAccount) have access to the path?" |
| エラー | ファイル読み取り不可 | "$servername cannot read the file $filepath. Is the database detached?" |
| エラー | ファイル構造列挙失敗 | "$servername unable to enumerate database or log structure information for $filepath" |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| 接続エラー | Stop-Functionで処理を中断、関数を終了 |
| ファイルアクセス不可 | Stop-Functionで該当ファイルをスキップして続行 |
| ファイル読み取りエラー | Stop-Functionで該当ファイルをスキップして続行 |
| ファイル構造列挙失敗 | Stop-Functionで該当ファイルをスキップして続行 |

## 備考

- SQL Serverの `DetachedDatabaseInfo` メソッドを使用するため、オンラインのSQL Serverインスタンスが必要
- サポートするSQL Serverバージョン: SQL Server 6.5 から SQL Server 2025 まで
- MDFファイルはSQL Serverサービスアカウントからアクセス可能である必要がある
- このコマンドはデータベースをアタッチしません（読み取り専用）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbDetachedFileInfo.ps1 | `public/Get-DbaDbDetachedFileInfo.ps1` | 出力PSCustomObject構造（行152-162） |
| 1-2 | Get-DbaDbDetachedFileInfo.ps1 | `public/Get-DbaDbDetachedFileInfo.ps1` | バージョンマッピングswitch文（行110-128） |

**読解のコツ**: SQL Serverの内部バージョン番号（exactdbversion）は各リリースごとに異なり、バージョン名への変換が必要です。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbDetachedFileInfo.ps1 | `public/Get-DbaDbDetachedFileInfo.ps1` | 関数定義全体（行1-165） |

**主要処理フロー**:
1. **行80-89**: beginブロックでSQL Server接続を確立
2. **行92-98**: パス検証とアクセス権限確認
3. **行100-107**: DetachedDatabaseInfoでメタデータ取得
4. **行110-128**: バージョン番号マッピング
5. **行130-137**: 照合順序名解決
6. **行141-151**: ファイル一覧列挙
7. **行152-162**: PSCustomObject出力

#### Step 3: 依存関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | SQL Server接続処理 |
| 3-2 | Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | ファイルパス検証処理 |
| 3-3 | Stop-Function.ps1 | `internal/functions/flowcontrol/Stop-Function.ps1` | エラー処理 |

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

```
Get-DbaDbDetachedFileInfo
    │
    ├─ Connect-DbaInstance (beginブロック)
    │
    ├─ Test-DbaPath
    │      └─ ファイルアクセス権限確認
    │
    ├─ $server.DetachedDatabaseInfo($filepath)
    │      └─ SMO メソッド
    │
    ├─ $server.databases['master'].ExecuteWithResults($collationsql)
    │      └─ fn_helpcollations() クエリ
    │
    ├─ $server.EnumDetachedDatabaseFiles($filepath)
    │
    └─ $server.EnumDetachedLogFiles($filepath)
```

### データフロー図

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

Path (MDF) ───▶ Connect-DbaInstance
                           │
                           ▼
                    Test-DbaPath ───▶ アクセス確認
                           │
                           ▼
               DetachedDatabaseInfo ───▶ メタデータ
                           │
                           ▼
               バージョンマッピング ───▶ Version
                           │
                           ▼
               照合順序解決 ───▶ Collation
                           │
                           ▼
               ファイル列挙 ───▶ DataFiles/LogFiles
                           │
                           ▼
                     PSCustomObject ───▶ パイプライン
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbDetachedFileInfo.ps1 | `public/Get-DbaDbDetachedFileInfo.ps1` | ソース | メイン関数定義 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | ソース | パス検証 |
| Stop-Function.ps1 | `internal/functions/flowcontrol/Stop-Function.ps1` | ソース | エラーハンドリング |
| Test-FunctionInterrupt.ps1 | `internal/functions/flowcontrol/Test-FunctionInterrupt.ps1` | ソース | 割り込み検出 |
