# 機能設計書 252-Test-DbaPath

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける`Test-DbaPath`コマンドレットの機能設計書です。ファイルやディレクトリがSQL Serverサービスアカウントからアクセス可能かどうかをテストします。

### 本機能の処理概要

`Test-DbaPath`コマンドは、SQL Serverの拡張ストアドプロシージャ`master.dbo.xp_fileexist`を使用して、指定されたファイルまたはディレクトリがSQL Serverサービスアカウントのセキュリティコンテキストからアクセス可能かどうかを検証します。

**業務上の目的・背景**：SQL Serverでのバックアップ、リストア、バルクインサートなどの操作では、SQL Serverサービスアカウントがファイルシステム上のパスにアクセスできる必要があります。ユーザーの資格情報とSQL Serverサービスアカウントの権限は異なる場合があり、事前にパスのアクセス可能性を確認することで、操作失敗を防止できます。本機能は、バックアップ先やリストア元のパスが正しくアクセスできることを事前検証するために使用されます。

**機能の利用シーン**：
- バックアップ操作実行前のバックアップ先パス検証
- リストア操作実行前のバックアップファイル存在確認
- バルクインサート用データファイルのアクセス確認
- 新しいネットワーク共有の接続テスト
- ディスク構成変更後のアクセス検証

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスへの接続を確立
2. テスト対象パスをバッチ処理用にグループ化（100件ずつ）
3. 各パスに対して`xp_fileexist`を実行
4. ファイル存在有無とディレクトリ判定結果を返却

**関連システム・外部連携**：SQL Serverの`master.dbo.xp_fileexist`拡張ストアドプロシージャを使用してファイルシステムにアクセスします。

**権限による制御**：`xp_fileexist`の実行権限が必要です。通常、publicロールで実行可能ですが、セキュリティ設定によっては制限される場合があります。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本機能はPowerShellコマンドレットであり、関連するGUI画面はありません |

## 機能種別

バリデーション / ファイルシステムアクセス検証

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | テストを実行するSQL Serverインスタンス | パイプラインから受け付け可能 |
| SqlCredential | PSCredential | No | 代替認証情報 | Get-Credentialで生成された資格情報オブジェクト |
| Path | object | Yes | テスト対象のファイルまたはディレクトリパス | 単一パス、配列、パイプライン入力に対応 |
| EnableException | switch | No | 例外を有効にする | - |

### 入力データソース

- PowerShellコマンドラインからの直接入力
- パイプライン経由での入力
- 配列としての複数パス指定

## 出力仕様

### 出力データ

**単一パス・単一インスタンスの場合（System.Boolean）：**

| 項目名 | 型 | 説明 |
|--------|-----|------|
| （戻り値） | bool | ファイルまたはディレクトリがアクセス可能な場合$true、そうでない場合$false |

**複数パスまたは複数インスタンスの場合（PSCustomObject）：**

| 項目名 | 型 | 説明 |
|--------|-----|------|
| SqlInstance | string | SQL Serverインスタンス名 |
| InstanceName | string | インスタンス名 |
| ComputerName | string | コンピュータ名 |
| FilePath | string | テストされたファイル/ディレクトリパス |
| FileExists | bool | ファイルまたはディレクトリが存在しアクセス可能な場合$true |
| IsContainer | bool | パスがディレクトリ（コンテナ）の場合$true |

### 出力先

- PowerShellパイプライン（BooleanまたはPSCustomObject）
- コンソール表示

## 処理フロー

### 処理シーケンス

```
1. process ブロック
   └─ 各SqlInstanceに対してループ処理
      ├─ Connect-DbaInstanceでSQL Server接続
      ├─ 接続エラー時はStop-FunctionでスキップしてContinue
      ├─ パスを100件ずつのグループに分割
      │   └─ 各グループに対して
      │       ├─ xp_fileexistクエリを構築（セミコロン区切りで連結）
      │       ├─ ExecuteWithResultsでバッチ実行
      │       └─ 結果を処理
      │           ├─ 単一パス・単一インスタンス → Boolean返却
      │           └─ 複数 → PSCustomObject返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstanceループ}
    B -->|次のインスタンス| C[Connect-DbaInstance]
    C -->|成功| D[パスを100件ずつグループ化]
    C -->|失敗| E[Stop-Function/Continue]
    E --> B
    D --> F{各グループ処理}
    F -->|次のグループ| G[xp_fileexistクエリ構築]
    G --> H[ExecuteWithResults実行]
    H --> I{単一パス・単一インスタンス?}
    I -->|Yes| J[Boolean返却]
    I -->|No| K[PSCustomObject生成・出力]
    J --> L[終了]
    K --> F
    F -->|完了| B
    B -->|完了| L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | バッチサイズ | パスは100件ずつバッチ処理される | 複数パス指定時 |
| BR-002 | 単一結果Boolean | 単一パス・単一インスタンスの場合はBooleanを返却 | Path.Count==1 && SqlInstance.Count==1 && 配列でない |
| BR-003 | FileExists判定 | ファイル存在またはディレクトリ存在の場合にtrue | 常に適用 |

### 計算ロジック

- `FileExists` = xp_fileexist結果の[0]（ファイル存在）または[1]（ディレクトリ存在）がtrue
- `IsContainer` = xp_fileexist結果の[1]（ディレクトリ存在）がtrue

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ファイル存在確認 | - | EXEC | xp_fileexistストアドプロシージャ実行 |

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

#### xp_fileexist実行

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| EXEC | File Exists | 戻り値列0 | 1=存在、0=存在しない |
| EXEC | File is a Directory | 戻り値列1 | 1=ディレクトリ、0=ファイル |
| EXEC | Parent Directory Exists | 戻り値列2 | 1=親ディレクトリ存在 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverへの接続失敗 | Stop-Functionで警告を出力し、次のインスタンスへ続行 |

### リトライ仕様

本機能にはリトライ機能はありません。

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

本機能は読み取り専用（ファイルシステム検査）であり、トランザクション管理は不要です。

## パフォーマンス要件

- 100パスごとにバッチ処理することで、大量パスの効率的な検証を実現
- 各xp_fileexist呼び出しは通常ミリ秒単位で完了

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

- SQL Serverサービスアカウントのセキュリティコンテキストでファイルシステムにアクセス
- パス文字列はクエリに直接埋め込まれるため、信頼できる入力元からのみ使用すること
- 読み取り専用操作のためファイルシステムへの変更は行わない

## 備考

- 単一パス・単一インスタンスの場合は直接Boolean値を返却し、スクリプト内での条件分岐に便利
- 複数パスの場合はPSCustomObjectを返却し、詳細な分析が可能

---

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

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

### 推奨読解順序

#### Step 1: パラメータとエントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | 関数全体の構造とパラメータ定義 |

**主要処理フロー**:
1. **69-78行目**: パラメータ定義（SqlInstance、Path、SqlCredential、EnableException）
2. **79-122行目**: processブロックでの処理ロジック

**読解のコツ**:
- `[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseOutputTypeCorrectly", ...)]`は出力型の動的変更（Boolean/PSCustomObject）に対する警告抑制
- Pathパラメータはobject型で、様々な入力形式を受け付け

#### Step 2: バッチ処理ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | 86-97行目：バッチ処理とxp_fileexistクエリ構築 |

**主要処理フロー**:
- **86-90行目**: パスを100件ずつグループ化（`Group-Object`使用）
- **91-97行目**: 各グループのパスに対してxp_fileexistクエリを構築
- **98行目**: `ExecuteWithResults`でバッチ実行

#### Step 3: 結果処理と出力を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | 99-119行目：結果の処理と出力形式の分岐 |

**主要処理フロー**:
- **99-104行目**: 単一パス・単一インスタンスの場合のBoolean返却
- **105-118行目**: 複数の場合のPSCustomObject生成とループ出力

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

```
Test-DbaPath
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server SMOオブジェクト取得
    │
    └─ $server.ConnectionContext.ExecuteWithResults
           └─ EXEC master.dbo.xp_fileexist 'パス'
```

### データフロー図

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

SqlInstance     ───▶ Connect-DbaInstance
Path (array)    ───▶ 100件ずつグループ化   ───▶ xp_fileexist実行
                            │
                            ▼
                     ExecuteWithResults
                            │
                            ▼
                     結果セット (DataTable)
                            │
                            ├─ 単一パス ─────▶ Boolean ($true/$false)
                            │
                            └─ 複数パス ─────▶ PSCustomObject[]
                                               (FilePath, FileExists, IsContainer)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | ソース | メイン関数定義 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
| Stop-Function.ps1 | `internal/functions/flowcontrol/Stop-Function.ps1` | ソース | エラーハンドリング関数 |
