# 機能設計書 441-Enable-DbaReplPublishing

## 概要

本ドキュメントは、SQL Serverインスタンスをレプリケーションパブリッシャーとして構成するdbatools PowerShellコマンドレット `Enable-DbaReplPublishing` の機能設計を記述する。

### 本機能の処理概要

Enable-DbaReplPublishingは、既存のディストリビューターに対してSQL Serverインスタンスをレプリケーションパブリッシャーとして構成するコマンドレットである。

**業務上の目的・背景**：SQL Serverレプリケーション環境を構築する際、ディストリビューターの構成後にパブリッシャーを有効化する必要がある。この機能は、レプリケーショントポロジーのセットアップにおいて2番目のステップとして使用され、データベース管理者がPowerShellを通じて効率的にレプリケーション環境を構築できるようにする。

**機能の利用シーン**：
- 新規レプリケーション環境の構築時、Enable-DbaReplDistributorでディストリビューターを構成した後にパブリッシャーを有効化する場面
- 複数のSQL Serverインスタンスをパブリッシャーとして一括で構成する場面
- 災害復旧手順の自動化において、レプリケーション環境を再構築する場面

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスに接続し、レプリケーションサーバーオブジェクトを取得する
2. インスタンスがディストリビューターとして構成されているか検証する
3. DistributionPublisherオブジェクトを作成し、接続コンテキスト、名前、配布データベースを設定する
4. スナップショット作業ディレクトリを設定する（未指定の場合はInstallDataDirectory\ReplDataを使用）
5. パブリッシャーセキュリティ（Windows認証またはSQL認証）を構成する
6. DistributionPublisher.Create()メソッドを呼び出してパブリッシャーを作成する
7. ReplicationServerオブジェクトを更新して結果を返す

**関連システム・外部連携**：
- SQL Server Replication Management Objects (RMO) を使用してレプリケーション構成を操作
- Microsoft.SqlServer.Replication.dll および Microsoft.SqlServer.Rmo.dll ライブラリに依存

**権限による制御**：
- SQL Serverインスタンスに対してsysadmin権限が必要
- Windows認証またはSQL Server認証による接続をサポート

## 関連画面

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

## 機能種別

データ連携 / システム構成変更

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | パブリッシャーとして構成するSQL Serverインスタンス | 有効なSQL Serverインスタンス名であること |
| SqlCredential | PSCredential | No | 代替認証情報（SQL認証、AD認証をサポート） | Get-Credentialで取得した有効な認証情報 |
| SnapshotShare | string | No | スナップショットファイルを保存するネットワーク共有パス | 有効なファイルパスであること |
| PublisherSqlLogin | PSCredential | No | パブリッシャーセキュリティ認証用のSQL Serverログイン | Get-Credentialで取得した有効な認証情報 |
| EnableException | switch | No | 例外処理を有効化し、詳細なエラー情報を取得可能にする | - |
| WhatIf | switch | No | 実行内容を表示するが実際の変更は行わない | - |
| Confirm | switch | No | 操作実行前に確認プロンプトを表示する | - |

### 入力データソース

PowerShellコマンドライン引数、パイプライン入力（SqlInstanceパラメータ）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverインスタンスをホストするコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名（コンピュータ\インスタンス） |
| IsDistributor | bool | ディストリビューターとして構成されているかどうか |
| IsPublisher | bool | パブリッシャーとして構成されているかどうか（実行後はTrue） |
| DistributionServer | string | ディストリビューターとして構成されているサーバー名 |
| DistributionDatabase | string | 配布データベース名 |

### 出力先

PowerShellパイプライン（Microsoft.SqlServer.Replication.ReplicationServerオブジェクト）

## 処理フロー

### 処理シーケンス

```
1. SqlInstanceパラメータの各インスタンスに対してループ処理
   └─ foreach ($instance in $SqlInstance)
2. Get-DbaReplServerを呼び出してレプリケーションサーバーオブジェクトを取得
   └─ $replServer = Get-DbaReplServer -SqlInstance $instance
3. ディストリビューター構成の検証
   └─ if ($replServer.IsDistributor) で確認
4. DistributionPublisherオブジェクトの作成と構成
   └─ New-Object Microsoft.SqlServer.Replication.DistributionPublisher
5. スナップショット共有ディレクトリの設定
   └─ 未指定時はInstallDataDirectory\ReplDataをデフォルト使用
6. パブリッシャーセキュリティの構成
   └─ PublisherSqlLogin指定時はSQL認証、それ以外はWindows認証
7. DistributionPublisher.Create()でパブリッシャーを作成
8. ReplicationServerをリフレッシュして結果を返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[SqlInstanceループ開始]
    B --> C[Get-DbaReplServer呼び出し]
    C --> D{IsDistributor?}
    D -->|No| E[エラー: ディストリビューター未構成]
    D -->|Yes| F{WhatIf?}
    F -->|Yes| G[処理内容を表示]
    F -->|No| H[DistributionPublisher作成]
    H --> I{SnapshotShare指定?}
    I -->|No| J[デフォルトパス設定]
    I -->|Yes| K[指定パス設定]
    J --> L{PublisherSqlLogin指定?}
    K --> L
    L -->|Yes| M[SQL認証設定]
    L -->|No| N[Windows認証設定]
    M --> O[Create実行]
    N --> O
    O --> P[ReplicationServer更新]
    P --> Q[結果出力]
    E --> R{次のインスタンス?}
    G --> R
    Q --> R
    R -->|Yes| B
    R -->|No| S[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ディストリビューター前提条件 | パブリッシャーを有効化する前にディストリビューターが構成されている必要がある | 常時 |
| BR-002 | デフォルトスナップショットパス | SnapshotShare未指定時はInstallDataDirectory\ReplDataを使用 | SnapshotShareパラメータ未指定時 |
| BR-003 | 認証方式デフォルト | PublisherSqlLogin未指定時はWindows認証を使用 | PublisherSqlLoginパラメータ未指定時 |

### 計算ロジック

スナップショット共有パスのデフォルト値計算：
```powershell
$SnapshotShare = Join-Path (Connect-DbaInstance -SqlInstance $instance).InstallDataDirectory 'ReplData'
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| パブリッシャー登録 | distribution.dbo.MSdistpublishers | INSERT | RMO経由でパブリッシャー情報を登録 |

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

#### distribution.dbo.MSdistpublishers

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name | SqlInstanceの値 | パブリッシャー名として登録 |
| INSERT | distribution_db | DistributionDatabases.Name | 配布データベース名 |
| INSERT | working_directory | SnapshotShare | スナップショット作業ディレクトリ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | SQL Serverインスタンスへの接続失敗 | 接続情報を確認し再試行 |
| - | ConfigurationError | ディストリビューター未構成 | Enable-DbaReplDistributorを先に実行 |
| - | RMOError | パブリッシャー作成失敗 | エラーメッセージに従い問題を解決 |

### リトライ仕様

リトライは自動では行われない。エラー発生時はStop-Functionで処理を停止し、-Continueフラグにより次のインスタンスの処理を継続する。

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

RMOのDistributionPublisher.Create()メソッドは内部でトランザクション管理を行う。明示的なトランザクション制御は本コマンドレットでは行わない。

## パフォーマンス要件

通常のネットワーク環境において、1インスタンスあたり数秒以内で処理が完了することが期待される。

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

- SQL Server認証を使用する場合、認証情報はSecureStringとして処理される
- PublisherSqlLoginのパスワードはSecureSqlStandardPasswordプロパティを使用して安全に設定される
- Windows認証が推奨されるセキュリティ方式として文書化されている

## 備考

- SQL Server Management Studioがインストールされている環境での実行が推奨される
- レプリケーションライブラリ（Microsoft.SqlServer.Replication.dll, Microsoft.SqlServer.Rmo.dll）が必要

---

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

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

### 推奨読解順序

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

レプリケーション関連のオブジェクト構造を把握する。

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

**読解のコツ**: Microsoft.SqlServer.Replication.dllとMicrosoft.SqlServer.Rmo.dllが基盤となるライブラリである。

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

処理の起点となる関数を特定する。

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

**主要処理フロー**:
1. **89-91行目**: processブロック開始、SqlInstanceのループ処理
2. **92行目**: Get-DbaReplServerを呼び出してレプリケーションサーバー情報を取得
3. **96-140行目**: ディストリビューター構成確認とパブリッシャー作成処理

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaReplServer.ps1 | `public/Get-DbaReplServer.ps1` | レプリケーションサーバーオブジェクトの取得方法 |
| 3-2 | Connect-DbaInstance | - | SQL Server接続の基盤関数 |

**主要処理フロー**:
- **91行目**: ReplicationServerオブジェクトの作成
- **92行目**: ConnectionContextの設定

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

```
Enable-DbaReplPublishing
    │
    ├─ Get-DbaReplServer
    │      └─ Connect-DbaInstance
    │      └─ New-Object Microsoft.SqlServer.Replication.ReplicationServer
    │
    ├─ Connect-DbaInstance (SnapshotShare取得用)
    │
    └─ New-Object Microsoft.SqlServer.Replication.DistributionPublisher
           └─ Create()
```

### データフロー図

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

SqlInstance ──────────────────▶ Get-DbaReplServer ────────────────────▶ ReplicationServer
                                      │
SqlCredential ────────────────▶ Connect-DbaInstance ──────────────────▶ 接続コンテキスト
                                      │
SnapshotShare ────────────────▶ DistributionPublisher設定 ────────────▶ 作業ディレクトリ
                                      │
PublisherSqlLogin ────────────▶ PublisherSecurity設定 ────────────────▶ 認証情報
                                      │
                               Create() 実行
                                      │
                               Refresh() 実行
                                      │
                                      ▼
                               ReplicationServerオブジェクト（更新済）
```

### 関連ファイル一覧

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