# 機能設計書 468-Remove-DbaRegServerGroup

## 概要

本ドキュメントは、SQL Server Central Management Server (CMS)から登録済みサーバーグループを削除するRemove-DbaRegServerGroup機能の設計を記述する。

### 本機能の処理概要

Remove-DbaRegServerGroupは、Central Management Serverから指定されたサーバーグループを削除する機能である。削除対象グループ内のネストされたサブグループと登録済みサーバーも同時に削除される。

**業務上の目的・背景**：Central Management Serverは、複数のSQL Serverインスタンスを組織的に管理するための重要な機能である。環境の整理、廃止されたサーバーグループの削除、CMS構成の再編成などの場面で、不要になったサーバーグループを削除する必要がある。この機能により、DBAはスクリプトベースでCMSのクリーンアップを自動化でき、大規模な環境管理の効率化に貢献する。

**機能の利用シーン**：
- 廃止されたサーバーグループの削除
- CMS構成の整理・クリーンアップ
- テスト環境のサーバーグループ削除
- 自動化スクリプトでのCMS管理

**主要な処理内容**：
1. 削除対象のサーバーグループを特定（SqlInstanceとNameまたはInputObject）
2. ShouldProcessで確認（ConfirmImpact = 'High'）
3. Azure Data Studioのグループでないことを確認
4. SMOのDrop()またはScriptDrop()で削除を実行
5. 削除結果をPSCustomObjectで返却

**関連システム・外部連携**：Get-DbaRegServerGroupからパイプライン入力を受け取ることができる。SMOのRegisteredServers名前空間を使用する。

**権限による制御**：CMSへの書き込み権限が必要。通常はsysadminロールまたはCMS管理権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 146 | 登録済みサーバーグループ | 主機能 | 登録済みサーバーグループの削除 |

## 機能種別

DELETE / 削除

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | CMSが存在するSQL Serverインスタンス | - |
| SqlCredential | PSCredential | No | 代替認証情報 | - |
| Name | String[] | No | 削除するサーバーグループ名（Group エイリアス） | - |
| InputObject | Microsoft.SqlServer.Management.RegisteredServers.ServerGroup[] | No | 削除するServerGroupオブジェクト | ValueFromPipeline |
| EnableException | switch | No | 例外を直接スローするかどうか | - |

### 入力データソース

- パラメータ入力（SqlInstance、Name）
- パイプライン入力（ServerGroupオブジェクト）
- ローカル登録済みサーバー（SqlInstance未指定時）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | CMSホストのコンピュータ名（CMS使用時） |
| InstanceName | String | CMSのSQL Serverインスタンス名（CMS使用時） |
| SqlInstance | String | 完全なSQL Serverインスタンス名（CMS使用時） |
| Name | String | 削除されたサーバーグループ名 |
| Status | String | 削除結果（"Dropped"） |

### 出力先

- PowerShellパイプライン（標準出力）
- PSCustomObject

## 処理フロー

### 処理シーケンス

```
1. SqlInstanceが指定されている場合、Get-DbaRegServerGroupを呼び出し
   └─ ServerGroupオブジェクトをInputObjectに追加
2. SqlInstanceもInputObjectも未指定の場合
   └─ ローカル登録済みサーバーからグループを取得
3. 各ServerGroupオブジェクトに対して繰り返し処理
4. グループにIDがある場合（CMS）
   └─ Get-RegServerParentで親サーバーを取得
5. グループにIDがない場合（ローカル）
   └─ ターゲットを"Local Registered Servers"に設定
6. ShouldProcessで確認（ConfirmImpact = 'High'）
7. Azure Data Studioのグループでないことを確認
8. 削除実行
   ├─ CMS: ScriptDrop()でSQL生成・ExecuteNonQuery
   └─ ローカル: Drop()メソッド
9. 削除結果をPSCustomObjectで出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance指定?}
    B -->|Yes| C[Get-DbaRegServerGroup呼び出し]
    B -->|No| D{InputObject指定?}
    C --> E[ServerGroupループ開始]
    D -->|Yes| E
    D -->|No| F[ローカル登録済みサーバーから取得]
    F --> E
    E --> G{グループにID?}
    G -->|Yes| H[Get-RegServerParent]
    G -->|No| I[ターゲット=Local]
    H --> J{ShouldProcess確認}
    I --> J
    J -->|Yes| K{Azure Data Studio?}
    J -->|No| E
    K -->|Yes| L[Stop-Function: ADS非対応]
    K -->|No| M{グループにID?}
    L --> E
    M -->|Yes| N[ScriptDrop + ExecuteNonQuery]
    M -->|No| O[Drop]
    N --> P[接続切断]
    O --> Q[PSCustomObject出力]
    P --> Q
    Q --> E
    E --> R[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 確認必須 | ConfirmImpact='High'により削除前に確認を求める | 常に適用 |
| BR-002 | カスケード削除 | 削除されるグループ内のサブグループと登録済みサーバーも削除 | 常に適用 |
| BR-003 | Azure Data Studio非対応 | ADS由来のグループは削除不可 | Source="Azure Data Studio"時 |
| BR-004 | ローカル対応 | SqlInstance未指定時はローカル登録済みサーバーを対象 | SqlInstance未指定時 |
| BR-005 | パイプラインサポート | Get-DbaRegServerGroupからの出力をパイプラインで受け取り可能 | パイプライン使用時 |

### 計算ロジック

該当なし（削除機能のため）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| グループ削除 | msdb.dbo.sysmanagement_shared_server_groups | DELETE | サーバーグループの削除 |

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

SMOのScriptDrop()またはDrop()メソッドが内部的にT-SQLを生成・実行する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Azure Data Studioエラー | ADS由来のグループを削除しようとした | dbatools以外のツールで管理 |
| - | 親取得失敗 | Get-RegServerParentがnullを返す | CMSの接続状態を確認 |
| - | 削除失敗 | Drop/ScriptDrop実行時のエラー | エラーメッセージを確認 |

### リトライ仕様

リトライ処理は実装されていない。

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

SMOのDrop()またはScriptDrop()による単一操作。明示的なトランザクション管理は実装されていない。

## パフォーマンス要件

- メタデータ操作のため、軽量な処理
- 通常1秒未満で完了

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

- CMSへの書き込み権限が必要
- ShouldProcess（ConfirmImpact='High'）による確認機能を提供
- SqlCredentialパラメータによる安全な認証情報の受け渡し

## 備考

- Azure Data Studioの登録済みサーバーグループは操作不可
- サブグループと登録済みサーバーも同時に削除されるため注意
- -Confirm:$falseで確認をスキップ可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Remove-DbaRegServerGroup.ps1 | `public/Remove-DbaRegServerGroup.ps1` | .OUTPUTSセクション（46-62行目）で出力オブジェクトの構造を確認 |

**読解のコツ**: 出力はPSCustomObject。CMSとローカルで表示プロパティが異なる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Remove-DbaRegServerGroup.ps1 | `public/Remove-DbaRegServerGroup.ps1` | processブロック（88-136行目）がメイン処理 |

**主要処理フロー**:
1. **89-91行目**: SqlInstance指定時はGet-DbaRegServerGroupを呼び出してInputObjectに追加
2. **93-95行目**: SqlInstanceもInputObjectも未指定時はローカルから取得
3. **97行目**: ServerGroupループ開始
4. **98-108行目**: グループにIDがあればCMS処理、なければローカル処理を設定
5. **110-113行目**: Azure Data Studioチェック
6. **115-121行目**: CMS: ScriptDrop()でSQL生成・ExecuteNonQuery
7. **120行目**: ローカル: Drop()メソッド
8. **123-131行目**: PSCustomObjectで結果出力

#### Step 3: 依存関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaRegServerGroup.ps1 | `public/Get-DbaRegServerGroup.ps1` | ServerGroupオブジェクトの取得方法 |
| 3-2 | Get-RegServerParent | `private/functions/Get-RegServerParent.ps1` | 親サーバー接続の取得方法 |

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

```
Remove-DbaRegServerGroup
    │
    ├─ Get-DbaRegServerGroup (SqlInstance指定時)
    │
    ├─ Get-DbaRegServerGroup (ローカル、SqlInstance/InputObject未指定時)
    │
    ├─ Get-RegServerParent (CMS時)
    │      └─ 親ServerConnection取得
    │
    ├─ ScriptDrop().GetScript() (CMS時)
    │      └─ 削除SQL生成
    │
    ├─ ExecuteNonQuery (CMS時)
    │      └─ SQL実行
    │
    ├─ Drop() (ローカル時)
    │
    └─ Select-DefaultView (結果出力)
```

### データフロー図

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

SqlInstance + Name ────▶ Get-DbaRegServerGroup ───▶ ServerGroup
       or                        │
InputObject (pipeline) ──────────┤
       or                        │
ローカル ─────────────────────────┘
                                 │
                                 ▼
                        Get-RegServerParent (CMS)
                                 │
                                 ▼
                        Azure Data Studio チェック
                                 │
                    ┌────────────┴────────────┐
                    ▼                          ▼
            CMS: ScriptDrop              ローカル: Drop
            + ExecuteNonQuery
                    │                          │
                    └──────────┬───────────────┘
                               ▼
                       PSCustomObject ────▶ 削除結果
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Remove-DbaRegServerGroup.ps1 | `public/Remove-DbaRegServerGroup.ps1` | ソース | 本機能のメイン実装 |
| Get-DbaRegServerGroup.ps1 | `public/Get-DbaRegServerGroup.ps1` | ソース | ServerGroupオブジェクト取得 |
| Get-RegServerParent.ps1 | `private/functions/Get-RegServerParent.ps1` | ソース | 親サーバー接続取得 |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラーハンドリング |
| Select-DefaultView.ps1 | `private/functions/Select-DefaultView.ps1` | ソース | デフォルト表示プロパティ設定 |
