# 機能設計書 652-Show-DbaInstanceFileSystem

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `Show-DbaInstanceFileSystem` 関数の機能設計を記述するものである。本機能はリモートSQL Serverのファイルシステムをツリービュー形式のGUIで表示し、選択されたディレクトリパスを返すコマンドレットである。

### 本機能の処理概要

**業務上の目的・背景**：
SQL Server Management Studio (SSMS) でリモートサーバーを参照する際に表示されるファイルシステムポップアップと同様の機能を提供する。DBA がバックアップ先、リストア元、データファイルやログファイルのパスを指定する際に、リモートサーバーのファイル構造を視覚的に確認しながらパスを選択できるようにすることで、手動入力によるパスの誤りを防止し、作業効率を向上させる。

**機能の利用シーン**：
- データベースバックアップ先ディレクトリの選択時
- データベースリストア時のファイル配置先指定時
- データファイルやログファイルの移動先パス指定時
- SQL Server関連ファイルの配置場所確認時

**主要な処理内容**：
1. Windows Presentation Framework (WPF) の読み込みと検証
2. SQL Serverインスタンスへの接続
3. SMO経由で利用可能なドライブの列挙
4. ツリービュー形式のGUIウィンドウの表示
5. ユーザーがディレクトリを選択した際のサブディレクトリ動的読み込み
6. 選択されたパスの返却

**関連システム・外部連携**：
- Windows Presentation Framework (WPF) によるGUI表示
- SQL Server Management Objects (SMO) の EnumAvailableMedia/EnumDirectories メソッド
- Connect-DbaInstance コマンドレットによるSQL Server接続

**権限による制御**：
SQL Serverへの接続権限が必要。表示されるディレクトリは実行アカウントのファイルシステム権限に依存する。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | ファイルシステムブラウザGUI | 主画面 | ツリービューでのディレクトリ選択 |

## 機能種別

GUI表示処理 / データ取得処理（SELECT）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter | Yes | 対象SQL Serverインスタンス | 必須、パイプライン入力可 |
| SqlCredential | PSCredential | No | SQL Server接続用資格情報 | - |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- PowerShellコマンドラインからのパラメータ入力
- GUIでのユーザー操作（ツリービューでのディレクトリ選択）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| - | System.String | 選択されたディレクトリパス（末尾にバックスラッシュ付き） |

### 出力先

- PowerShellパイプライン（文字列として返却）
- ユーザーがキャンセルした場合は $null を返却

## 処理フロー

### 処理シーケンス

```
1. 初期化処理（beginブロック）
   └─ PresentationFramework アセンブリの読み込み
   └─ ヘルパー関数の定義（Add-TreeItem, Get-SubDirectory, Convert-b64toimg）
   └─ アイコン画像のBase64デコード

2. メイン処理（processブロック）
   └─ SQL Serverへの接続
   └─ 利用可能ドライブの列挙（EnumAvailableMedia）
   └─ XAMLベースのGUIウィンドウ生成
   └─ ツリービューへのドライブ項目追加
   └─ イベントハンドラ設定（Expanded, Selected）
   └─ ダイアログ表示

3. 終了処理（endブロック）
   └─ テキストボックスの内容を評価
   └─ パスが存在する場合、末尾にバックスラッシュを追加して返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{PresentationFramework読み込み可能?}
    B -->|No| C[エラー: WPF未インストール]
    B -->|Yes| D[SQL Server接続]
    D --> E{接続成功?}
    E -->|No| F[接続エラー]
    E -->|Yes| G[EnumAvailableMedia実行]
    G --> H{ドライブ取得成功?}
    H -->|No| I[アクセスエラー]
    H -->|Yes| J[XAMLウィンドウ生成]
    J --> K[ツリービューにドライブ追加]
    K --> L[イベントハンドラ設定]
    L --> M[ダイアログ表示]
    M --> N{OKボタン押下?}
    N -->|Yes| O[選択パス取得]
    N -->|No| P[キャンセル: null返却]
    O --> Q[パス + バックスラッシュ返却]
    Q --> R[終了]
    P --> R
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | システムフォルダ除外 | $で始まるフォルダとSystem Volume Informationは表示しない | サブディレクトリ列挙時 |
| BR-002 | パス形式 | 返却パスには末尾にバックスラッシュを追加 | パス選択時 |
| BR-003 | 動的読み込み | ディレクトリ展開時にサブディレクトリを動的に読み込む | ツリービュー展開時 |

### 計算ロジック

特になし（ファイルシステムの参照のみ）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベースへの直接操作なし（SMOメソッド経由でファイルシステム情報を取得） |

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

データベーステーブルへの直接操作は行わない。SMOの以下のメソッドを使用：
- `Server.EnumAvailableMedia()`: 利用可能なドライブを列挙
- `Server.EnumDirectories(path)`: 指定パスのサブディレクトリを列挙

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 環境エラー | Windows Presentation Framework未インストール | Stop-Functionでエラーメッセージ表示、処理終了 |
| - | 接続エラー | SQL Serverへの接続失敗 | Stop-Functionでエラーメッセージ表示、処理終了 |
| - | アクセスエラー | リモートファイルシステムへのアクセス不可 | Stop-Functionでエラーメッセージ表示、処理終了 |

### リトライ仕様

自動リトライは実装されていない。

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

データベーストランザクションは使用しない（読み取り専用のSMOメソッド呼び出し）。

## パフォーマンス要件

- GUI表示は即座に行われる必要がある
- ディレクトリ展開時の動的読み込みは、ネットワーク状態とリモートサーバーの応答速度に依存

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

- SQL Server接続はWindows認証またはSQL認証をサポート
- 表示されるファイルシステムは実行アカウントの権限に制限される
- 隠しフォルダ（$で始まるフォルダ）は自動的に除外される

## 備考

- Windows Presentation Framework (WPF) が必要なため、Windows環境でのみ動作
- Linux/macOS環境では使用不可
- SSMSのファイルブラウザダイアログと同等の機能を提供

---

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

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

### 推奨読解順序

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

GUIで使用されるXAML構造とアイコンのBase64エンコーディングを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Show-DbaInstanceFileSystem.ps1 | `public/Show-DbaInstanceFileSystem.ps1` | 143-145行目: アイコン画像のBase64定義 |
| 1-2 | Show-DbaInstanceFileSystem.ps1 | `public/Show-DbaInstanceFileSystem.ps1` | 159-173行目: XAML定義（ウィンドウ構造） |

**読解のコツ**: `Convert-b64toimg`関数でBase64文字列からBitmapImageオブジェクトを生成している。XAML内でTreeView、TextBox、Buttonが定義されている。

#### Step 2: ヘルパー関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Show-DbaInstanceFileSystem.ps1 | `public/Show-DbaInstanceFileSystem.ps1` | 71-109行目: Add-TreeItem関数 |
| 2-2 | Show-DbaInstanceFileSystem.ps1 | `public/Show-DbaInstanceFileSystem.ps1` | 111-130行目: Get-SubDirectory関数 |
| 2-3 | Show-DbaInstanceFileSystem.ps1 | `public/Show-DbaInstanceFileSystem.ps1` | 132-141行目: Convert-b64toimg関数 |

**主要処理フロー**:
- **71-109行目（Add-TreeItem）**: ツリービューに項目を追加、ドライブとフォルダでアイコンを切り替え
- **111-130行目（Get-SubDirectory）**: EnumDirectories呼び出しでサブディレクトリ取得、フィルタリング適用

#### Step 3: メイン処理フローを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Show-DbaInstanceFileSystem.ps1 | `public/Show-DbaInstanceFileSystem.ps1` | 148-156行目: SQL Server接続 |
| 3-2 | Show-DbaInstanceFileSystem.ps1 | `public/Show-DbaInstanceFileSystem.ps1` | 180-190行目: ドライブ列挙とツリービュー初期化 |
| 3-3 | Show-DbaInstanceFileSystem.ps1 | `public/Show-DbaInstanceFileSystem.ps1` | 192-212行目: イベントハンドラ設定 |

**主要処理フロー**:
- **151-152行目**: Connect-DbaInstance でSQL Server接続
- **181行目**: EnumAvailableMedia でドライブ一覧取得
- **192-202行目**: SourceInitialized イベントで Expanded/Selected イベントハンドラを登録
- **204-211行目**: OKボタンとキャンセルボタンのクリックハンドラ

#### Step 4: 結果返却処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Show-DbaInstanceFileSystem.ps1 | `public/Show-DbaInstanceFileSystem.ps1` | 216-222行目: endブロックでの結果返却 |

**主要処理フロー**:
- **218-220行目**: テキストボックスの内容が空でなければ、末尾にバックスラッシュを追加して返却

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

```
Show-DbaInstanceFileSystem
    │
    ├─ begin ブロック
    │      ├─ Add-Type -AssemblyName PresentationFramework
    │      ├─ Add-TreeItem（関数定義）
    │      ├─ Get-SubDirectory（関数定義）
    │      └─ Convert-b64toimg（関数定義）
    │
    ├─ process ブロック
    │      ├─ Connect-DbaInstance
    │      │      └─ SQL Server接続
    │      │
    │      ├─ Server.EnumAvailableMedia()
    │      │      └─ ドライブ一覧取得
    │      │
    │      ├─ XamlReader.Load()
    │      │      └─ WPFウィンドウ生成
    │      │
    │      ├─ Add-TreeItem（各ドライブを追加）
    │      │
    │      ├─ イベントハンドラ登録
    │      │      ├─ Expanded → Get-SubDirectory
    │      │      └─ Selected → Get-SubDirectory
    │      │
    │      └─ window.ShowDialog()
    │             └─ GUIダイアログ表示
    │
    └─ end ブロック
           └─ 選択パス返却
```

### データフロー図

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

SqlInstance ─────────▶ Connect-DbaInstance
                              │
                              ▼
                      Server.EnumAvailableMedia()
                              │
                              ▼
                      ドライブ一覧 ──▶ ツリービュー初期化
                              │
                              ▼
                      GUIダイアログ表示
                              │
                      ┌───────┴───────┐
                      ▼               ▼
              ツリー展開         ツリー選択
                      │               │
                      ▼               ▼
              Get-SubDirectory   テキストボックス更新
              (EnumDirectories)
                              │
                              ▼
                      OKボタン押下
                              │
                              ▼
                      パス + "\" ────────────────▶ System.String
                                                 (ディレクトリパス)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Show-DbaInstanceFileSystem.ps1 | `public/Show-DbaInstanceFileSystem.ps1` | ソース | メイン機能実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
