# 機能設計書 380-Get-DbaBuild

## 概要

本ドキュメントは、dbatools PowerShellモジュールのGet-DbaBuildコマンドの機能設計を定義する。このコマンドはSQL Serverのビルド番号から、サービスパック、累積更新プログラム、KB記事番号、およびサポートライフサイクル日付などの詳細情報を取得する機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：SQL Serverのパッチ管理とコンプライアンス管理において、各インスタンスにインストールされているサービスパックや累積更新プログラムの特定は重要な作業である。ビルド番号から対応するパッチレベルへの手動での変換は時間がかかり、エラーが発生しやすい。本コマンドは、オフラインおよびオンラインの参照インデックスを使用して、ビルド番号の意味を自動的に解釈し、サポート終了日などの重要な情報も提供する。

**機能の利用シーン**：
- SQL Serverパッチレベルの監査とコンプライアンスレポート
- サポート終了が近いビルドの特定
- KB番号からの対応ビルドの検索
- 特定のバージョン/SP/CU組み合わせのビルド番号確認
- 廃止されたビルドの警告表示

**主要な処理内容**：
1. ビルド参照インデックス（JSON）の読み込みと管理
2. 複数の入力方式のサポート（ビルド番号、KB番号、バージョン指定、SqlInstance）
3. ビルド情報の解決とマッチング
4. サポートライフサイクル情報の付与

**関連システム・外部連携**：
- SQL Server（SqlInstance指定時のConnect-DbaInstance）
- ローカルビルド参照インデックス（dbatools-buildref-index.json）
- オンライン更新（Update-DbaBuildReference）

**権限による制御**：SqlInstance指定時はSQL Server接続権限が必要。その他の入力方式では権限不要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | コマンドライン/PowerShell | 主画面 | コマンド実行とパラメータ指定 |

## 機能種別

データ取得 / ユーティリティ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Build | version[] | No | ビルド番号（例: "12.00.4502"） | - |
| Kb | string[] | No | KB記事番号（例: "KB4057119"または"4057119"） | - |
| MajorVersion | string | No | SQLメジャーバージョン（例: "SQL2016", "2016", "2008R2"） | 形式: SQL2XXXまたは2XXX |
| ServicePack | string | No | サービスパックレベル（例: "SP1", "1", "RTM"） | Alias: SP、デフォルト: "RTM" |
| CumulativeUpdate | string | No | 累積更新レベル（例: "CU5", "5"） | Alias: CU |
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス（パイプライン入力可） | - |
| SqlCredential | PSCredential | No | SQL Server接続用の代替資格情報 | - |
| Update | switch | No | オンラインでビルド参照インデックスを更新 | - |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- ローカルビルド参照インデックス: `$PSModuleRoot/bin/dbatools-buildref-index.json`
- ユーザー書き込み可能インデックス: `$DbatoolsData/dbatools-buildref-index.json`

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| SqlInstance | string | SQL Serverインスタンス名（SqlInstance指定時のみ） |
| Build | version | 完全なビルドバージョン番号 |
| NameLevel | string | SQL Server製品名（例: "SQL Server 2014"） |
| SPLevel | string | サービスパックレベル（例: "SP1", "RTM"） |
| CULevel | string | 累積更新レベル（例: "CU11"） |
| KBLevel | string[] | 関連するKB記事番号の配列 |
| BuildLevel | version | 正規化されたビルドバージョン |
| SupportedUntil | DateTime | Microsoftサポート終了日 |
| MatchType | string | マッチの精度（"Exact"または"Approximate"） |
| Warning | string | 廃止等の警告メッセージ（該当時のみ） |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. Begin ブロック: パラメータ検証とインデックス読み込み
   └─ 排他パラメータの検証
   └─ MajorVersion/ServicePack/CumulativeUpdateの形式正規化
   └─ Get-DbaBuildReferenceIndexでインデックス読み込み
   └─ Update指定時はオンライン更新

2. Process ブロック: ビルド情報の解決
   └─ SqlInstance指定時
      └─ Connect-DbaInstanceで接続
      └─ サーバーバージョンを取得してResolve-DbaBuild
   └─ Build指定時
      └─ 各ビルド番号をResolve-DbaBuild
   └─ Kb指定時
      └─ 各KB番号をResolve-DbaBuild
   └─ MajorVersion指定時
      └─ バージョン/SP/CUをResolve-DbaBuild
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[パラメータ検証]
    B --> C{排他パラメータ違反?}
    C -->|Yes| D[エラー出力]
    C -->|No| E[MajorVersion形式検証]
    E --> F[インデックス読み込み]
    F --> G{Update指定?}
    G -->|Yes| H[Update-DbaBuildReference]
    G -->|No| I[Process開始]
    H --> I
    I --> J{SqlInstance指定?}
    J -->|Yes| K[Connect-DbaInstance]
    K --> L[Resolve-DbaBuild with $server.Version]
    J -->|No| M{Build指定?}
    L --> N[結果出力]
    M -->|Yes| O[Resolve-DbaBuild with Build]
    M -->|No| P{Kb指定?}
    O --> N
    P -->|Yes| Q[Resolve-DbaBuild with Kb]
    P -->|No| R{MajorVersion指定?}
    Q --> N
    R -->|Yes| S[Resolve-DbaBuild with MajorVersion/SP/CU]
    R -->|No| T[終了]
    S --> N
    N --> T
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 排他パラメータ | Build, Kb, MajorVersion, SqlInstanceは相互排他 | 常に |
| BR-002 | MajorVersion依存 | ServicePack/CumulativeUpdate使用時はMajorVersionが必須 | SP/CU指定時 |
| BR-003 | RTMデフォルト | ServicePack未指定時はRTM扱い | MajorVersion使用時 |
| BR-004 | インデックス更新警告 | 45日以上古いインデックスは警告表示 | 常に（Beginブロック） |
| BR-005 | 廃止ビルド警告 | 公式に廃止されたビルドには警告を付与 | 廃止フラグあり時 |

### 計算ロジック

- ビルド番号の正規化: Minor版が0, 50以外の場合、10の倍数に丸め

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| バージョン取得 | - | SELECT（SMO経由） | $server.Versionプロパティ取得のみ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvalidArgument | パラメータ未指定 | Stop-Functionでメッセージ表示 |
| - | InvalidArgument | 排他パラメータ同時指定 | Stop-Functionでメッセージ表示 |
| - | InvalidArgument | MajorVersion形式不正 | Stop-Functionでメッセージ表示 |
| - | ConnectionError | SQL Server接続失敗 | Stop-Functionで継続 |
| - | IndexError | ビルド参照インデックス読み込み失敗 | Stop-Functionで終了 |

### リトライ仕様

リトライ機構は実装されていない。

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

トランザクション管理は行わない（読み取り専用）。

## パフォーマンス要件

- インデックスファイルはJSONとしてメモリに読み込み
- 複数インスタンス処理: 順次処理

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

- SqlCredentialパラメータによる代替資格情報のサポート
- オンライン更新はdbatools公式リポジトリから取得

## 備考

- ビルド参照インデックスは定期的に更新推奨（-Update使用）
- インデックスが45日以上古い場合は警告表示
- Approximate matchの場合は最も近いビルドを返す

---

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

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

### 推奨読解順序

#### Step 1: ヘルパー関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaBuild.ps1 | `public/Get-DbaBuild.ps1` | **206-268行目**: Get-DbaBuildReferenceIndex関数 |
| 1-2 | Get-DbaBuild.ps1 | `public/Get-DbaBuild.ps1` | **271-377行目**: Resolve-DbaBuild関数 |

**読解のコツ**: Get-DbaBuildReferenceIndexはインデックスファイルの管理（モジュール版とユーザー版の比較、更新）を行う。Resolve-DbaBuildは実際のビルド解決ロジックを実装。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaBuild.ps1 | `public/Get-DbaBuild.ps1` | **103-136行目**: パラメータ定義 |

**主要処理フロー**:
1. **104行目**: DefaultParameterSet = 'Build'
2. **106-107行目**: Buildパラメータ（version[]）
3. **109-110行目**: Kbパラメータ（string[]）
4. **112-114行目**: MajorVersionパラメータ
5. **116-119行目**: ServicePackパラメータ（Alias: SP、デフォルト: RTM）
6. **121-123行目**: CumulativeUpdateパラメータ（Alias: CU）
7. **125-127行目**: SqlInstanceパラメータ（ValueFromPipeline）

#### Step 3: Beginブロック - パラメータ検証

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaBuild.ps1 | `public/Get-DbaBuild.ps1` | **138-203行目**: パラメータ検証とインデックス読み込み |

**主要処理フロー**:
- **141-165行目**: 排他パラメータの検証
- **166-169行目**: SP/CU使用時のMajorVersion必須チェック
- **170-202行目**: MajorVersion/ServicePack/CumulativeUpdateの形式正規化
- **379-386行目**: インデックス読み込み

#### Step 4: Processブロック - ビルド解決

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaBuild.ps1 | `public/Get-DbaBuild.ps1` | **388-472行目**: 各入力方式に対する処理 |

**主要処理フロー**:
- **392-421行目**: SqlInstance指定時の接続と解決
- **423-437行目**: Build指定時の解決
- **440-454行目**: Kb指定時の解決
- **457-471行目**: MajorVersion指定時の解決

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

```
Get-DbaBuild
    │
    ├─ Get-DbaBuildReferenceIndex (内部関数)
    │      ├─ Get-DbatoolsConfigValue
    │      ├─ Update-DbaBuildReference (Update指定時)
    │      └─ ConvertFrom-Json (インデックス読み込み)
    │
    ├─ [SqlInstance指定時]
    │      └─ Connect-DbaInstance
    │             └─ $server.Version取得
    │
    └─ Resolve-DbaBuild (内部関数)
           └─ ビルド情報解決とマッチング
```

### データフロー図

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

Build/Kb/MajorVersion ──▶ パラメータ検証
SqlInstance                       │
                                  ▼
                    Get-DbaBuildReferenceIndex ──▶ インデックスデータ
                                  │
                                  ▼
                    Resolve-DbaBuild ────────────▶ PSCustomObject
                    (ビルド情報マッチング)              (NameLevel, SPLevel,
                                                     CULevel, KBLevel,
                                                     SupportedUntil等)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaBuild.ps1 | `public/Get-DbaBuild.ps1` | ソース | メイン機能実装 |
| dbatools-buildref-index.json | `bin/dbatools-buildref-index.json` | データ | ビルド参照インデックス |
| Update-DbaBuildReference.ps1 | `public/Update-DbaBuildReference.ps1` | ソース | インデックス更新機能 |
