# 機能設計書 432-Get-DbaRegServer

## 概要

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

### 本機能の処理概要

Get-DbaRegServerは、SQL Server Management Studio（SSMS）、Azure Data Studio、およびCentral Management Server（CMS）から登録済みSQL Serverインスタンス情報を取得する機能である。

**業務上の目的・背景**：データベース管理者は、管理対象の複数SQL Serverインスタンスを把握する必要がある。この機能は、CMSやローカル登録サーバーから一括でサーバー一覧を取得し、インベントリ管理、一括操作、レポート作成などの基盤となる情報を提供する。手動でのサーバー一覧管理を排除し、常に最新の登録情報にアクセスできるようにする。

**機能の利用シーン**：
- 管理対象サーバーの一覧を取得して一括操作を実行する場合
- 特定グループに属するサーバーのみを抽出する場合
- サーバー名パターンで対象を絞り込む場合
- DNS解決を含むネットワーク情報を取得する場合
- CMSとローカル登録サーバーを統合して確認する場合

**主要な処理内容**：
1. SqlInstance指定時はCMSに接続して登録サーバーを取得
2. SqlInstance未指定時はローカル登録サーバーとAzure Data Studioから取得
3. Name/ServerName/Patternによるフィルタリングを適用
4. Group/ExcludeGroupによるグループフィルタリングを適用
5. ResolveNetworkName指定時はDNS解決を実行
6. IncludeSelf指定時はCMSインスタンス自体も結果に追加

**関連システム・外部連携**：SQL Server Management Studio、Azure Data Studio、Central Management Server（CMS）、DNSサーバー（ResolveNetworkName使用時）

**権限による制御**：CMSへの接続権限が必要。ローカル登録サーバーはユーザープロファイルのアクセス権で制御。

## 関連画面

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

## 機能種別

データ取得 / SELECT処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | CMSインスタンス（未指定時はローカル） | パイプライン入力可能 |
| SqlCredential | PSCredential | No | 代替認証情報 | - |
| Name | string[] | No | 表示名でフィルタリング | - |
| ServerName | string[] | No | サーバーインスタンス名でフィルタリング | - |
| Pattern | string[] | No | 正規表現パターンでフィルタリング | 正規表現構文 |
| ExcludeServerName | string[] | No | 除外するサーバーインスタンス名 | - |
| Group | string[] | No | 対象グループ名 | バックスラッシュで階層指定可能 |
| ExcludeGroup | string[] | No | 除外するグループ名 | - |
| Id | int[] | No | 内部ID番号でフィルタリング | - |
| IncludeSelf | switch | No | CMSインスタンス自体を結果に含める | - |
| ResolveNetworkName | switch | No | DNS解決を実行 | - |
| IncludeLocal | switch | No | ローカル登録サーバーも含める | デフォルト設定あり |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- Central Management Server（CMS）の登録サーバー情報
- ローカルSSMS登録サーバー（RegSrvr.xmlファイル）
- Azure Data Studioの接続情報

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Name | string | 登録サーバーの表示名 |
| ServerName | string | SQL Server接続文字列 |
| Group | string | グループパス（バックスラッシュ区切り） |
| Description | string | 説明文 |
| Source | string | 取得元（Central Management Servers/Local Server Groups/Azure Data Studio） |
| ComputerName | string | NetBIOSコンピュータ名（ResolveNetworkName時） |
| FQDN | string | 完全修飾ドメイン名（ResolveNetworkName時） |
| IPAddress | string | IPアドレス（ResolveNetworkName時） |
| ConnectionString | string | 復号化されたパスワードを含む接続文字列 |
| SecureConnectionString | SecureString | セキュア接続文字列 |

### 出力先

- パイプライン出力（他のコマンドレットへの連携用）
- コンソール表示（Select-DefaultViewによるフォーマット）

## 処理フロー

### 処理シーケンス

```
1. 初期化処理
   └─ デフォルト表示プロパティの設定、Unprotect-String関数定義
2. SqlInstanceの処理
   └─ 各インスタンスに対してGet-DbaRegServerStoreで接続
3. ローカル登録サーバーの取得
   └─ SSMSのLocalFileStoreから登録サーバーを取得
4. Azure Data Studioの取得
   └─ AzureDataStudioConnectionStoreから接続情報を取得
5. フィルタリング適用
   └─ Name/ServerName/Pattern/ExcludeServerName/Idで絞り込み
6. グループ情報の付与
   └─ 各サーバーのグループパスを計算
7. 接続文字列のパスワード復号化
   └─ 暗号化されたパスワードを復号化
8. DNS解決（オプション）
   └─ ResolveNetworkName指定時にResolve-DbaNetworkNameを呼び出し
9. 結果出力
   └─ Select-DefaultViewで整形して出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance指定?}
    B -->|Yes| C[Get-DbaRegServerStoreでCMS接続]
    B -->|No| D[ローカルファイルストア取得]
    C --> E{Group指定?}
    E -->|Yes| F[Get-DbaRegServerGroupで取得]
    E -->|No| G[全サーバー取得]
    D --> H[SSMS登録サーバー取得]
    H --> I[Azure Data Studio取得]
    F --> J[フィルタリング処理]
    G --> J
    I --> J
    J --> K{Name/ServerName/Pattern?}
    K -->|Yes| L[フィルタ適用]
    K -->|No| M[次の処理]
    L --> M
    M --> N[グループ情報付与]
    N --> O{パスワード復号?}
    O -->|Yes| P[Unprotect-String実行]
    O -->|No| Q[スキップ]
    P --> R{ResolveNetworkName?}
    Q --> R
    R -->|Yes| S[DNS解決]
    R -->|No| T[結果出力]
    S --> T
    T --> U{IncludeSelf?}
    U -->|Yes| V[CMSインスタンス追加]
    U -->|No| W[終了]
    V --> W
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ローカル優先 | SqlInstance未指定時はローカル登録サーバーを返却 | SqlInstance未指定 |
| BR-002 | パスワード復号化 | ローカル登録サーバーのパスワードは復号化可能 | ConnectionStringWithEncryptedPassword存在時 |
| BR-003 | 正規表現パターン | PatternパラメータはNameとServerNameの両方にマッチ | Pattern指定時 |
| BR-004 | グループ階層 | グループパスはバックスラッシュで区切られた階層表現 | 常時 |
| BR-005 | IncludeLocal結合 | CMS指定時でもIncludeLocalでローカルサーバーを追加可能 | IncludeLocal指定時 |

### 計算ロジック

パスワード復号化ロジック（Unprotect-String関数）：
- Base64エンコードされた暗号化パスワードを取得
- Windows Data Protection API（DPAPI）で復号化
- 現在のユーザーコンテキストでのみ復号化可能

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

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

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

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

本機能はデータベーステーブルへの直接操作を行わない。SMOのRegisteredServersStoreを介してメタデータを読み取る。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 接続エラー | CMSへのアクセス失敗 | 接続情報、権限を確認 |
| - | DNS解決エラー | ResolveNetworkName失敗 | ネットワーク接続を確認 |

### リトライ仕様

DNS解決では2段階のリトライを実装：
1. Turboモードで試行
2. 失敗時は通常モードで再試行

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

トランザクション管理は不要（読み取り専用操作）。

## パフォーマンス要件

- ResolveNetworkName使用時はDNS解決のため処理時間が増加
- 大量のサーバー登録がある場合、フィルタリング処理に時間がかかる可能性

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

- パスワード復号化はDPAPIを使用し、現在のユーザーコンテキストでのみ可能
- 復号化されたパスワードはSecureStringとしても保持
- CMSへのアクセスにはWindows認証またはSQL認証が必要

## 備考

- 設定値`commands.get-dbaregserver.defaultcms`でデフォルトCMSを指定可能
- 設定値`commands.get-dbaregserver.includelocal`でIncludeLocalのデフォルトを制御可能

---

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

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

### 推奨読解順序

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

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

**読解のコツ**: RegisteredServerオブジェクトにAdd-Memberで動的プロパティを追加している点に注目。

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

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

**主要処理フロー**:
1. **155-173行目**: パラメータ定義
2. **174-195行目**: begin block - デフォルト表示プロパティ、Unprotect-String関数定義
3. **196-225行目**: CMS接続処理

#### Step 3: ローカル登録サーバー取得を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaRegServer.ps1 | `public/Get-DbaRegServer.ps1` | LocalFileStoreアクセス、Azure Data Studio処理 |

**主要処理フロー**:
- **227-276行目**: ローカルファイルストアとAzure Data Studio処理
- **229行目**: LocalFileStore.DomainInstanceNameでファイルパス取得
- **232-238行目**: リフレクションでInitChildObjectsメソッド呼び出し

#### Step 4: フィルタリングと出力を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaRegServer.ps1 | `public/Get-DbaRegServer.ps1` | フィルタリング処理、プロパティ追加 |

**主要処理フロー**:
- **278-301行目**: Name/ServerName/Pattern/ExcludeServerName/Idフィルタリング
- **303-376行目**: グループ情報付与、パスワード復号化、DNS解決
- **378-390行目**: 結果出力、IncludeSelf処理

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

```
Get-DbaRegServer
    │
    ├─ Get-DbaRegServerStore
    │      └─ CMS接続
    │
    ├─ Get-DbaRegServerGroup
    │      └─ グループ取得
    │
    ├─ Get-ADSConnection (内部関数)
    │      └─ Azure Data Studio接続情報
    │
    ├─ Get-RegServerGroupReverseParse (内部関数)
    │      └─ グループパス計算
    │
    ├─ Unprotect-String (ローカル関数)
    │      └─ パスワード復号化
    │
    └─ Resolve-DbaNetworkName
           └─ DNS解決
```

### データフロー図

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

SqlInstance ──────────▶ Get-DbaRegServerStore ──────┐
                                                    │
ローカルファイル ─────▶ LocalFileStore.Init ────────┼──▶ RegisteredServer[]
                                                    │
Azure Data Studio ────▶ AzureDataStudioStore ──────┘
                              │
                              ▼
                        フィルタリング
                              │
                              ▼
                        プロパティ追加
                              │
                              ▼
                        Select-DefaultView ──▶ 整形済み出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaRegServer.ps1 | `public/Get-DbaRegServer.ps1` | ソース | メイン機能実装 |
| Get-DbaRegServerStore.ps1 | `public/Get-DbaRegServerStore.ps1` | ソース | ストア取得 |
| Get-DbaRegServerGroup.ps1 | `public/Get-DbaRegServerGroup.ps1` | ソース | グループ取得 |
| Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | ソース | DNS解決 |
