# 画面設計書 225-ファイル取得

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるリモートファイル取得機能の設計仕様を定義する。SQL Serverマシン上のファイルシステムを、xp_dirtree拡張ストアドプロシージャを使用してリモートから列挙する機能を提供するCLIインターフェースである。

### 本画面の処理概要

本機能は、SQL ServerのxP_dirtree拡張ストアドプロシージャを使用して、SQL Serverマシン上のディレクトリとファイルをリモートから検索する。直接的なファイルシステムアクセスやRDP接続を必要とせず、SQL Server接続のみでファイル一覧を取得できる。

**業務上の目的・背景**：DBAは、孤立したデータベースファイルの検出、バックアップファイルのリストア前確認、ディスク使用量の監査、ファイルマイグレーションの準備など、SQL Serverマシン上のファイル情報を頻繁に必要とする。しかし、セキュリティ上の理由からファイルサーバーへの直接アクセスが制限されている環境も多い。本機能は、SQL Server経由でファイルシステムを探索することで、この制約を回避しつつ必要な情報を取得する。

**画面へのアクセス方法**：PowerShellコンソールから以下のコマンドを実行することでアクセスする。
- `Get-DbaFile` - リモートファイルの列挙

**主要な操作・処理内容**：
1. 指定ディレクトリ内のファイル・サブディレクトリの列挙
2. ファイル拡張子によるフィルタリング
3. 再帰的な深さ指定による検索範囲制御
4. デフォルトデータディレクトリの自動検索
5. 複数パス・複数インスタンスの一括検索

**画面遷移**：本機能はCLIコマンドであり、画面遷移は存在しない。ただし、`Find-DbaOrphanedFile`や`Restore-DbaDatabase`などの内部処理で使用されることがある。

**権限による表示制御**：xp_dirtreeの実行権限が必要。SQL Serverサービスアカウントがアクセス可能なパスのみ列挙可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | Get-DbaFile | 主機能 | SQL Server経由でのファイル列挙 |
| - | Get-DbaDefaultPath | 関連機能 | デフォルトパスの取得（Path未指定時） |
| - | Find-DbaOrphanedFile | 関連機能 | 孤立ファイル検索で使用 |
| - | Test-HostOSLinux | 関連機能 | Linuxサーバー判定でパス区切り文字変更 |
| - | Connect-DbaInstance | 関連機能 | SQL Serverインスタンスへの接続確立 |

## 画面種別

CLIコマンド（PowerShell関数）

## URL/ルーティング

PowerShellコマンドレット：
- `Get-DbaFile`

## 入出力項目

### Get-DbaFile パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | SQL Server認証用資格情報 |
| Path | string[] | No | 検索するディレクトリパス |
| FileType | string[] | No | フィルタする拡張子（ドットなし） |
| Depth | int | No | 再帰検索の深さ（デフォルト:1） |
| EnableException | switch | No | 例外処理モードの切り替え |

## 表示項目

### Get-DbaFile 出力

| 項目名 | 型 | 説明 | 表示 |
|--------|-----|------|------|
| ComputerName | string | コンピュータ名 | 非表示 |
| InstanceName | string | インスタンス名 | 非表示 |
| SqlInstance | string | 完全インスタンス名 | 表示 |
| Filename | string | ファイルのフルパス | 表示 |
| RemoteFilename | string | UNCパス | 非表示 |

## イベント仕様

### 1-ファイル取得処理

リモートファイルを列挙する処理フロー：

1. Connect-DbaInstanceでSQL Serverに接続
2. Path未指定時はGet-DbaDefaultPathでデフォルトデータディレクトリを取得
3. ホストOSを判定（Linux/Windows）でパス区切り文字を決定
4. Get-SQLDirTreeQuery関数でSQLクエリを構築：
   - #DirectoryTreeテンポラリテーブルを作成
   - 各Pathに対してxp_dirtreeを実行
   - 親ディレクトリ情報を更新
   - フルパスを構築してファイル一覧を取得
5. FileType指定時は拡張子でフィルタリング
6. パス区切り文字を正規化
7. 結果をPSCustomObjectで出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaFile | tempdb（一時テーブル） | CREATE/INSERT/SELECT | ファイル情報の一時格納 |
| Get-DbaFile | (なし) | EXEC | xp_dirtree実行 |

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

本機能は一時テーブルを使用するが、永続的なデータベース更新は行わない。

## メッセージ仕様

| 種別 | メッセージID | メッセージ内容 | 発生条件 |
|------|-------------|---------------|---------|
| Error | - | Failure | 接続失敗時 |
| Verbose | - | Adding paths | パス追加処理時 |
| Verbose | - | N files found | ファイル検出数表示 |
| Debug | - | (SQLクエリ内容) | クエリ詳細表示時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 接続エラー | Stop-Functionで処理中断、ConnectionErrorカテゴリ |
| xp_dirtree実行エラー | エラー内容を伝播 |
| パスアクセス不可 | 結果が空で返却 |

## 備考

- Depthのデフォルト値は1（直下のみ検索）
- Path未指定時はインスタンスのデフォルトデータディレクトリを検索
- Windows/Linux両方のSQL Serverに対応（パス区切り文字自動判定）
- SMBシェアパス（\\で始まる）は先頭の\\を維持
- RECYCLE.BINディレクトリは自動的に除外
- FileTypeは大文字小文字を区別しない

---

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

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

### 推奨読解順序

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

出力されるPSCustomObjectの構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaFile.ps1 | `public/Get-DbaFile.ps1` | 225-231, 241-247行目の出力オブジェクト構造 |

**読解のコツ**: RemoteFilenameプロパティはJoin-AdminUnc関数でUNCパスに変換される。

#### Step 2: SQLクエリ構築を理解する

xp_dirtreeを使用した動的SQLクエリの構築ロジックを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaFile.ps1 | `public/Get-DbaFile.ps1` | 106-170行目のGet-SQLDirTreeQuery関数 |

**主要処理フロー**:
1. **112-124行目**: #DirectoryTreeテンポラリテーブル作成
2. **126-140行目**: xp_dirtree実行とParentDirectory更新
3. **142-162行目**: CTEでフルパス構築（再帰クエリ）
4. **166行目**: dirnameプレースホルダーをPathに置換

#### Step 3: パス正規化を理解する

Windows/Linux対応のパス区切り文字処理を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaFile.ps1 | `public/Get-DbaFile.ps1` | 197-201, 215-224, 237-240行目 |

**主要処理フロー**:
- **197-201行目**: Test-HostOSLinuxでOS判定、区切り文字設定
- **218-222行目**: SMBシェアパスの先頭\\維持処理
- **239-240行目**: 二重スラッシュ/バックスラッシュの正規化

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

```
Get-DbaFile
    |
    +-- Connect-DbaInstance
    |
    +-- Get-DbaDefaultPath（Path未指定時）
    |
    +-- Test-HostOSLinux（パス区切り判定）
    |
    +-- Get-SQLDirTreeQuery（SQLクエリ構築）
    |       +-- xp_dirtree（SQLServer側）
    |
    +-- ExecuteWithResults（クエリ実行）
    |
    +-- Join-AdminUnc（UNCパス変換）
```

### データフロー図

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

Path/FileType -------> SQLクエリ構築 -------> xp_dirtree -------> PSCustomObject
パラメータ              #DirectoryTree        ファイル列挙         (Filename等)

【SQLクエリ処理フロー】
1. CREATE #DirectoryTree
2. EXEC xp_dirtree @Path, @Depth, 1
3. UPDATE ParentDirectory
4. WITH CTE...SELECT FullPath
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaFile.ps1 | `public/Get-DbaFile.ps1` | ソース | リモートファイル取得機能 |
| Get-DbaDefaultPath.ps1 | `public/Get-DbaDefaultPath.ps1` | ソース | デフォルトパス取得（依存） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続確立（依存） |
