# 機能設計書 446-Get-DbaReplPublication

## 概要

本ドキュメントは、SQL Serverインスタンスからレプリケーションパブリケーション（トランザクション、マージ、スナップショット）を取得するdbatools PowerShellコマンドレット `Get-DbaReplPublication` の機能設計を記述する。

### 本機能の処理概要

Get-DbaReplPublicationは、SQL Serverインスタンスに構成されているすべてのレプリケーションパブリケーションの詳細情報を取得するコマンドレットである。

**業務上の目的・背景**：レプリケーション環境において、どのパブリケーションが存在し、どのタイプ（トランザクション、マージ、スナップショット）で構成されているかを把握することは、トポロジー管理とトラブルシューティングに不可欠である。この機能により、データベース管理者は各パブリケーションの詳細（関連アーティクル、サブスクリプション、設定）を効率的に確認できる。

**機能の利用シーン**：
- レプリケーショントポロジーの監査時にパブリケーション構成を確認する場面
- 特定のパブリケーションタイプ（トランザクション、マージ、スナップショット）の一覧を取得する場面
- パブリケーションのトラブルシューティング時に構成を確認する場面
- レプリケーション設定のドキュメント化

**主要な処理内容**：
1. Add-ReplicationLibraryでレプリケーションライブラリをロード
2. Connect-DbaInstanceで各SQL Serverインスタンスに接続（最小バージョン9 = SQL Server 2005）
3. アクセス可能な非システムデータベースを取得し、フィルタリング
4. 各データベースのReplicationOptionsを確認してパブリッシュ済みかどうかを判定
5. Connect-ReplicationDBでレプリケーションデータベースオブジェクトを取得
6. TransPublicationsとMergePublicationsを結合してパブリケーション一覧を作成
7. Type、Nameでフィルタリング
8. 各パブリケーションにメタデータ（Articles, Subscriptions）を追加して出力

**関連システム・外部連携**：
- SQL Server Replication Management Objects (RMO) を使用
- Connect-ReplicationDBプライベート関数に依存

**権限による制御**：
- SQL Serverインスタンスへのアクセス権限が必要（SQL Server 2005以上）
- データベースへの読み取りアクセス権限が必要

## 関連画面

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

## 機能種別

データ取得 / 情報参照

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象のSQL Serverインスタンス | 有効なSQL Serverインスタンス名 |
| SqlCredential | PSCredential | No | 代替認証情報 | Get-Credentialで取得した有効な認証情報 |
| Database | object[] | No | フィルタリング対象のデータベース名 | ワイルドカード対応 |
| Name | String | No | フィルタリング対象のパブリケーション名 | 有効なパブリケーション名 |
| Type | object[] | No | パブリケーションタイプ（Transactional, Merge, Snapshot） | ValidateSet制約 |
| EnableException | switch | No | 例外処理を有効化 | - |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverインスタンスをホストするコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | object | SQL Serverレプリケーションサーバーオブジェクト |
| DatabaseName | string | パブリケーションを含むデータベース名 |
| Name | string | パブリケーション名 |
| Type | string | パブリケーションタイプ（Transactional, Merge, Snapshot） |
| Articles | object | パブリッシュされたアーティクルのコレクション |
| Subscriptions | object | パブリケーションへのサブスクリプションのコレクション |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. beginブロック
   └─ Add-ReplicationLibraryでライブラリをロード
2. processブロック
   └─ Test-FunctionInterruptで中断チェック
   └─ 各SqlInstanceに対してループ
       └─ Connect-DbaInstanceで接続（MinimumVersion 9）
       └─ アクセス可能な非システムDBを取得
       └─ Databaseパラメータでフィルタリング
       └─ 各データベースに対してループ
           └─ ReplicationOptionsでパブリッシュ済みか確認
           └─ 未パブリッシュならスキップ
           └─ Connect-ReplicationDBでレプリケーションDB取得
           └─ TransPublications + MergePublicationsを結合
           └─ Type, Nameでフィルタリング
           └─ ArticlesとSubscriptionsをタイプに応じて取得
           └─ メタデータを追加
           └─ Select-DefaultViewで出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Add-ReplicationLibrary]
    B --> C{Test-FunctionInterrupt?}
    C -->|Yes| D[終了]
    C -->|No| E[SqlInstanceループ]
    E --> F[Connect-DbaInstance MinVer=9]
    F --> G{接続成功?}
    G -->|No| H[Stop-Function]
    G -->|Yes| I[非システムDB取得]
    I --> J{Databaseフィルタ?}
    J -->|Yes| K[DBフィルタリング]
    J -->|No| L[全DB取得]
    K --> M[各DBループ]
    L --> M
    M --> N{ReplicationOptions?}
    N -->|未パブリッシュ| O[スキップ]
    N -->|パブリッシュ済| P[Connect-ReplicationDB]
    P --> Q[Trans+Merge結合]
    Q --> R{Typeフィルタ?}
    R -->|Yes| S[Typeフィルタリング]
    R -->|No| T{Nameフィルタ?}
    S --> T
    T -->|Yes| U[Nameフィルタリング]
    T -->|No| V[Articles/Subs取得]
    U --> V
    V --> W[メタデータ追加]
    W --> X[Select-DefaultView]
    X --> Y{次のPub?}
    O --> Z{次のDB?}
    Y -->|Yes| V
    Y -->|No| Z
    Z -->|Yes| M
    Z -->|No| AA{次のInstance?}
    H --> AA
    AA -->|Yes| E
    AA -->|No| D
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | SQL Server 2005以上 | MinimumVersion 9でSQL Server 2005以上を要求 | 常時 |
| BR-002 | 非システムDBのみ処理 | IsSystemObject=falseのデータベースのみ処理 | 常時 |
| BR-003 | パブリッシュ済みDBのみ処理 | Published/MergePublishedフラグが立っているDBのみ処理 | 常時 |
| BR-004 | タイプ別アーティクル取得 | MergeタイプはMergeArticles、それ以外はTransArticles | 常時 |

### 計算ロジック

ReplicationOptionsによるパブリッシュ判定:
```powershell
(($db.ReplicationOptions -band [Microsoft.SqlServer.Management.Smo.ReplicationOptions]::Published) -ne [Microsoft.SqlServer.Management.Smo.ReplicationOptions]::Published) -and
(($db.ReplicationOptions -band [Microsoft.SqlServer.Management.Smo.ReplicationOptions]::MergePublished) -ne [Microsoft.SqlServer.Management.Smo.ReplicationOptions]::MergePublished)
```

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

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

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | SQL Serverインスタンスへの接続失敗 | 接続情報を確認し再試行 |
| - | VersionError | SQL Server 2005未満 | SQL Server 2005以上にアップグレード |
| - | PublicationError | パブリケーション取得失敗 | レプリケーション構成を確認 |

### リトライ仕様

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

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

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

## パフォーマンス要件

データベース数とパブリケーション数に依存するが、通常は数秒以内に完了する。

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

- 認証情報はPSCredentialとして安全に処理される
- レプリケーション構成情報の読み取りには適切な権限が必要

## 備考

- Description, PubId, Status, CompatibilityLevel, RetentionPeriodなどの追加プロパティはSelect-Object *で取得可能
- スナップショットパブリケーションはTransPublicationsに含まれる（Typeプロパティで区別）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Connect-ReplicationDB.ps1 | `private/functions/Connect-ReplicationDB.ps1` | ReplicationDatabaseオブジェクトの構造 |
| 1-2 | Add-ReplicationLibrary.ps1 | `private/functions/Add-ReplicationLibrary.ps1` | ライブラリロード |

**読解のコツ**: TransPublicationsとMergePublicationsは別コレクションだが、結合して処理される。

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

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

**主要処理フロー**:
1. **115-117行目**: beginブロックでライブラリロード
2. **122-123行目**: Connect-DbaInstanceで接続（MinimumVersion 9）
3. **141-146行目**: ReplicationOptionsによるパブリッシュ判定
4. **149行目**: Connect-ReplicationDBでレプリケーションDB取得
5. **151行目**: TransPublications + MergePublicationsを結合
6. **161-168行目**: タイプに応じたArticles/Subscriptions取得
7. **171-177行目**: メタデータ追加と出力

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Connect-ReplicationDB.ps1 | `private/functions/Connect-ReplicationDB.ps1` | レプリケーションDB接続 |
| 3-2 | Connect-DbaInstance | - | SQL Server接続 |

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

```
Get-DbaReplPublication
    │
    ├─ Add-ReplicationLibrary (begin)
    │
    ├─ Connect-DbaInstance (MinimumVersion 9)
    │
    └─ Connect-ReplicationDB
           ├─ Add-ReplicationLibrary
           └─ New-Object Microsoft.SqlServer.Replication.ReplicationDatabase
```

### データフロー図

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

SqlInstance ──────────────────▶ Connect-DbaInstance ──────────────────▶ Server
                                      │
Database ─────────────────────▶ データベースフィルタ
                                      │
                               ReplicationOptions判定
                                      │
                               Connect-ReplicationDB
                                      │
                               TransPub + MergePub結合
                                      │
Type, Name ───────────────────▶ フィルタリング
                                      │
                               Articles/Subscriptions取得
                                      │
                               メタデータ追加
                                      │
                               Select-DefaultView
                                      │
                                      ▼
                               Publicationオブジェクト（8プロパティ）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaReplPublication.ps1 | `public/Get-DbaReplPublication.ps1` | ソース | メインコマンドレット実装 |
| Connect-ReplicationDB.ps1 | `private/functions/Connect-ReplicationDB.ps1` | ソース | レプリケーションDB接続 |
| Add-ReplicationLibrary.ps1 | `private/functions/Add-ReplicationLibrary.ps1` | ソース | レプリケーションライブラリのロード |
| Get-DbaReplPublication.Tests.ps1 | `tests/Get-DbaReplPublication.Tests.ps1` | テスト | ユニットテスト |
