# 機能設計書 434-Import-DbaRegServer

## 概要

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

### 本機能の処理概要

Import-DbaRegServerは、XMLファイル、他のCMSインスタンス、またはカスタムオブジェクト（CSV等）からSQL Server Central Management Server（CMS）に登録サーバーおよびサーバーグループをインポートする機能である。

**業務上の目的・背景**：CMS構成の移行、複数ソースからのサーバーインベントリ統合、バックアップからのリストアなど、サーバー登録情報の一括インポートが必要な場面は多い。この機能は、手動でのサーバー登録作業を自動化し、大規模環境でのCMS構築・移行を効率化する。XMLエクスポートファイル、他のCMSインスタンス、CSVファイルなど多様なソースからのインポートをサポート。

**機能の利用シーン**：
- 環境間でCMS構成を移行する場合
- 複数のCMSインスタンスからサーバーを統合する場合
- CSVファイルからサーバー一覧を一括登録する場合
- バックアップしたXMLファイルからCMSを復元する場合
- 新規CMSセットアップ時にサーバー一覧を投入する場合

**主要な処理内容**：
1. 入力ソースの判定（Path/InputObject）
2. 入力オブジェクトの型に応じた処理分岐
3. 不足しているサーバーグループの自動作成
4. Add-DbaRegServerを使用してサーバーを登録
5. XMLファイルの場合はSMOのImportメソッドを使用

**関連システム・外部連携**：SQL Server Central Management Server（CMS）、ファイルシステム（XMLファイル）

**権限による制御**：対象CMSへの登録権限（通常はsysadmin）が必要。

## 関連画面

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

## 機能種別

データ連携 / インポート処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | インポート先のCMSインスタンス | 必須パラメータ |
| SqlCredential | PSCredential | No | 代替認証情報 | - |
| Path | string[] | No | インポート元XMLファイルパス | ファイル存在確認 |
| InputObject | object[] | No | インポート対象オブジェクト | パイプライン入力可能 |
| Group | object | No | インポート先グループ | ServerGroupオブジェクトまたは文字列 |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- XMLファイル（Export-DbaRegServerまたはSSMSでエクスポート）
- 他のCMSインスタンスからのRegisteredServerオブジェクト
- ServerGroupオブジェクト
- カスタムオブジェクト（CSVなど、ServerName列必須）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Name | string | 登録サーバーの表示名 |
| ServerName | string | SQL Server接続文字列 |
| Group | string | グループパス |
| Description | string | 説明文 |
| Source | string | 取得元識別子 |

### 出力先

- インポートされた登録サーバーオブジェクトをパイプライン出力

## 処理フロー

### 処理シーケンス

```
1. Path指定時のファイル取得
   └─ Get-ChildItemでファイルオブジェクトを取得
2. Group指定時のグループオブジェクト取得
   └─ ServerGroupオブジェクトまたはGet-DbaRegServerGroupで取得
3. InputObjectのループ処理
   └─ 各オブジェクトの型に応じた処理を実行
4. RegisteredServer型の処理
   └─ 親グループ存在確認・作成、Add-DbaRegServerで登録
5. ServerGroup型の処理
   └─ グループ内の各サーバーを個別に登録
6. FileInfo型の処理
   └─ SMOのImportメソッドでXMLをインポート
7. カスタムオブジェクト型の処理
   └─ ServerName列を使用してAdd-DbaRegServerで登録
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Path指定?}
    B -->|Yes| C[Get-ChildItemでファイル取得]
    B -->|No| D{Group指定?}
    C --> D
    D -->|Yes| E[グループオブジェクト取得]
    D -->|No| F[InputObjectループ開始]
    E --> F
    F --> G{オブジェクト型判定}
    G -->|RegisteredServer| H[親グループ確認・作成]
    H --> I[Add-DbaRegServer]
    G -->|ServerGroup| J[グループ内サーバーループ]
    J --> K[各サーバーを登録]
    G -->|FileInfo| L[ファイル存在確認]
    L --> M{存在?}
    M -->|No| N[Stop-Function]
    M -->|Yes| O[SMO Import実行]
    O --> P[新規登録サーバー取得]
    G -->|その他| Q{ServerName存在?}
    Q -->|No| R[Stop-Function]
    Q -->|Yes| S[Add-DbaRegServer]
    I --> T{次のオブジェクト?}
    K --> T
    P --> T
    S --> T
    N --> T
    T -->|Yes| F
    T -->|No| U[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | グループ自動作成 | 存在しないグループは自動的に作成 | RegisteredServer/ServerGroup型入力時 |
| BR-002 | ServerName必須 | カスタムオブジェクトにはServerName列が必須 | カスタムオブジェクト入力時 |
| BR-003 | 差分インポート | XMLインポート時は新規追加されたサーバーのみ出力 | FileInfo型入力時 |
| BR-004 | グループパス指定 | バックスラッシュ記法でネストされたグループを指定可能 | Group指定時 |

### 計算ロジック

差分検出ロジック：
- インポート前のUrn.Valueリストを保存
- インポート後にUrn.Valueが新規のサーバーのみを返却

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| サーバー登録 | msdb系システムテーブル | INSERT | 登録サーバー情報の追加 |
| グループ作成 | msdb系システムテーブル | INSERT | サーバーグループの追加 |

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

SMOを介した間接的な操作のため、直接のテーブル操作仕様は非公開。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | グループ不存在 | 指定グループがCMSに存在しない | グループを事前に作成するか、別のグループを指定 |
| - | ファイル不存在 | 指定XMLファイルが存在しない | ファイルパスを確認 |
| - | ServerName不足 | カスタムオブジェクトにServerName列がない | 入力データを修正 |
| - | インポートエラー | SMO Importメソッド失敗 | XMLファイルの形式を確認 |

### リトライ仕様

リトライ機能は実装されていない。

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

トランザクション管理はSMOに委譲。個別のサーバー登録は独立して実行される。

## パフォーマンス要件

特定のパフォーマンス要件は定義されていない。大量サーバーのインポート時は処理時間に注意。

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

- 対象CMSへの適切な権限（sysadmin推奨）が必要
- XMLファイルにパスワードが含まれる場合、ファイルの取り扱いに注意

## 備考

- Get-DbaRegServer、Get-DbaRegServerGroupからパイプラインで直接インポート可能
- CSVからのインポートにはImport-CsvをパイプでInputObjectに渡す

---

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

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

### 推奨読解順序

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

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

**読解のコツ**: 入力オブジェクトの型判定（-is演算子）でRegisteredServer、ServerGroup、FileInfo、その他を区別している。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Import-DbaRegServer.ps1 | `public/Import-DbaRegServer.ps1` | パラメータ定義、process block構造 |

**主要処理フロー**:
1. **94-105行目**: パラメータ定義
2. **106-121行目**: 入力準備（Path/Group処理）

#### Step 3: オブジェクト型別処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Import-DbaRegServer.ps1 | `public/Import-DbaRegServer.ps1` | 各オブジェクト型の処理ロジック |

**主要処理フロー**:
- **123-130行目**: RegisteredServer型処理
- **131-138行目**: ServerGroup型処理
- **139-165行目**: FileInfo型処理（SMO Import）
- **166-176行目**: カスタムオブジェクト処理

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

```
Import-DbaRegServer
    │
    ├─ Get-ChildItem
    │      └─ XMLファイル取得
    │
    ├─ Get-DbaRegServerGroup
    │      └─ グループオブジェクト取得
    │
    ├─ Add-DbaRegServerGroup
    │      └─ グループ自動作成
    │
    ├─ Add-DbaRegServer
    │      └─ サーバー登録
    │
    ├─ [SMO ServerGroup].Import()
    │      └─ XMLファイルインポート
    │
    └─ Get-DbaRegServer
           └─ インポート結果取得
```

### データフロー図

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

Path (XMLファイル) ─────▶ Get-ChildItem ──────────┐
                                                  │
InputObject ────────────▶ 型判定 ─────────────────┤
  ├─ RegisteredServer                             │
  ├─ ServerGroup                                  │
  ├─ FileInfo                                     │
  └─ カスタムオブジェクト                          │
                                                  │
                         Add-DbaRegServer ────────┼──▶ RegisteredServer[]
                                                  │
                         [SMO].Import() ──────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Import-DbaRegServer.ps1 | `public/Import-DbaRegServer.ps1` | ソース | メイン機能実装 |
| Get-DbaRegServerGroup.ps1 | `public/Get-DbaRegServerGroup.ps1` | ソース | グループ取得 |
| Add-DbaRegServerGroup.ps1 | `public/Add-DbaRegServerGroup.ps1` | ソース | グループ作成 |
| Add-DbaRegServer.ps1 | `public/Add-DbaRegServer.ps1` | ソース | サーバー登録 |
| Get-DbaRegServer.ps1 | `public/Get-DbaRegServer.ps1` | ソース | 結果取得 |
