# 機能設計書 13-Get-DbaAgHadr

## 概要

本ドキュメントは、SQL ServerインスタンスのHigh Availability Disaster Recovery (HADR) サービス状態を取得するGet-DbaAgHadrコマンドの機能設計書です。

### 本機能の処理概要

Get-DbaAgHadrは、SQL ServerインスタンスでAvailability Groups機能が有効になっているかどうかを確認するPowerShellコマンドレットです。各インスタンスのコンピュータ名、インスタンス名、およびHADR有効状態（true/false）を返します。

**業務上の目的・背景**：可用性グループを構成する前に、HADRがサービスレベルで有効になっている必要があります。このコマンドは、環境監査やAGセットアップ時のトラブルシューティングに役立ち、複数のインスタンスにまたがるHADR設定状態を効率的に確認できます。手動でSQL Server構成マネージャーや各インスタンスのプロパティを確認する必要がなくなります。

**機能の利用シーン**：
- 可用性グループ構成前の前提条件確認
- 環境全体のHADR設定状況の監査
- AGセットアップ問題のトラブルシューティング
- インフラストラクチャドキュメンテーション
- 自動化スクリプトでの前提条件チェック

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスに接続
2. サーバーオブジェクトのIsHadrEnabledプロパティを取得
3. インスタンス情報とHADR状態を含むオブジェクトを出力

**関連システム・外部連携**：
- SQL Server SMO (Server Management Objects)
- SQL Server構成マネージャー（設定変更時）
- Windows Server Failover Clustering (WSFC)

**権限による制御**：VIEW SERVER STATE権限またはCONNECT ANY DATABASE権限が必要です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | PowerShellコンソール/ISE | 主画面 | コマンド実行 |
| - | SQL Server構成マネージャー | 参照画面 | HADR設定の視覚的確認 |

## 機能種別

SELECT（データ取得）/ 設定確認

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | インスタンス接続可能性検証 |
| SqlCredential | PSCredential | No | 代替認証資格情報 | 有効なPSCredentialオブジェクト |
| EnableException | switch | No | 例外を有効化（詳細エラー表示） | なし |

### 入力データソース

- PowerShellパラメータ入力
- パイプラインからのSqlInstanceパラメータ（ValueFromPipeline対応）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名（MSSQLSERVER または名前付きインスタンス） |
| SqlInstance | string | 完全なSQL Serverインスタンス識別子 |
| IsHadrEnabled | bool | HADRが有効（$true）または無効（$false） |

### 出力先

- PowerShellパイプライン（標準出力）
- オブジェクト型：SMO Serverオブジェクト（カスタムプロパティ付き）

## 処理フロー

### 処理シーケンス

```
1. 各インスタンスをforeach処理
   └─ SqlInstanceパラメータの各要素を処理
2. インスタンス接続
   └─ Connect-DbaInstanceでサーバーオブジェクト取得
3. エラー処理
   └─ 接続失敗時はStop-Functionで継続
4. プロパティ追加
   └─ Add-MemberでComputerName等を追加
5. 出力
   └─ Select-DefaultViewでフォーマット出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[各SqlInstanceをforeach]
    B --> C[Connect-DbaInstance呼び出し]
    C --> D{接続成功?}
    D -->|No| E[Stop-Function: ConnectionError]
    E --> B
    D -->|Yes| F[Add-Member: ComputerName]
    F --> G[Add-Member: InstanceName]
    G --> H[Add-Member: SqlInstance]
    H --> I[Select-DefaultView出力]
    I --> B
    B -->|完了| J[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | パラメータ必須 | SqlInstanceは必須パラメータ | 常時 |
| BR-02 | 接続継続 | 一部インスタンス接続失敗時も他インスタンスは処理継続 | 複数インスタンス指定時 |
| BR-03 | パイプライン対応 | SqlInstanceはパイプラインから受け取り可能 | パイプライン使用時 |

### 計算ロジック

特になし（プロパティ取得のみ）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| HADR状態取得 | サーバープロパティ | SELECT | SMO経由でIsHadrEnabledプロパティ取得 |

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

本コマンドはSMOのサーバーオブジェクトプロパティを使用し、直接T-SQLは発行しません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | インスタンス接続失敗 | 接続情報・ネットワーク確認 |

### リトライ仕様

リトライ機能なし。接続失敗時は次のインスタンスに継続。

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

読み取り専用操作のため、トランザクション管理なし

## パフォーマンス要件

- 単一インスタンスの場合：接続時間 + 数ミリ秒
- 複数インスタンスの場合：インスタンス数に比例

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

- Windows認証/SQL認証/AD認証対応
- SqlCredentialによる資格情報の安全な受け渡し
- VIEW SERVER STATE権限推奨

## 備考

- SQL Server 2012以上で可用性グループ機能が利用可能
- HADRを有効にするにはSQL Server構成マネージャーまたはEnable-DbaAgHadrを使用

---

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

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

### 推奨読解順序

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

SMO ServerオブジェクトのIsHadrEnabledプロパティが主要なデータです。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaAgHadr.ps1 | `public/Get-DbaAgHadr.ps1` | 出力プロパティ（70行目のSelect-DefaultView） |

**読解のコツ**: 非常にシンプルなコマンドです。SMOサーバーオブジェクトにAdd-Memberでプロパティを追加し、Select-DefaultViewで出力をフォーマットしています。

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

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

**主要処理フロー**:
1. **59行目**: SqlInstanceのforeachループ開始
2. **60-64行目**: Connect-DbaInstanceでサーバーオブジェクト取得、エラー時は継続
3. **66-68行目**: Add-Memberでプロパティ追加
4. **70行目**: Select-DefaultViewで出力

#### Step 3: 依存コマンドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | インスタンス接続処理 |

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

```
Get-DbaAgHadr
    │
    ├─ Connect-DbaInstance (インスタンス接続)
    │      └─ 認証処理・SMOサーバーオブジェクト生成
    │
    ├─ Add-Member (プロパティ追加)
    │
    └─ Select-DefaultView (出力フォーマット)
```

### データフロー図

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

SqlInstance ───▶ Connect-DbaInstance ───▶ SMO Server Object
                                                 │
                                           Add-Member
                                                 │
                                    ┌────────────┴────────────┐
                                    │ ComputerName            │
                                    │ InstanceName            │
                                    │ SqlInstance             │
                                    │ IsHadrEnabled (既存)    │
                                    └────────────┬────────────┘
                                                 │
                                       Select-DefaultView ───▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaAgHadr.ps1 | `public/Get-DbaAgHadr.ps1` | ソース | メインコマンド実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続依存コマンド |
| Get-DbaAgHadr.Tests.ps1 | `tests/Get-DbaAgHadr.Tests.ps1` | テスト | 単体・統合テスト |
| Enable-DbaAgHadr.ps1 | `public/Enable-DbaAgHadr.ps1` | ソース | HADR有効化コマンド（関連） |
| Disable-DbaAgHadr.ps1 | `public/Disable-DbaAgHadr.ps1` | ソース | HADR無効化コマンド（関連） |
