# 画面設計書 272-設定値取得

## 概要

本ドキュメントは、dbatoolsモジュールの設定値取得機能（Get-DbatoolsConfigValue）に関する画面設計書です。

### 本画面の処理概要

dbatoolsの特定の設定項目の実際の値を直接取得するPowerShellコマンドを提供します。Get-DbatoolsConfigと異なり、設定オブジェクト全体ではなく値のみを返すため、スクリプト内での直接的な値参照に適しています。

**業務上の目的・背景**：dbatools内部の関数やユーザースクリプトにおいて、設定値を効率的に参照する必要があります。接続タイムアウト、デフォルトパス、メールサーバー設定などの値を取得し、それに基づいた動的な処理を実現します。また、設定が未定義の場合のフォールバック値を指定することで、堅牢なスクリプト作成が可能になります。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから`Get-DbatoolsConfigValue`コマンドを実行します。

**主要な操作・処理内容**：
1. 完全修飾名（Module.Name形式）による設定値の取得
2. 設定が未定義の場合のフォールバック値の指定
3. null値を許可しない厳格モードでの取得

**画面遷移**：CLIベースのため画面遷移は存在しません。dbatools内部関数から頻繁に呼び出されます。

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 156 | Get-DbatoolsConfigValue | 主機能 | dbatools設定値の取得 |

## 画面種別

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

## URL/ルーティング

PowerShellコマンドレット
- `Get-DbatoolsConfigValue`

## 入出力項目

### Get-DbatoolsConfigValue

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| FullName | string | Yes | 完全な設定キー名（Module.Name形式） |
| Fallback | object | No | 設定が未定義の場合のデフォルト値 |
| NotNull | switch | No | null値を許可しない（エラーをスロー） |

## 表示項目

### Get-DbatoolsConfigValue出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| （戻り値） | object | 設定値そのもの（string, int, bool, datetime など設定に依存） |

## イベント仕様

### 1-設定値取得

Get-DbatoolsConfigValueコマンド実行時、ConfigurationHostの静的ディクショナリから指定された完全修飾名の設定を検索し、その値を返します。

**処理詳細**：
1. FullNameを小文字に変換して正規化
2. ConfigurationHost.Configurations[fullname].Valueを取得
3. 値がnullの場合、Fallback値を使用
4. 値が"Mandatory"の場合は$trueに、"Optional"の場合は$falseに変換（スイッチパラメータ互換性のため）
5. NotNullが指定されていて値がnullの場合、Stop-Functionでエラー

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

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| N/A | N/A | SELECT（メモリ内） | 設定値の読み取りのみ |

## メッセージ仕様

| 種別 | メッセージ | 条件 |
|------|----------|------|
| Error | No Configuration Value available for {Name} | NotNull指定時に値がnull |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 設定が存在しない（nullを返す） | Fallbackが指定されていれば返却、NotNullが指定されていればエラー |
| 不正な設定名 | ConfigurationHost.Configurationsに存在しない場合はnull返却 |

## 備考

- Get-DbatoolsConfigとの違い：本関数は設定オブジェクトではなく値のみを返す
- 主にdbatools内部関数で使用される
- "Mandatory"/"Optional"文字列の$true/$false変換はスイッチパラメータとの互換性確保のため
- Aliasとして`-Name`も使用可能（`-FullName`の別名）

---

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

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

### 推奨読解順序

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

設定値はConfigurationHostクラスのConfigurationsディクショナリに格納されており、各設定のValueプロパティが実際の設定値を保持しています。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbatoolsConfigValue.ps1 | `public/Get-DbatoolsConfigValue.ps1` | 戻り値の型（object）と特殊な文字列変換を理解 |

**読解のコツ**: 戻り値は設定によって異なる型（string, int, bool等）になります。型は設定定義時に決まります。

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

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

**主要処理フロー**:
1. **65行目**: FullNameを小文字に変換
2. **68行目**: ConfigurationHost.Configurations[fullname].Valueで値取得
3. **69-75行目**: null処理とMandatory/Optional変換
4. **77-80行目**: NotNullパラメータによるエラー処理

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbatoolsConfig.ps1 | `public/Get-DbatoolsConfig.ps1` | 設定オブジェクト全体を返すコマンドとの違い |
| 3-2 | Get-DbatoolsPath.ps1 | `public/Get-DbatoolsPath.ps1` | Get-DbatoolsConfigValueを呼び出す使用例 |

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

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

```
Get-DbatoolsConfigValue
    │
    └─ [Dataplat.Dbatools.Configuration.ConfigurationHost]::Configurations[$FullName]
           │
           └─ .Value プロパティ
                  │
                  ├─ null → $Fallback
                  │
                  ├─ "Mandatory" → $true
                  │
                  ├─ "Optional" → $false
                  │
                  └─ NotNull && null → Stop-Function
```

### データフロー図

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

FullName ──────────────▶ ConfigurationHost.Configurations ───▶ 設定値（object）
                              │
Fallback ──────────────▶ null判定 ──────────────────────────▶ フォールバック値
                              │
NotNull ───────────────▶ null検証 ──────────────────────────▶ エラー/値
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbatoolsConfigValue.ps1 | `public/Get-DbatoolsConfigValue.ps1` | ソース | 設定値取得コマンド |
| Get-DbatoolsConfig.ps1 | `public/Get-DbatoolsConfig.ps1` | ソース | 設定オブジェクト取得（関連） |
| Get-DbatoolsPath.ps1 | `public/Get-DbatoolsPath.ps1` | ソース | 本関数を使用する例 |
