# 画面設計書 228-ファイルシステム表示

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるファイルシステム表示機能の設計仕様を定義する。SQL Server Management Studio（SSMS）のリモートファイルブラウザに似たGUIを提供し、SQL Server経由でリモートマシンのファイルシステムをツリービューで閲覧・選択できる機能を提供する。

### 本画面の処理概要

本機能は、Windows Presentation Framework（WPF）を使用してGUIダイアログを表示し、SQL Server Management Objects（SMO）のEnumDirectoriesおよびEnumAvailableMedia機能を使用してリモートSQL Serverマシンのファイルシステムを探索する。ユーザーはツリービューでディレクトリを展開・選択し、OKボタンで選択したパスを返却できる。

**業務上の目的・背景**：バックアップ先、リストア先、データベースファイルのパスなど、DBA作業ではリモートSQL Serverマシン上のパスを指定する必要が頻繁にある。手動でパスを入力するのはエラーが発生しやすく、SSMSのようなGUIブラウザがあると便利である。本機能は、スクリプトからGUIダイアログを呼び出し、ユーザーにパスを視覚的に選択させることで、パス入力エラーを減少させる。

**画面へのアクセス方法**：PowerShellコンソールから以下のコマンドを実行することでアクセスする。
- `Show-DbaInstanceFileSystem` - ファイルシステムブラウザダイアログの表示

**主要な操作・処理内容**：
1. WPFダイアログの表示
2. 利用可能ドライブの列挙
3. ディレクトリツリーの動的展開
4. パスの選択と返却
5. キャンセル操作のサポート

**画面遷移**：本機能は単一ダイアログのGUIであり、画面遷移は存在しない。OKまたはCancelでダイアログを閉じる。

**権限による表示制御**：SQL Serverへの接続権限が必要。表示されるディレクトリはSQL Serverサービスアカウントがアクセス可能なものに限定される。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | Show-DbaInstanceFileSystem | 主機能 | ファイルシステムブラウザGUI |
| - | Connect-DbaInstance | 関連機能 | SQL Serverインスタンスへの接続確立 |
| - | Backup-DbaDatabase | 関連機能 | バックアップ先パス選択に使用 |
| - | Restore-DbaDatabase | 関連機能 | リストア先パス選択に使用 |

## 画面種別

GUIダイアログ（WPF TreeView）

## URL/ルーティング

PowerShellコマンドレット：
- `Show-DbaInstanceFileSystem`

## 入出力項目

### Show-DbaInstanceFileSystem パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter | Yes | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | SQL Server認証用資格情報 |
| EnableException | switch | No | 例外処理モードの切り替え |

## 表示項目

### GUI要素

| 要素名 | 型 | 説明 |
|--------|-----|------|
| ウィンドウタイトル | Label | "Locate Folder" |
| 指示ラベル | Label | "Select the folder:" |
| ツリービュー | TreeView | ディレクトリ階層表示 |
| パステキストボックス | TextBox | 選択されたパス表示（初期値: C:\） |
| OKボタン | Button | 選択確定 |
| Cancelボタン | Button | キャンセル |

### アイコン種別

| アイコン | 用途 | 説明 |
|---------|------|------|
| ディスクアイコン | ドライブ | ルートドライブ表示 |
| フォルダアイコン | ディレクトリ | サブディレクトリ表示 |
| dbatoolsアイコン | ウィンドウ | ウィンドウアイコン |

### 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (戻り値) | string | 選択されたパス（末尾にバックスラッシュ付き）、キャンセル時はnull |

## イベント仕様

### 1-初期化処理

ダイアログ表示時の初期化処理：

1. PresentationFrameworkアセンブリの読み込み
2. Base64エンコードアイコンのデコード
3. Connect-DbaInstanceでSQL Serverに接続
4. EnumAvailableMediaでドライブ一覧を取得
5. 各ドライブをTreeViewに追加
6. ダイアログを表示

### 2-ツリー展開処理

ツリーノード展開時の処理：

1. ExpandedまたはSelectedイベントを検出
2. クリックされたノードの子アイテムをクリア
3. Get-SubDirectory関数でサブディレクトリを取得
4. $サインで始まるディレクトリを除外
5. "System Volume Information"を除外
6. サブディレクトリをTreeViewItemとして追加

### 3-選択処理

パス選択時の処理：

1. TreeViewItemのTagからパスを取得
2. テキストボックスにパスを表示

### 4-完了処理

OKボタンクリック時の処理：

1. ダイアログを閉じる
2. テキストボックスのパスに末尾バックスラッシュを追加
3. パス文字列を返却

### 5-キャンセル処理

Cancelボタンクリック時の処理：

1. テキストボックスをnullに設定
2. ダイアログを閉じる
3. nullを返却

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Show-DbaInstanceFileSystem | (なし) | - | データベース更新なし |

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

本機能はデータベースの更新を行わない。SMO経由のメタデータ取得のみ。

## メッセージ仕様

| 種別 | メッセージID | メッセージ内容 | 発生条件 |
|------|-------------|---------------|---------|
| Error | - | Windows Presentation Framework required but not installed. | WPF未インストール時 |
| Error | - | Failure | 接続失敗時 |
| Error | - | No access to remote SQL Server files. | EnumAvailableMedia失敗時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| WPF未インストール | Stop-Functionでエラー表示、return |
| 接続エラー | Stop-FunctionでConnectionErrorカテゴリ、return |
| ファイルアクセス不可 | Stop-Functionでエラー表示、return |
| ディレクトリ列挙失敗 | 例外をキャッチ、処理続行 |

## 備考

- WPFを使用するためWindowsプラットフォームのみ対応
- ダイアログは中央に表示（WindowStartupLocation="CenterScreen"）
- ウィンドウサイズは620x440ピクセル
- $記号で始まる隠しディレクトリは表示されない
- System Volume Informationは表示されない
- 返却パスは末尾にバックスラッシュが付く
- アイコンはBase64エンコードで埋め込み
- パイプライン入力をサポート（ValueFromPipeline）

---

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

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

### 推奨読解順序

#### Step 1: GUI定義を理解する

XAMLによるWPFダイアログ定義を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Show-DbaInstanceFileSystem.ps1 | `public/Show-DbaInstanceFileSystem.ps1` | 159-173行目のXAML定義 |

**読解のコツ**: XAMLはWPFの標準UI定義形式。TreeView、TextBox、Buttonの配置を確認。

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

Add-TreeItemとGet-SubDirectory関数を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 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関数 |

**主要処理フロー**:
1. **71-109行目**: TreeViewItemの作成、アイコン設定、階層構造の構築
2. **91-100行目**: ドライブ（1文字）とフォルダの判別
3. **111-130行目**: SMOのEnumDirectoriesでサブディレクトリ取得
4. **126行目**: $記号ディレクトリとSystem Volume Informationの除外

#### Step 3: イベントハンドリングを理解する

展開・選択・ボタンイベントを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Show-DbaInstanceFileSystem.ps1 | `public/Show-DbaInstanceFileSystem.ps1` | 192-211行目のイベントハンドラ |

**主要処理フロー**:
- **192-202行目**: SourceInitializedでExpanded/Selectedイベントをフック
- **204-206行目**: OKボタンでダイアログを閉じる
- **208-211行目**: Cancelでテキストをnullにしてダイアログを閉じる

#### Step 4: 戻り値処理を理解する

endブロックでの戻り値生成を把握する。

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

**主要処理フロー**:
- **218-220行目**: テキストボックスに値がある場合、末尾にバックスラッシュを追加して返却

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

```
Show-DbaInstanceFileSystem
    |
    +-- Add-Type -AssemblyName PresentationFramework
    |
    +-- Convert-b64toimg（アイコンデコード）
    |
    +-- Connect-DbaInstance
    |
    +-- $server.EnumAvailableMedia()（ドライブ列挙）
    |
    +-- Add-TreeItem（各ドライブ追加）
    |
    +-- $window.ShowDialog()
    |       |
    |       +-- [Expanded/Selected Event]
    |       |       +-- Get-SubDirectory
    |       |               +-- $server.EnumDirectories($nameSpace)
    |       |               +-- Add-TreeItem
    |       |
    |       +-- [OK Click] → Close
    |       +-- [Cancel Click] → $textbox.Text = $null, Close
    |
    +-- return "$drive\"
```

### データフロー図

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

SqlInstance -------> Connect -------> EnumAvailableMedia -------> TreeView
                     接続確立         ドライブ列挙               GUI表示

[ユーザー操作]
ノード展開 -------> EnumDirectories -------> TreeViewItem追加
                    サブディレクトリ取得

[完了]
OKクリック -------> textbox.Text + "\" -------> string
                    パス文字列生成
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Show-DbaInstanceFileSystem.ps1 | `public/Show-DbaInstanceFileSystem.ps1` | ソース | ファイルシステムブラウザGUI |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続確立（依存） |
