# 機能設計書 216-Set-DbaAvailabilityGroup

## 概要

本ドキュメントは、SQL Server可用性グループの構成設定を変更するSet-DbaAvailabilityGroup関数の機能設計書です。

### 本機能の処理概要

Set-DbaAvailabilityGroupは、既存の可用性グループの構成プロパティを変更し、AG設定全体をスクリプト化して再作成する必要なく設定を更新できます。DTC（分散トランザクション）サポートの有効化、レプリカ間のバックアップ優先度の調整、自動フェールオーバーの障害条件レベルの構成、監視用のヘルスチェックタイムアウトの設定などに使用されます。

**業務上の目的・背景**：可用性グループは、高可用性・災害復旧ソリューションの中核ですが、運用中に設定変更が必要になることがあります。SQL Server Management StudioやT-SQL ALTER AVAILABILITY GROUP文を使用する代わりに、本機能を使用することで、複数のAGに対する設定変更を効率的に実行できます。

**機能の利用シーン**：
- 分散トランザクションを使用するアプリケーション用にDTCサポートを有効化する場合
- バックアップ負荷をセカンダリレプリカにオフロードする設定を変更する場合
- フェールオーバー感度を調整する場合
- ヘルスチェックタイムアウトを環境に合わせて調整する場合

**主要な処理内容**：
1. 対象可用性グループの取得（SqlInstanceまたはInputObject）
2. 指定されたプロパティの更新
3. SMO Alter()メソッドによる変更の適用
4. 更新された可用性グループオブジェクトの出力

**関連システム・外部連携**：
- SQL Server Management Objects (SMO)
- Windows Server Failover Clustering (WSFC)

**権限による制御**：可用性グループに対するALTER ANY AVAILABILITY GROUP権限が必要です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIインターフェース | 主画面 | コマンドライン実行 |

## 機能種別

構成変更 / 高可用性管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | SQL Server 2012以降 |
| SqlCredential | PSCredential | No | 認証用資格情報 | PSCredential型 |
| AvailabilityGroup | string[] | No | 変更する可用性グループ名 | 文字列配列 |
| AllAvailabilityGroups | switch | No | すべての可用性グループを対象 | スイッチ型 |
| DtcSupportEnabled | switch | No | DTC分散トランザクションサポート | スイッチ型 |
| ClusterType | string | No | クラスタリング技術 | Wsfc, External, None（SQL 2017+） |
| AutomatedBackupPreference | string | No | バックアップ優先度 | None, Primary, Secondary, SecondaryOnly |
| FailureConditionLevel | string | No | 障害条件レベル | OnServerDown〜OnAnyQualifiedFailureCondition |
| HealthCheckTimeout | int | No | ヘルスチェックタイムアウト（ミリ秒） | 整数 |
| BasicAvailabilityGroup | switch | No | Basic AGとして構成 | スイッチ型 |
| DatabaseHealthTrigger | switch | No | データベースヘルストリガー | スイッチ型 |
| IsDistributedAvailabilityGroup | switch | No | 分散AG | スイッチ型 |
| ClusterConnectionOption | string | No | クラスター接続オプション | SQL 2025+、TDS 8.0設定 |
| InputObject | AvailabilityGroup[] | No | パイプライン入力 | SMO AvailabilityGroupオブジェクト |
| EnableException | switch | No | 例外を有効化 | スイッチ型 |
| WhatIf | switch | No | 実行シミュレーション | スイッチ型 |
| Confirm | switch | No | 確認プロンプト | スイッチ型 |

### 入力データソース

- SqlInstance指定によるAG取得
- Get-DbaAvailabilityGroupからのパイプライン入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| AvailabilityGroup | Microsoft.SqlServer.Management.Smo.AvailabilityGroup | 更新された可用性グループオブジェクト |

### 出力先

- パイプライン出力

## 処理フロー

### 処理シーケンス

```
1. 入力検証
   ├─ SqlInstance/InputObjectのいずれかを確認
   └─ SqlInstance使用時はAvailabilityGroup/AllAvailabilityGroupsを確認

2. 可用性グループの取得
   └─ Get-DbaAvailabilityGroupで対象AG取得

3. プロパティ更新ループ
   ├─ 各プロパティの変更判定（Test-Bound）
   ├─ ClusterConnectionOption（SQL 2025+チェック）
   └─ AG.Alter()で変更を適用

4. 更新されたオブジェクトの出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance or InputObject?}
    B -->|Neither| C[エラー終了]
    B -->|SqlInstance| D{AG or All指定?}
    D -->|Neither| C
    D -->|Yes| E[Get-DbaAvailabilityGroup]
    B -->|InputObject| F[InputObjectを使用]

    E --> F
    F --> G[各AGをループ]

    G --> H{ShouldProcess確認}
    H -->|No| I[スキップ]
    H -->|Yes| J[プロパティ更新]

    J --> K{ClusterConnectionOption?}
    K -->|Yes| L{SQL 2025+?}
    L -->|Yes| M[ClusterConnectionOptions設定]
    L -->|No| N[警告メッセージ]
    K -->|No| O[AG.Alter実行]
    M --> O
    N --> O

    O --> P[AGオブジェクト出力]
    I --> Q{次のAG?}
    P --> Q
    Q -->|Yes| G
    Q -->|No| R[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 入力必須 | SqlInstanceまたはInputObjectのいずれかが必須 | 常時 |
| BR-002 | AG指定必須 | SqlInstance使用時はAGまたはAll指定が必須 | SqlInstance指定時 |
| BR-003 | ClusterTypeバージョン制約 | SQL Server 2017以降でのみサポート | ClusterType指定時 |
| BR-004 | ClusterConnectionOptionバージョン制約 | SQL Server 2025以降でのみサポート | ClusterConnectionOption指定時 |
| BR-005 | 条件付きプロパティ更新 | Test-Boundでパラメータ指定を確認し、指定されたものだけ更新 | 常時 |

### 計算ロジック

該当なし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| AG設定変更 | sys.availability_groups | UPDATE | AG構成の更新 |

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

SMO経由でのALTER AVAILABILITY GROUP実行。直接テーブル操作ではない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 入力不足 | SqlInstance/InputObject両方未指定 | エラーメッセージ出力、処理終了 |
| - | AG指定不足 | SqlInstance使用時にAG未指定 | エラーメッセージ出力、処理終了 |
| - | バージョン制約 | ClusterConnectionOptionをSQL 2025未満で使用 | 警告メッセージ、スキップ |
| - | SMOエラー | AG.Alter()実行失敗 | Stop-Functionで継続処理 |

### リトライ仕様

リトライは行いません。エラー発生時は次のAGへ継続処理します。

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

SMOのAlter()メソッド内でトランザクション管理されます。

## パフォーマンス要件

特になし。AG設定変更は軽量な操作です。

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

- ALTER ANY AVAILABILITY GROUP権限が必要
- クラスター管理権限も必要になる場合がある
- DTCサポート有効化時はDTCサービスの構成も必要

## 備考

- SQL Server 2012以降でサポート
- ClusterType: SQL Server 2017以降
- ClusterConnectionOption: SQL Server 2025以降（TDS 8.0サポート）
- 変更はWSFCレジストリに永続化

---

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

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

### 推奨読解順序

#### Step 1: パラメータと検証ロジックを理解する

関数のエントリーポイントと入力検証を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Set-DbaAvailabilityGroup.ps1 | `public/Set-DbaAvailabilityGroup.ps1` 150-171行目 | パラメータ定義、ValidateSet |

**読解のコツ**: ValidateSetで許可される値が定義されており、SMO列挙型と対応しています。

#### Step 2: 入力検証処理を理解する

SqlInstanceとInputObjectの検証ロジックを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Set-DbaAvailabilityGroup.ps1 | `public/Set-DbaAvailabilityGroup.ps1` 172-184行目 | 入力検証ロジック |

**主要処理フロー**:
1. **173-176行目**: SqlInstance/InputObject両方未指定チェック
2. **178-181行目**: SqlInstance指定時のAG/All未指定チェック
3. **182-184行目**: SqlInstance指定時のGet-DbaAvailabilityGroup呼び出し

#### Step 3: プロパティ更新処理を理解する

各AGに対するプロパティ更新ロジックを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbaAvailabilityGroup.ps1 | `public/Set-DbaAvailabilityGroup.ps1` 185-212行目 | プロパティ設定、Alter実行 |

**主要処理フロー**:
- **185行目**: Select-DefaultViewで出力プロパティ定義
- **187-194行目**: 各プロパティの条件付き更新（Test-Boundでパラメータ指定確認）
- **196-203行目**: ClusterConnectionOptionのバージョンチェック（SQL 2025+）
- **205行目**: AG.Alter()で変更適用
- **206行目**: AGオブジェクト出力

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

```
Set-DbaAvailabilityGroup
    │
    ├─ Test-Bound (パラメータ指定確認)
    │
    ├─ Get-DbaAvailabilityGroup (AG取得)
    │      └─ Connect-DbaInstance
    │
    ├─ Get-Variable (パラメータ値取得)
    │
    ├─ AvailabilityGroup.Alter() (SMO更新)
    │
    └─ Stop-Function (エラー処理)
```

### データフロー図

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

SqlInstance        ───▶ Get-DbaAvailabilityGroup  ───▶
     or                       │
InputObject                   ▼
               ───▶ プロパティ設定           ───▶
                    (Test-Bound判定)
                              │
                              ▼
               ───▶ AG.Alter()              ───▶ AvailabilityGroup[]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Set-DbaAvailabilityGroup.ps1 | `public/Set-DbaAvailabilityGroup.ps1` | ソース | メイン関数 |
| Get-DbaAvailabilityGroup.ps1 | `public/Get-DbaAvailabilityGroup.ps1` | ソース | AG取得 |
| Test-Bound.ps1 | `private/functions/Test-Bound.ps1` | ソース | パラメータ指定確認 |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラー処理 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
