# 機能設計書 86-Export-DbatoolsConfig

## 概要

本ドキュメントは、dbatools PowerShellモジュールのExport-DbatoolsConfig関数の機能設計を定義する。この関数は、dbatoolsモジュールの設定をJSONファイルにエクスポートし、バックアップや他のマシンへの移行を可能にする機能を提供する。

### 本機能の処理概要

Export-DbatoolsConfig は、dbatoolsモジュールの設定をJSON形式でファイルにエクスポートするコマンドレットである。接続タイムアウト、デフォルトパス、メッセージング設定など、デフォルト値から変更された設定を保存・移行できる。

**業務上の目的・背景**：dbatoolsモジュールはカスタマイズ可能な多数の設定を持っており、これらの設定を複数のマシンで一貫して使用したい場合や、設定のバックアップを取っておきたい場合がある。本機能は、現在の設定をJSON形式で保存し、Import-DbatoolsConfigで別のマシンや新しいセッションに復元することを可能にする。

**機能の利用シーン**：
- 複数の管理用ワークステーション間でのdbatools設定の同期
- dbatools設定変更前のバックアップ作成
- チーム内での標準設定の配布
- CI/CDパイプラインでの一貫した設定適用
- モジュール更新前の設定保存

**主要な処理内容**：
1. 設定項目の取得（FullName、Module、Config経由）
2. 変更された設定のフィルタリング（SkipUnchanged使用時）
3. JSON形式での設定ファイル書き込み
4. モジュールエクスポート時の定義済みスコープへの保存

**関連システム・外部連携**：
- dbatools設定システム（Dataplat.Dbatools.Configuration）
- PowerShellの設定管理機能
- ファイルシステムへのJSON出力

**権限による制御**：
- 出力先ディレクトリへの書き込み権限が必要
- システムスコープへの書き込みには管理者権限が必要な場合がある

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 271 | 設定管理 | 補助機能 | dbatools設定のエクスポート |

## 機能種別

設定管理 / エクスポート

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| FullName | string | Yes (FullNameセット) | 完全な設定名 | 有効な設定名 |
| Module | string | Yes (Moduleセット) | モジュール名でフィルター | 有効なモジュール名 |
| Name | string | No | Module内の設定名パターン | ワイルドカード対応 |
| Config | Dataplat.Dbatools.Configuration.Config[] | Yes (Configセット) | 設定オブジェクト | パイプライン入力対応 |
| ModuleName | string | Yes (ModuleNameセット) | モジュール固有エクスポート用 | 有効なモジュール名 |
| ModuleVersion | int | No | モジュールバージョン番号 | デフォルト: 1 |
| Scope | ConfigScope | No | 保存先スコープ | FileUserLocal/FileUserShared/FileSystem |
| OutPath | string | Yes (Config/FullName/Moduleセット) | 出力ファイルパス | 有効なファイルパス |
| SkipUnchanged | switch | No | 未変更設定を除外 | - |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- パイプライン入力: Get-DbatoolsConfig の出力をConfigパラメータで受け取り
- 直接指定: FullName、Module、ModuleName パラメータで設定を指定

## 出力仕様

### 出力データ

本関数は出力を生成しない（Void）。設定はJSONファイルとして指定されたパスに書き込まれる。

### 出力先

- ファイルシステム: OutPath で指定されたパスにJSONファイル
- または: ModuleName 使用時は定義済みシステムパス

## 処理フロー

### 処理シーケンス

```
1. パラメータセットの判定
   ├─ FullName: 特定の設定名で取得
   ├─ Module: モジュール名でフィルター
   ├─ Config: パイプラインオブジェクト
   └─ ModuleName: モジュールエクスポート

2. 設定の取得
   ├─ Get-DbatoolsConfigで設定オブジェクト取得
   └─ SkipUnchanged時は未変更設定を除外

3. 設定の書き込み
   ├─ 通常: Write-DbatoolsConfigFileで指定パスに出力
   └─ ModuleName: スコープに応じた定義済みパスに出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> 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
    G --> H{SkipUnchanged?}
    H -->|Yes| I[Unchanged除外]
    H -->|No| J[Write-DbatoolsConfigFile]
    I --> J
    J --> K[終了]
    F -->|FileUserLocal| L[LocalPathに出力]
    F -->|FileUserShared| M[SharedPathに出力]
    F -->|FileSystem| N[SystemPathに出力]
    L --> K
    M --> K
    N --> K
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | レジストリスコープ禁止 | ModuleName使用時はファイルスコープのみ許可 | ModuleName使用時 |
| BR-002 | ModuleExportフラグ | ModuleName使用時はModuleExportフラグ付き設定のみ | ModuleName使用時 |
| BR-003 | 未変更フィルター | SkipUnchanged時はUnchanged=trueの設定を除外 | SkipUnchanged指定時 |
| BR-004 | スコープデフォルト | ModuleName使用時のデフォルトスコープはFileUserShared | Scope未指定時 |

### 計算ロジック

ModuleName使用時のファイルパス:
- FileUserLocal: `{path_FileUserLocal}/{modulename}-{version}.json`
- FileUserShared: `{path_FileUserShared}/{modulename}-{version}.json`
- FileSystem: `{path_FileSystem}/{modulename}-{version}.json`

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

本機能はデータベース操作を行わない。dbatools内部の設定システムとファイルシステムのみを使用する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| InvalidArgument | パラメータエラー | レジストリスコープ指定（ModuleName使用時） | ファイルスコープを使用 |
| WriteError | 書き込みエラー | 出力ファイルへの書き込み失敗 | パスと権限を確認 |

### リトライ仕様

自動リトライは実装されていない。エラー発生時はStop-Functionで処理を停止する。

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

ファイル書き込み操作はアトミックではない。書き込み中に中断された場合、ファイルは不完全な状態になる可能性がある。

## パフォーマンス要件

- 設定項目数に比例した処理時間
- 通常のdbatools設定では数秒以内に完了

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

- 設定ファイルには接続情報やパスが含まれる可能性がある
- システムスコープへの書き込みには管理者権限が必要
- 出力ファイルのアクセス制御を適切に設定する必要がある

## 備考

- インポートはImport-DbatoolsConfigを使用
- 現在の設定確認はGet-DbatoolsConfigを使用
- スコープは16進数のビットマスクで管理される（16=FileUserLocal、32=FileUserShared、64=FileSystem）

---

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

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

### 推奨読解順序

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

設定オブジェクトの構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Export-DbatoolsConfig.ps1 | `public/Export-DbatoolsConfig.ps1` | 90-92行目のConfig型定義を確認 |

**読解のコツ**: Dataplat.Dbatools.Configuration.Config型はdbatools内部で定義された設定オブジェクトで、Name、Value、Unchangedなどのプロパティを持つ。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 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. **105-109行目**: OutPathパラメータ（複数セットで使用）

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

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

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

**主要処理フロー**:
- **123-126行目**: レジストリスコープ（ビットマスク15以下）の拒否

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

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

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

**主要処理フロー**:
- **131行目**: パイプラインからのConfigオブジェクト収集
- **132行目**: FullNameでの設定取得
- **133行目**: Module/Nameでの設定取得

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

設定のJSON出力を確認する。

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

**主要処理フロー**:
- **140-145行目**: 通常パス（OutPath指定）でのWrite-DbatoolsConfigFile呼び出し
- **146-155行目**: ModuleName使用時のスコープ別出力

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

```
Export-DbatoolsConfig
    │
    ├─ Get-DbatoolsConfig
    │      └─ 設定オブジェクトの取得
    │
    └─ Write-DbatoolsConfigFile
           └─ JSON形式でのファイル書き込み
```

### データフロー図

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

FullName ─────┐
              │
Module/Name ──┼──▶ Get-DbatoolsConfig
              │           │
Config ───────┘           ▼
(パイプライン)      設定オブジェクト収集
                          │
                  ┌───────┴───────┐
                  │ SkipUnchanged?│
                  └───────┬───────┘
                     Yes──┤──No
                       │  │   │
              Unchanged除外│   │
                       │  │   │
                       └──┴───┘
                          │
                          ▼
               Write-DbatoolsConfigFile
                          │
                          ▼
                   JSONファイル ──────▶ ファイルシステム
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Export-DbatoolsConfig.ps1 | `public/Export-DbatoolsConfig.ps1` | ソース | メイン関数定義 |
| Import-DbatoolsConfig.ps1 | `public/Import-DbatoolsConfig.ps1` | ソース | 設定インポート（対になる機能） |
| Get-DbatoolsConfig.ps1 | `public/Get-DbatoolsConfig.ps1` | ソース | 設定取得 |
| Set-DbatoolsConfig.ps1 | `public/Set-DbatoolsConfig.ps1` | ソース | 設定変更 |
| Write-DbatoolsConfigFile.ps1 | `private/functions/Write-DbatoolsConfigFile.ps1` | ソース | JSON書き込み |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラーハンドリング関数 |
| Write-Message.ps1 | `private/functions/Write-Message.ps1` | ソース | メッセージ出力関数 |
