# 画面設計書 93-インスタンスインストール

## 概要

本ドキュメントはdbatools PowerShellモジュールにおけるインスタンスインストール機能（Install-DbaInstance、Update-DbaInstance）の画面設計書です。

### 本画面の処理概要

**業務上の目的・背景**：
SQL Serverインスタンスのインストールは、通常手作業で行うと時間がかかり、構成のばらつきが生じやすい作業です。本機能は、ローカルおよびリモートコンピュータへのSQL Serverの無人インストールを自動化し、構成ファイルの生成、サービスアカウント設定、インストール前提条件の管理を一元化します。これにより、複数サーバーへの一貫した構成でのデプロイ、開発・テスト環境の迅速な構築、災害復旧用のスタンバイサーバー準備が効率的に行えます。

**画面へのアクセス方法**：
PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスします。
- `Install-DbaInstance -Version <バージョン> -Feature <機能>`
- `Update-DbaInstance -Version <バージョン> -Path <パッチパス>`

**主要な操作・処理内容**：
1. **構成ファイル自動生成**：パラメータに基づきConfiguration.iniファイルを動的に生成
2. **前提条件チェック**：再起動保留状態の検出、認証プロトコルのテスト
3. **インストールメディア検索**：指定パスからsetup.exeを自動検出
4. **サービスアカウント設定**：Database Engine、Agent、SSAS、SSIS、SSRS等のサービスアカウント構成
5. **TempDB最適化**：CPU コア数に基づくTempDBファイル数の自動設定（SQL 2016以降）
6. **インストール後設定**：TCPポートの構成、ボリュームメンテナンスタスク権限付与
7. **並列インストール**：複数サーバーへの同時インストール（Throttleで制御）

**画面遷移**：
インストール完了後、Connect-DbaInstance、Get-DbaDatabase等の管理機能へ遷移する。インストール結果のログファイルは指定パスに保存される。

**権限による表示制御**：
- ターゲットコンピュータへの管理者権限が必要
- CredSSP認証が必要な場合あり（ネットワーク共有からのインストール時）
- SQL Server sysadmin権限は自動的に付与される（AdminAccountパラメータ）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 319 | Install-DbaInstance | 主機能 | SQLインスタンスのインストール |
| 385 | Update-DbaInstance | 主機能 | SQLインスタンスの更新 |
| 325 | Invoke-DbaAdvancedInstall | 補助機能 | 高度なインストール実行 |
| 162 | Invoke-DbaAdvancedUpdate | 補助機能 | 高度な更新実行 |

## 画面種別

CLI（コマンドラインインターフェース）/ 構成・デプロイ

## URL/ルーティング

PowerShellコマンド:
- `Install-DbaInstance`
- `Update-DbaInstance`

## 入出力項目

### Install-DbaInstance パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | いいえ | インストール先（デフォルト: $env:COMPUTERNAME） |
| Version | string | はい | SQL Serverバージョン（2008/2008R2/2012/2014/2016/2017/2019/2022/2025） |
| SaCredential | PSCredential | いいえ | saアカウントのパスワード（混合認証時） |
| Credential | PSCredential | いいえ | リモート接続用Windows資格情報 |
| Authentication | string | いいえ | 認証プロトコル（Credssp/Kerberos/Basic等） |
| ConfigurationFile | string | いいえ | 既存のConfiguration.iniファイルパス |
| Configuration | hashtable | いいえ | カスタム構成パラメータ |
| Feature | string[] | いいえ | インストール機能（Default/All/Engine/Tools等） |
| InstanceName | string | いいえ | インスタンス名 |
| InstancePath | string | いいえ | インスタンスファイルのルートディレクトリ |
| DataPath | string | いいえ | データファイルのデフォルトディレクトリ |
| LogPath | string | いいえ | ログファイルのデフォルトディレクトリ |
| TempPath | string | いいえ | TempDBファイルのディレクトリ |
| BackupPath | string | いいえ | バックアップファイルのデフォルトディレクトリ |
| UpdateSourcePath | string | いいえ | 更新プログラムのパス（スリップストリーム用） |
| AdminAccount | string[] | いいえ | sysadmin権限を付与するアカウント |
| ASAdminAccount | string[] | いいえ | Analysis Services管理者アカウント |
| Port | int | いいえ | インストール後のTCPポート |
| ProductID | string | いいえ | プロダクトライセンスキー |
| SqlCollation | string | いいえ | サーバーレベル照合順序 |
| AsCollation | string | いいえ | Analysis Services照合順序 |
| EngineCredential | PSCredential | いいえ | Database Engineサービスアカウント |
| AgentCredential | PSCredential | いいえ | SQL Agentサービスアカウント |
| ASCredential | PSCredential | いいえ | Analysis Servicesサービスアカウント |
| ISCredential | PSCredential | いいえ | Integration Servicesサービスアカウント |
| RSCredential | PSCredential | いいえ | Reporting Servicesサービスアカウント |
| FTCredential | PSCredential | いいえ | Full-Text Filterサービスアカウント |
| PBEngineCredential | PSCredential | いいえ | PolyBase Engineサービスアカウント |
| Path | string[] | いいえ | インストールメディアのパス |
| PerformVolumeMaintenanceTasks | switch | いいえ | 瞬時ファイル初期化を有効化 |
| SaveConfiguration | string | いいえ | 生成した構成ファイルの保存先 |
| Throttle | int | いいえ | 並列インストール数（デフォルト: 50） |
| Restart | switch | いいえ | 必要時に自動再起動 |
| AuthenticationMode | string | いいえ | 認証モード（Windows/Mixed） |
| NoPendingRenameCheck | switch | いいえ | ファイルリネーム保留チェックをスキップ |
| EnableException | switch | いいえ | 例外を有効化 |

## 表示項目

### 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | インストール先コンピュータ名 |
| InstanceName | string | インストールされたインスタンス名 |
| Version | string | インストールされたSQL Serverバージョン |
| Port | int? | 構成されたTCPポート |
| Successful | bool | インストール成功可否 |
| Restarted | bool | インストール中に再起動されたか |
| Installer | string | 使用されたsetup.exeのパス |
| ExitCode | int? | setup.exeの終了コード（0=成功、3010=再起動必要） |
| LogFile | string | インストールログ（Summary.txt）のパス |
| Notes | string[] | 警告、エラー、後処理メモ |
| SACredential | PSCredential | 設定されたSA資格情報 |
| Configuration | hashtable | 使用された構成設定 |
| ExitMessage | string | 終了メッセージテキスト |
| Log | string[] | Summary.txtの全内容 |
| ConfigurationFile | string | 使用されたConfiguration.iniのパス |

## イベント仕様

### 1-インストール準備

1. バージョン番号を正規バージョンに変換（2017→14.0等）
2. 機能リストを構築（Feature→実際のコンポーネント名）
3. 混合認証モード選択時、SaCredential未指定なら128文字のランダムパスワード生成
4. 構成ファイルが指定されていれば読み込み、なければ動的生成

### 2-ターゲットコンピュータ検証

1. Resolve-DbaNetworkNameでコンピュータ名解決
2. Test-PendingRebootで再起動保留状態を確認
3. -Credentialと認証プロトコルの検証（CredSSP自動構成含む）
4. インストールメディアへのアクセス確認

### 3-構成ファイル生成

1. メインキーの決定（SQL 2012以降: OPTIONS、SQL 2008: SQLSERVER2008）
2. デフォルト管理者アカウントの決定
3. Browser Serviceスタートアップタイプの設定（名前付きインスタンスはAutomatic）
4. TempDBファイル数の自動計算（SQL 2016以降、CPU論理コア数ベース、最大8）
5. サービスアカウント情報の設定
6. カスタム構成のマージ

### 4-インストール実行

1. Invoke-DbaAdvancedInstallでsetup.exe実行
2. 終了コードの確認（0=成功、3010=再起動必要）
3. ログファイルの解析
4. TCPポート構成（-Port指定時）

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

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

| 操作（イベント） | 対象 | 操作種別 | 概要 |
|----------------|------|---------|------|
| インスタンスインストール | SQL Serverシステム | CREATE | 新規インスタンス作成 |
| sysadmin付与 | SQL Server | INSERT | SQLSYSADMINACCOUNTS設定 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 |
|-------------|------|---------------|
| MSG001 | エラー | Path to SQL Server setup folder is not set |
| MSG002 | エラー | Version {Version} is not supported |
| MSG003 | エラー | Feature {Feature} is not supported on SQL{Version} |
| MSG004 | 警告 | Explicit -Credential might be required when running against remote hosts |
| MSG005 | エラー | {computer} is pending a reboot |
| MSG006 | 警告 | Primary protocol ({Authentication}) failed |
| MSG007 | エラー | Failed to find setup file for SQL{Version} in {Path} |
| MSG008 | 情報 | Looking for setup files |
| MSG009 | 情報 | Generating a configuration file |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| Pathパラメータ未設定 | Stop-Functionでエラー出力 |
| 未サポートバージョン | Stop-Functionでエラー出力 |
| 再起動保留状態 | -Restartなしの場合はStop-Function |
| 認証プロトコル失敗 | CredSSP自動構成を試行、それでも失敗時は警告 |
| setup.exe見つからない | Stop-Functionでエラー出力 |
| インストール失敗 | ExitCodeと詳細ログを出力に含める |

## 備考

- ProductID未指定時はEvaluation版としてインストール（180日制限）
- ネットワーク共有からのインストールにはCredSSP認証が必要な場合あり
- SQL Server 2016以降では瞬時ファイル初期化がConfiguration.ini経由で設定可能
- SQL Server 2022以降ではx86オプションが削除

---

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

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

### 推奨読解順序

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

出力オブジェクトと構成ファイル構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Install-DbaInstance.ps1 | `public/Install-DbaInstance.ps1` | 263-289行目の.OUTPUTSセクション |
| 1-2 | dbatools-sqlinstallationcomponents.json | `bin/dbatools-sqlinstallationcomponents.json` | 機能コンポーネントのマッピング定義 |

**読解のコツ**: 出力プロパティはInvoke-DbaAdvancedInstallから返される。構成ファイル形式はINI形式。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Install-DbaInstance.ps1 | `public/Install-DbaInstance.ps1` | 344-395行目のparamブロック |
| 2-2 | Install-DbaInstance.ps1 | `public/Install-DbaInstance.ps1` | 484-888行目のprocessブロック |

**主要処理フロー**:
1. **491-505行目**: バージョンを正規化（2017→14.0）
2. **508-523行目**: 機能リストの構築
3. **526-529行目**: 混合認証用パスワード生成
4. **555-573行目**: ターゲットコンピュータの名前解決と再起動チェック
5. **619-667行目**: setup.exeの検索と検証
6. **668-810行目**: 構成ファイルの生成
7. **892-911行目**: Invoke-DbaAdvancedInstallの呼び出し

#### Step 3: 内部ユーティリティ関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Install-DbaInstance.ps1 | `public/Install-DbaInstance.ps1` | 397-424行目のRead-IniFile関数 |
| 3-2 | Install-DbaInstance.ps1 | `public/Install-DbaInstance.ps1` | 425-457行目のWrite-IniFile関数 |
| 3-3 | Install-DbaInstance.ps1 | `public/Install-DbaInstance.ps1` | 458-476行目のUpdate-ServiceCredential関数 |

#### Step 4: インストール実行を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Invoke-DbaAdvancedInstall.ps1 | `private/functions/Invoke-DbaAdvancedInstall.ps1` | 実際のsetup.exe実行ロジック |

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

```
Install-DbaInstance
    │
    ├─ Read-IniFile (内部関数)
    │      └─ Configuration.ini読み込み
    │
    ├─ Resolve-DbaNetworkName
    │      └─ コンピュータ名解決
    │
    ├─ Test-PendingReboot
    │      └─ 再起動保留チェック
    │
    ├─ Initialize-CredSSP
    │      └─ CredSSP認証設定
    │
    ├─ Find-SqlInstanceSetup
    │      └─ setup.exe検索
    │
    ├─ Get-DbaCmObject
    │      └─ CPU情報取得（TempDB最適化用）
    │
    ├─ Write-IniFile (内部関数)
    │      └─ Configuration.ini生成
    │
    └─ Invoke-DbaAdvancedInstall
           │
           ├─ setup.exe実行
           │      └─ /ConfigurationFile
           │
           └─ Set-DbaTcpPort（オプション）
                  └─ TCPポート構成
```

### データフロー図

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

Version ─────────────────▶ バージョン正規化
                                  │
Feature ─────────────────▶ 機能リスト構築
                                  │
ConfigurationFile ───────▶ INIファイル読み込み
       または                      │
Configuration ───────────▶ 構成生成
                                  │
サービス資格情報 ─────────▶ サービスアカウント設定
                                  │
                          ┌───────▼───────┐
                          │ Write-IniFile │
                          └───────────────┘
                                  │
                          ┌───────▼───────┐
                          │ setup.exe実行  │──────▶ ExitCode
                          └───────────────┘         LogFile
                                  │                 Successful
                          ┌───────▼───────┐
Port ────────────────────▶│ Set-DbaTcpPort│
                          └───────────────┘
                                  │
                                  ▼
                          [PSCustomObject出力]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Install-DbaInstance.ps1 | `public/Install-DbaInstance.ps1` | ソース | メインのインストール機能 |
| Invoke-DbaAdvancedInstall.ps1 | `private/functions/Invoke-DbaAdvancedInstall.ps1` | ソース | 実際のインストール実行 |
| dbatools-sqlinstallationcomponents.json | `bin/dbatools-sqlinstallationcomponents.json` | 設定 | 機能コンポーネントマッピング |
| Test-PendingReboot.ps1 | `private/functions/Test-PendingReboot.ps1` | ソース | 再起動保留チェック |
| Find-SqlInstanceSetup.ps1 | `private/functions/Find-SqlInstanceSetup.ps1` | ソース | setup.exe検索 |
