# 画面設計書 181-ビルド情報

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるSQL Serverビルド情報管理機能の設計を定義する。

### 本画面の処理概要

SQL Serverインスタンスのビルドバージョンを特定し、サービスパック（SP）、累積更新プログラム（CU）、関連するKB記事番号、サポートライフサイクル日付などの詳細情報を提供するコマンド群を管理する。

**業務上の目的・背景**：データベース管理者は、SQL Serverのパッチレベルを迅速に把握し、Microsoftによるサポート終了日やセキュリティ更新の適用状況を確認する必要がある。この機能により、コンプライアンス監査、パッチ管理計画、およびセキュリティ評価を効率的に実施できる。

**画面へのアクセス方法**：PowerShellコンソールから以下のコマンドを実行する：
- `Get-DbaBuild` - ビルド情報の取得
- `Test-DbaBuild` - ビルドコンプライアンスのテスト
- `Update-DbaBuildReference` - ビルドリファレンスデータの更新

**主要な操作・処理内容**：
1. SQL Serverインスタンスに接続してビルドバージョンを取得
2. ビルド番号からSP/CUレベル、KB記事番号を解決
3. KB記事番号からビルド情報を逆引き検索
4. メジャーバージョンとSP/CU組み合わせから正確なビルドを特定
5. ビルドリファレンスインデックスをオンラインから更新
6. パッチコンプライアンス要件に対するテスト実行

**画面遷移**：単独のCLIコマンド群として動作。Connect-DbaInstanceで確立した接続を活用可能。Get-DbaRegServerからパイプライン入力可能。

**権限による表示制御**：SQL Serverインスタンスへの接続にはSqlCredentialパラメータで代替認証を使用可能。ローカルのビルドリファレンスファイル更新にはファイルシステム書き込み権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 380 | Get-DbaBuild | 主機能 | SQL Serverビルド情報の取得 |
| 383 | Test-DbaBuild | 補助機能 | ビルドバージョンのテスト |
| 384 | Update-DbaBuildReference | 補助機能 | ビルドリファレンスの更新 |

## 画面種別

コマンドラインインターフェース（CLI）

## URL/ルーティング

PowerShellコマンド:
- `Get-DbaBuild`
- `Test-DbaBuild`
- `Update-DbaBuildReference`

## 入出力項目

### Get-DbaBuild パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| Build | version[] | No | 検索するビルド番号（例: "12.00.4502"） |
| Kb | string[] | No | 検索するKB記事番号（例: "KB4057119"） |
| MajorVersion | string | No | SQLメジャーバージョン（例: "SQL2016", "2016"） |
| ServicePack | string | No | サービスパックレベル（デフォルト: "RTM"） |
| CumulativeUpdate | string | No | 累積更新プログラムレベル |
| SqlInstance | DbaInstanceParameter[] | No | 対象SQLインスタンス |
| SqlCredential | PSCredential | No | SQL認証用資格情報 |
| Update | switch | No | オンラインリファレンス更新フラグ |
| EnableException | switch | No | 例外を有効にするフラグ |

### Test-DbaBuild パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| Build | version[] | No | テストするビルド番号 |
| MinimumBuild | version | No | 最小コンプライアンスビルド |
| MaxBehind | string | No | 許容される最大遅延（例: "1SP", "2CU"） |
| Latest | switch | No | 最新ビルド要求フラグ |
| SqlInstance | DbaInstanceParameter[] | No | 対象SQLインスタンス |
| SqlCredential | PSCredential | No | SQL認証用資格情報 |
| Update | switch | No | オンラインリファレンス更新フラグ |
| Quiet | switch | No | Boolean結果のみ返却 |
| EnableException | switch | No | 例外を有効にするフラグ |

## 表示項目

### Get-DbaBuild 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| SqlInstance | string | SQLインスタンス名 |
| Build | version | ビルドバージョン番号 |
| NameLevel | string | SQL Server製品名 |
| SPLevel | string | サービスパックレベル |
| CULevel | string | 累積更新レベル |
| KBLevel | string[] | 関連KB記事番号配列 |
| BuildLevel | version | 正規化されたビルドバージョン |
| SupportedUntil | DateTime | サポート終了日 |
| MatchType | string | マッチ精度（Exact/Approximate） |
| Warning | string | 警告メッセージ |

### Test-DbaBuild 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Build | version | テストしたビルドバージョン |
| MatchType | string | マッチ精度 |
| Compliant | bool | コンプライアンス結果 |
| MinimumBuild | version | 最小必須ビルド |
| MaxBehind | string | 最大許容遅延 |
| SPTarget | string | 目標SPレベル |
| CUTarget | string | 目標CUレベル |
| BuildTarget | version | 目標ビルドバージョン |

## イベント仕様

### 1-ビルド情報取得（Get-DbaBuild）

1. パラメータ検証（相互排他チェック）
2. ビルドリファレンスインデックスの読み込み
3. 指定されたソース（Build/Kb/MajorVersion/SqlInstance）に基づきビルド解決
4. 結果オブジェクトをパイプラインに出力

### 2-ビルドコンプライアンステスト（Test-DbaBuild）

1. コンプライアンス仕様パラメータの検証
2. Get-DbaBuildを呼び出してビルド情報取得
3. 指定されたコンプライアンス要件に対してテスト
4. コンプライアンス結果を含むオブジェクトを出力

### 3-リファレンス更新（Update-DbaBuildReference）

1. ローカルリファレンスファイルの存在確認
2. オンラインまたはローカルファイルから新データ取得
3. 日付比較を行い新しい場合は更新
4. 書き込み可能な場所にファイル保存

## データベース更新仕様

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

この機能はSQL Serverデータベースへの更新操作を行わない。ローカルファイルシステムのJSONファイルのみを更新する。

| 操作（イベント） | 対象 | 操作種別 | 概要 |
|----------------|------|---------|------|
| リファレンス更新 | dbatools-buildref-index.json | ファイル書き込み | ビルドリファレンスインデックスの更新 |

## メッセージ仕様

| 種別 | メッセージ | 発生条件 |
|------|----------|---------|
| Warning | Index is stale, last update on: {日付} | インデックスが45日以上古い場合 |
| Warning | No info in store for this Release | ビルド情報が見つからない場合 |
| Warning | {Build} not found, closest build we have is {version} | 完全一致しない場合 |
| Warning | This version has been officially retired by Microsoft | 廃止バージョンの場合 |
| Error | You need to choose at least one parameter | パラメータ未指定の場合 |
| Error | -MinimumBuild, -MaxBehind and -Latest are mutually exclusive | 相互排他パラメータ違反 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 接続エラー | Stop-Functionで処理を中断し、エラーメッセージを表示 |
| リファレンスファイル未検出 | モジュール整合性チェックを推奨するメッセージを表示 |
| オンライン更新失敗 | プロキシ設定を試行後、警告メッセージを表示 |
| パラメータ検証失敗 | InvalidArgumentカテゴリのStop-Functionで中断 |

## 備考

- ビルドリファレンスインデックスは `$PSModuleRoot\bin\dbatools-buildref-index.json` に格納
- 書き込み可能なコピーは `Path.DbatoolsData` 設定で指定されたディレクトリに保存
- オンライン更新URLは `assets.sqlbuildreference` 設定で指定
- SQL Server 2000以降のすべてのバージョンに対応

---

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

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

### 推奨読解順序

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

ビルドリファレンスインデックスのJSON構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | dbatools-buildref-index.json | `bin/dbatools-buildref-index.json` | LastUpdated、Data配列の構造（Version, Name, SP, CU, KBList, SupportedUntil, Retired） |

**読解のコツ**: JSONファイルのData配列には各SQL Serverビルドの情報がバージョン順に格納されている。

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

Get-DbaBuild関数の構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaBuild.ps1 | `public/Get-DbaBuild.ps1` | パラメータセット、相互排他検証、Resolve-DbaBuild内部関数 |

**主要処理フロー**:
1. **行103-136**: パラメータ定義（Build, Kb, MajorVersion, SqlInstance等）
2. **行140-202**: パラメータ相互排他検証とフォーマット正規化
3. **行206-268**: Get-DbaBuildReferenceIndex内部関数でインデックス読み込み
4. **行271-376**: Resolve-DbaBuild内部関数でビルド解決ロジック
5. **行392-421**: SqlInstanceパラメータ処理（サーバー接続してビルド取得）
6. **行423-471**: Build/Kb/MajorVersionパラメータ処理

#### Step 3: コンプライアンステスト機能を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Test-DbaBuild.ps1 | `public/Test-DbaBuild.ps1` | MaxBehindパース、コンプライアンス判定ロジック |

**主要処理フロー**:
- **行175-216**: MaxBehind文字列のパース（"1SP", "2CU"形式）
- **行229-233**: Get-DbaBuildを呼び出してビルド情報取得
- **行251-313**: コンプライアンス判定（MinimumBuild/MaxBehind/Latest）
- **行314-324**: 結果オブジェクトへのプロパティ追加

#### Step 4: リファレンス更新機能を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Update-DbaBuildReference.ps1 | `public/Update-DbaBuildReference.ps1` | オンライン取得、ファイル比較、更新ロジック |

**主要処理フロー**:
- **行66-86**: Get-DbaBuildReferenceIndexOnline内部関数
- **行90-123**: ローカルファイル存在確認と初期化
- **行126-143**: 新データ取得と日付比較による更新判定

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

```
Get-DbaBuild (public/Get-DbaBuild.ps1)
    │
    ├─ Get-DbaBuildReferenceIndex (内部関数)
    │      ├─ Get-DbatoolsConfigValue (Path.DbatoolsData)
    │      ├─ Test-Path / Copy-Item (ファイル操作)
    │      └─ Update-DbaBuildReference (オプション)
    │
    ├─ Connect-DbaInstance (SqlInstance指定時)
    │
    └─ Resolve-DbaBuild (内部関数)
           └─ ビルド情報解決ロジック

Test-DbaBuild (public/Test-DbaBuild.ps1)
    │
    ├─ Get-DbaBuild (ビルド情報取得)
    │
    └─ Get-DbaBuildReferenceIndex (内部関数)
           └─ コンプライアンス判定

Update-DbaBuildReference (public/Update-DbaBuildReference.ps1)
    │
    ├─ Get-DbatoolsConfigValue
    │
    └─ Get-DbaBuildReferenceIndexOnline (内部関数)
           └─ Invoke-TlsWebRequest
```

### データフロー図

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

SqlInstance ─────────────▶ Connect-DbaInstance ──▶ Server.Version
                                    │
Build番号 ────────────────▶ Resolve-DbaBuild ────▶ ビルド詳細情報
                                    ▲
KB番号 ───────────────────▶        │
                                    │
MajorVersion/SP/CU ───────▶        │
                                    │
dbatools-buildref-index.json ─────▶│
                                    │
                                    ▼
                           [PSCustomObject]
                           ├─ SqlInstance
                           ├─ Build
                           ├─ NameLevel
                           ├─ SPLevel
                           ├─ CULevel
                           ├─ KBLevel
                           ├─ BuildLevel
                           ├─ SupportedUntil
                           ├─ MatchType
                           └─ Warning
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaBuild.ps1 | `public/Get-DbaBuild.ps1` | ソース | ビルド情報取得メイン関数 |
| Test-DbaBuild.ps1 | `public/Test-DbaBuild.ps1` | ソース | ビルドコンプライアンステスト |
| Update-DbaBuildReference.ps1 | `public/Update-DbaBuildReference.ps1` | ソース | リファレンスインデックス更新 |
| dbatools-buildref-index.json | `bin/dbatools-buildref-index.json` | データ | ビルドリファレンスインデックス |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQLインスタンス接続 |
