# 画面設計書 273-パス管理

## 概要

本ドキュメントは、dbatoolsモジュールのパス管理機能（Get-DbatoolsPath、Set-DbatoolsPath）に関する画面設計書です。

### 本画面の処理概要

dbatoolsが使用するファイルパス（一時ファイル、ログ、出力データの保存先など）を取得・設定するPowerShellコマンド群を提供します。

**業務上の目的・背景**：SQL Server管理業務において、バックアップファイルのステージング場所、エクスポート先ディレクトリ、ログ出力先などを柔軟に管理する必要があります。組織のファイルストレージポリシーに準拠したパス設定や、権限問題を回避するためのパスカスタマイズを実現します。チーム内で統一したパス設定を共有することで、スクリプトの可搬性を向上させます。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行します。
- `Get-DbatoolsPath` - パスの取得
- `Set-DbatoolsPath` - パスの設定

**主要な操作・処理内容**：
1. 名前付きパスの取得（Get-DbatoolsPath）
2. 名前付きパスの設定（Set-DbatoolsPath）
3. パス設定の永続化（Set-DbatoolsPath -Register）

**画面遷移**：CLIベースのため画面遷移は存在しません。他のdbatoolsコマンドから内部的に参照されます。

**権限による表示制御**：パスの設定自体には特別な権限は不要ですが、設定するパスへのアクセス権限はユーザーに依存します。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 159 | Get-DbatoolsPath | 主機能 | dbatoolsパスの取得 |
| 233 | Set-DbatoolsPath | 主機能 | dbatoolsパスの設定 |

## 画面種別

コマンドラインインターフェース（CLI）

## URL/ルーティング

PowerShellコマンドレット
- `Get-DbatoolsPath`
- `Set-DbatoolsPath`

## 入出力項目

### Get-DbatoolsPath

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| Name | string | Yes | パスの名前（Temp、LocalAppData、AppData、ProgramData、またはカスタム名） |

### Set-DbatoolsPath

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| Name | string | Yes | パスに割り当てるエイリアス名 |
| Path | string | Yes | 設定するディレクトリパス |
| Register | switch | No | パス設定をセッション間で永続化 |
| Scope | ConfigScope | No | 永続化時のスコープ（デフォルト: UserDefault） |

## 表示項目

### Get-DbatoolsPath出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| （戻り値） | string | 設定されているファイルパス |

## イベント仕様

### 1-パス取得

Get-DbatoolsPathコマンド実行時、内部でGet-DbatoolsConfigValueを呼び出し、"Path.Managed.{Name}"形式の設定値を取得します。

**処理詳細**：
1. 指定されたNameパラメータを使用
2. Get-DbatoolsConfigValue -FullName "Path.Managed.$Name" を呼び出し
3. 設定値（パス文字列）を返却

### 2-パス設定

Set-DbatoolsPathコマンド実行時、Set-DbatoolsConfigを呼び出してパスを設定します。

**処理詳細**：
1. Set-DbatoolsConfig -FullName "Path.Managed.$Name" -Value $Path を呼び出し
2. Registerパラメータが指定された場合、Register-DbatoolsConfig を呼び出して永続化

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

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

本機能はSQL Serverデータベースに対する直接的な操作は行いません。dbatoolsモジュール自体のパス設定を管理します。

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Set-DbatoolsPath -Register | N/A（レジストリ/ファイル） | INSERT/UPDATE | パス設定を永続化 |

## メッセージ仕様

| 種別 | メッセージ | 条件 |
|------|----------|------|
| （なし） | 本コマンドは特別なメッセージを出力しません | - |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 存在しないパス名を指定（Get） | $nullを返却 |
| 無効なスコープを指定（Set） | Register-DbatoolsConfigでエラー |

## 備考

- パスは "Path.Managed.{Name}" 形式で設定システムに保存
- 事前定義パス名：Temp、LocalAppData、AppData、ProgramData
- カスタムパス名を自由に定義可能
- Set-DbatoolsPathは$Env:TEMPなどの環境変数を上書きしない
- パス設定の永続化にはRegister-DbatoolsConfigが内部で使用される

---

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

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

### 推奨読解順序

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

パス設定は"Path.Managed.{Name}"形式でdbatools設定システムに格納されます。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbatoolsPath.ps1 | `public/Get-DbatoolsPath.ps1` | パス設定の格納形式を理解 |
| 1-2 | Set-DbatoolsPath.ps1 | `public/Set-DbatoolsPath.ps1` | パス設定の保存方法を理解 |

**読解のコツ**: 両コマンドは設定システムの薄いラッパーであり、実際の処理はGet-DbatoolsConfigValue/Set-DbatoolsConfigに委譲されます。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbatoolsPath.ps1 | `public/Get-DbatoolsPath.ps1` | パス取得のメインロジック |
| 2-2 | Set-DbatoolsPath.ps1 | `public/Set-DbatoolsPath.ps1` | パス設定のメインロジック |

**主要処理フロー（Get-DbatoolsPath）**:
1. **41行目**: Get-DbatoolsConfigValue -FullName "Path.Managed.$Name"

**主要処理フロー（Set-DbatoolsPath）**:
1. **60行目**: Set-DbatoolsConfig -FullName "Path.Managed.$Name" -Value $Path
2. **61行目**: Register-DbatoolsConfig（Registerパラメータ指定時）

#### Step 3: 依存コマンドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbatoolsConfigValue.ps1 | `public/Get-DbatoolsConfigValue.ps1` | 値取得の実装詳細 |
| 3-2 | Register-DbatoolsConfig.ps1 | `public/Register-DbatoolsConfig.ps1` | 永続化の実装詳細 |

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

```
Get-DbatoolsPath
    │
    └─ Get-DbatoolsConfigValue
           │
           └─ ConfigurationHost.Configurations["path.managed.{name}"].Value

Set-DbatoolsPath
    │
    ├─ Set-DbatoolsConfig -FullName "Path.Managed.$Name" -Value $Path
    │
    └─ Register-DbatoolsConfig -FullName "Path.Managed.$Name" -Scope $Scope
           （Registerパラメータ指定時のみ）
```

### データフロー図

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

Name ──────────────────▶ Get-DbatoolsConfigValue ──────────▶ パス文字列
                              │
                              └─ "Path.Managed.$Name" 形式で検索

Name + Path ───────────▶ Set-DbatoolsConfig ───────────────▶ 設定更新
    │
    └─ Register ────────▶ Register-DbatoolsConfig ─────────▶ 永続化
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbatoolsPath.ps1 | `public/Get-DbatoolsPath.ps1` | ソース | パス取得コマンド |
| Set-DbatoolsPath.ps1 | `public/Set-DbatoolsPath.ps1` | ソース | パス設定コマンド |
| Get-DbatoolsConfigValue.ps1 | `public/Get-DbatoolsConfigValue.ps1` | ソース | 内部で使用（値取得） |
| Register-DbatoolsConfig.ps1 | `public/Register-DbatoolsConfig.ps1` | ソース | 内部で使用（永続化） |
