# 帳票設計書 21-Export-DbatoolsConfig

## 概要

本ドキュメントは、dbatools PowerShellモジュールの`Export-DbatoolsConfig`コマンドレットによる設定エクスポート機能の帳票設計を定義する。この機能は、dbatoolsモジュールの設定をJSON形式でファイルに出力し、バックアップや他のマシンへの移行を可能にする。

### 本帳票の処理概要

Export-DbatoolsConfigは、dbatoolsモジュールのカスタマイズされた設定値をJSON形式のファイルとして出力するコマンドレットである。接続タイムアウト、デフォルトパス、メッセージング設定などのモジュール設定を永続化し、異なる環境間での設定共有や災害復旧時の設定復元を可能にする。

**業務上の目的・背景**：データベース管理者は複数のワークステーションや異なる環境でdbatools を利用することが多い。これらの環境で一貫した動作を保証するためには、モジュール設定の統一管理が不可欠である。また、設定変更前のバックアップや、チーム内での標準設定の配布といったニーズにも対応する。本機能により、手動での設定再現作業を排除し、ヒューマンエラーを防止できる。

**帳票の利用シーン**：
- 新規ワークステーションへのdbatools環境構築時の設定移行
- dbatools更新前の現行設定のバックアップ
- チームメンバー間での標準化された設定の共有
- CI/CDパイプラインでの一貫した設定適用
- 災害復旧時の設定復元

**主要な出力内容**：
1. 設定項目の完全修飾名（FullName）とその値
2. 設定の型情報（Type）とバージョン情報
3. 永続化スタイル（Style）情報
4. シンプルエクスポート時のデータ値（Data）

**帳票の出力タイミング**：ユーザーがExport-DbatoolsConfigコマンドレットを実行し、出力先パスまたはモジュール名を指定したときに出力される。

**帳票の利用者**：データベース管理者（DBA）、システム管理者、DevOpsエンジニア、CI/CDパイプライン

## 帳票種別

設定エクスポートファイル（JSONフォーマット）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| N/A | PowerShellコンソール | N/A | Export-DbatoolsConfigコマンド実行 |
| 271 | 設定管理 | N/A | エクスポートボタン/コマンド |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | JSON |
| 用紙サイズ | N/A（電子ファイル） |
| 向き | N/A |
| ファイル名 | OutPath指定時：ユーザー指定、ModuleName使用時：`{modulename}-{version}.json` |
| 出力方法 | ファイルシステムへの書き込み |
| 文字コード | UTF-8 |

### JSON固有設定

| 項目 | 内容 |
|-----|------|
| インデント | PowerShell標準（ConvertTo-Json） |
| 既存ファイルマージ | -Replaceなし時はマージ、あり時は上書き |
| フォルダ自動作成 | 有 |

## 帳票レイアウト

### レイアウト概要

JSON配列形式で設定項目を出力する。各要素は設定項目の詳細情報を含むオブジェクトとして構成される。

```
[
  {
    "Version": 1,
    "FullName": "module.setting.name",
    "Value": "persisted-value",
    "Type": "type-name",
    "Style": "default"
  },
  ...
]
```

### JSON構造詳細

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | Version | 設定スキーマバージョン | 固定値：1 | 数値 |
| 2 | FullName | 設定の完全修飾名 | Config.FullName | 文字列 |
| 3 | Value | 永続化された設定値 | ConfigurationHost.ConvertToPersistedValue | 文字列 |
| 4 | Type | 設定値の型名 | ConfigurationHost.ConvertToPersistedValue | 文字列 |
| 5 | Style | エクスポートスタイル | 固定値："default" | 文字列 |
| 6 | Data | シンプルエクスポート時の値 | Config.Value（SimpleExport時） | 任意 |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| FullName | 完全修飾名による設定指定 | FullNameパラメータセット時 |
| Module/Name | モジュール名とワイルドカードによるフィルター | Moduleパラメータセット時 |
| Config | パイプライン入力による設定オブジェクト | Configパラメータセット時 |
| ModuleName | モジュール固有エクスポート対象 | ModuleNameパラメータセット時 |
| SkipUnchanged | 未変更設定の除外 | No（オプション） |
| ModuleExport | ModuleName使用時のフラグ条件 | ModuleName使用時に自動適用 |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| N/A | 設定名順 | Get-DbatoolsConfigの返却順 |

### 改ページ条件

N/A（JSONファイルのため改ページなし）

## データベース参照仕様

### 参照テーブル一覧

本機能はデータベースを参照しない。dbatools内部の設定システム（インメモリ）を使用する。

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| ConfigurationHost.Configurations | 設定値の保持 | N/A（インメモリ） |

### テーブル別参照項目詳細

#### ConfigurationHost.Configurations

| 参照項目（プロパティ名） | 帳票項目との対応 | 取得条件 | 備考 |
|-------------------|----------------|---------|------|
| FullName | FullName | パラメータセットに応じたフィルター | Module.Name形式 |
| Value | Value/Data | 全設定 | 型変換あり |
| Unchanged | 除外判定 | SkipUnchanged時 | true時は除外 |
| ModuleExport | 出力対象判定 | ModuleName使用時 | フラグ |
| SimpleExport | 出力形式判定 | 全設定 | Data/Value切替 |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| PersistedValue | ConfigurationHost.ConvertToPersistedValue(Value) | N/A | 型変換処理 |
| 出力ファイルパス（ModuleName） | Join-Path {scope_path} "{modulename}-{version}.json" | N/A | 小文字変換 |

### スコープビットマスク

| スコープ | ビット値 | パス変数 |
|---------|---------|---------|
| レジストリスコープ（禁止） | 1-15 | N/A |
| FileUserLocal | 16 | $script:path_FileUserLocal |
| FileUserShared | 32 | $script:path_FileUserShared |
| FileSystem | 64 | $script:path_FileSystem |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[Export-DbatoolsConfig実行] --> B{パラメータセット判定}
    B -->|FullName| C[Get-DbatoolsConfig -FullName]
    B -->|Module| D[Get-DbatoolsConfig -Module -Name]
    B -->|Config| E[パイプライン入力収集]
    B -->|ModuleName| F{スコープ検証}

    C --> G[items配列に追加]
    D --> G
    E --> G

    F -->|レジストリスコープ| H[Stop-Function: エラー]
    F -->|ファイルスコープ| I{スコープ別出力}

    G --> J{SkipUnchanged?}
    J -->|Yes| K[Unchanged除外フィルター]
    J -->|No| L[Write-DbatoolsConfigFile]
    K --> L

    I -->|FileUserLocal| M[LocalPathに出力]
    I -->|FileUserShared| N[SharedPathに出力]
    I -->|FileSystem| O[SystemPathに出力]

    L --> P[JSONファイル生成完了]
    M --> P
    N --> P
    O --> P
    H --> Q[処理中断]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| InvalidArgument | ModuleName使用時にレジストリスコープ指定 | Cannot export modulecache to registry! Please pick a file scope for your export destination | ファイルスコープ（FileUserLocal/FileUserShared/FileSystem）を使用 |
| WriteError | 出力ファイルへの書き込み失敗 | Failed to export to file | パスの存在確認と書き込み権限確認 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 通常100-500設定項目 |
| 目標出力時間 | 5秒以内 |
| 同時出力数上限 | N/A（単一プロセス） |

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

- 設定ファイルには接続文字列やパス情報が含まれる可能性があるため、適切なファイルアクセス制御が必要
- システムスコープ（FileSystem）への書き込みには管理者権限が必要な場合がある
- 出力ファイルには機密情報が含まれる可能性があるため、共有時には内容の確認を推奨
- レジストリスコープへのエクスポートは明示的に禁止されている

## 備考

- 設定のインポートにはImport-DbatoolsConfigを使用
- 現在の設定確認にはGet-DbatoolsConfigを使用
- 設定変更にはSet-DbatoolsConfigを使用
- Write-DbatoolsConfigFileは-Replaceなしでマージ動作、ありで完全置換
- JSONエンコーディングはUTF-8固定

---

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

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

### 推奨読解順序

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

まず、設定オブジェクトの型定義とプロパティを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Export-DbatoolsConfig.ps1 | `public/Export-DbatoolsConfig.ps1` | 90-92行目のConfigパラメータ型定義を確認 |
| 1-2 | Get-DbatoolsConfig.ps1 | `public/Get-DbatoolsConfig.ps1` | 78-89行目の設定取得ロジック |

**読解のコツ**: `Dataplat.Dbatools.Configuration.Config`型はdbatools内部で定義された設定オブジェクトで、FullName、Value、Unchanged、ModuleExport、SimpleExportなどのプロパティを持つ。ConfigurationHostは静的クラスとして設定を管理する。

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

4つのパラメータセットの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Export-DbatoolsConfig.ps1 | `public/Export-DbatoolsConfig.ps1` | 76-116行目のparam()ブロック |

**主要処理フロー**:
1. **77-80行目**: FullNameパラメータセット - 完全修飾名による単一設定指定
2. **82-88行目**: Moduleパラメータセット - モジュール名とワイルドカードフィルター
3. **90-92行目**: Configパラメータセット - パイプライン入力対応
4. **94-104行目**: ModuleNameパラメータセット - モジュール固有エクスポート
5. **106-109行目**: OutPathパラメータ - FullName/Module/Configセットで使用

#### Step 3: スコープ検証を理解する

ModuleName使用時のスコープ検証ロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Export-DbatoolsConfig.ps1 | `public/Export-DbatoolsConfig.ps1` | 118-127行目のbeginブロック |

**主要処理フロー**:
- **123行目**: ビットマスク15以下（レジストリスコープ）の検出
- **124-125行目**: Stop-Functionによるエラー処理とreturn

#### Step 4: 設定収集処理を理解する

パラメータセットに応じた設定取得を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Export-DbatoolsConfig.ps1 | `public/Export-DbatoolsConfig.ps1` | 128-136行目のprocessブロック |

**主要処理フロー**:
- **131行目**: ModuleName以外のケースでの処理分岐
- **132行目**: パイプラインからのConfigオブジェクト収集
- **133行目**: FullNameによるGet-DbatoolsConfig呼び出し
- **134行目**: Module/NameによるGet-DbatoolsConfig呼び出し

#### Step 5: ファイル出力処理を理解する

設定のJSON出力ロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | Export-DbatoolsConfig.ps1 | `public/Export-DbatoolsConfig.ps1` | 137-157行目のendブロック |
| 5-2 | Write-DbatoolsConfigFile.ps1 | `private/functions/configuration/Write-DbatoolsConfigFile.ps1` | 全体 |

**主要処理フロー**:
- **140-141行目**: 通常パス時のSkipUnchangedフィルターとWrite-DbatoolsConfigFile呼び出し
- **147-155行目**: ModuleName時のスコープ別ビットマスク判定と出力

#### Step 6: JSON書き込み処理を理解する

Write-DbatoolsConfigFileの内部処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 6-1 | Write-DbatoolsConfigFile.ps1 | `private/functions/configuration/Write-DbatoolsConfigFile.ps1` | 40-56行目のbeginブロック |
| 6-2 | Write-DbatoolsConfigFile.ps1 | `private/functions/configuration/Write-DbatoolsConfigFile.ps1` | 57-79行目のprocessブロック |
| 6-3 | Write-DbatoolsConfigFile.ps1 | `private/functions/configuration/Write-DbatoolsConfigFile.ps1` | 80-83行目のendブロック |

**主要処理フロー**:
- **42-46行目**: 親ディレクトリの自動作成
- **48-55行目**: 既存ファイルの読み込みとマージ準備（-Replaceなし時）
- **61-77行目**: 設定オブジェクトからJSONデータ構造への変換
- **65-74行目**: SimpleExport判定によるData/Value出力の切替
- **82行目**: ConvertTo-JsonとSet-ContentによるUTF-8出力

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

```
Export-DbatoolsConfig
    │
    ├─ Write-Message
    │      └─ デバッグメッセージ出力
    │
    ├─ Stop-Function (レジストリスコープエラー時)
    │      └─ エラー処理・中断
    │
    ├─ Test-FunctionInterrupt
    │      └─ 中断フラグ確認
    │
    ├─ Get-DbatoolsConfig (FullName/Module/ModuleNameパラメータセット時)
    │      └─ ConfigurationHost.Configurationsから設定取得
    │
    └─ Write-DbatoolsConfigFile
           │
           ├─ Split-Path
           │      └─ 親ディレクトリ取得
           │
           ├─ Test-Path / New-Item
           │      └─ ディレクトリ自動作成
           │
           ├─ Get-Content / ConvertFrom-Json (マージ時)
           │      └─ 既存設定の読み込み
           │
           ├─ ConfigurationHost.ConvertToPersistedValue
           │      └─ 設定値の永続化形式変換
           │
           └─ ConvertTo-Json / Set-Content
                  └─ JSONファイル出力（UTF-8）
```

### データフロー図

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

FullName ──────┐
               │
Module/Name ───┼──▶ Get-DbatoolsConfig ──▶ Config[]
               │           │
Config ────────┘           │
(パイプライン)              ▼
                    ┌─────────────────┐
                    │ パラメータセット │
                    │    判定         │
                    └────────┬────────┘
                             │
              ┌──────────────┼──────────────┐
              │              │              │
              ▼              ▼              ▼
        FullName/        ModuleName      Config
        Module                           パイプライン
              │              │              │
              └──────────────┼──────────────┘
                             │
                    ┌────────┴────────┐
                    │  SkipUnchanged  │
                    │    フィルター    │
                    └────────┬────────┘
                             │
                             ▼
              ┌──────────────────────────┐
              │  Write-DbatoolsConfigFile │
              │                          │
              │  ・既存ファイルマージ     │
              │  ・ConvertToPersistedValue│
              │  ・ConvertTo-Json        │
              └─────────────┬────────────┘
                            │
                            ▼
ModuleName ──▶ スコープ別   ├──▶ OutPath指定パス
               パス生成     │
                            ├──▶ path_FileUserLocal/{modulename}-{version}.json
                            ├──▶ path_FileUserShared/{modulename}-{version}.json
                            └──▶ path_FileSystem/{modulename}-{version}.json
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Export-DbatoolsConfig.ps1 | `public/Export-DbatoolsConfig.ps1` | ソース | メイン関数定義（158行） |
| Import-DbatoolsConfig.ps1 | `public/Import-DbatoolsConfig.ps1` | ソース | 設定インポート（対になる機能、184行） |
| Get-DbatoolsConfig.ps1 | `public/Get-DbatoolsConfig.ps1` | ソース | 設定取得（90行） |
| Set-DbatoolsConfig.ps1 | `public/Set-DbatoolsConfig.ps1` | ソース | 設定変更 |
| Write-DbatoolsConfigFile.ps1 | `private/functions/configuration/Write-DbatoolsConfigFile.ps1` | ソース | JSON書き込み処理（85行） |
| Read-DbatoolsConfigFile.ps1 | `private/functions/configuration/Read-DbatoolsConfigFile.ps1` | ソース | JSON読み込み処理（Import用） |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラーハンドリング関数 |
| Write-Message.ps1 | `private/functions/Write-Message.ps1` | ソース | メッセージ出力関数 |
| Export-DbatoolsConfig.Tests.ps1 | `tests/Export-DbatoolsConfig.Tests.ps1` | テスト | 単体テスト（33行） |
