# 機能設計書 161-Import-DbatoolsConfig

## 概要

本ドキュメントは、dbatools PowerShellモジュールの`Import-DbatoolsConfig`コマンドレットに関する機能設計書である。このコマンドは、JSONファイルやデフォルトのモジュールパスからdbatools構成設定をインポートする機能を提供する。

### 本機能の処理概要

Import-DbatoolsConfigは、dbatools構成設定をJSONファイル、WebURL、またはモジュール固有のデフォルト設定パスから読み込み、現在のセッションに適用する機能を提供する。これにより、保存済みのdbatools設定の復元、チーム間での標準設定の共有、複数サーバーへの構成ベースラインの適用が可能となる。

**業務上の目的・背景**：
大規模なSQL Server環境を管理するDBAチームでは、dbatools構成の一貫性が運用効率に直結する。このコマンドにより、ログ設定、接続デフォルト、セキュリティポリシーなどの構成をチーム間で統一でき、新しい環境のセットアップ時間を大幅に短縮できる。また、構成のバージョン管理や監査対応にも活用できる。

**機能の利用シーン**：
- 新規チームメンバーの環境セットアップ時に標準設定を適用
- 複数サーバー環境で一貫した接続設定を維持
- バックアップからの構成復元
- CI/CDパイプラインでの自動化された構成適用
- Web上でホストされた共有構成のダウンロードと適用

**主要な処理内容**：
1. 入力ソースの判定（ファイルパス、WebURL、JSON文字列、モジュール名）
2. 構成データの読み込みとパース
3. IncludeFilter/ExcludeFilterによる構成項目のフィルタリング
4. Peekモードによるプレビューまたは実際の設定適用
5. Set-DbatoolsConfigを使用した構成値の設定

**関連システム・外部連携**：
- dbatools内部構成システム（Dataplat.Dbatools.Configuration）
- Read-DbatoolsConfigFile（構成ファイル読み込み）
- Read-DbatoolsConfigPersisted（永続化構成読み込み）
- Set-DbatoolsConfig（構成値設定）

**権限による制御**：
構成ファイルのスコープ（FileUserLocal、FileUserShared、FileSystem）により、ユーザー固有設定とシステム全体設定を区別して管理できる。ユーザー設定はシステム設定を上書きする。

## 関連画面

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

## 機能種別

データ連携 / 構成管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Path | string[] | Yes (ParameterSet: Path) | JSONファイルパス、WebURL、またはJSON文字列 | パイプライン入力対応 |
| ModuleName | string | Yes (ParameterSet: ModuleName) | インポートするモジュール名 | - |
| ModuleVersion | int | No | モジュール構成スキーマのバージョン（デフォルト: 1） | - |
| Scope | ConfigScope | No | 構成検索スコープ（デフォルト: FileUserLocal, FileUserShared, FileSystem） | ConfigScope列挙型 |
| IncludeFilter | string[] | No | インポートする構成項目のワイルドカードパターン | -like演算子対応 |
| ExcludeFilter | string[] | No | 除外する構成項目のワイルドカードパターン | -like演算子対応 |
| Peek | switch | No | 適用せずにプレビューのみ表示 | - |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

- ローカルファイルシステム上のJSONファイル
- HTTP/HTTPS経由のWebリソース
- JSON形式の文字列（直接入力）
- dbatools永続化構成ストレージ（モジュール名指定時）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| FullName | string | 構成項目の完全修飾名（-Peek使用時） |
| Value | object | 構成値（-Peek使用時） |
| Type | string | 構成値のデータ型（-Peek使用時） |
| KeepPersisted | boolean | セッション間で永続化するかどうか（-Peek使用時） |

### 出力先

- Peekモード: コンソール（構成要素オブジェクトの配列）
- 通常モード: dbatools内部構成ストレージ（出力なし）

## 処理フロー

### 処理シーケンス

```
1. 入力パラメータの検証
   └─ ParameterSetの判定（Path or ModuleName）
2. 入力ソースからのデータ読み込み
   ├─ Pathの場合:
   │   ├─ http*で始まる場合: Read-DbatoolsConfigFile -Weblink
   │   ├─ ファイルパスとして解決可能な場合: Read-DbatoolsConfigFile -Path
   │   └─ それ以外: Read-DbatoolsConfigFile -RawJson
   └─ ModuleNameの場合: Read-DbatoolsConfigPersisted
3. 各構成要素の処理
   ├─ ExcludeFilterによる除外判定
   ├─ IncludeFilterによる包含判定
   └─ Peekモードの判定
       ├─ Peek: オブジェクトを出力
       └─ 通常: Set-DbatoolsConfigで設定適用
4. エラーハンドリング
   └─ Stop-Functionによる継続可能なエラー処理
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{ParameterSet判定}
    B -->|Path| C[Pathをループ処理]
    B -->|ModuleName| D[Read-DbatoolsConfigPersisted]

    C --> E{URLか?}
    E -->|Yes| F[Read-DbatoolsConfigFile -Weblink]
    E -->|No| G{ファイルパスか?}
    G -->|Yes| H[Read-DbatoolsConfigFile -Path]
    G -->|No| I[Read-DbatoolsConfigFile -RawJson]

    F --> J[構成要素のループ処理]
    H --> J
    I --> J
    D --> K[構成値のループ処理]

    J --> L{ExcludeFilter該当?}
    L -->|Yes| J
    L -->|No| M{IncludeFilter設定?}
    M -->|Yes| N{IncludeFilter該当?}
    N -->|No| J
    N -->|Yes| O{Peekモード?}
    M -->|No| O
    O -->|Yes| P[オブジェクト出力]
    O -->|No| Q[Set-DbatoolsConfig]
    P --> J
    Q --> J

    K --> R{KeepPersisted?}
    R -->|No| S[Set-DbatoolsConfig -Value]
    R -->|Yes| T[Set-DbatoolsConfig + ConvertFromPersistedValue]
    S --> K
    T --> K

    J --> U[終了]
    K --> U
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ExcludeFilter優先 | ExcludeFilterはIncludeFilterより先に適用される | 両フィルタが指定された場合 |
| BR-002 | ユーザー設定優先 | 同じ構成項目が複数スコープに存在する場合、ユーザー設定がシステム設定を上書き | ModuleName使用時 |
| BR-003 | 永続化保持 | KeepPersistedフラグがtrueの場合、永続化された値として設定 | 構成要素にKeepPersistedが設定されている場合 |

### 計算ロジック

該当なし

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

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

該当なし（ファイルシステム操作のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ImportError | ファイルの読み込み失敗 | Stop-Functionで継続、EnableExceptionで例外throw |
| - | SetError | 構成値の設定失敗 | Stop-Functionで継続、エラーログ出力 |

### リトライ仕様

リトライ機能なし（エラー発生時は次の項目に継続）

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

該当なし（各構成項目は個別に処理）

## パフォーマンス要件

特に定義されていない。構成項目数に比例した処理時間が発生する。

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

- 資格情報を含む構成ファイルの取り扱いに注意が必要
- Webからの構成読み込み時はHTTPS推奨
- ExcludeFilterを使用して機密設定を除外可能

## 備考

- Export-DbatoolsConfigと対で使用することで、構成のバックアップと復元が可能
- 一般的なモジュール名には'message'（ログ設定）、'sql'（接続デフォルト）などがある

---

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

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

### 推奨読解順序

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

dbatools構成システムの基本構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ConfigScope | `Dataplat.Dbatools.Configuration.ConfigScope` | 構成スコープの列挙型定義 |

**読解のコツ**: ConfigScopeはFileUserLocal、FileUserShared、FileSystemの3つのスコープを持ち、ビットフラグとして組み合わせ可能。

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

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

**主要処理フロー**:
1. **86-117行目**: パラメータ定義（Path、ModuleName等の2つのパラメータセット）
2. **119-121行目**: beginブロック（デバッグメッセージ出力）
3. **122-170行目**: processブロック（Pathパラメータセットの処理）
4. **172-179行目**: processブロック（ModuleNameパラメータセットの処理）

#### Step 3: 構成ファイル読み込み処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Read-DbatoolsConfigFile | 内部関数 | JSON構成ファイルの読み込みロジック |
| 3-2 | Read-DbatoolsConfigPersisted | 内部関数 | 永続化構成の読み込みロジック |

**主要処理フロー**:
- **126-133行目**: 入力ソースの種別判定（URL、ファイル、JSON文字列）
- **136-143行目**: ExcludeFilterによる除外処理
- **145-157行目**: IncludeFilterによる包含処理
- **159-167行目**: PeekモードまたはSet-DbatoolsConfig呼び出し

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

```
Import-DbatoolsConfig
    │
    ├─ Read-DbatoolsConfigFile (Pathパラメータセット)
    │      ├─ -Weblink (URL入力時)
    │      ├─ -Path (ファイルパス入力時)
    │      └─ -RawJson (JSON文字列入力時)
    │
    ├─ Read-DbatoolsConfigPersisted (ModuleNameパラメータセット)
    │      └─ ConfigurationHost.ConvertFromPersistedValue
    │
    └─ Set-DbatoolsConfig (構成適用時)
           ├─ -FullName + -Value (通常)
           └─ -FullName + -PersistedValue + -PersistedType (永続化)
```

### データフロー図

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

JSONファイル ──────┐
                   │
WebURL ───────────┼──▶ Read-DbatoolsConfigFile ──┐
                   │                              │
JSON文字列 ────────┘                              │
                                                  ├──▶ フィルタリング ──▶ Set-DbatoolsConfig ──▶ dbatools構成ストレージ
モジュール名 ──────────▶ Read-DbatoolsConfigPersisted ─┘                     │
                                                                           └──▶ コンソール出力 (Peek時)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Import-DbatoolsConfig.ps1 | `public/Import-DbatoolsConfig.ps1` | ソース | メイン関数定義 |
| Export-DbatoolsConfig.ps1 | `public/Export-DbatoolsConfig.ps1` | ソース | 対となるエクスポート機能 |
| Set-DbatoolsConfig.ps1 | `public/Set-DbatoolsConfig.ps1` | ソース | 構成値の設定 |
| Get-DbatoolsConfig.ps1 | `public/Get-DbatoolsConfig.ps1` | ソース | 構成値の取得 |
