# 機能設計書 156-Get-DbatoolsConfigValue

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `Get-DbatoolsConfigValue` コマンドレットの機能設計を記述する。本機能は、指定された構成設定の値を直接取得するための機能である。

### 本機能の処理概要

dbatoolsモジュールの特定の構成設定の値を、その完全名（FullName）を指定して直接取得する機能である。Get-DbatoolsConfigが設定オブジェクト全体を返すのに対し、本機能は設定の生の値のみを返す。

**業務上の目的・背景**：dbatools内部の各コマンドや、ユーザーのカスタムスクリプトにおいて、特定の構成設定値を直接参照する必要がある。オブジェクト全体ではなく値のみを取得することで、スクリプト内での条件分岐や変数代入が簡潔になる。また、設定が存在しない場合のフォールバック値や、必須設定のバリデーションもサポートする。

**機能の利用シーン**：
- dbatools内部コマンドでの設定値参照
- カスタムスクリプトでの接続タイムアウト値取得
- デフォルトパス設定の参照
- 条件分岐での設定値チェック
- 設定未定義時のデフォルト値適用

**主要な処理内容**：
1. 構成キー名による設定値の検索
2. 値が存在しない場合のフォールバック値適用
3. NotNull指定時の存在チェックとエラー発生
4. "Mandatory"/"Optional"文字列のブール値変換

**関連システム・外部連携**：dbatools内部構成システム（Dataplat.Dbatools.Configuration.ConfigurationHost）

**権限による制御**：特別な権限は不要。

## 関連画面

本機能はコマンドライン機能であり、直接的な関連画面は存在しない。

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | - |

## 機能種別

データ取得（モジュール構成値）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| FullName | string | Yes | 構成キーの完全名（Module.Name形式） | エイリアス: Name |
| Fallback | object | No | 設定が存在しない場合のデフォルト値 | - |
| NotNull | switch | No | 値がnullの場合にエラーをスロー | - |

### 入力データソース

- ユーザー入力（コマンドラインパラメータ）
- 内部構成システム（ConfigurationHost.Configurations）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (値) | object | 構成設定の値（型は設定による） |

### 出力先

- PowerShellパイプライン（設定値そのもの）

## 処理フロー

### 処理シーケンス

```
1. キー名の正規化
   └─ FullNameを小文字に変換

2. 設定値の取得
   └─ ConfigurationHost.Configurationsから値を取得

3. null判定と処理
   ├─ 値がnull → Fallback値を使用
   └─ 値が存在 → 特殊文字列の変換処理

4. 特殊文字列変換
   ├─ "Mandatory" → $true
   └─ "Optional" → $false

5. NotNullチェック
   └─ 値がnullかつNotNull指定時 → Stop-Functionでエラー

6. 出力
   └─ 値をパイプラインに出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[FullName小文字変換]
    B --> C[ConfigurationHost.Configurationsから取得]
    C --> D{値がnull?}
    D -->|Yes| E[Fallback値を使用]
    D -->|No| F{"Mandatory"?}
    F -->|Yes| G[true に変換]
    F -->|No| H{"Optional"?}
    H -->|Yes| I[false に変換]
    H -->|No| J[値をそのまま使用]
    E --> K{NotNull指定?}
    G --> L[値を返す]
    I --> L
    J --> L
    K -->|No| L
    K -->|Yes| M{値がnull?}
    M -->|Yes| N[Stop-Function エラー]
    M -->|No| L
    N --> O[終了]
    L --> O
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | キー名小文字化 | FullNameは小文字に変換して検索 | 常時 |
| BR-002 | Fallback適用 | 値がnullの場合Fallback値を使用 | Fallback指定時 |
| BR-003 | Mandatoryブール変換 | 文字列"Mandatory"はtrue | 値が"Mandatory"の場合 |
| BR-004 | Optionalブール変換 | 文字列"Optional"はfalse | 値が"Optional"の場合 |
| BR-005 | NotNullエラー | NotNull指定時にnullならエラー | NotNull指定かつnull時 |

### 計算ロジック

特になし

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

本機能はデータベースにアクセスしない。内部構成システムから設定を取得する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| InvalidData | 設定値なし | NotNull指定かつ値がnull | Stop-Functionで例外スロー |

### リトライ仕様

リトライは実装されていない。

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

本機能は読み取り専用操作のため、トランザクション管理は不要。

## パフォーマンス要件

- 構成設定はメモリ上に保持されており、即時取得可能
- 単一値の取得のため、ミリ秒単位で完了

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

- 構成値にはセンシティブな情報が含まれる可能性がある
- 適切なアクセス制御はdbatools構成システムに委譲

## 備考

- 主にdbatools内部で使用される関数
- 関連コマンド: Get-DbatoolsConfig, Set-DbatoolsConfig
- "Mandatory"/"Optional"変換はswitchパラメータ解析問題を回避するため

---

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

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

### 推奨読解順序

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

本機能は設定の生の値を返す。オブジェクトではなく値そのもの。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbatoolsConfigValue.ps1 | `public/Get-DbatoolsConfigValue.ps1` | 21-32行目の.OUTPUTSセクションで出力仕様を確認 |

**読解のコツ**: 戻り値がobject型であり、設定により異なる型が返される点を理解する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbatoolsConfigValue.ps1 | `public/Get-DbatoolsConfigValue.ps1` | 55-63行目のパラメータ定義 |

**主要処理フロー**:
1. **55行目**: SuppressMessageAttributeでPSScriptAnalyzer警告抑制
2. **57-62行目**: パラメータ定義（FullName必須、Fallbackオプション、NotNullスイッチ）
3. **58行目**: Aliasで"Name"も使用可能

#### Step 3: コア処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbatoolsConfigValue.ps1 | `public/Get-DbatoolsConfigValue.ps1` | 64-81行目のメイン処理 |

**主要処理フロー**:
- **65行目**: FullNameを小文字に変換
- **67-68行目**: ConfigurationHostから値を取得
- **69-75行目**: null判定とFallback/特殊文字列変換
- **77-81行目**: NotNullチェックと出力

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

```
Get-DbatoolsConfigValue
    │
    ├─ $FullName.ToLowerInvariant()
    │      └─ キー名の正規化
    │
    ├─ ConfigurationHost.Configurations[$FullName].Value
    │      └─ 設定値の取得
    │
    ├─ [null判定]
    │      ├─ Fallback値適用
    │      └─ Mandatory/Optional変換
    │
    └─ Stop-Function (NotNull && null時)
           └─ エラーハンドリング
```

### データフロー図

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

FullName ───▶ ToLowerInvariant
                    │
                    ▼
            ConfigurationHost.Configurations
                    │
                    ▼
            ┌───────┴───────┐
            │               │
         値あり           値null
            │               │
            ▼               ▼
    Mandatory/Optional   Fallback適用
       変換チェック          │
            │               │
            └───────┬───────┘
                    │
                    ▼
              NotNullチェック
                    │
            ┌───────┴───────┐
         OK │               │ NG && NotNull
            ▼               ▼
          値返却        Stop-Function
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbatoolsConfigValue.ps1 | `public/Get-DbatoolsConfigValue.ps1` | ソース | メイン機能実装 |
| Get-DbatoolsConfig.ps1 | `public/Get-DbatoolsConfig.ps1` | ソース | 設定オブジェクト取得（関連コマンド） |
| Set-DbatoolsConfig.ps1 | `public/Set-DbatoolsConfig.ps1` | ソース | 設定変更（関連コマンド） |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラー処理ユーティリティ |
