# 機能設計書 381-Get-DbaInstalledPatch

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるGet-DbaInstalledPatch機能の設計仕様を記載する。本機能は、Windowsレジストリから SQL Server のパッチインストール履歴を取得し、パッチコンプライアンス監査やレポーティングに使用する。

### 本機能の処理概要

本機能は、ローカルまたはリモートコンピュータのWindowsレジストリを照会し、SQL Serverに適用されたすべてのパッチ（Cumulative Updates、Service Packs、Hotfixes）の完全な履歴を取得する。

**業務上の目的・背景**：データベース管理者は、セキュリティコンプライアンス監査やアップグレード計画の立案において、どのSQL Serverパッチがいつインストールされたかを把握する必要がある。手動で各サーバーを確認する作業は時間がかかり、複数サーバー環境では特に非効率となる。本機能により、SQL Server環境全体のパッチレベルを迅速に評価できる。

**機能の利用シーン**：
- セキュリティ監査時のパッチコンプライアンスレポート作成
- SQL Serverアップグレード前の現状把握
- 複数サーバー間のパッチレベル比較
- トラブルシューティング時のパッチ適用状況確認

**主要な処理内容**：
1. 指定されたコンピュータへのリモート接続確立（Invoke-Command2使用）
2. Windowsレジストリ（HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall）からパッチ情報を取得
3. SQL Server関連パッチ（Hotfix、Service Pack、GDR）のフィルタリング
4. 取得データをPSCustomObjectとして整形・出力

**関連システム・外部連携**：Windowsレジストリへの読み取りアクセスが必要。リモートコンピュータの場合、PowerShellリモーティングが有効である必要がある。

**権限による制御**：レジストリへの読み取り権限が必要。リモートコンピュータの場合、-Credentialパラメータで認証情報を指定可能。

## 関連画面

本機能はCLIベースのPowerShellコマンドレットであり、GUI画面との直接的な関連はない。

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | PowerShellコンソール | 主画面 | コマンド実行とパッチ情報表示 |

## 機能種別

データ取得（SELECT）/ レジストリ照会

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | DbaInstanceParameter[] | No | 対象コンピュータ名（複数可）。デフォルトはローカルコンピュータ | ValueFromPipeline対応 |
| Credential | PSCredential | No | リモートコンピュータ接続用の資格情報 | 有効なPSCredentialオブジェクト |
| EnableException | switch | No | 例外処理の有効化フラグ | - |

### 入力データソース

- パイプライン入力：ComputerNameパラメータがValueFromPipelineをサポート
- テキストファイル：Get-Contentと組み合わせてサーバーリストをパイプ可能
- 直接指定：カンマ区切りで複数コンピュータ名を指定可能

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | パッチが見つかったコンピュータ名 |
| Name | string | パッチの表示名（例: "Hotfix for SQL Server 2019 (KB5012345)"） |
| Version | string | レジストリに格納されているパッチのバージョン番号 |
| InstallDate | DbaDate | インストール日（DbaDate型。.Dateで日付のみ、.DateTimeで完全な日時） |

### 出力先

PowerShellパイプラインへPSCustomObjectとして出力。標準出力に表示、またはパイプラインで後続コマンドへ渡す。

## 処理フロー

### 処理シーケンス

```
1. ComputerNameパラメータの解析
   └─ 指定がない場合は$env:COMPUTERNAMEをデフォルト値として使用
2. 各コンピュータに対してループ処理
   └─ Invoke-Command2でリモート接続
3. レジストリからパッチ情報を取得
   └─ HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall配下を検索
   └─ DisplayNameが"Hotfix*SQL*"、"Service Pack*SQL*"、"GDR*SQL*"のいずれかにマッチするエントリをフィルタ
4. 取得結果をInstallDateでソート
5. 各パッチ情報をPSCustomObjectに変換
   └─ InstallDateをyyyyMMdd形式からDbaDate型に変換
6. パイプラインに出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[ComputerNameパラメータ取得]
    B --> C{ComputerName指定あり?}
    C -->|No| D[ローカルコンピュータ名を設定]
    C -->|Yes| E[指定されたコンピュータ名を使用]
    D --> F[各コンピュータでループ]
    E --> F
    F --> G[Invoke-Command2でリモート接続]
    G --> H{接続成功?}
    H -->|No| I[Stop-Function でエラー処理]
    I --> J{次のコンピュータあり?}
    H -->|Yes| K[レジストリからパッチ情報取得]
    K --> L[SQL Server関連パッチをフィルタ]
    L --> M[InstallDateでソート]
    M --> N[各パッチをPSCustomObjectに変換]
    N --> O[パイプラインに出力]
    O --> J
    J -->|Yes| F
    J -->|No| P[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | SQL Serverパッチフィルタ | DisplayNameが"Hotfix*SQL*"、"Service Pack*SQL*"、"GDR*SQL*"のいずれかにマッチするエントリのみ取得 | 常時 |
| BR-002 | 日付形式変換 | レジストリのInstallDate（yyyyMMdd形式）をDbaDate型に変換 | 常時 |
| BR-003 | ソート順 | 取得結果はInstallDateの昇順でソート | 常時 |

### 計算ロジック

日付変換: `[DbaDate][datetime]::ParseExact($patch.InstallDate, 'yyyyMMdd', $null)`

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

本機能はデータベースを操作しない。

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| なし | - | - | Windowsレジストリのみを参照 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 接続エラー | リモートコンピュータへの接続失敗 | Stop-Functionで処理継続。EnableExceptionが有効な場合は例外スロー |
| - | 認証エラー | 資格情報が無効または権限不足 | 有効な資格情報を-Credentialで指定 |
| - | レジストリアクセスエラー | レジストリキーへのアクセス権限がない | 管理者権限で実行 |

### リトライ仕様

リトライ機能は実装されていない。-Continueパラメータにより、エラー発生時も次のコンピュータの処理を継続する。

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

本機能はデータベース操作を行わないため、トランザクション管理は不要。

## パフォーマンス要件

- レジストリ照会は軽量な操作であり、通常1秒以内に完了
- 複数コンピュータを指定した場合、順次処理となる
- 大量のサーバーを対象とする場合は、パイプラインストリーミングによりメモリ効率を維持

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

- リモートコンピュータへのアクセスにはPowerShellリモーティングが必要
- 資格情報は-Credentialパラメータで安全に受け渡し
- レジストリへの読み取り権限のみ必要（書き込みは不要）

## 備考

- パッチコンプライアンステストにはTest-DbaBuildの使用を推奨
- InstallDateは特殊なDbaDate型であり、ソート時は.Dateプロパティを使用
- GDRパッチ（セキュリティ更新）もフィルタ対象に含まれる

---

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

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

### 推奨読解順序

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

本機能は単純なPSCustomObjectを出力するため、複雑なデータ構造は存在しない。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaInstalledPatch.ps1 | `public/Get-DbaInstalledPatch.ps1` | 出力オブジェクトの構造（82-87行目） |

**読解のコツ**: DbaDate型はdbatoolsモジュール独自の日時型で、.Dateや.DateTimeプロパティを持つ。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaInstalledPatch.ps1 | `public/Get-DbaInstalledPatch.ps1` | パラメータ定義と処理の開始点（64-70行目） |

**主要処理フロー**:
1. **64-70行目**: パラメータ定義。ComputerNameはValueFromPipelineをサポート
2. **71行目**: processブロック開始
3. **72行目**: ComputerName.ComputerNameでforeachループ

#### Step 3: コア処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaInstalledPatch.ps1 | `public/Get-DbaInstalledPatch.ps1` | レジストリ照会ロジック（74-76行目） |
| 3-2 | Get-DbaInstalledPatch.ps1 | `public/Get-DbaInstalledPatch.ps1` | 出力オブジェクト生成（81-88行目） |

**主要処理フロー**:
- **74-76行目**: Invoke-Command2でリモートスクリプト実行。レジストリからSQL Serverパッチをフィルタ
- **77-79行目**: エラーハンドリング（Stop-Functionで継続）
- **81-88行目**: 各パッチをPSCustomObjectに変換して出力

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

```
Get-DbaInstalledPatch
    │
    ├─ Invoke-Command2 (内部関数)
    │      └─ PowerShellリモーティング経由でレジストリ照会
    │
    └─ Stop-Function (内部関数)
           └─ エラー処理とロギング
```

### データフロー図

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

ComputerName ───▶ Invoke-Command2 ───▶ PSCustomObject
                      │                      │
                      ▼                      ├─ ComputerName
              レジストリ照会                 ├─ Name
              HKLM:\SOFTWARE\...            ├─ Version
                      │                      └─ InstallDate
                      ▼
              SQL Serverパッチ
              フィルタリング
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaInstalledPatch.ps1 | `public/Get-DbaInstalledPatch.ps1` | ソース | メイン機能実装 |
| Get-DbaInstalledPatch.Tests.ps1 | `tests/Get-DbaInstalledPatch.Tests.ps1` | テスト | 単体テスト |
