# 機能設計書 460-Get-DbaRegServerGroup

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける`Get-DbaRegServerGroup`関数の機能設計を定義する。この関数はSQL Server Central Management Server (CMS)またはローカル登録サーバーストアからサーバーグループオブジェクトを取得し、サーバー管理の階層構造を参照可能にする。

### 本機能の処理概要

**業務上の目的・背景**：Central Management Serverのサーバーグループは、複数のSQL Serverインスタンスを論理的に整理するための階層構造を提供する。本関数は、この階層構造を参照し、グループ内の登録サーバー一覧の取得や、グループ単位での一括操作の基盤となる情報を提供する。

**機能の利用シーン**：
- 既存のCMSグループ構造の確認時
- 登録サーバーの一括操作前のグループ特定時
- CMSインベントリのドキュメント化時
- 自動化スクリプトでの対象サーバーグループ取得時

**主要な処理内容**：
1. CMSインスタンスまたはローカルストアへの接続
2. 指定されたグループパス（バックスラッシュ記法対応）の解析
3. サーバーグループオブジェクトの取得
4. 除外グループのフィルタリング
5. ID指定によるグループ取得（ルートグループはID=1）

**関連システム・外部連携**：SQL Server Management Objects (SMO) RegisteredServers名前空間

**権限による制御**：CMSサーバーへの接続権限が必要。ローカル操作時は特別な権限不要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | SQL Server Management Studio - 登録済みサーバー | 参照画面 | サーバーグループ一覧表示に相当 |
| N/A | Azure Data Studio - サーバーグループ | 参照画面 | サーバーグループ参照 |

## 機能種別

CRUD操作（Read） / CMS構成参照

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | CMSサーバーSQL Serverインスタンス | パイプライン入力対応 |
| SqlCredential | PSCredential | No | SQL Server認証用資格情報 | 有効な認証情報 |
| Group | Object[] | No | 取得するグループ名（バックスラッシュでネスト可） | 有効なグループパス |
| ExcludeGroup | Object[] | No | 除外するグループ名 | 有効なグループパス |
| Id | Int[] | No | グループID（1=ルート） | 正の整数 |
| EnableException | Switch | No | 例外を有効化 | なし |

### 入力データソース

- パラメータ入力
- CMSサーバーまたはローカルストア

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | CMSホストのコンピュータ名（CMS接続時） |
| InstanceName | String | CMSインスタンス名（CMS接続時） |
| SqlInstance | String | フルCMSインスタンス名（CMS接続時） |
| Name | String | グループ名 |
| DisplayName | String | 表示名 |
| Description | String | グループ説明 |
| ServerGroups | Collection | 子グループコレクション |
| RegisteredServers | Collection | 登録サーバーコレクション |

### 出力先

パイプラインにMicrosoft.SqlServer.Management.RegisteredServers.ServerGroupオブジェクトを出力

## 処理フロー

### 処理シーケンス

```
1. サーバーストアの取得
   ├─ SqlInstance指定時: Get-DbaRegServerStoreでCMSストア取得
   └─ SqlInstance未指定時: ローカルストア取得
2. グループ取得処理
   ├─ Group指定時
   │   ├─ ServerGroupオブジェクトの場合: パス解析
   │   ├─ DatabaseEngineServerGroup\を含む場合: プレフィックス除去
   │   ├─ バックスラッシュを含む場合: 階層的に解析
   │   └─ 単一グループ名の場合: 直接取得
   ├─ Group未指定時: ルートの全サーバーグループを取得
   └─ Group = 'DatabaseEngineServerGroup'の場合: ルートグループ自体を取得
3. ExcludeGroupフィルタリング
   └─ 指定グループを除外
4. ID指定時の処理
   ├─ Id = 1: DatabaseEngineServerGroup（ルート）を取得
   └─ Id != 1: 登録サーバーの親グループからID一致を検索
5. 結果出力
   └─ NotePropertyでComputerName等を追加してSelect-DefaultView
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance指定?}
    B -->|Yes| C[Get-DbaRegServerStore]
    B -->|No| D[ローカルストア取得]
    C --> E[foreach serverstore]
    D --> E
    E --> F{Group指定?}
    F -->|Yes| G[foreach currentgroup]
    F -->|No| H[ルート全ServerGroups取得]
    G --> I{ServerGroupオブジェクト?}
    I -->|Yes| J[Get-RegServerGroupReverseParse]
    I -->|No| K{DatabaseEngineServerGroup\含む?}
    J --> L{バックスラッシュ含む?}
    K -->|Yes| M[プレフィックス除去]
    K -->|No| L
    M --> L
    L -->|Yes| N[階層的解析ループ]
    L -->|No| O[直接取得]
    N --> P[groups追加]
    O --> P
    H --> P
    P --> Q{Group = DatabaseEngineServerGroup?}
    Q -->|Yes| R[ルートグループ設定]
    Q -->|No| S{ExcludeGroup指定?}
    R --> S
    S -->|Yes| T[Urn比較で除外]
    S -->|No| U{Id指定?}
    T --> U
    U -->|Yes| V{Id = 1?}
    U -->|No| W[接続クローズ]
    V -->|Yes| X[DatabaseEngineServerGroup]
    V -->|No| Y[登録サーバー親からID検索]
    X --> Z[groups設定]
    Y --> Z
    W --> AA[foreach groupobject]
    Z --> AA
    AA --> AB[NoteProperty追加]
    AB --> AC[Select-DefaultView]
    AC --> AD[次のgroupobject]
    AD --> AA
    AA -->|完了| AE[次のserverstore]
    AE --> E
    E -->|完了| AF[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ルートグループID | ID=1は常にDatabaseEngineServerGroup（ルート）を指す | Id指定時 |
| BR-002 | ネストグループ対応 | バックスラッシュ（\）でグループパスを区切り、階層的に解析 | Groupにバックスラッシュ含む場合 |
| BR-003 | プレフィックス除去 | 'DatabaseEngineServerGroup\'は自動的に除去 | Groupパスに含まれる場合 |
| BR-004 | ローカルストアフォールバック | SqlInstance未指定時はローカルストアを使用 | SqlInstance未指定時 |
| BR-005 | 登録サーバー経由のID検索 | ID!=1の場合、登録サーバーの親グループから検索 | Id != 1 |

### 計算ロジック

特になし

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

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

本関数は読み取り専用操作であり、データベースへの変更は行わない。

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| グループ取得 | CMS内部ストア | SELECT | ServerGroupの取得 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | 接続エラー | CMSサーバー接続失敗 | 接続情報確認 |
| N/A | グループ不存在 | 指定グループが見つからない | グループ名確認 |

### リトライ仕様

本関数にリトライ機能は実装されていない。

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

読み取り専用操作であり、トランザクションは使用しない。

## パフォーマンス要件

グループ取得は即座に完了。多数のネストグループがある場合でも処理時間への影響は軽微。

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

- CMSサーバーへの適切な接続権限が必要
- SqlCredentialはSecureStringとして処理
- ローカルストア操作時はOSレベルのファイルアクセス権限のみ必要

## 備考

- 152行目の空のcatchブロックは意図的（グループ未存在時のエラー抑制）
- 接続後にServerConnection.Disconnect()でクリーンアップ
- ローカルストア参照時はComputerName/InstanceName/SqlInstanceは出力に含まれない

---

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

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

### 推奨読解順序

#### Step 1: 関数構造とパラメータを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaRegServerGroup.ps1 | `public/Get-DbaRegServerGroup.ps1` | param()ブロック（91-100行目） |

**読解のコツ**: すべてのパラメータがオプション。SqlInstance未指定時はローカルストアを使用。

#### Step 2: サーバーストア取得を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaRegServerGroup.ps1 | `public/Get-DbaRegServerGroup.ps1` | processブロック前半（104-116行目） |

**主要処理フロー**:
1. **105-111行目**: SqlInstance指定時のGet-DbaRegServerStore呼び出し
2. **113-115行目**: SqlInstance未指定時のローカルストア取得

#### Step 3: グループ解析ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaRegServerGroup.ps1 | `public/Get-DbaRegServerGroup.ps1` | Group処理（117-159行目） |

**主要処理フロー**:
- **118-155行目**: Group指定時の階層解析ループ
- **121-123行目**: ServerGroupオブジェクトの場合のパス解析
- **125-127行目**: DatabaseEngineServerGroup\プレフィックス除去
- **129-142行目**: バックスラッシュを含む場合の階層的解析

#### Step 4: フィルタリングとID検索を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaRegServerGroup.ps1 | `public/Get-DbaRegServerGroup.ps1` | フィルタ処理（166-179行目） |

**主要処理フロー**:
- **166-169行目**: ExcludeGroup指定時のUrn比較による除外
- **172-179行目**: ID指定時の処理（ID=1はルート、それ以外は登録サーバー経由検索）

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

```
Get-DbaRegServerGroup
    │
    ├─ [begin] $serverstores = @(), $groups = @()
    │
    └─ [process]
           │
           ├─ Get-DbaRegServerStore
           │      ├─ SqlInstance指定時: CMSストア取得
           │      └─ SqlInstance未指定時: ローカルストア取得
           │
           ├─ foreach (serverstore)
           │      │
           │      ├─ Group指定時
           │      │      ├─ Get-RegServerGroupReverseParse (ServerGroupの場合)
           │      │      ├─ DatabaseEngineServerGroup.ServerGroups[$name]
           │      │      └─ 階層的解析（バックスラッシュ分割）
           │      │
           │      ├─ Group未指定時
           │      │      └─ DatabaseEngineServerGroup.ServerGroups（全グループ）
           │      │
           │      ├─ ExcludeGroup処理
           │      │      └─ Get-DbaRegServerGroup再帰呼び出し
           │      │
           │      └─ Id指定時
           │             ├─ Id=1: DatabaseEngineServerGroup
           │             └─ Id!=1: GetDescendantRegisteredServers().Parent
           │
           └─ foreach (groupobject)
                  │
                  ├─ Add-Member (ComputerName, InstanceName, SqlInstance, ParentServer)
                  │
                  └─ Select-DefaultView
```

### データフロー図

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

SqlInstance ─────────────────▶ Get-DbaRegServerStore ────────────────▶ サーバーストア
                                   │
Group ───────────────────────▶ 階層解析 ─────────────────────────────▶ 対象グループ特定
                                   │
                             DatabaseEngineServerGroup ───────────────▶ グループオブジェクト
                             .ServerGroups[$name]                       │
                                   │                                    │
ExcludeGroup ────────────────▶ Urn比較フィルタ ──────────────────────▶ 除外処理
                                   │
Id ──────────────────────────▶ ID検索 ───────────────────────────────▶ 特定グループ
                                   │
                             Add-Member ──────────────────────────────▶ プロパティ追加
                                   │
                             Select-DefaultView ──────────────────────▶ ServerGroup
                                                                        オブジェクト
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaRegServerGroup.ps1 | `public/Get-DbaRegServerGroup.ps1` | ソース | メイン関数定義 |
| Get-DbaRegServerStore.ps1 | `public/Get-DbaRegServerStore.ps1` | ソース | ストアオブジェクト取得 |
| Add-DbaRegServerGroup.ps1 | `public/Add-DbaRegServerGroup.ps1` | ソース | 対となるグループ作成機能 |
| Remove-DbaRegServerGroup.ps1 | `public/Remove-DbaRegServerGroup.ps1` | ソース | グループ削除機能 |
| Get-DbaRegServer.ps1 | `public/Get-DbaRegServer.ps1` | ソース | 登録サーバー取得 |
