# 画面設計書 267-ファイルマッピング

## 概要

本ドキュメントは、dbatoolsのデータベースファイルマッピング取得機能に関する画面設計書です。既存データベースから論理ファイル名と物理ファイルパスのマッピングを抽出し、リストア操作で使用できるハッシュテーブル形式で返すPowerShellコマンドを定義します。

### 本画面の処理概要

本機能は、既存データベースから論理ファイル名と物理ファイル名のマッピングを抽出し、Restore-DbaDatabase互換のハッシュテーブル形式で返すGet-DbaDbFileMappingコマンドを提供します。

**業務上の目的・背景**：データベースを異なるサーバーや場所にリストアする際、手動でファイルパスを指定する必要がありますが、これは煩雑でエラーが発生しやすい作業です。本機能は、既存データベースのファイル構造を保持しながらリストア操作に使用できるマッピング情報を自動生成し、リストア時のファイルパス指定を簡略化します。

**画面へのアクセス方法**：PowerShellコンソールから以下のコマンドを実行してアクセスします。
```powershell
Get-DbaDbFileMapping -SqlInstance <インスタンス名> -Database <データベース名>
```

**主要な操作・処理内容**：
1. 指定されたSQL Serverインスタンスへの接続
2. データベースファイルグループからデータファイル情報を取得
3. ログファイル情報を取得
4. 論理ファイル名をキー、物理パスを値としたハッシュテーブルを構築
5. Restore-DbaDatabase互換の形式で出力

**画面遷移**：
- `Connect-DbaInstance`で接続を確立後に実行可能
- `Get-DbaDatabase`からパイプライン入力可能
- 取得結果の`FileMapping`プロパティをRestore-DbaDatabase -FileMappingに渡せる

**権限による表示制御**：
- データベースへの接続権限が必要
- データベースファイル情報への読み取りアクセス権限が必要

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 636 | Get-DbaDbFileMapping | 主機能 | データベースファイルマッピングの取得 |

## 画面種別

CLI（コマンドラインインターフェース）- PowerShellコマンド

## URL/ルーティング

PowerShellコマンド: `Get-DbaDbFileMapping`

## 入出力項目

### パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス（パイプライン入力対応） |
| SqlCredential | PSCredential | No | 代替認証情報 |
| Database | string[] | No | 対象データベース（ワイルドカード対応） |
| InputObject | Database[] | No | パイプライン入力（Get-DbaDatabase出力） |
| EnableException | switch | No | 例外を有効化 |

## 表示項目

### 出力オブジェクト（PSCustomObject）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| Database | string | データベース名 |
| FileMapping | hashtable | 論理ファイル名をキー、物理ファイルパスを値としたハッシュテーブル |

### FileMappingハッシュテーブルの構造

```powershell
@{
    "論理データファイル名1" = "C:\Data\ファイル1.mdf"
    "論理データファイル名2" = "C:\Data\ファイル2.ndf"
    "論理ログファイル名" = "C:\Log\ファイル.ldf"
}
```

## イベント仕様

### 1-Get-DbaDbFileMapping実行

1. SqlInstanceとInputObjectの両方が未指定の場合は警告メッセージを出力
2. SqlInstance指定時はGet-DbaDatabase経由でデータベースオブジェクトを取得
3. 各データベースに対して以下を実行:
   - IsAccessibleチェック（アクセス不可の場合はスキップ）
   - FileGroupsからデータファイル情報を取得
   - LogFilesからログファイル情報を取得
   - ハッシュテーブル構築と出力

### 2-ファイルマッピング構築

```powershell
$fileMap = @{ }

# データファイル（FileGroups.Files）
foreach ($file in $db.FileGroups.Files) {
    $fileMap[$file.Name] = $file.FileName
}

# ログファイル
foreach ($file in $db.LogFiles) {
    $fileMap[$file.Name] = $file.FileName
}
```

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaDbFileMapping | SMO Database.FileGroups | 読取 | ファイルグループ情報の取得 |
| Get-DbaDbFileMapping | SMO Database.LogFiles | 読取 | ログファイル情報の取得 |

本コマンドはSMOオブジェクトのプロパティ読み取りのみを行い、データベースの変更は行いません。

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|--------------|---------|
| MSG001 | 警告 | You must specify either a SQL instance or supply an InputObject | SqlInstanceとInputObjectの両方が未指定 |
| MSG002 | 情報 | Processing database: {db} | 詳細出力時 |
| MSG003 | 情報 | Skipping processing of database: {db} as database is not accessible | データベースにアクセス不可 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| パラメータ未指定 | 警告メッセージを出力して処理終了 |
| データベースアクセス不可 | Verboseメッセージを出力してスキップ |

## 備考

- Restore-DbaDatabase -FileMappingパラメータと互換性のある形式で出力
- FileGroupsプロパティからデータファイル（.mdf, .ndf）を取得
- LogFilesプロパティからログファイル（.ldf）を取得
- アクセス可能なデータベースのみを処理（IsAccessible = true）
- 複数データベースを指定した場合、各データベースに対してFileMappingを生成

---

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

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

### 推奨読解順序

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

SMO Databaseオブジェクトのファイル関連プロパティを理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbFileMapping.ps1 | `public/Get-DbaDbFileMapping.ps1` | 行83-90のファイルマッピング構築ロジック |

**読解のコツ**: $db.FileGroups.Filesと$db.LogFilesの構造、Name（論理名）とFileName（物理パス）のプロパティを理解します。

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

processブロックでの処理フローを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbFileMapping.ps1 | `public/Get-DbaDbFileMapping.ps1` | 行70-103のprocessブロック |

**主要処理フロー**:
1. **71-74行**: SqlInstanceとInputObjectの検証
2. **76-78行**: SqlInstance指定時のGet-DbaDatabase呼び出し
3. **80-81行**: IsAccessibleチェック
4. **83行**: 空のハッシュテーブル初期化
5. **85-87行**: FileGroups.Filesのループ処理
6. **88-90行**: LogFilesのループ処理
7. **92-98行**: PSCustomObjectの構築と出力

#### Step 3: 使用例を理解する

Restore-DbaDatabase との連携を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDbFileMapping.ps1 | `public/Get-DbaDbFileMapping.ps1` | 行56-59のドキュメント例 |

**使用例**:
```powershell
$filemap = Get-DbaDbFileMapping -SqlInstance sql2016 -Database test
Get-ChildItem \\nas\db\backups\test | Restore-DbaDatabase -SqlInstance sql2019 -Database test -FileMapping $filemap.FileMapping
```

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

```
Get-DbaDbFileMapping
    |
    +-- process block
            |
            +-- Test-Bound ('SqlInstance', 'InputObject')
            |       |
            |       +-- 未指定時: 警告メッセージ出力
            |
            +-- Get-DbaDatabase (SqlInstance指定時)
            |       |
            |       +-- $InputObject += （データベースオブジェクト）
            |
            +-- foreach ($db in $InputObject)
                    |
                    +-- $db.IsAccessible チェック
                    |       |
                    |       +-- false: Verboseメッセージ、スキップ
                    |
                    +-- $fileMap = @{ }
                    |
                    +-- foreach ($file in $db.FileGroups.Files)
                    |       |
                    |       +-- $fileMap[$file.Name] = $file.FileName
                    |
                    +-- foreach ($file in $db.LogFiles)
                    |       |
                    |       +-- $fileMap[$file.Name] = $file.FileName
                    |
                    +-- [PSCustomObject] 出力
```

### データフロー図

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

SqlInstance/         +------------------+
Database         -->| Get-DbaDatabase  |
                     | (必要時)         |
                     +--------+---------+
                              |
                              v
InputObject          +------------------+
                 -->| IsAccessible     |
                     | チェック         |
                     +--------+---------+
                              |
                              v
                     +------------------+
                     | FileGroups.Files |
                     | 処理             |
                     +--------+---------+
                              |
                              v
                     +------------------+
                     | LogFiles         |
                     | 処理             |
                     +--------+---------+
                              |
                              v
                     +------------------+
                     | PSCustomObject   |---> PSCustomObject
                     | 構築             |     (FileMapping含む)
                     +------------------+
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbFileMapping.ps1 | `public/Get-DbaDbFileMapping.ps1` | ソース | ファイルマッピング取得の主要ロジック |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | 依存 | データベースオブジェクト取得 |
| Restore-DbaDatabase.ps1 | `public/Restore-DbaDatabase.ps1` | 関連 | リストア時にFileMappingを使用 |
