# 画面設計書 226-パス操作

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるパス操作機能の設計仕様を定義する。ファイルパスの結合、解決、存在確認など、SQL Server環境でのパス操作をサポートするユーティリティ機能を提供するCLIインターフェースである。

### 本画面の処理概要

本機能は、SQL Serverと連携したファイルパス操作を提供する。Windows/Linux両方のSQL Serverに対応し、ターゲットサーバーのOSに応じた適切なパス区切り文字を使用してパスを構築する。また、パスの検証、解決、アクセス可能性テストなど、DBA作業に必要なパス関連ユーティリティを提供する。

**業務上の目的・背景**：バックアップ、リストア、データファイル管理など、DBA作業ではファイルパスの構築が頻繁に必要となる。特にLinux SQL Serverの登場により、Windows（バックスラッシュ）とLinux（スラッシュ）のパス区切り文字の違いが問題となる。本機能は、ターゲットサーバーのOSを自動検出し、正しいパス区切り文字でパスを構築することで、クロスプラットフォームスクリプトの作成を容易にする。

**画面へのアクセス方法**：PowerShellコンソールから以下のコマンドを実行することでアクセスする。
- `Join-DbaPath` - パスの結合
- `Resolve-DbaPath` - パスの解決と検証
- `Test-DbaPath` - SQL Serverからのパスアクセス確認

**主要な操作・処理内容**：
1. 複数パスセグメントの結合（OS適応型）
2. 相対パスから絶対パスへの解決
3. パス存在確認とプロバイダー検証
4. SQL Serverサービスアカウントからのパスアクセス確認
5. ファイル/ディレクトリの判別

**画面遷移**：本機能はCLIコマンドであり、画面遷移は存在しない。他のdbatoolsコマンドの内部処理やユーザースクリプトで使用される。

**権限による表示制御**：Test-DbaPathはSQL Serverへの接続権限とxp_fileexist実行権限が必要。Join-DbaPath、Resolve-DbaPathはローカル権限のみ必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | Join-DbaPath | 主機能 | パスセグメントの結合（OS適応型） |
| - | Resolve-DbaPath | 主機能 | パスの解決と検証 |
| - | Test-DbaPath | 主機能 | SQL Serverからのパスアクセス確認 |
| - | Test-HostOSLinux | 関連機能 | ターゲットOSのLinux判定 |
| - | Connect-DbaInstance | 関連機能 | SQL Serverインスタンスへの接続確立 |

## 画面種別

CLIコマンド（PowerShell関数）

## URL/ルーティング

PowerShellコマンドレット：
- `Join-DbaPath`
- `Resolve-DbaPath`
- `Test-DbaPath`

## 入出力項目

### Join-DbaPath パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| Path | string | Yes | ベースパス |
| SqlInstance | DbaInstanceParameter | No | 対象SQL Serverインスタンス（OS判定用） |
| Child | string[] | No | 追加するパスセグメント |

### Resolve-DbaPath パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| Path | string[] | Yes | 解決するパス |
| Provider | string | No | 検証するプロバイダー（FileSystem等） |
| SingleItem | switch | No | 単一パスに解決されることを要求 |
| NewChild | switch | No | 新規ファイル用（親ディレクトリの存在のみ確認） |

### Test-DbaPath パラメータ

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

## 表示項目

### Join-DbaPath 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (戻り値) | string | 結合されたパス文字列 |

### Resolve-DbaPath 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (戻り値) | string | 解決されたパス文字列 |

### Test-DbaPath 出力（単一パス・単一インスタンス時）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (戻り値) | bool | パスがアクセス可能かどうか |

### Test-DbaPath 出力（複数パスまたは複数インスタンス時）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| SqlInstance | string | 完全インスタンス名 |
| InstanceName | string | インスタンス名 |
| ComputerName | string | コンピュータ名 |
| FilePath | string | テストしたパス |
| FileExists | bool | ファイル/ディレクトリが存在するか |
| IsContainer | bool | ディレクトリかどうか |

## イベント仕様

### 1-Join（パス結合）処理

パスセグメントを結合する処理フロー：

1. SqlInstance未指定時：
   - ローカルOSの区切り文字でパスを結合
2. SqlInstance指定時：
   - Test-HostOSLinuxでターゲットOSを判定
   - Linuxの場合：スラッシュ(/)で結合
   - Windowsの場合：[IO.Path]::Combineで結合
3. 結合されたパス文字列を返却

### 2-Resolve（パス解決）処理

パスを検証・解決する処理フロー：

1. NewChild指定時：
   - 親ディレクトリのパスを解決
   - 子要素名を取得
   - SingleItem指定時は複数親パスでエラー
   - Provider指定時はプロバイダーを検証
   - 親パスと子要素を結合して返却
2. NewChild未指定時：
   - パスを直接解決
   - SingleItem指定時は複数パスでエラー
   - Provider指定時はプロバイダーを検証
   - ProviderPathを返却

### 3-Test（パステスト）処理

SQL Serverからのパスアクセスを確認する処理フロー：

1. Connect-DbaInstanceでSQL Serverに接続
2. パスを100個ずつのバッチに分割
3. 各バッチに対してxp_fileexistを実行
4. 単一パス・単一インスタンスの場合：bool値を返却
5. それ以外の場合：PSCustomObjectを返却

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Join-DbaPath | (なし) | - | ローカル処理のみ |
| Resolve-DbaPath | (なし) | - | ローカル処理のみ |
| Test-DbaPath | (なし) | EXEC | xp_fileexist実行 |

## メッセージ仕様

| 種別 | メッセージID | メッセージ内容 | 発生条件 |
|------|-------------|---------------|---------|
| Error | - | Failed to resolve path | パス解決失敗時 |
| Error | - | Could not resolve to a single parent path | SingleItem指定で複数パス時 |
| Error | - | Resolved provider is X when it should be Y | プロバイダー不一致時 |
| Verbose | - | Linux detected on remote server | リモートLinux検出時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| パス解決失敗 | Stop-Functionでエラー表示、EnableException時は例外送出 |
| 複数パス解決（SingleItem時） | Stop-Functionでエラー表示、EnableException時は例外送出 |
| プロバイダー不一致 | Stop-Functionでエラー表示、EnableException時は例外送出 |
| 接続エラー | Stop-Functionで処理中断 |

## 備考

- Join-DbaPathはSqlInstance指定時のみリモートOS判定を行う
- Resolve-DbaPathはローカルファイルシステムのみ対象
- Test-DbaPathは100パスごとのバッチ処理で効率化
- FileExistsはファイルまたはディレクトリが存在する場合にtrue
- IsContainerはディレクトリの場合にtrue

---

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

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

### 推奨読解順序

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

各コマンドの出力型を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Join-DbaPath.ps1 | `public/Join-DbaPath.ps1` | 出力型string、パラメータ定義 |
| 1-2 | Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | 条件分岐による出力型の違い |

**読解のコツ**: Test-DbaPathは入力条件により出力型が変わる（bool/PSCustomObject）。

#### Step 2: OS判定とパス結合を理解する

クロスプラットフォーム対応のパス結合ロジックを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Join-DbaPath.ps1 | `public/Join-DbaPath.ps1` | 56-83行目のOS分岐処理 |

**主要処理フロー**:
1. **56-60行目**: SqlInstance未指定時のローカルOS用パス結合
2. **64行目**: Test-HostOSLinuxでリモートOS判定
3. **66-70行目**: Linux用のスラッシュ結合
4. **71-79行目**: Windows用の[IO.Path]::Combine使用

#### Step 3: パス解決ロジックを理解する

NewChild分岐とプロバイダー検証を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Resolve-DbaPath.ps1 | `public/Resolve-DbaPath.ps1` | 78-116行目のprocess処理 |

**主要処理フロー**:
- **83-102行目**: NewChild時の親ディレクトリ解決と子結合
- **103-116行目**: 通常のパス解決とプロバイダー検証

#### Step 4: xp_fileexist実行を理解する

バッチ処理とSQL実行を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | 79-121行目のprocess処理 |

**主要処理フロー**:
- **86-90行目**: 100パスごとのバッチ分割
- **94-96行目**: xp_fileexistクエリ構築
- **99-104行目**: 単一パス・単一インスタンス時のbool返却
- **105-118行目**: 複数時のPSCustomObject返却

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

```
Join-DbaPath
    |
    +-- Test-HostOSLinux（SqlInstance指定時）
    |
    +-- [IO.Path]::Combine（Windows時）

Resolve-DbaPath
    |
    +-- Split-Path（NewChild時）
    |
    +-- Resolve-Path
    |
    +-- Join-Path（NewChild時）

Test-DbaPath
    |
    +-- Connect-DbaInstance
    |
    +-- Group-Object（バッチ分割）
    |
    +-- ExecuteWithResults（xp_fileexist実行）
```

### データフロー図

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

【Join-DbaPath】
Path + Child -------> OS判定 -------> パス結合 -------> string
パスセグメント        Linux/Windows    区切り文字選択     結合パス

【Test-DbaPath】
Path -------> バッチ分割 -------> xp_fileexist -------> bool/PSCustomObject
パス配列      100個ずつ          SQL実行              結果
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Join-DbaPath.ps1 | `public/Join-DbaPath.ps1` | ソース | パス結合機能 |
| Resolve-DbaPath.ps1 | `public/Resolve-DbaPath.ps1` | ソース | パス解決機能 |
| Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | ソース | パステスト機能 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続確立（依存） |
