# 機能設計書 431-Export-DbaRegServer

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるExport-DbaRegServer機能の設計仕様を定義する。

### 本機能の処理概要

Export-DbaRegServerは、SQL Server Central Management Server（CMS）またはローカル登録サーバーからサーバー登録情報をXMLファイルにエクスポートする機能である。

**業務上の目的・背景**：データベース管理者は複数のSQL Serverインスタンスを管理する際、サーバー登録情報を一元的に管理する必要がある。この機能は、サーバー登録情報のバックアップ、環境間での移行、他のDBAとの共有を可能にする。手動でのエクスポート作業を自動化し、作業効率を向上させることで、運用管理の負担を軽減する。

**機能の利用シーン**：
- CMSサーバーの移行時に登録サーバー情報を新環境へ転送する場合
- サーバー登録情報の定期的なバックアップを取得する場合
- 複数のDBAチーム間でサーバー一覧を共有する場合
- Azure Data StudioやSSMSでインポート可能な形式でサーバー一覧を配布する場合

**主要な処理内容**：
1. 対象となるSQLインスタンスまたはパイプラインから登録サーバー/グループを取得
2. グループフィルタリング（Group/ExcludeGroupパラメータ）を適用
3. 出力ファイルパスの検証と生成（.xmlまたは.regsrvr拡張子の確認）
4. SMOのExportメソッドを使用してXML形式でエクスポート
5. エクスポート完了後のファイル情報を返却

**関連システム・外部連携**：SQL Server Management Studio、Azure Data Studio、Central Management Server（CMS）

**権限による制御**：CMSへのアクセス権限（通常はSQLログインまたはWindows認証）が必要。エクスポート先ディレクトリへの書き込み権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 該当なし（コマンドライン機能） | - | - |

## 機能種別

データ連携 / エクスポート処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象のSQL Serverインスタンス | - |
| SqlCredential | PSCredential | No | 代替認証情報 | - |
| InputObject | object[] | No | 登録サーバーまたはサーバーグループオブジェクト | パイプライン入力可能 |
| Path | string | No | エクスポート先ディレクトリ | デフォルトはdbatools設定のエクスポートディレクトリ |
| FilePath | System.IO.FileInfo | No | 完全なファイルパス（ファイル名含む） | .xmlまたは.regsrvr拡張子が必須 |
| CredentialPersistenceType | string | No | 資格情報の保存方法 | None/PersistLoginName/PersistLoginNameAndPassword |
| Group | object[] | No | エクスポート対象のグループ名 | - |
| ExcludeGroup | object[] | No | エクスポートから除外するグループ名 | - |
| Overwrite | switch | No | 既存ファイルの上書きを許可 | - |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- SQL Server Central Management Server（CMS）からの登録サーバー情報
- ローカル登録サーバー（SSMSまたはAzure Data Studio）
- Get-DbaRegServer、Get-DbaRegServerGroupからのパイプライン入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Name | string | エクスポートされたファイル名 |
| FullName | string | 完全なファイルパス |
| Directory | DirectoryInfo | ファイルの格納ディレクトリ |
| Extension | string | ファイル拡張子（.xmlまたは.regsrvr） |
| Length | long | ファイルサイズ（バイト） |
| CreationTime | DateTime | ファイル作成日時 |
| LastWriteTime | DateTime | 最終更新日時 |
| Attributes | FileAttributes | ファイル属性 |

### 出力先

- 指定されたディレクトリにXMLファイルとして出力
- デフォルトはdbatools設定のエクスポートディレクトリ

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ FilePathが指定されている場合、拡張子が.xmlまたは.regsrvrであることを確認
2. 出力ディレクトリの検証
   └─ Test-ExportDirectory関数でディレクトリの存在確認
3. タイムスタンプの生成
   └─ ファイル名に付与するタイムスタンプを取得
4. SqlInstanceからの登録サーバー取得
   └─ Get-DbaRegServerGroupを使用してグループ情報を取得
5. InputObjectの処理
   └─ RegisteredServersStore、RegisteredServer、ServerGroupの各型に応じた処理
6. エクスポート実行
   └─ SMOのExportメソッドでXML形式にエクスポート
7. 結果返却
   └─ Get-ChildItemで作成されたファイル情報を返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{FilePathが指定?}
    B -->|Yes| C{拡張子が.xml/.regsrvr?}
    C -->|No| D[エラー終了]
    C -->|Yes| E{ファイル存在?}
    E -->|Yes| F{Overwrite指定?}
    F -->|No| G[エラー終了]
    F -->|Yes| H[処理続行]
    E -->|No| H
    B -->|No| H
    H --> I[SqlInstanceからグループ取得]
    I --> J[InputObject処理ループ]
    J --> K{オブジェクト型判定}
    K -->|RegisteredServersStore| L[グループ取得]
    K -->|RegisteredServer/ServerGroup| M[ファイル名生成]
    L --> M
    M --> N[Exportメソッド実行]
    N --> O[ファイル情報返却]
    O --> P{次のオブジェクト?}
    P -->|Yes| J
    P -->|No| Q[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ファイル拡張子制限 | エクスポートファイルは.xmlまたは.regsrvr拡張子のみ許可 | FilePath指定時 |
| BR-002 | 上書き保護 | 既存ファイルへの上書きはOverwriteスイッチが必要 | ファイルが存在する場合 |
| BR-003 | 自動ファイル名生成 | 複数オブジェクトエクスポート時は自動でファイル名を分離 | InputObject.length > 1の場合 |
| BR-004 | 資格情報の保存オプション | デフォルトはNoneでセキュリティを優先 | 常時 |

### 計算ロジック

ファイル名生成ロジック：
- RegisteredServer: `{serverName}-regserver-{regname}-{timestamp}.xml`
- ServerGroup: `{serverName}-reggroup-{regname}-{timestamp}.xml`

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| N/A | N/A | N/A | データベースへの直接操作なし（SMO経由のメタデータ読み取りのみ） |

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

本機能はデータベーステーブルへの直接操作を行わない。SMOを介してCMS内のメタデータを読み取り、ファイルにエクスポートする。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 検証エラー | FilePathの拡張子が不正 | .xmlまたは.regsrvr拡張子を使用 |
| - | ファイル存在エラー | 出力ファイルが既存でOverwrite未指定 | Overwriteパラメータを指定 |
| - | 型エラー | InputObjectが登録サーバー/グループでない | 正しい型のオブジェクトを渡す |
| - | エクスポートエラー | Exportメソッド実行失敗 | 権限、ディスク容量を確認 |

### リトライ仕様

リトライ機能は実装されていない。エラー発生時はStop-Functionで処理を中断。

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

トランザクション管理は不要（読み取り専用操作およびファイル出力）。

## パフォーマンス要件

特定のパフォーマンス要件は定義されていない。エクスポートするサーバー数に応じて処理時間が変動。

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

- CredentialPersistenceTypeのデフォルトはNoneで、パスワードは保存されない
- PersistLoginNameAndPasswordを使用する場合、エクスポートファイルにパスワードが含まれるため、ファイルのアクセス権限管理が重要
- SqlCredentialパラメータでMFA以外の認証方式をサポート

## 備考

- SSMSおよびAzure Data Studioでインポート可能なXML形式で出力
- Central Management ServerおよびローカルServer Groupsの両方に対応

---

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

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

### 推奨読解順序

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

SMOの登録サーバー関連クラスの理解が重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Microsoft.SqlServer.Management.RegisteredServers | (SMO) | RegisteredServer、ServerGroup、RegisteredServersStoreクラスの構造 |

**読解のコツ**: SMOのRegisteredServersネームスペースは、CMSの階層構造（Store > Group > Server）を反映している。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Export-DbaRegServer.ps1 | `public/Export-DbaRegServer.ps1` | 関数全体の構造、パラメータ定義 |

**主要処理フロー**:
1. **101-117行目**: パラメータ定義（CmdletBinding、param block）
2. **118-137行目**: begin block - ディレクトリ検証、タイムスタンプ生成、FilePath検証
3. **139-154行目**: process block開始 - SqlInstanceからのグループ取得

#### Step 3: メイン処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Export-DbaRegServer.ps1 | `public/Export-DbaRegServer.ps1` | InputObjectのループ処理とエクスポート実行 |

**主要処理フロー**:
- **156-170行目**: RegisteredServersStoreの処理分岐
- **172-193行目**: ファイル名生成ロジック
- **195行目**: SMOのExportメソッド呼び出し
- **197行目**: 結果のファイル情報返却

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

```
Export-DbaRegServer
    │
    ├─ Test-ExportDirectory
    │      └─ ディレクトリ存在確認
    │
    ├─ Get-DbatoolsConfigValue
    │      └─ 設定値取得（Path.DbatoolsExport）
    │
    ├─ Get-DbaRegServerGroup
    │      └─ 登録サーバーグループ取得
    │
    └─ [SMO].Export()
           └─ XMLファイルへのエクスポート
```

### データフロー図

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

SqlInstance ───────▶ Get-DbaRegServerGroup ─────┐
                                                │
InputObject ───────▶ 型判定・フィルタリング ───┼──▶ .Export() ──▶ XMLファイル
(パイプライン)                                  │
                                                │
Group/ExcludeGroup ▶ グループフィルタ ─────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Export-DbaRegServer.ps1 | `public/Export-DbaRegServer.ps1` | ソース | メイン機能実装 |
| Get-DbaRegServer.ps1 | `public/Get-DbaRegServer.ps1` | ソース | 関連機能（登録サーバー取得） |
| Get-DbaRegServerGroup.ps1 | `public/Get-DbaRegServerGroup.ps1` | ソース | グループ取得機能 |
| Get-DbaRegServerStore.ps1 | `public/Get-DbaRegServerStore.ps1` | ソース | ストア取得機能 |
