# 画面設計書 147-登録済みサーバーストア

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるRegisteredServersStoreオブジェクト取得機能の設計仕様を定義する。

### 本画面の処理概要

SQL Server Central Management Server（CMS）またはローカルSSMSの登録済みサーバーストアオブジェクトを取得する機能を提供する。RegisteredServersStoreは、サーバーグループと登録済みサーバーへのアクセスを提供するルートオブジェクトである。

**業務上の目的・背景**：RegisteredServersStoreオブジェクトは、CMSリポジトリにアクセスするための基盤オブジェクトである。Get-DbaRegServerやGet-DbaRegServerGroup等の関連コマンドで内部的に使用されるが、上級者が直接SMOオブジェクトを操作する場合にも使用できる。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行する。
- `Get-DbaRegServerStore` - ストアオブジェクトの取得
- `Get-DbaRegServerStore -SqlInstance <CMS>` - CMSストアの取得

**主要な操作・処理内容**：
1. SqlInstance指定時：Connect-DbaInstanceでCMSに接続し、RegisteredServersStoreオブジェクトを作成
2. SqlInstance未指定時：LocalFileStoreを初期化してローカル登録済みサーバーストアを返却

**画面遷移**：CLIベースのため画面遷移は存在しない。

**権限による表示制御**：CMSへのアクセスにはSQL Server接続権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 252 | Get-DbaRegServerStore | 主機能 | 登録済みサーバーストアの取得 |
| - | Get-DbaRegServer | 連携機能 | 登録済みサーバー取得（内部でStore使用） |
| - | Get-DbaRegServerGroup | 連携機能 | グループ取得（内部でStore使用） |

## 画面種別

コマンドラインインターフェース（CLI）/ PowerShell関数

## URL/ルーティング

```powershell
# CMSの登録済みサーバーストアを取得
Get-DbaRegServerStore -SqlInstance sqlcms

# ローカル登録済みサーバーストアを取得
Get-DbaRegServerStore

# SQL認証を使用
Get-DbaRegServerStore -SqlInstance sqlcms -SqlCredential $cred
```

## 入出力項目

### Get-DbaRegServerStore パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | No | CMSインスタンス（未指定時はローカル） |
| SqlCredential | PSCredential | No | SQL Server認証用資格情報 |
| EnableException | switch | No | 例外処理モードの有効化 |

## 表示項目

### Get-DbaRegServerStore 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | CMSホストのコンピュータ名 |
| InstanceName | string | CMSのインスタンス名 |
| SqlInstance | string | CMSの完全インスタンス名 |
| DatabaseEngineServerGroup | ServerGroup | ルートサーバーグループ |
| ServerGroups | collection | トップレベルのサーバーグループ |
| RegisteredServers | collection | ルートレベルの登録済みサーバー |

### 非表示プロパティ（Select-Object *で参照可能）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ServerConnection | object | サーバー接続オブジェクト |
| DomainInstanceName | string | ドメインインスタンス名 |
| DomainName | string | ドメイン名 |
| Urn | string | URN識別子 |
| Properties | collection | プロパティコレクション |
| Metadata | object | メタデータ |
| Parent | object | 親オブジェクト |
| ConnectionContext | object | 接続コンテキスト |
| ParentServer | Server | 親サーバーオブジェクト |

## イベント仕様

### 1-CMSストア取得

**Get-DbaRegServerStore -SqlInstance 実行時**

1. Connect-DbaInstanceでCMSに接続
2. RegisteredServersStoreコンストラクタでストアオブジェクト作成
3. Add-MemberでComputerName/InstanceName/SqlInstance/ParentServerを追加
4. Select-DefaultViewで内部プロパティを非表示に設定
5. ストアオブジェクトを返却

### 2-ローカルストア取得

**Get-DbaRegServerStore（SqlInstance未指定）実行時**

1. LocalFileStore.DomainInstanceNameでローカルファイルパスを取得
2. ファイルが存在しない場合、テンプレートのRegSrvr.xmlをコピー
3. InitChildObjectsメソッド（リフレクション経由）でストアを初期化
4. 初期化されたローカルストアを返却

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| CMSストア取得 | なし | N/A | 接続のみ、データ更新なし |
| ローカルストア取得 | なし | N/A | ファイル読み取りのみ |

本機能はストアオブジェクトを取得するのみで、データベース更新は行わない。

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| MSG001 | エラー | "Failure" | Connect-DbaInstance失敗 |
| MSG002 | エラー | "Cannot access Central Management Server on X" | RegisteredServersStore作成失敗 |

## 例外処理

| 例外条件 | 対応処理 |
|---------|---------|
| SQL Server接続失敗 | Stop-Functionでエラー記録、Continueで次インスタンスへ |
| RegisteredServersStore作成失敗 | Stop-Functionでエラー記録、Continueで次インスタンスへ |

## 備考

- RegisteredServersStoreはSMOオブジェクトで、DatabaseEngineServerGroupプロパティがルートグループへの参照を持つ
- ローカルファイルストアはユーザープロファイル下のRegSrvr.xmlに保存
- SqlInstance未指定時、ファイルが存在しない場合はテンプレートが自動コピーされる
- InitChildObjectsはprivateメソッドのため、リフレクション経由で呼び出し

---

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

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

### 推奨読解順序

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

RegisteredServersStoreオブジェクトの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaRegServerStore.ps1 | `public/Get-DbaRegServerStore.ps1` | 37-53行目: .OUTPUTSセクション |
| 1-2 | Get-DbaRegServerStore.ps1 | `public/Get-DbaRegServerStore.ps1` | 87-91行目: プロパティ追加と出力 |

**読解のコツ**: RegisteredServersStoreはDatabaseEngineServerGroupプロパティがルートグループへの参照を持つ。ここから階層構造全体にアクセス可能。

#### Step 2: CMSストア取得を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaRegServerStore.ps1 | `public/Get-DbaRegServerStore.ps1` | 74-79行目: Connect-DbaInstance |
| 2-2 | Get-DbaRegServerStore.ps1 | `public/Get-DbaRegServerStore.ps1` | 81-85行目: RegisteredServersStoreコンストラクタ |
| 2-3 | Get-DbaRegServerStore.ps1 | `public/Get-DbaRegServerStore.ps1` | 87-91行目: プロパティ追加と出力 |

**主要処理フロー**:
- **76行目**: Connect-DbaInstanceでCMS接続
- **82行目**: RegisteredServersStoreコンストラクタに$server.ConnectionContextを渡す
- **87-90行目**: Add-MemberでComputerName等を追加
- **91行目**: Select-DefaultViewで内部プロパティを除外

#### Step 3: ローカルストア取得を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaRegServerStore.ps1 | `public/Get-DbaRegServerStore.ps1` | 94-106行目: ローカルストア処理 |
| 3-2 | Get-DbaRegServerStore.ps1 | `public/Get-DbaRegServerStore.ps1` | 96行目: LocalFileStore.DomainInstanceName |
| 3-3 | Get-DbaRegServerStore.ps1 | `public/Get-DbaRegServerStore.ps1` | 98-101行目: テンプレートコピー |
| 3-4 | Get-DbaRegServerStore.ps1 | `public/Get-DbaRegServerStore.ps1` | 102-104行目: InitChildObjectsリフレクション |

**主要処理フロー**:
- **96行目**: LocalFileStoreからローカルファイルパスを取得
- **98-101行目**: ファイル未存在時はテンプレートをコピー
- **102-104行目**: リフレクションでInitChildObjectsを呼び出し

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

```
Get-DbaRegServerStore
    │
    ├─ [SqlInstance指定時]
    │      │
    │      ├─ Connect-DbaInstance (CMS接続)
    │      │
    │      ├─ RegisteredServersStore()コンストラクタ
    │      │      └─ $server.ConnectionContext
    │      │
    │      ├─ Add-Member (プロパティ追加)
    │      │      ├─ ComputerName
    │      │      ├─ InstanceName
    │      │      ├─ SqlInstance
    │      │      └─ ParentServer
    │      │
    │      └─ Select-DefaultView (内部プロパティ除外)
    │
    └─ [SqlInstance未指定時]
           │
           ├─ LocalFileStore.DomainInstanceName
           │
           ├─ [ファイル未存在時]
           │      └─ Copy-Item RegSrvr.xml
           │
           └─ InitChildObjects (リフレクション)
                  └─ GetMethod('InitChildObjects', 'Static,NonPublic')
```

### データフロー図

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

SqlInstance ───────▶ Connect-DbaInstance ───▶ SMO Server
                              │
                              ▼
                     RegisteredServersStore()
                              │
                              ▼
                     Add-Member                    RegisteredServersStore
                     (プロパティ追加)              │
                              │                    ├─ ComputerName
                              ▼                    ├─ InstanceName
                     Select-DefaultView            ├─ SqlInstance
                     (内部プロパティ除外)          ├─ DatabaseEngineServerGroup
                                                  ├─ ServerGroups
                                                  └─ RegisteredServers

[SqlInstance未指定]

                     LocalFileStore
                     .DomainInstanceName
                              │
                              ▼
                     [ファイル存在チェック]
                              │
                   ┌──────────┴──────────┐
                   ▼                     ▼
              存在する               存在しない
                   │                     │
                   │              Copy-Item
                   │              RegSrvr.xml
                   │                     │
                   └──────────┬──────────┘
                              │
                              ▼
                     InitChildObjects
                     (リフレクション)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaRegServerStore.ps1 | `public/Get-DbaRegServerStore.ps1` | ソース | ストア取得 |
| RegSrvr.xml | `bin/RegSrvr.xml` | テンプレート | ローカルストアテンプレート |
| Get-DbaRegServer.ps1 | `public/Get-DbaRegServer.ps1` | ソース | 内部でStore使用 |
| Get-DbaRegServerGroup.ps1 | `public/Get-DbaRegServerGroup.ps1` | ソース | 内部でStore使用 |
