# 機能設計書 198-Register-DbatoolsConfig

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける`Register-DbatoolsConfig`機能の設計仕様を記載する。この機能は、既存のdbatools設定オブジェクトをレジストリまたはファイルシステムに永続化する。

### 本機能の処理概要

**業務上の目的・背景**：dbatoolsモジュールには多数の設定項目（接続タイムアウト、SSL設定、メッセージ出力形式等）があり、これらの設定をPowerShellセッション間で永続化する必要がある。本機能は、設定をWindowsレジストリまたはJSON設定ファイルに保存し、次回以降のセッションで自動的に読み込まれるようにする。グループポリシー用のレジストリテンプレート生成にも使用可能。

**機能の利用シーン**：
- 接続設定の永続化（TrustServerCertificate等）
- メッセージ出力設定の固定
- 企業全体での設定強制（SystemMandatory）
- クロスプラットフォーム環境での設定共有

**主要な処理内容**：
1. Scopeに応じた保存先の決定
2. 非Windows環境でのファイルベースへのリダイレクト
3. 設定オブジェクトの検証（型サポート確認）
4. レジストリパスの存在確認・作成
5. Set-ItemPropertyで設定値を書き込み
6. ファイルベースの場合はWrite-DbatoolsConfigFileで出力

**関連システム・外部連携**：Windowsレジストリ、ファイルシステム（JSON設定ファイル）。

**権限による制御**：SystemDefault/SystemMandatoryスコープは管理者権限が必要。UserDefaultはユーザー権限で書き込み可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 271 | 設定管理 | 補助機能 | dbatools設定の登録 |

## 機能種別

設定管理 / 永続化

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Config | Config[] | No | 設定オブジェクト（パイプライン入力可） | ParameterSetName: Default |
| FullName | string[] | No | 設定の完全名（パイプライン入力可） | ParameterSetName: Default |
| Module | string | No | モジュール名 | ParameterSetName: Name, Mandatory |
| Name | string | No | 設定名（ワイルドカード可、デフォルト: *） | ParameterSetName: Name |
| Scope | ConfigScope | No | 保存スコープ（デフォルト: UserDefault） | - |
| EnableException | switch | No | 例外をスローするかどうか | - |

### Scopeの値

| 値 | 説明 | 保存先 |
|---|------|-------|
| UserDefault | ユーザーデフォルト | HKCU:\SOFTWARE\Microsoft\WindowsPowerShell\dbatools\Config |
| UserMandatory | ユーザー強制 | HKCU:\SOFTWARE\Microsoft\WindowsPowerShell\dbatools\Config\Enforced |
| SystemDefault | システムデフォルト | HKLM:\SOFTWARE\Microsoft\WindowsPowerShell\dbatools\Config |
| SystemMandatory | システム強制 | HKLM:\SOFTWARE\Microsoft\WindowsPowerShell\dbatools\Config\Enforced |
| FileUserLocal | ファイル（ユーザーローカル） | JSONファイル |
| FileUserShared | ファイル（ユーザー共有） | JSONファイル |
| FileSystem | ファイル（システム） | JSONファイル |

### 入力データソース

- パラメータ入力: Config、FullName、Module、Name
- パイプライン入力: Get-DbatoolsConfigから

## 出力仕様

### 出力データ

本機能は出力を返さない。設定はレジストリまたはファイルシステムに永続化される。

### 出力先

- Windowsレジストリ（Windows環境、Scope 1-8）
- JSONファイル（クロスプラットフォーム、Scope 16-64）

## 処理フロー

### 処理シーケンス

```
1. beginブロック
   ├─ 非Windows環境でのレジストリスコープ検出→エラー
   ├─ 非Windows環境でのUserDefault→FileUserLocalリダイレクト
   ├─ 非Windows環境でのSystemDefault→FileSystemリダイレクト
   ├─ ParameterSetName取得
   ├─ Write-Configヘルパー関数定義
   └─ Ensure-RegistryPathヘルパー関数定義
2. processブロック
   ├─ レジストリベース処理（Scope AND 15）
   │   ├─ Default ParameterSet
   │   │   ├─ Configオブジェクト処理
   │   │   └─ FullName文字列処理
   │   └─ Name ParameterSet
   │       └─ Module/Nameでフィルタして処理
   └─ ファイルベース処理（それ以外）
       ├─ configurationItemsに追加
       └─ endブロックで一括出力
3. endブロック
   ├─ FileUserLocal（Scope AND 16）
   ├─ FileUserShared（Scope AND 32）
   └─ FileSystem（Scope AND 64）
       └─ Write-DbatoolsConfigFile
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{非Windows?}
    B -->|Yes| C{レジストリスコープ?}
    C -->|Yes| D[Stop-Function エラー]
    C -->|No| E[スコープリダイレクト]
    B -->|No| F{Scope AND 15?}
    E --> F
    F -->|Yes| G[レジストリベース処理]
    F -->|No| H[ファイルベース処理]
    G --> I{Default ParameterSet?}
    I -->|Yes| J[Config/FullName処理]
    I -->|No| K[Module/Name処理]
    J --> L[Write-Config]
    K --> L
    H --> M[configurationItemsに追加]
    M --> N[endブロック]
    N --> O[Write-DbatoolsConfigFile]
    L --> P[終了]
    O --> P
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 非Windows制限 | 非WindowsではレジストリスコープをFileにリダイレクト | 非Windows環境 |
| BR-002 | 型サポート | サポートされない型の設定は登録不可 | RegistryData = "<type not supported>" |
| BR-003 | スコープビット演算 | スコープはビットフラグで判定 | 常時 |
| BR-004 | パス自動作成 | レジストリパスが存在しない場合は自動作成 | レジストリベース |

### スコープビット定義

| スコープ | ビット値 |
|---------|---------|
| UserDefault | 1 |
| UserMandatory | 2 |
| SystemDefault | 4 |
| SystemMandatory | 8 |
| FileUserLocal | 16 |
| FileUserShared | 32 |
| FileSystem | 64 |

### 計算ロジック

ビット演算でスコープを判定:
- `$Scope -band 15`: レジストリベース判定
- `$Scope -band 16`: FileUserLocal判定
- `$Scope -band 32`: FileUserShared判定
- `$Scope -band 64`: FileSystem判定

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

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

データベース操作はない。

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| NotSupported | Stop-Function | 非Windowsでレジストリスコープ | ファイルベーススコープを使用 |
| InvalidArgument | Stop-Function | サポートされない型 | 型を確認して修正 |
| - | Stop-Function | 設定エクスポート失敗 | 権限を確認 |

### リトライ仕様

本機能にリトライ機能はない。

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

レジストリ/ファイル操作のため、データベーストランザクションは関与しない。

## パフォーマンス要件

特になし。設定の永続化は軽量な操作。

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

- SystemDefault/SystemMandatoryには管理者権限が必要
- 設定値には機密情報を含めないことを推奨
- レジストリ権限に依存した保護

## 備考

- Get-DbatoolsConfigで設定を取得し、パイプでRegister-DbatoolsConfigに渡すのが一般的な使用パターン
- Set-DbatoolsConfig -PassThruと組み合わせて設定と登録を一度に行うことも可能
- ファイルベースの設定はpsf_config.jsonに保存される

---

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

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

### 推奨読解順序

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

Dataplat.Dbatools.Configuration.Config型を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Register-DbatoolsConfig.ps1 | `public/Register-DbatoolsConfig.ps1` | パラメータ定義（81-101行目） |

**読解のコツ**: ConfigScopeはビットフラグ列挙型で、複数のスコープを組み合わせることが可能。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Register-DbatoolsConfig.ps1 | `public/Register-DbatoolsConfig.ps1` | 関数定義とパラメータ構造 |

**主要処理フロー**:
1. **79-101行目**: param()ブロック
2. **103-117行目**: 非Windows環境チェックとリダイレクト
3. **120-174行目**: Write-Configヘルパー関数
4. **176-187行目**: Ensure-RegistryPathヘルパー関数
5. **192-239行目**: メイン処理ロジック
6. **241-254行目**: ファイルベース出力

#### Step 3: Write-Configヘルパー関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Register-DbatoolsConfig.ps1 | `public/Register-DbatoolsConfig.ps1` | レジストリ書き込みロジック |

**主要処理フロー**:
- **136-139行目**: 型サポートチェック
- **143-148行目**: UserDefault書き込み（ビット1）
- **150-155行目**: UserMandatory書き込み（ビット2）
- **157-162行目**: SystemDefault書き込み（ビット4）
- **164-169行目**: SystemMandatory書き込み（ビット8）

#### Step 4: ファイルベース処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Register-DbatoolsConfig.ps1 | `public/Register-DbatoolsConfig.ps1` | ファイル出力ロジック |

**主要処理フロー**:
- **219-238行目**: configurationItemsへの追加
- **245-253行目**: Write-DbatoolsConfigFile呼び出し

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

```
Register-DbatoolsConfig
    │
    ├─ Write-Config (内部関数)
    │      ├─ Ensure-RegistryPath (内部関数)
    │      │      └─ New-Item (レジストリパス作成)
    │      └─ Set-ItemProperty (レジストリ書き込み)
    │
    ├─ ConfigurationHost.Configurations (静的プロパティ)
    │      └─ 設定オブジェクト取得
    │
    └─ Write-DbatoolsConfigFile
           └─ JSONファイル出力
```

### データフロー図

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

Config (パイプライン) ─────┐
    または                 │
FullName ──────────────────┤
    または                 │
Module + Name ─────────────┼──▶ Register-DbatoolsConfig
                           │           │
Scope ─────────────────────┘           ├─ スコープ判定
                                       │     │
                                       │     ├─ レジストリベース（1-8）
                                       │     │     └─ Write-Config
                                       │     │           └─ Set-ItemProperty
                                       │     │
                                       │     └─ ファイルベース（16-64）
                                       │           └─ Write-DbatoolsConfigFile
                                       │
                                       ▼
                              レジストリ または JSONファイル
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Register-DbatoolsConfig.ps1 | `public/Register-DbatoolsConfig.ps1` | ソース | メイン関数定義 |
| Get-DbatoolsConfig.ps1 | `public/Get-DbatoolsConfig.ps1` | ソース | 設定取得（パイプライン元） |
| Set-DbatoolsConfig.ps1 | `public/Set-DbatoolsConfig.ps1` | ソース | 設定変更（-PassThru連携） |
| Write-DbatoolsConfigFile.ps1 | `private/functions/Write-DbatoolsConfigFile.ps1` | ソース | JSON出力 |
