# 画面設計書 271-設定管理

## 概要

本ドキュメントは、dbatoolsモジュールの設定管理機能（Get-DbatoolsConfig、Export-DbatoolsConfig、Import-DbatoolsConfig、Register-DbatoolsConfig、Reset-DbatoolsConfig、Unregister-DbatoolsConfig）に関する画面設計書です。

### 本画面の処理概要

dbatoolsモジュールの動作を制御する設定項目の取得、変更、エクスポート、インポート、登録、リセット、登録解除を行うPowerShellコマンド群を提供します。

**業務上の目的・背景**：SQL Server管理業務において、dbatoolsモジュールの動作設定（接続タイムアウト、デフォルトパス、メール設定など）を柔軟に変更・管理する必要があります。また、設定を永続化して複数のPowerShellセッション間で共有したり、他のマシンに設定を移行したりする要件に対応します。組織のセキュリティポリシーや運用ルールに合わせてdbatoolsの動作をカスタマイズすることで、効率的なデータベース管理を実現します。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行します。
- `Get-DbatoolsConfig` - 設定の取得
- `Export-DbatoolsConfig` - 設定のエクスポート
- `Import-DbatoolsConfig` - 設定のインポート
- `Register-DbatoolsConfig` - 設定の永続化
- `Reset-DbatoolsConfig` - 設定のリセット
- `Unregister-DbatoolsConfig` - 設定の登録解除

**主要な操作・処理内容**：
1. 設定項目の一覧取得および特定設定の検索（Get-DbatoolsConfig）
2. 設定をJSONファイルにエクスポート（Export-DbatoolsConfig）
3. JSONファイルまたはURLから設定をインポート（Import-DbatoolsConfig）
4. 設定をレジストリまたはファイルに永続化（Register-DbatoolsConfig）
5. 設定をデフォルト値にリセット（Reset-DbatoolsConfig）
6. 永続化された設定の登録を解除（Unregister-DbatoolsConfig）

**画面遷移**：CLIベースのため画面遷移は存在しません。パイプラインで他のdbatoolsコマンドと連携可能です。

**権限による表示制御**：SystemDefaultスコープでの設定登録には管理者権限が必要です。UserDefaultスコープはユーザー権限で操作可能です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 155 | Get-DbatoolsConfig | 主機能 | dbatools設定の取得 |
| 86 | Export-DbatoolsConfig | 補助機能 | dbatools設定のエクスポート |
| 161 | Import-DbatoolsConfig | 補助機能 | dbatools設定のインポート |
| 198 | Register-DbatoolsConfig | 補助機能 | dbatools設定の登録 |
| 211 | Reset-DbatoolsConfig | 補助機能 | dbatools設定のリセット |
| 255 | Unregister-DbatoolsConfig | 補助機能 | dbatools設定の登録解除 |

## 画面種別

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

## URL/ルーティング

PowerShellコマンドレット
- `Get-DbatoolsConfig`
- `Export-DbatoolsConfig`
- `Import-DbatoolsConfig`
- `Register-DbatoolsConfig`
- `Reset-DbatoolsConfig`
- `Unregister-DbatoolsConfig`

## 入出力項目

### Get-DbatoolsConfig

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| FullName | string | No | 完全な設定キー名（Module.Name形式） |
| Name | string | No | 設定名（デフォルト: "*"） |
| Module | string | No | モジュール名（デフォルト: "*"） |
| Force | switch | No | 隠し設定も表示 |

### Export-DbatoolsConfig

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| FullName | string | Yes* | 完全な設定名 |
| Module | string | Yes* | モジュール名 |
| Name | string | No | 設定名パターン |
| Config | Config[] | Yes* | 設定オブジェクト |
| ModuleName | string | Yes* | モジュール名 |
| OutPath | string | Yes | 出力ファイルパス |
| SkipUnchanged | switch | No | 未変更設定を除外 |

### Import-DbatoolsConfig

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| Path | string[] | Yes* | インポートするファイルパス/URL |
| ModuleName | string | Yes* | モジュール名 |
| ModuleVersion | int | No | モジュールバージョン |
| Scope | ConfigScope | No | スコープ |
| IncludeFilter | string[] | No | 含めるフィルター |
| ExcludeFilter | string[] | No | 除外フィルター |
| Peek | switch | No | プレビューモード |

### Register-DbatoolsConfig

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| Config | Config[] | No | 設定オブジェクト |
| FullName | string[] | No | 完全な設定名 |
| Module | string | Yes* | モジュール名 |
| Name | string | No | 設定名パターン |
| Scope | ConfigScope | No | スコープ（デフォルト: UserDefault） |

### Reset-DbatoolsConfig

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| ConfigurationItem | Config[] | No | 設定オブジェクト |
| FullName | string[] | No | 完全な設定名 |
| Module | string | Yes* | モジュール名 |
| Name | string | No | 設定名パターン |

### Unregister-DbatoolsConfig

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| ConfigurationItem | Config[] | No | 設定オブジェクト |
| FullName | string[] | No | 完全な設定名 |
| Module | string | Yes* | モジュール名 |
| Name | string | No | 設定名パターン |
| Scope | ConfigScope | No | スコープ |

## 表示項目

### Get-DbatoolsConfig出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Module | string | モジュール名 |
| Name | string | 設定名 |
| Value | object | 現在の値 |
| Description | string | 設定の説明 |
| Hidden | bool | 隠し設定フラグ |

## イベント仕様

### 1-設定取得

Get-DbatoolsConfigコマンド実行時、ConfigurationHostの静的コレクションから条件に合致する設定項目を取得し、Module名とName名でソートして出力します。

### 2-設定エクスポート

Export-DbatoolsConfigコマンド実行時、指定された設定項目をJSON形式に変換し、指定されたファイルパスに書き出します。

### 3-設定インポート

Import-DbatoolsConfigコマンド実行時、JSONファイル、URL、またはRaw JSON文字列から設定を読み込み、Set-DbatoolsConfigを呼び出して設定を適用します。

### 4-設定登録

Register-DbatoolsConfigコマンド実行時、設定をレジストリ（Windows）またはJSONファイル（クロスプラットフォーム）に永続化します。

### 5-設定リセット

Reset-DbatoolsConfigコマンド実行時、設定オブジェクトのResetValue()メソッドを呼び出してデフォルト値に戻します。

### 6-設定登録解除

Unregister-DbatoolsConfigコマンド実行時、レジストリまたはJSONファイルから永続化された設定を削除します。

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

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

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

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

## メッセージ仕様

| 種別 | メッセージ | 条件 |
|------|----------|------|
| Warning | Cannot register configurations on non-windows machines to registry | 非Windows環境でレジストリスコープを指定 |
| Warning | Cannot unregister configurations from registry on non-windows machines | 非Windows環境でレジストリからの登録解除を試行 |
| Error | Cannot export modulecache to registry | レジストリスコープでモジュールキャッシュをエクスポート |
| Error | Failed to export to file | ファイルエクスポート失敗 |
| Error | Failed to import {path} | インポート失敗 |
| Error | Invalid Input, cannot export {name}, type not supported | サポートされない型のエクスポート |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 存在しないパスの指定 | Stop-Functionでエラーメッセージを出力 |
| 権限不足 | レジストリ書き込み時にエラー |
| 無効なJSON | インポート時にエラーを出力して続行 |
| ポリシーで強制された設定のリセット | リセット不可 |

## 備考

- ConfigurationHostクラスは.NET側で実装されており、静的コレクションで設定を管理
- 設定値は「Module.Name」形式の完全修飾名で識別
- スコープには UserDefault、UserMandatory、SystemDefault、SystemMandatory、FileUserLocal、FileUserShared、FileSystem が存在
- 非Windows環境ではレジストリベースのスコープは使用不可

---

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

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

### 推奨読解順序

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

dbatoolsの設定システムはConfigurationHostクラスで管理されており、設定項目はConfigurationValue/Configオブジェクトとして表現されます。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbatoolsConfig.ps1 | `public/Get-DbatoolsConfig.ps1` | 出力される設定オブジェクト（Dataplat.Dbatools.Configuration.ConfigurationValue）の構造を理解 |

**読解のコツ**: ConfigurationHostクラスの静的プロパティConfigurationsがDictionary形式で設定を保持しています。

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

各コマンドのエントリーポイントを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbatoolsConfig.ps1 | `public/Get-DbatoolsConfig.ps1` | 設定取得のメインロジック |
| 2-2 | Export-DbatoolsConfig.ps1 | `public/Export-DbatoolsConfig.ps1` | エクスポートのパラメータセット処理 |
| 2-3 | Import-DbatoolsConfig.ps1 | `public/Import-DbatoolsConfig.ps1` | インポートのソース判別ロジック |

**主要処理フロー**:
1. **78-89行目（Get-DbatoolsConfig）**: ParameterSetNameによる分岐処理
2. **83行目**: ConfigurationHost.Configurationsからの取得とフィルタリング

#### Step 3: 設定永続化層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Register-DbatoolsConfig.ps1 | `public/Register-DbatoolsConfig.ps1` | スコープ別の永続化処理 |
| 3-2 | Unregister-DbatoolsConfig.ps1 | `public/Unregister-DbatoolsConfig.ps1` | 永続化設定の削除処理 |

**主要処理フロー**:
- **104-116行目（Register）**: 非Windowsマシンでのスコープ自動変換
- **144-175行目（Register）**: スコープ別のレジストリ/ファイル書き込み

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

```
Get-DbatoolsConfig
    │
    └─ [Dataplat.Dbatools.Configuration.ConfigurationHost]::Configurations
           └─ Where-Object (フィルタリング)
                 └─ Sort-Object Module, Name

Export-DbatoolsConfig
    │
    ├─ Get-DbatoolsConfig (設定取得)
    │
    └─ Write-DbatoolsConfigFile (内部関数)
           └─ ConvertTo-Json → Set-Content

Import-DbatoolsConfig
    │
    ├─ Read-DbatoolsConfigFile (内部関数)
    │      └─ Get-Content → ConvertFrom-Json
    │
    └─ Set-DbatoolsConfig (設定適用)

Register-DbatoolsConfig
    │
    ├─ Write-Config (内部関数)
    │      ├─ Ensure-RegistryPath
    │      └─ Set-ItemProperty (レジストリ)
    │
    └─ Write-DbatoolsConfigFile (ファイルベース)
```

### データフロー図

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

設定名/パターン ───────▶ ConfigurationHost.Configurations ───▶ ConfigurationValue[]
                             │
JSONファイル ──────────▶ Read-DbatoolsConfigFile ───────────▶ 設定適用
                             │
設定オブジェクト ──────▶ Write-DbatoolsConfigFile ──────────▶ JSONファイル
                             │
設定オブジェクト ──────▶ Write-Config ──────────────────────▶ レジストリ/ファイル
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbatoolsConfig.ps1 | `public/Get-DbatoolsConfig.ps1` | ソース | 設定取得コマンド |
| Export-DbatoolsConfig.ps1 | `public/Export-DbatoolsConfig.ps1` | ソース | 設定エクスポートコマンド |
| Import-DbatoolsConfig.ps1 | `public/Import-DbatoolsConfig.ps1` | ソース | 設定インポートコマンド |
| Register-DbatoolsConfig.ps1 | `public/Register-DbatoolsConfig.ps1` | ソース | 設定登録コマンド |
| Reset-DbatoolsConfig.ps1 | `public/Reset-DbatoolsConfig.ps1` | ソース | 設定リセットコマンド |
| Unregister-DbatoolsConfig.ps1 | `public/Unregister-DbatoolsConfig.ps1` | ソース | 設定登録解除コマンド |
