# 機能設計書 442-Export-DbaReplServerSetting

## 概要

本ドキュメントは、SQL Serverレプリケーションのディストリビューターおよびパブリケーション構成を再作成するためのT-SQLスクリプトを生成するdbatools PowerShellコマンドレット `Export-DbaReplServerSetting` の機能設計を記述する。

### 本機能の処理概要

Export-DbaReplServerSettingは、SQL Serverレプリケーション設定をT-SQLスクリプトとしてエクスポートするコマンドレットである。

**業務上の目的・背景**：レプリケーション環境の災害復旧計画、環境移行、トポロジー文書化のために、現在のレプリケーション構成を再現可能なスクリプトとして保存する必要がある。この機能により、データベース管理者はレプリケーション設定のバックアップを取得し、異なるサーバーで同一の構成を再構築できる。

**機能の利用シーン**：
- 災害復旧計画の一環としてレプリケーション構成をスクリプト化する場面
- テスト環境から本番環境へレプリケーション設定を移行する場面
- レプリケーショントポロジーの変更前にバックアップを取得する場面
- 複数サーバーのレプリケーション構成を一括でドキュメント化する場面

**主要な処理内容**：
1. Add-ReplicationLibraryを呼び出してレプリケーションライブラリをロードする
2. 出力パスの妥当性を検証する（Test-ExportDirectory）
3. 各SqlInstanceに対してGet-DbaReplServerを呼び出しレプリケーションサーバーオブジェクトを取得
4. ReplicationServer.Script()メソッドを使用してT-SQLスクリプトを生成
5. sp_dropdistributorステートメントをスクリプトの先頭に追加
6. 指定されたファイルパスにスクリプトを出力（またはPassthru時はコンソールに出力）

**関連システム・外部連携**：
- SQL Server Replication Management Objects (RMO) を使用
- Microsoft.SqlServer.Replication.ScriptOptionsを使用してスクリプト生成オプションを制御

**権限による制御**：
- SQL Serverインスタンスへのアクセス権限が必要
- レプリケーション構成の読み取り権限が必要

## 関連画面

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

## 機能種別

データ連携 / スクリプト生成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | スクリプト生成対象のSQL Serverインスタンス | 有効なSQL Serverインスタンス名 |
| SqlCredential | PSCredential | No | 代替認証情報 | Get-Credentialで取得した有効な認証情報 |
| Path | string | No | スクリプトファイルを出力するディレクトリ（デフォルト: dbatools export path） | 有効なディレクトリパス |
| FilePath | string | No | 出力ファイルの完全パス（PathとFilenameを上書き） | 有効なファイルパス |
| ScriptOption | object[] | No | カスタムScriptOptionsフラグ | Microsoft.SqlServer.Replication.ScriptOptions |
| InputObject | object[] | No | Get-DbaReplServerからのパイプライン入力 | ReplicationServerオブジェクト |
| Encoding | string | No | 出力ファイルのエンコーディング（デフォルト: UTF8） | ASCII, BigEndianUnicode, Byte, String, Unicode, UTF7, UTF8, Unknown |
| Passthru | switch | No | スクリプトをコンソールに出力 | - |
| NoClobber | switch | No | 既存ファイルの上書きを防止 | - |
| Append | switch | No | 既存ファイルに追記 | - |
| EnableException | switch | No | 例外処理を有効化 | - |

### 入力データソース

PowerShellコマンドライン引数、パイプライン入力（InputObjectパラメータ）、Get-DbaReplServerの出力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (Passthru時) | System.String | 生成されたT-SQLスクリプト |
| (通常時) | なし | ファイルに直接出力 |

### 出力先

- Passthru指定時: PowerShellコンソール（System.String）
- 通常時: 指定されたファイルパス（.sqlファイル）

## 処理フロー

### 処理シーケンス

```
1. beginブロック
   └─ Add-ReplicationLibraryでライブラリをロード
   └─ Test-ExportDirectoryで出力パスを検証
2. processブロック
   └─ Test-FunctionInterruptで中断チェック
   └─ SqlInstanceからGet-DbaReplServerでInputObjectを取得
   └─ 各repserverに対してループ処理
       └─ Get-ExportFilePathでファイルパスを生成
       └─ ScriptOption未指定時はデフォルトオプションでScript()を実行
       └─ ScriptOption指定時は指定オプションでScript()を実行
       └─ Passthru時はコンソールに出力
       └─ 通常時はファイルに出力（sp_dropdistributorを先頭に追加）
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Add-ReplicationLibrary]
    B --> C[Test-ExportDirectory]
    C --> D{Test-FunctionInterrupt?}
    D -->|Yes| E[終了]
    D -->|No| F[SqlInstanceループ]
    F --> G[Get-DbaReplServer]
    G --> H[InputObjectループ]
    H --> I[Get-ExportFilePath]
    I --> J{ScriptOption指定?}
    J -->|No| K[デフォルトオプションでScript]
    J -->|Yes| L[指定オプションでScript]
    K --> M{Passthru?}
    L --> M
    M -->|Yes| N[コンソール出力]
    M -->|No| O[sp_dropdistributor追加]
    O --> P[ファイル出力]
    N --> Q{次のrepserver?}
    P --> Q
    Q -->|Yes| H
    Q -->|No| R{次のinstance?}
    R -->|Yes| F
    R -->|No| E
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | デフォルトスクリプトオプション | Creation, IncludeAll, EnableReplicationDB, IncludeInstallDistributorを組み合わせて使用 | ScriptOption未指定時 |
| BR-002 | クリーンアップステートメント | sp_dropdistributor @no_checks = 1, @ignore_distributor = 1を先頭に追加 | 常時 |
| BR-003 | デフォルトエンコーディング | UTF8を使用 | Encoding未指定時 |
| BR-004 | デフォルト出力パス | dbatools設定のPath.DbatoolsExportを使用 | Path未指定時 |

### 計算ロジック

デフォルトスクリプトオプションの組み合わせ：
```powershell
[Microsoft.SqlServer.Replication.ScriptOptions]::Creation `
    -bor [Microsoft.SqlServer.Replication.ScriptOptions]::IncludeAll `
    -bor [Microsoft.SqlServer.Replication.ScriptOptions]::EnableReplicationDB `
    -bor [Microsoft.SqlServer.Replication.ScriptOptions]::IncludeInstallDistributor
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| レプリケーション情報取得 | 各種レプリケーションシステムテーブル | SELECT | RMO経由で読み取り専用アクセス |

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

本機能は読み取り専用操作のため、データベースへの書き込みは行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | SQL Serverインスタンスへの接続失敗 | 接続情報を確認し再試行 |
| - | ExportError | スクリプト生成失敗（レプリケーション未構成） | レプリケーションが構成されているか確認 |
| - | FileError | ファイル出力失敗 | 出力パスのアクセス権限を確認 |

### リトライ仕様

自動リトライは行わない。Stop-Functionで処理を停止し、-Continueで次の処理を継続する。

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

読み取り専用操作のため、トランザクション管理は不要。

## パフォーマンス要件

レプリケーション構成の複雑さに依存するが、通常は数秒以内に完了する。

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

- 認証情報はPSCredentialとして安全に処理される
- 出力スクリプトにはレプリケーション構成情報が含まれるため、適切なアクセス制御が必要

## 備考

- SQL Server Management Studioがインストールされている環境での実行が推奨される
- 一部の環境ではレプリケーションライブラリのロードに問題が発生する可能性がある（GitHub Issue #7428参照）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Add-ReplicationLibrary.ps1 | `private/functions/Add-ReplicationLibrary.ps1` | レプリケーションライブラリのロード |

**読解のコツ**: Microsoft.SqlServer.Replication.ScriptOptionsはビットフラグの列挙型で、-borで組み合わせて使用する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Export-DbaReplServerSetting.ps1 | `public/Export-DbaReplServerSetting.ps1` | メインのコマンドレット実装 |

**主要処理フロー**:
1. **114-117行目**: beginブロックでライブラリロードとパス検証
2. **119-122行目**: SqlInstanceからInputObjectを構築
3. **127-136行目**: Script()メソッドの呼び出しとオプション設定
4. **140-147行目**: 出力処理（Passthruまたはファイル出力）

#### Step 3: 依存関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaReplServer.ps1 | `public/Get-DbaReplServer.ps1` | レプリケーションサーバーオブジェクトの取得 |

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

```
Export-DbaReplServerSetting
    │
    ├─ Add-ReplicationLibrary (begin)
    │
    ├─ Test-ExportDirectory (begin)
    │
    ├─ Get-DbaReplServer (process)
    │      └─ Connect-DbaInstance
    │
    ├─ Get-ExportFilePath
    │
    └─ ReplicationServer.Script()
           └─ Out-File / Out-String
```

### データフロー図

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

SqlInstance ──────────────────▶ Get-DbaReplServer ────────────────────▶ ReplicationServer
                                      │
ScriptOption ─────────────────▶ Script() メソッド ─────────────────────▶ T-SQLスクリプト
                                      │
                               sp_dropdistributor追加
                                      │
Path/FilePath ────────────────▶ Get-ExportFilePath ───────────────────▶ ファイルパス
                                      │
Passthru ─────────────────────▶ 出力先判定
                                      │
                                      ▼
                               ファイル出力 または コンソール出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Export-DbaReplServerSetting.ps1 | `public/Export-DbaReplServerSetting.ps1` | ソース | メインコマンドレット実装 |
| Get-DbaReplServer.ps1 | `public/Get-DbaReplServer.ps1` | ソース | レプリケーションサーバー情報取得 |
| Add-ReplicationLibrary.ps1 | `private/functions/Add-ReplicationLibrary.ps1` | ソース | レプリケーションライブラリのロード |
| Export-DbaReplServerSetting.Tests.ps1 | `tests/Export-DbaReplServerSetting.Tests.ps1` | テスト | ユニットテスト |
