# 機能設計書 10-Enable-DbaAgHadr

## 概要

本ドキュメントは、dbatools PowerShellモジュールのEnable-DbaAgHadr機能の設計仕様を定義する。本機能は、SQL ServerインスタンスのHADR（High Availability Disaster Recovery）サービス設定を有効化し、可用性グループへの参加を可能にする。

### 本機能の処理概要

Enable-DbaAgHadrは、SQL ServerインスタンスのHADRサービス設定を有効化するPowerShellコマンドである。この設定変更により、インスタンスは可用性グループに参加できるようになる。設定変更はWMI経由で行われ、反映にはSQL Serverサービスの再起動が必要である。

**業務上の目的・背景**：可用性グループを構成する前提条件として、参加するすべてのSQL ServerインスタンスでHADR機能を有効化する必要がある。手動での設定変更はSQL Server構成マネージャーを使用する必要があり、多数のサーバーへの適用や自動化が困難である。本機能は、PowerShellからHADR設定を制御し、AG構築の自動化を可能にする。

**機能の利用シーン**：
- 新規可用性グループ構築の事前準備
- 新サーバーの可用性グループ参加準備
- DR環境の構築
- インフラ自動化スクリプトでの使用

**主要な処理内容**：
1. 対象インスタンスへの接続
2. 現在のHADR状態の確認（WMI経由）
3. HADR設定の有効化（ChangeHadrServiceSetting(1)）
4. オプションでサービス再起動（-Force時）
5. 新しいHADR状態の確認と出力

**関連システム・外部連携**：
- SQL Server WMI Provider
- Windows Service Control Manager
- Windows Server Failover Cluster

**権限による制御**：
- 対象サーバーへのリモート管理権限
- SQL Server構成の変更権限
- サービス制御権限（-Force時）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 7 | HADR設定 | 主機能 | AlwaysOn HADR機能の有効化 |

## 機能種別

インフラストラクチャ管理 / サービス構成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | パイプライン対応 |
| Credential | PSCredential | No | Windows認証情報 | - |
| Force | switch | No | サービス自動再起動 | - |
| EnableException | switch | No | 例外有効化 | - |

### 入力データソース

- SQL Serverインスタンスへの接続情報
- パイプライン経由のインスタンス指定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| IsHadrEnabled | bool | HADR有効状態（常に$true） |

### 出力先

- PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. 管理者権限確認
   └─ Test-ElevationRequirement

2. 現在のHADR状態取得
   └─ Get-WmiHadr

3. HADR設定有効化
   └─ Invoke-ManagedComputerCommand
   └─ ChangeHadrServiceSetting(1)

4. サービス再起動（Force時）
   └─ Stop-DbaService（Agent, Engine）
   └─ Start-DbaService（Agent, Engine）

5. 新しいHADR状態取得
   └─ Get-WmiHadr

6. 結果出力
   └─ Force未指定時は再起動が必要な旨を警告
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Test-ElevationRequirement]
    B --> C{管理者権限?}
    C -->|No| Z[return]
    C -->|Yes| D[Get-WmiHadr]
    D --> E[現在のHADR状態取得]
    E --> F{ShouldProcess?}
    F -->|No| G[スキップ]
    F -->|Yes| H[Invoke-ManagedComputerCommand]
    H --> I[ChangeHadrServiceSetting/1/]
    I --> J{成功?}
    J -->|No| K[エラー: Enterprise Edition必要/WSFC必要等]
    J -->|Yes| L{Force指定?}
    K --> Z
    L -->|Yes| M[Stop-DbaService]
    M --> N[Start-DbaService]
    L -->|No| O[警告: 再起動必要]
    N --> P[Get-WmiHadr]
    O --> P
    P --> Q[結果出力]
    Q --> R[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 管理者権限必須 | リモート管理には管理者権限が必要 | 常時 |
| BR-02 | サービス再起動必要 | 設定変更の反映には再起動が必要 | 常時 |
| BR-03 | Enterprise Edition | HADR機能はEnterprise Editionが必要 | SQL Server 2012-2016 |
| BR-04 | WSFC要件 | WSFCクラスタが構成されている必要がある | 常時 |
| BR-05 | SQL Server 2012以上 | HADR機能はSQL Server 2012以降でサポート | 常時 |

### 計算ロジック

- 特になし

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

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

| 操作 | 対象 | 操作種別 | 概要 |
|-----|------|---------|------|
| HADR設定 | SQL Server構成 | UPDATE | サービス設定変更 |

### WMI操作詳細

| 操作 | メソッド | 引数 | 備考 |
|-----|---------|------|------|
| 有効化 | ChangeHadrServiceSetting | 1 | 有効化 |
| 無効化 | ChangeHadrServiceSetting | 0 | Disable-DbaAgHadrで使用 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ElevationError | 管理者権限なし | 管理者として実行 |
| - | ConnectionError | WMI接続失敗 | リモート管理設定確認 |
| - | EditionError | Enterprise Edition以外 | エディション確認 |
| - | WSFCError | WSFCクラスタ未構成 | WSFC構成確認 |
| - | ServiceError | サービス再起動失敗 | サービス状態確認 |

### リトライ仕様

- 本機能にリトライロジックは実装されていない

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

- サービス設定変更は即座に適用
- サービス再起動は別プロセス

## パフォーマンス要件

- WMI経由の設定変更は数秒
- サービス再起動には追加時間を要する

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

- リモート管理権限が必要
- Credentialパラメータで別ユーザーとして実行可能
- ConfirmImpact = "High"で確認プロンプト

## 備考

- SupportsShouldProcess対応
- Force指定でConfirmをスキップ
- コメントアウトされた状態チェックコード（WMI結果の信頼性問題）
- エラーメッセージにWSFC、Enterprise Edition要件を記載

---

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

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

### 推奨読解順序

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

パラメータ構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Enable-DbaAgHadr.ps1 | `public/Enable-DbaAgHadr.ps1` | param()ブロック（69-76行目） |
| 1-2 | Enable-DbaAgHadr.ps1 | `public/Enable-DbaAgHadr.ps1` | CmdletBinding属性（ConfirmImpact = "High"） |

**読解のコツ**: Disable-DbaAgHadrとほぼ同一の構造。ChangeHadrServiceSettingの引数が1（有効化）である点が異なる。

#### Step 2: 権限確認を理解する

管理者権限の確認ロジックを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Enable-DbaAgHadr.ps1 | `public/Enable-DbaAgHadr.ps1` | Test-ElevationRequirement呼び出し（84-86行目） |

**主要処理フロー**:
- **78行目**: Force時はConfirmPreferenceを'none'に
- **84-86行目**: Test-ElevationRequirementで権限確認

#### Step 3: HADR設定変更を理解する

WMI経由のHADR設定変更を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Enable-DbaAgHadr.ps1 | `public/Enable-DbaAgHadr.ps1` | Get-WmiHadrで現在状態取得（98-102行目） |
| 3-2 | Enable-DbaAgHadr.ps1 | `public/Enable-DbaAgHadr.ps1` | ScriptBlockでChangeHadrServiceSetting(1)（115-119行目） |
| 3-3 | Enable-DbaAgHadr.ps1 | `public/Enable-DbaAgHadr.ps1` | Invoke-ManagedComputerCommand実行（122-127行目） |

**主要処理フロー**:
- **115-119行目**: ScriptBlockで$wmi.Servicesからサービス取得、ChangeHadrServiceSetting(1)呼び出し
- **124行目**: Invoke-ManagedComputerCommandでリモート実行
- **126行目**: エラーメッセージにWSFC、Enterprise Edition要件を記載

#### Step 4: サービス再起動を理解する

Force時のサービス再起動処理を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Enable-DbaAgHadr.ps1 | `public/Enable-DbaAgHadr.ps1` | Force時のサービス再起動（131-140行目） |

**主要処理フロー**:
- **134行目**: Stop-DbaService（Agent, Engine）
- **135行目**: Start-DbaService（Agent, Engine）

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

```
Enable-DbaAgHadr
    │
    ├─ Test-ElevationRequirement (権限確認)
    │
    ├─ Get-WmiHadr (現在状態取得)
    │
    ├─ Invoke-ManagedComputerCommand
    │      └─ ChangeHadrServiceSetting(1)
    │
    ├─ Stop-DbaService (Force時)
    │      └─ Agent, Engine
    │
    ├─ Start-DbaService (Force時)
    │      └─ Agent, Engine
    │
    └─ Get-WmiHadr (新状態取得)
```

### データフロー図

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

SqlInstance ─────────────▶ Test-ElevationRequirement
                                  │
Credential ──────────────▶ Get-WmiHadr (現在状態)
                                  │
                          Invoke-ManagedComputerCommand
                          ChangeHadrServiceSetting(1)
                                  │
Force ───────────────────▶ {Force判定}
                                  │
                    ┌─────────────┴─────────────┐
                    ▼                           ▼
             [Force=True]                [Force=False]
             Stop/Start-DbaService       警告メッセージ
                    │                           │
                    └─────────────┬─────────────┘
                                  ▼
                          Get-WmiHadr (新状態)
                                  │
                                  ▼
                          PSCustomObject
                          (IsHadrEnabled=$true)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Enable-DbaAgHadr.ps1 | `public/Enable-DbaAgHadr.ps1` | ソース | メインコマンド実装 |
| Get-WmiHadr.ps1 | `private/Get-WmiHadr.ps1` | ソース | WMI HADR状態取得 |
| Invoke-ManagedComputerCommand.ps1 | `private/Invoke-ManagedComputerCommand.ps1` | ソース | WMIコマンド実行 |
| Stop-DbaService.ps1 | `public/Stop-DbaService.ps1` | ソース | サービス停止 |
| Start-DbaService.ps1 | `public/Start-DbaService.ps1` | ソース | サービス起動 |
| Test-ElevationRequirement.ps1 | `private/Test-ElevationRequirement.ps1` | ソース | 権限確認 |
