# 機能設計書 233-Set-DbatoolsPath

## 概要

本ドキュメントは、dbatools PowerShellモジュールのSet-DbatoolsPath関数に関する機能設計書です。この関数は名前付きパス設定を構成し、後でGet-DbatoolsPathを使用して取得できるようにします。

### 本機能の処理概要

**業務上の目的・背景**：データベース管理作業では、バックアップ先、スクリプト格納場所、ログ出力先など、頻繁に使用するパスを管理する必要があります。本機能により、これらのパスに分かりやすい名前を付けて管理でき、スクリプトの可読性と保守性が向上します。また、チーム間でパス設定を共有することで、環境差異によるエラーを防止できます。

**機能の利用シーン**：バックアップスクリプトで使用するパスの設定時、チーム共有のスクリプトでのパス管理時、環境ごとに異なるパスを抽象化する場合、自動化スクリプトでの設定ファイル作成時に使用されます。

**主要な処理内容**：
1. 指定された名前でパスをdbatools設定に保存
2. Register指定時は設定を永続化

**関連システム・外部連携**：dbatoolsの内部設定システム（Set-DbatoolsConfig, Register-DbatoolsConfig）と連携します。

**権限による制御**：特別な権限は不要です。設定スコープによりユーザー単位またはシステム全体への適用が可能です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | CLIコマンド | 主機能 | PowerShellコマンドラインから直接実行 |

## 機能種別

構成設定変更処理（Configuration Management）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Name | string | Yes | パスに関連付けるエイリアス名 | 必須 |
| Path | string | Yes | 保存するディレクトリパス | 必須 |
| Register | switch | No | 設定を永続化する | ParameterSet 'Register'で必須 |
| Scope | ConfigScope | No | 永続化設定のスコープ（デフォルト：UserDefault） | 有効なConfigScopeのみ |

### 入力データソース

- PowerShellコマンドライン引数

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| - | None | パイプラインへの出力なし |

### 出力先

- 設定値はdbatoolsの内部設定システム（Path.Managed.{Name}）に保存

## 処理フロー

### 処理シーケンス

```
1. 設定名の構築
   └─ "Path.Managed.{Name}" 形式で設定キーを生成
2. 設定値の保存
   └─ Set-DbatoolsConfigで設定を保存
3. 永続化判定
   └─ Register指定時は設定を登録
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[設定キー構築]
    B --> C[Set-DbatoolsConfig実行]
    C --> D{Register指定?}
    D -->|Yes| E[Register-DbatoolsConfig実行]
    D -->|No| F[終了]
    E --> F
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 設定キー形式 | 設定キーは"Path.Managed.{Name}"形式 | 常時 |
| BR-002 | 永続化オプション | Register指定時のみ永続化 | Register指定時 |
| BR-003 | スコープデフォルト | 永続化スコープのデフォルトはUserDefault | Register指定時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベース操作なし |

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

データベース操作はありません。dbatools内部設定システムのみを操作します。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | 通常はエラーなし | - |

### リトライ仕様

リトライ処理は不要です。

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

トランザクション管理は不要です（設定変更のみ）。

## パフォーマンス要件

即座に設定が適用されます。

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

- パス設定にセキュリティ上の制限はありません
- ネットワークパスやマップドドライブも設定可能
- 設定したパスの存在確認は行われません

## 備考

- Get-DbatoolsPathを使用して設定したパスを取得できます
- 環境変数（$Env:TEMP等）はオーバーライドされません

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Set-DbatoolsPath.ps1 | `public/Set-DbatoolsPath.ps1` | パラメータ定義（47-57行目） |

**読解のコツ**: ParameterSetNameにより、RegisterパラメータとScopeパラメータの関係が定義されています。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Set-DbatoolsPath.ps1 | `public/Set-DbatoolsPath.ps1` | 関数定義とprocess block（45-63行目） |

**主要処理フロー**:
1. **60行目**: Set-DbatoolsConfigで"Path.Managed.{Name}"に値を設定
2. **61行目**: Register指定時にRegister-DbatoolsConfigで永続化

#### Step 3: 関連コマンドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbatoolsPath.ps1 | `public/Get-DbatoolsPath.ps1` | パス取得の仕組み |
| 3-2 | Set-DbatoolsConfig.ps1 | `public/Set-DbatoolsConfig.ps1` | 設定値の変更方法 |

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

```
Set-DbatoolsPath
    │
    ├─ Set-DbatoolsConfig
    │      └─ Path.Managed.{Name} = {Path}
    │
    └─ Register-DbatoolsConfig (条件付き)
           └─ Path.Managed.{Name}永続化
```

### データフロー図

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

Name ──────────────┐
                   │
Path ──────────────┼──▶ Set-DbatoolsPath ──────────────▶ なし（内部設定変更のみ）
                   │         │
Register ──────────┤         ├─ Set-DbatoolsConfig
                   │         └─ Register-DbatoolsConfig
Scope ─────────────┘

[dbatools内部設定] ◄───── 設定書き込み ─────┘
(Path.Managed.{Name})
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Set-DbatoolsPath.ps1 | `public/Set-DbatoolsPath.ps1` | ソース | メイン関数実装 |
| Get-DbatoolsPath.ps1 | `public/Get-DbatoolsPath.ps1` | ソース | パス取得（対となる機能） |
| Set-DbatoolsConfig.ps1 | `public/Set-DbatoolsConfig.ps1` | ソース | 設定値変更ヘルパー |
| Register-DbatoolsConfig.ps1 | `public/Register-DbatoolsConfig.ps1` | ソース | 設定永続化ヘルパー |
