# 機能設計書 325-Invoke-DbaAdvancedInstall

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `Invoke-DbaAdvancedInstall` 機能の設計書である。SQL Serverのインストールワークフローを自動再起動処理を含めて実行する内部関数で、Install-DbaInstanceから呼び出される。

### 本機能の処理概要

**業務上の目的・背景**：SQL Serverのインストールは、設定ファイルの準備、再起動の必要性判定、setup.exeの実行、後処理（ポート設定、IFI権限付与）など、多くのステップを含む複雑なプロセスである。本機能は、これらのステップを自動化し、リモートマシンへのインストールも含めて一貫したワークフローを提供する。

**機能の利用シーン**：Install-DbaInstanceからの内部呼び出し、複数サーバーへのSQL Server自動デプロイ、CI/CDパイプラインでのSQL Server環境構築、構成ファイルを使用した標準化インストールなどで利用される。

**主要な処理内容**：
1. インストール前の再起動必要性チェックと実行
2. 構成ファイルのリモートマシンへのコピー
3. setup.exeの実行とインストールログの取得
4. インストール後のTCPポート設定
5. ボリュームメンテナンスタスク権限の付与（IFI）
6. インストール後の再起動処理
7. インストール結果の返却

**関連システム・外部連携**：
- SQL Server setup.exe（インストーラー実行）
- PowerShellリモーティング（リモートインストール）
- Set-DbaTcpPort（ポート設定）
- Set-DbaPrivilege（IFI権限設定）
- Restart-DbaService（サービス再起動）

**権限による制御**：ターゲットマシンへの管理者権限が必要。リモートインストール時はCredSSPまたは適切な認証方式が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIコマンド | 内部関数 | Install-DbaInstanceから呼び出し |

## 機能種別

インストール処理 / リモート実行

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | string | No | ターゲットコンピュータ名 | - |
| InstanceName | string | No | インスタンス名 | - |
| Port | nullable[int] | No | TCPポート番号 | - |
| InstallationPath | string | No | setup.exeのパス | - |
| ConfigurationPath | string | No | 構成ファイルパス | - |
| ArgumentList | string[] | No | setup.exeへの追加引数 | - |
| Version | version | No | SQL Serverバージョン | - |
| Configuration | hashtable | No | カスタム構成ハッシュテーブル | - |
| Restart | bool | No | 自動再起動フラグ | - |
| Credential | PSCredential | No | リモート接続用資格情報 | - |
| Authentication | string | No | 認証方式（デフォルト: CredSSP） | ValidateSet |
| PerformVolumeMaintenanceTasks | bool | No | IFI権限付与フラグ | - |
| SaveConfiguration | string | No | 構成ファイル保存先パス | - |
| SaCredential | PSCredential | No | SA認証用資格情報 | - |
| NoPendingRenameCheck | switch | No | 保留中リネームチェックをスキップ | - |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

- Configuration.ini: SQL Serverインストール構成ファイル
- SQL Server setup.exe: インストールメディア

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | ターゲットコンピュータ名 |
| InstanceName | string | インスタンス名 |
| Version | version | SQL Serverバージョン |
| Port | nullable[int] | 設定されたTCPポート |
| Successful | bool | インストール成功フラグ |
| Restarted | bool | 再起動実行フラグ |
| Installer | string | setup.exeのパス |
| ExitCode | nullable[int] | setup.exeの終了コード |
| LogFile | string | Summary.txtのパス |
| Notes | string[] | 警告・エラーメッセージ配列 |
| SACredential | PSCredential | SA資格情報（混合モード時） |
| Configuration | hashtable | 使用された構成設定 |
| ExitMessage | string | インストールサマリからの終了メッセージ |
| Log | string[] | Summary.txtの内容 |
| ConfigurationFile | string | ConfigurationFile.iniのパス |

### 出力先

PowerShellパイプライン（PSCustomObject、Select-DefaultViewで主要プロパティを表示）

## 処理フロー

### 処理シーケンス

```
1. インストール前再起動チェック
   └─ Test-PendingRebootで再起動必要性確認
   └─ Restart=trueかつ再起動必要時にRestart-Computer実行
2. 構成ファイル保存（オプション）
   └─ SaveConfiguration指定時にコピー
3. リモートセッション確立とファイル転送
   └─ リモートの場合はNew-PSSessionでセッション作成
   └─ Send-Fileで構成ファイル転送
4. インストール実行
   └─ Invoke-Programでsetup.exe実行
5. インストールログ取得
   └─ Get-SqlInstallSummaryでSummary.txt取得
6. 後処理：IFI権限付与
   └─ PerformVolumeMaintenanceTasks時にSet-DbaPrivilege
7. 後処理：ポート設定
   └─ Port指定時にSet-DbaTcpPortとRestart-DbaService
8. インストール後再起動
   └─ 終了コード3010またはTest-PendingReboot時
9. 一時ファイルクリーンアップ
   └─ リモート構成ファイル削除
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Test-PendingReboot<br>再起動必要性確認]
    B --> C{再起動必要<br>かつ Restart=true?}
    C -->|Yes| D[Restart-Computer<br>事前再起動]
    C -->|No| E[続行]
    D --> E
    E --> F{SaveConfiguration<br>指定あり?}
    F -->|Yes| G[構成ファイルコピー]
    F -->|No| H[続行]
    G --> H
    H --> I{ローカル or<br>リモート?}
    I -->|ローカル| J[ローカルパス使用]
    I -->|リモート| K[New-PSSession]
    K --> L[Send-File<br>構成ファイル転送]
    L --> J
    J --> M[Invoke-Program<br>setup.exe実行]
    M --> N[Get-SqlInstallSummary<br>ログ取得]
    N --> O{インストール<br>成功?}
    O -->|No| P[エラーNotes追加]
    O -->|Yes| Q{PerformVolume<br>MaintenanceTasks?}
    P --> R[一時ファイル削除]
    Q -->|Yes| S[Set-DbaPrivilege<br>IFI権限付与]
    Q -->|No| T{Port指定<br>あり?}
    S --> T
    T -->|Yes| U[Set-DbaTcpPort]
    T -->|No| V[再起動チェック]
    U --> W[Restart-DbaService]
    W --> V
    V --> X{再起動必要<br>かつ Restart=true?}
    X -->|Yes| Y[Restart-Computer]
    X -->|No| R
    Y --> R
    R --> Z[結果オブジェクト出力]
    Z --> AA[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-325-01 | 事前再起動 | 保留中の再起動がある場合は事前に再起動 | Restart=true時 |
| BR-325-02 | 終了コード3010 | 再起動が必要なインストール完了を示す | setup.exe終了時 |
| BR-325-03 | CredSSP認証 | Credential指定時のデフォルト認証方式 | リモートインストール時 |
| BR-325-04 | IFI権限 | インスタントファイル初期化のための権限付与 | PerformVolumeMaintenanceTasks時 |
| BR-325-05 | 構成ファイル削除 | インストール後に一時構成ファイルを削除 | 常時 |

### 計算ロジック

バージョン番号からログパス算出：
- versionNumber = Major + Minor の最初3桁
- ログパス = `{ProgramFiles}\Microsoft SQL Server\{versionNumber}\Setup Bootstrap\Log`

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

本機能は直接的なデータベース操作を行わない。SQL Serverインストーラー（setup.exe）を実行する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | RebootError | 再起動失敗 | Stop-Functionで処理継続 |
| - | FileCopyError | 構成ファイルコピー失敗 | Stop-Functionで処理中断 |
| - | InstallError | setup.exe実行失敗 | Notesに追加して結果返却 |
| - | ServiceError | サービス再起動失敗 | Notesに追加して続行 |

### リトライ仕様

明示的なリトライ機能は実装されていない。Invoke-Programはフォールバック機能を持つ。

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

SQL Serverインストールは内部でトランザクション管理される。インストール失敗時はsetup.exeによってロールバックされる。

## パフォーマンス要件

特に定義されていない。Write-ProgressHelperで進捗表示を行う。

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

- CredSSP、Kerberos、Negotiate等の認証方式対応
- 資格情報はPSCredentialオブジェクトとして安全に管理
- SA資格情報は混合モード認証時のみ使用
- 一時構成ファイルは処理後に削除
- WinRM over SSL対応（設定による）

## 備考

- 内部関数としてInstall-DbaInstanceから呼び出される
- 作者: Chrissy LeMaire (@cl)
- SQL Serverインストールコマンドラインパラメータ: https://docs.microsoft.com/en-us/sql/database-engine/install-windows/install-sql-server-from-the-command-prompt

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造を把握することから始める。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Invoke-DbaAdvancedInstall.ps1 | `public/Invoke-DbaAdvancedInstall.ps1` | 200-217行目の出力オブジェクト初期化 |

**読解のコツ**: Select-DefaultViewで表示されるプロパティと全プロパティを区別して理解する。

#### Step 2: 内部関数を理解する

Get-SqlInstallSummary関数を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Invoke-DbaAdvancedInstall.ps1 | `public/Invoke-DbaAdvancedInstall.ps1` | 155-198行目のGet-SqlInstallSummary関数 |

**主要処理フロー**:
- **163-168行目**: ログパスの算出（バージョン番号から）
- **169-170行目**: Summary.txtの検索
- **177-185行目**: サマリ内容の読み込みと解析

#### Step 3: メイン処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Invoke-DbaAdvancedInstall.ps1 | `public/Invoke-DbaAdvancedInstall.ps1` | 229-247行目の事前再起動処理 |
| 3-2 | Invoke-DbaAdvancedInstall.ps1 | `public/Invoke-DbaAdvancedInstall.ps1` | 272-287行目のファイル転送処理 |
| 3-3 | Invoke-DbaAdvancedInstall.ps1 | `public/Invoke-DbaAdvancedInstall.ps1` | 305-322行目のインストール実行 |
| 3-4 | Invoke-DbaAdvancedInstall.ps1 | `public/Invoke-DbaAdvancedInstall.ps1` | 348-385行目の後処理 |

**主要処理フロー**:
- **231行目**: Test-PendingRebootで再起動必要性確認
- **241-246行目**: 事前再起動実行
- **277-281行目**: Send-Fileで構成ファイル転送
- **307行目**: Invoke-Programでsetup.exe実行
- **350行目**: Set-DbaPrivilegeでIFI権限付与
- **354行目**: Set-DbaTcpPortでポート設定

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

```
Invoke-DbaAdvancedInstall
    │
    ├─ Test-PendingReboot
    │      └─ 再起動必要性チェック
    │
    ├─ Restart-Computer
    │      └─ コンピュータ再起動
    │
    ├─ New-PSSession
    │      └─ リモートセッション作成
    │
    ├─ Send-File
    │      └─ ファイル転送
    │
    ├─ Invoke-Program
    │      └─ setup.exe実行
    │
    ├─ Get-SqlInstallSummary (内部関数)
    │      └─ Invoke-Command2
    │             └─ インストールログ取得
    │
    ├─ Set-DbaPrivilege
    │      └─ IFI権限付与
    │
    ├─ Set-DbaTcpPort
    │      └─ TCPポート設定
    │
    └─ Restart-DbaService
           └─ サービス再起動
```

### データフロー図

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

Configuration.ini ───▶ Send-File ───▶ リモート一時ファイル
                              │
InstallationPath              │
(setup.exe) ─────────▶ Invoke-Program ───▶ インストール実行
                              │
                              ▼
                    Get-SqlInstallSummary
                       （ログ取得）
                              │
                              ▼
                    Set-DbaPrivilege（IFI）
                              │
                              ▼
                    Set-DbaTcpPort（ポート）
                              │
                              ▼
                        PSCustomObject
                    （インストール結果）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Invoke-DbaAdvancedInstall.ps1 | `public/Invoke-DbaAdvancedInstall.ps1` | ソース | メイン関数の実装 |
| Install-DbaInstance.ps1 | `public/Install-DbaInstance.ps1` | ソース | 呼び出し元関数 |
| Test-PendingReboot.ps1 | `private/functions/Test-PendingReboot.ps1` | ソース | 再起動必要性チェック |
| Invoke-Program.ps1 | `private/functions/Invoke-Program.ps1` | ソース | プログラム実行 |
| Set-DbaPrivilege.ps1 | `public/Set-DbaPrivilege.ps1` | ソース | 権限設定 |
| Set-DbaTcpPort.ps1 | `public/Set-DbaTcpPort.ps1` | ソース | TCPポート設定 |
| Restart-DbaService.ps1 | `public/Restart-DbaService.ps1` | ソース | サービス再起動 |
