# 画面設計書：HADR設定

## 1. 基本情報

| 項目 | 内容 |
|------|------|
| 画面ID | 7 |
| 画面名 | HADR設定 |
| 画面種別 | CLI（コマンドラインインターフェース） |
| カテゴリ | AvailabilityGroup |
| 関連ファイル | public/Get-DbaAgHadr.ps1, public/Enable-DbaAgHadr.ps1, public/Disable-DbaAgHadr.ps1 |

## 2. 概要・目的

HADR設定は、SQL Server AlwaysOn可用性グループの前提条件となるHADR（High Availability Disaster Recovery）サービス設定を管理するPowerShellコマンド群です。

可用性グループを作成する前に、SQL Serverインスタンス上でHADR機能を有効化する必要があります。本コマンド群により以下の操作が可能です：
- HADRサービス設定の現在の状態を確認
- HADRサービスの有効化
- HADRサービスの無効化

**重要**: HADR設定の変更は、SQL Serverサービスの再起動後に有効になります。

## 3. 主要機能

### 3.1 Get-DbaAgHadr

SQL ServerインスタンスのHADRサービス状態を取得します。

**入力パラメータ：**

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| SqlInstance | DbaInstanceParameter[] | はい | - | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | いいえ | - | 代替認証情報 |
| EnableException | switch | いいえ | false | 例外を有効化 |

**出力プロパティ：**

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | SQL Serverインスタンス名 |
| IsHadrEnabled | bool | HADRが有効かどうか |

### 3.2 Enable-DbaAgHadr

SQL ServerインスタンスでHADRサービスを有効化します。

**入力パラメータ：**

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| SqlInstance | DbaInstanceParameter[] | はい | - | 対象SQL Serverインスタンス |
| Credential | PSCredential | いいえ | - | Windows認証情報 |
| Force | switch | いいえ | false | サービス自動再起動 |
| EnableException | switch | いいえ | false | 例外を有効化 |
| WhatIf | switch | いいえ | - | 実行せずに結果を表示 |
| Confirm | switch | いいえ | - | 実行前に確認プロンプト |

**出力プロパティ：**

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | SQL Serverインスタンス名 |
| IsHadrEnabled | bool | 常にtrue（有効化成功時） |

### 3.3 Disable-DbaAgHadr

SQL ServerインスタンスでHADRサービスを無効化します。

**入力パラメータ：**

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| SqlInstance | DbaInstanceParameter[] | はい | - | 対象SQL Serverインスタンス |
| Credential | PSCredential | いいえ | - | Windows認証情報 |
| Force | switch | いいえ | false | サービス自動再起動 |
| EnableException | switch | いいえ | false | 例外を有効化 |
| WhatIf | switch | いいえ | - | 実行せずに結果を表示 |
| Confirm | switch | いいえ | - | 実行前に確認プロンプト |

**出力プロパティ：**

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | SQL Serverインスタンス名 |
| IsHadrEnabled | bool | 常にfalse（無効化成功時） |

## 4. 処理フロー

### 4.1 Get-DbaAgHadr

```
[開始]
   ↓
[インスタンス接続]
   ├── Connect-DbaInstanceで接続
   ↓
[HADR状態取得]
   ├── server.IsHadrEnabledプロパティ取得
   ↓
[結果出力]
   ├── ComputerName, InstanceName, SqlInstance, IsHadrEnabled
   ↓
[終了]
```

### 4.2 Enable-DbaAgHadr

```
[開始]
   ↓
[権限確認]
   ├── Test-ElevationRequirementで管理者権限確認
   ↓
[現在の状態取得]
   ├── Get-WmiHadrで現在のHADR状態取得
   ↓
[HADR設定変更]
   ├── Invoke-ManagedComputerCommand実行
   ├── ChangeHadrServiceSetting(1)でHADR有効化
   ↓
[サービス再起動]（Force指定時）
   ├── Stop-DbaServiceでEngine/Agent停止
   ├── Start-DbaServiceでEngine/Agent開始
   ↓
[新しい状態取得]
   ├── Get-WmiHadrで変更後状態取得
   ↓
[警告表示]（Force未指定時）
   ├── 再起動が必要な旨を警告
   ↓
[結果出力]
   ├── IsHadrEnabled = true
   ↓
[終了]
```

### 4.3 Disable-DbaAgHadr

```
[開始]
   ↓
[権限確認]
   ├── Test-ElevationRequirementで管理者権限確認
   ↓
[現在の状態取得]
   ├── Get-WmiHadrで現在のHADR状態取得
   ↓
[HADR設定変更]
   ├── Invoke-ManagedComputerCommand実行
   ├── ChangeHadrServiceSetting(0)でHADR無効化
   ↓
[サービス再起動]（Force指定時）
   ├── Stop-DbaServiceでEngine/Agent停止
   ├── Start-DbaServiceでEngine/Agent開始
   ↓
[新しい状態取得]
   ├── Get-WmiHadrで変更後状態取得
   ↓
[警告表示]（Force未指定時）
   ├── 再起動が必要な旨を警告
   ↓
[結果出力]
   ├── IsHadrEnabled = false
   ↓
[終了]
```

## 5. WMIメソッドマッピング

| 操作 | メソッド | パラメータ |
|------|---------|----------|
| HADR有効化 | ChangeHadrServiceSetting() | 1 |
| HADR無効化 | ChangeHadrServiceSetting() | 0 |

## 6. バリデーションルール

### 6.1 権限要件

- Windows管理者権限が必要（Test-ElevationRequirement）
- WMI経由でSQL Serverサービスにアクセスするため

### 6.2 前提条件

- SQL Server 2012以降（Enterprise Edition）
- Windows Server 2012以降
- Windows Server Failover Clustering（WSFC）が構成済み

## 7. エラーハンドリング

| エラー条件 | メッセージ | 対処 |
|-----------|----------|------|
| 接続エラー | "Failure" | インスタンス接続確認 |
| HADR状態取得失敗 | "Failure to pull current state of Hadr setting on $computer" | WMI接続確認 |
| HADR設定変更失敗（Enable） | "Failed to enable HADR on $instance: ... AlwaysOn Availability Groups requires Enterprise Edition..." | エディション・OS・WSFC確認 |
| HADR設定変更失敗（Disable） | "Failure on $instance | This may be because AlwaysOn Availability Groups feature requires..." | 同上 |
| サービス再起動失敗 | "Issue restarting $instance" | サービス状態確認 |

## 8. ConfirmImpact

- **Get-DbaAgHadr**: なし（読み取り専用）
- **Enable-DbaAgHadr**: High（サービス再起動の可能性）
- **Disable-DbaAgHadr**: High（サービス再起動の可能性）

## 9. 使用例

### 9.1 HADR状態確認

```powershell
Get-DbaAgHadr -SqlInstance sql2016
```

### 9.2 HADR有効化（サービス再起動は後で）

```powershell
Enable-DbaAgHadr -SqlInstance sql2016
```

設定は変更されますが、サービス再起動が必要です。

### 9.3 HADR有効化（即時適用）

```powershell
Enable-DbaAgHadr -SqlInstance sql2016 -Force
```

設定変更後、SQL ServerとSQL Agentサービスを自動再起動します。

### 9.4 HADR無効化

```powershell
Disable-DbaAgHadr -SqlInstance sql2016 -Force
```

### 9.5 名前付きインスタンスでのHADR無効化

```powershell
Disable-DbaAgHadr -SqlInstance sql2012\dev1 -Force
```

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

### 10.1 理解の順序

1. **Get-DbaAgHadr.ps1** - シンプルな状態取得を理解
2. **Enable-DbaAgHadr.ps1** - WMI経由での設定変更フローを把握
3. **Disable-DbaAgHadr.ps1** - Enable/Disableの対称構造を確認

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

```
Get-DbaAgHadr
├── Connect-DbaInstance (Line 61)
├── Add-Member (Lines 66-68)
└── Select-DefaultView (Line 70)

Enable-DbaAgHadr
├── Test-ElevationRequirement (Line 84)
├── Get-WmiHadr (Lines 99, 141)
├── Invoke-ManagedComputerCommand (Line 124)
│     └── ChangeHadrServiceSetting(1) (Line 118)
├── Stop-DbaService (Line 134)
└── Start-DbaService (Line 135)

Disable-DbaAgHadr
├── Test-ElevationRequirement (Line 82)
├── Get-WmiHadr (Lines 97, 138)
├── Invoke-ManagedComputerCommand (Line 123)
│     └── ChangeHadrServiceSetting(0) (Line 117)
├── Stop-DbaService (Line 131)
└── Start-DbaService (Line 132)
```

### 10.3 データフロー図

```
[ユーザー入力]
     │
     └── SqlInstance
              │
              ├─[Get-DbaAgHadr]────────────────────────────────────────┐
              │       │                                                │
              │       └── Connect-DbaInstance                         │
              │                 │                                      │
              │                 └── server.IsHadrEnabled ──────────────┼─→ [HADR状態]
              │                                                        │
              ├─[Enable-DbaAgHadr]─────────────────────────────────────┤
              │       │                                                │
              │       ├── Test-ElevationRequirement                   │
              │       │                                                │
              │       ├── Get-WmiHadr (現在状態)                       │
              │       │                                                │
              │       ├── ChangeHadrServiceSetting(1)                 │
              │       │                                                │
              │       ├── [Force=true]                                 │
              │       │     ├── Stop-DbaService                       │
              │       │     └── Start-DbaService                      │
              │       │                                                │
              │       └── Get-WmiHadr (新状態) ─────────────────────────┼─→ [IsHadrEnabled=true]
              │                                                        │
              └─[Disable-DbaAgHadr]────────────────────────────────────┤
                      │                                                │
                      ├── Test-ElevationRequirement                   │
                      │                                                │
                      ├── Get-WmiHadr (現在状態)                       │
                      │                                                │
                      ├── ChangeHadrServiceSetting(0)                 │
                      │                                                │
                      ├── [Force=true]                                 │
                      │     ├── Stop-DbaService                       │
                      │     └── Start-DbaService                      │
                      │                                                │
                      └── Get-WmiHadr (新状態) ─────────────────────────┴─→ [IsHadrEnabled=false]
```

### 10.4 関連ファイル一覧

| ファイルパス | 役割 | 行数 |
|-------------|------|------|
| public/Get-DbaAgHadr.ps1 | HADR状態取得 | 73 |
| public/Enable-DbaAgHadr.ps1 | HADR有効化 | 155 |
| public/Disable-DbaAgHadr.ps1 | HADR無効化 | 153 |
| internal/functions/Get-WmiHadr.ps1 | WMI経由HADR取得（依存） | - |
| internal/functions/Invoke-ManagedComputerCommand.ps1 | WMIコマンド実行（依存） | - |
| public/Stop-DbaService.ps1 | サービス停止（依存） | - |
| public/Start-DbaService.ps1 | サービス開始（依存） | - |

### 10.5 重要コードポイント

#### WMI経由でのHADR設定変更（Enable-DbaAgHadr.ps1: Lines 115-119）
```powershell
$scriptBlock = {
    $instance = $args[0]
    $sqlService = $wmi.Services | Where-Object DisplayName -eq "SQL Server ($instance)"
    $sqlService.ChangeHadrServiceSetting(1)
}
```

#### サービス再起動（Enable-DbaAgHadr.ps1: Lines 131-140）
```powershell
if (Test-Bound -ParameterName Force) {
    $null = Stop-DbaService -ComputerName $computerFullName -InstanceName $instanceName -Type Agent, Engine
    $null = Start-DbaService -ComputerName $computerFullName -InstanceName $instanceName -Type Agent, Engine
}
```

#### 再起動必要警告（Enable-DbaAgHadr.ps1: Lines 143-145）
```powershell
if (Test-Bound -Not -ParameterName Force) {
    Write-Message -Level Warning -Message "You must restart the SQL Server for it to take effect."
}
```

## 11. 権限要件

| 操作 | 必要な権限 |
|------|----------|
| Get-DbaAgHadr | SQL Server接続権限 |
| Enable-DbaAgHadr | Windows管理者権限、SQL Serverサービス管理権限 |
| Disable-DbaAgHadr | Windows管理者権限、SQL Serverサービス管理権限 |

## 12. 注意事項

- HADR設定変更後は、SQL Serverサービスの再起動が必要
- `-Force`パラメータ使用時はサービスが自動再起動されるため、接続中のセッションは切断される
- Enterprise Editionが必要（Standard EditionのBasic AGは2016以降で対応）
- WSFCが正しく構成されている必要がある

## 13. 関連コマンド

- Get-DbaAvailabilityGroup - 可用性グループ取得
- New-DbaAvailabilityGroup - 可用性グループ作成
- Stop-DbaService - SQL Serverサービス停止
- Start-DbaService - SQL Serverサービス開始
