# 画面設計書 229-データベースリスト表示

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるデータベースリスト表示機能の設計仕様を定義する。Windows Presentation Framework（WPF）を使用してGUIダイアログを表示し、SQL Serverインスタンス上のデータベース一覧をツリービューで選択できる機能を提供する。

### 本画面の処理概要

本機能は、WPFを使用してデータベース選択ダイアログを表示し、ユーザーが視覚的にデータベースを選択できるようにする。インタラクティブなメンテナンススクリプトの構築、エンドユーザーにSSMSなしでデータベースを選択させる場面、環境ごとにデータベース名が異なる動的ツールの作成などに適している。

**業務上の目的・背景**：スクリプトでデータベース名を指定する際、ハードコーディングや手動入力ではエラーが発生しやすい。本機能は、接続先SQL Serverの実際のデータベース一覧を表示し、ユーザーに選択させることで、タイプミスや存在しないデータベース名の指定を防止する。

**画面へのアクセス方法**：PowerShellコンソールから以下のコマンドを実行することでアクセスする。
- `Show-DbaDbList` - データベース選択ダイアログの表示

**主要な操作・処理内容**：
1. WPFダイアログの表示
2. データベース一覧の取得と表示
3. デフォルトデータベースの事前選択
4. データベースの選択と返却
5. キャンセル操作のサポート

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

**権限による表示制御**：SQL Serverへの接続権限が必要。表示されるデータベースはユーザーがアクセス可能なものに限定される。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | Show-DbaDbList | 主機能 | データベース選択GUI |
| - | Connect-DbaInstance | 関連機能 | SQL Serverインスタンスへの接続確立 |
| - | Get-DbaDatabase | 関連機能 | データベース情報取得（類似機能） |

## 画面種別

GUIダイアログ（WPF TreeView）

## URL/ルーティング

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

## 入出力項目

### Show-DbaDbList パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter | Yes | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | SQL Server認証用資格情報 |
| Title | string | No | ウィンドウタイトル（デフォルト: "Select Database"） |
| Header | string | No | 指示ラベル（デフォルト: "Select the database:"） |
| DefaultDb | string | No | 事前選択するデータベース名 |
| EnableException | switch | No | 例外処理モードの切り替え |

## 表示項目

### GUI要素

| 要素名 | 型 | 説明 |
|--------|-----|------|
| ウィンドウタイトル | Label | カスタマイズ可能（デフォルト: "Select Database"） |
| 指示ラベル | Label | カスタマイズ可能（デフォルト: "Select the database:"） |
| ツリービュー | TreeView | データベース一覧表示 |
| OKボタン | Button | 選択確定 |
| Cancelボタン | Button | キャンセル |

### アイコン種別

| アイコン | 用途 | 説明 |
|---------|------|------|
| データベースアイコン | データベース | 各データベースノード |
| フォルダアイコン | Databases | ルートノード |
| dbatoolsアイコン | ウィンドウ | ウィンドウアイコン |

### 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (戻り値) | string | 選択されたデータベース名、キャンセル時はnull |

## イベント仕様

### 1-初期化処理

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

1. PresentationFrameworkアセンブリの読み込み
2. Base64エンコードアイコンのデコード
3. Connect-DbaInstanceでSQL Serverに接続
4. XAMLからWPFウィンドウを生成（Title/Headerをパラメータから設定）
5. "Databases"ルートノードを作成（フォルダアイコン、展開状態）
6. $server.Databases.Nameでデータベース一覧を取得
7. 各データベースをTreeViewItemとして追加
8. DefaultDb指定時は該当ノードを事前選択
9. ダイアログを表示

### 2-選択処理

TreeViewItem選択時の処理：

1. SelectedイベントでTagを取得
2. $script:selectedに選択値を保存

### 3-完了処理

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

1. $script:okay = $trueを設定
2. ダイアログを閉じる

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

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

1. $script:selected = $nullを設定
2. ダイアログを閉じる

### 5-戻り値処理

endブロックでの処理：

1. $script:selectedに値があり、$script:okay = $trueの場合
2. 選択されたデータベース名を返却
3. それ以外の場合はnullを返却（暗黙）

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

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

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

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

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

## メッセージ仕様

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

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| WPF未インストール | Stop-Functionでエラー表示、return |
| 接続エラー | Stop-FunctionでConnectionErrorカテゴリ、return |
| データベース一覧取得失敗 | 例外をキャッチ、return |

## 備考

- WPFを使用するためWindowsプラットフォームのみ対応
- ダイアログは中央に表示（WindowStartupLocation="CenterScreen"）
- ウィンドウサイズはコンテンツに合わせて自動調整（SizeToContent="WidthAndHeight"）
- 最大高さは600ピクセル（MaxHeight="600"）
- Title/Headerパラメータでダイアログテキストをカスタマイズ可能
- DefaultDbで事前選択するデータベースを指定可能
- 返却値はデータベース名のみ（パスなし）
- OKボタンをクリックせずにダイアログを閉じた場合はnullを返却
- パイプライン入力をサポート（ValueFromPipeline）

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: XAMLはWPFの標準UI定義形式。TitleとHeaderはパラメータから動的に設定される。SizeToContent="WidthAndHeight"でコンテンツに合わせたサイズ調整。

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

Add-TreeItem関数を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Show-DbaDbList.ps1 | `public/Show-DbaDbList.ps1` | 94-124行目のAdd-TreeItem関数 |

**主要処理フロー**:
1. **101-112行目**: TreeViewItemの作成、アイコン設定
2. **114-117行目**: DefaultDbと一致する場合は事前選択

#### Step 3: データベース列挙を理解する

SMO経由のデータベース一覧取得を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Show-DbaDbList.ps1 | `public/Show-DbaDbList.ps1` | 195-203行目のデータベース列挙 |

**主要処理フロー**:
- **196行目**: $server.Databases.Nameでデータベース名一覧を取得
- **201-203行目**: 各データベースをAdd-TreeItemで追加

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Show-DbaDbList.ps1 | `public/Show-DbaDbList.ps1` | 205-222行目のイベントハンドラ |

**主要処理フロー**:
- **205-208行目**: OKボタンで$script:okay = $trueを設定
- **210-213行目**: Cancelで$script:selected = $nullを設定
- **215-221行目**: SourceInitializedでSelectedイベントをフック

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | Show-DbaDbList.ps1 | `public/Show-DbaDbList.ps1` | 227-231行目のendブロック |

**主要処理フロー**:
- **228-230行目**: selectedに値があり、okayがtrueの場合のみ返却

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

```
Show-DbaDbList
    |
    +-- Add-Type -AssemblyName PresentationFramework
    |
    +-- Convert-b64toimg（アイコンデコード）
    |
    +-- Connect-DbaInstance
    |
    +-- $server.Databases.Name（データベース列挙）
    |
    +-- Add-TreeItem（各データベース追加）
    |       +-- DefaultDb比較 → IsSelected = $true
    |
    +-- $window.ShowDialog()
    |       |
    |       +-- [Selected Event] → $script:selected = Tag
    |       |
    |       +-- [OK Click] → $script:okay = $true, Close
    |       +-- [Cancel Click] → $script:selected = $null, Close
    |
    +-- return $script:selected（$okayがtrueの場合）
```

### データフロー図

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

SqlInstance -------> Connect -------> $server.Databases.Name -------> TreeView
Title/Header         接続確立         データベース列挙                GUI表示
DefaultDb

[ユーザー操作]
ノード選択 -------> $script:selected = Tag

[完了]
OKクリック -------> $script:okay = $true -------> $script:selected (string)
                                                   データベース名
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Show-DbaDbList.ps1 | `public/Show-DbaDbList.ps1` | ソース | データベース選択GUI |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続確立（依存） |
