# 機能設計書 319-Install-DbaInstance

## 概要

本ドキュメントは、SQL Serverインスタンスのインストールを自動化するInstall-DbaInstance機能の設計仕様を記載する。

### 本機能の処理概要

Install-DbaInstanceは、ローカルおよびリモートコンピュータに対してSQL Serverインスタンスの無人インストールを実行する機能である。構成ファイル（Configuration.ini）の自動生成、セットアップ実行、サービスアカウント設定、インストール後のポート設定まで一括で処理する。

**業務上の目的・背景**：SQL Serverのインストールは複雑で時間のかかる作業であり、手動での設定ミスが発生しやすい。本機能は、構成ファイルの自動生成、サービスアカウントの設定、前提条件チェック（保留中の再起動など）、認証プロトコルの処理を自動化することで、一貫性のある信頼性の高いインストールを実現する。また、複数サーバーへの並列インストールをサポートし、大規模環境でのデプロイメントを効率化する。

**機能の利用シーン**：本機能は以下のような場面で利用される。
- 新規SQL Server環境の構築
- 開発・テスト環境の自動プロビジョニング
- 複数サーバーへの一括インストール
- フェイルオーバークラスターインスタンスの構築
- スリップストリームインストール（更新プログラムの適用）

**主要な処理内容**：
1. 前提条件チェック（保留中の再起動、認証プロトコル）
2. インストールメディアの検出
3. Configuration.iniファイルの生成
4. setup.exeのリモート/ローカル実行
5. インストール後のTCPポート設定

**関連システム・外部連携**：PowerShellリモーティング（WinRM）、CredSSP認証、SQL Server setup.exe、WMI（CPU情報取得）。

**権限による制御**：対象コンピュータの管理者権限、CredSSP構成権限（リモート時）が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | インスタンスデプロイメント | 主機能 | SQL Serverインスタンスのインストール |

## 機能種別

インストール / インスタンス管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | インストール先コンピュータ（デフォルト: ローカル） | ポート番号指定可能 |
| Version | string | Yes | SQL Serverバージョン | 2008/2008R2/2012/2014/2016/2017/2019/2022/2025 |
| InstanceName | string | No | インスタンス名（デフォルト: MSSQLSERVER） | - |
| SaCredential | PSCredential | No | SA認証用パスワード（Mixed時） | 未指定時は128文字自動生成 |
| Credential | PSCredential | No | リモート接続用Windows資格情報 | - |
| ConfigurationFile | object | No | 既存のConfiguration.iniファイル | パイプライン入力対応 |
| Configuration | hashtable | No | カスタム構成パラメータ | - |
| Authentication | string | No | 認証プロトコル | CredSSP/Kerberos/Basic等 |
| Feature | string[] | No | インストール機能 | Default/All/個別機能 |
| InstancePath | string | No | インスタンスルートディレクトリ | - |
| DataPath | string | No | データファイルディレクトリ | - |
| LogPath | string | No | ログファイルディレクトリ | - |
| TempPath | string | No | tempdbディレクトリ | - |
| BackupPath | string | No | バックアップディレクトリ | - |
| UpdateSourcePath | string | No | 更新プログラムディレクトリ | スリップストリーム |
| AdminAccount | string[] | No | sysadmin権限付与アカウント | - |
| ASAdminAccount | string[] | No | SSAS管理者アカウント | - |
| Port | int | No | TCPポート番号 | - |
| ProductID | string | No | プロダクトキー | 未指定時はEvaluation |
| SqlCollation | string | No | DBエンジン照合順序 | - |
| AsCollation | string | No | SSAS照合順序 | - |
| EngineCredential | PSCredential | No | DBエンジンサービスアカウント | - |
| AgentCredential | PSCredential | No | SQL Agentサービスアカウント | - |
| ASCredential | PSCredential | No | SSASサービスアカウント | - |
| ISCredential | PSCredential | No | SSISサービスアカウント | - |
| RSCredential | PSCredential | No | SSRSサービスアカウント | - |
| FTCredential | PSCredential | No | フルテキストサービスアカウント | - |
| PBEngineCredential | PSCredential | No | PolyBaseサービスアカウント | - |
| Path | string[] | No | インストールメディアパス | 設定値またはパラメータ |
| Throttle | int | No | 並列インストール数（デフォルト: 50） | - |
| Restart | switch | No | 必要時に自動再起動 | - |
| PerformVolumeMaintenanceTasks | switch | No | 瞬時ファイル初期化有効化 | SQL 2016+ |
| AuthenticationMode | string | No | SQL認証モード | Windows/Mixed |
| NoPendingRenameCheck | switch | No | 保留中リネームチェックをスキップ | - |
| SaveConfiguration | string | No | 構成ファイル保存先 | - |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- SQL Serverインストールメディア（展開済み）
- Configuration.iniファイル（オプション）
- WMI（CPU情報取得）

## 出力仕様

### 出力データ

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

### 出力先

- PowerShellパイプライン（PSCustomObject形式）

## 処理フロー

### 処理シーケンス

```
1. 前処理（beginブロック）
   └─ コンポーネント定義読み込み
   └─ 内部関数定義（Read-IniFile、Write-IniFile、Update-ServiceCredential）
2. バージョン変換
   └─ Versionパラメータをcanonic versionに変換
3. 機能リスト構築
   └─ Feature指定をSQL Server機能名に展開
4. SA資格情報処理
   └─ Mixed認証で未指定時は128文字パスワード自動生成
5. インスタンスループ
   └─ foreach SqlInstance
6. 前提条件チェック
   └─ 名前解決、保留中再起動チェック、認証テスト
7. インストールメディア検出
   └─ Find-SqlInstanceSetupでsetup.exe検索
8. Configuration.ini生成
   └─ パラメータから構成ファイルを生成
9. アクションプラン作成
   └─ インストール対象リストを構築
10. インストール実行
    └─ Invoke-DbaAdvancedInstall呼び出し（並列対応）
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[バージョン変換]
    B --> C[機能リスト構築]
    C --> D{AuthenticationMode = Mixed?}
    D -->|Yes| E{SaCredential指定?}
    E -->|No| F[128文字パスワード生成]
    E -->|Yes| G[foreach SqlInstance]
    D -->|No| G
    F --> G
    G --> H[名前解決]
    H --> I[保留中再起動チェック]
    I --> J{再起動必要?}
    J -->|Yes| K{Restart指定?}
    K -->|No| L[エラー, Continue]
    K -->|Yes| M[認証プロトコルテスト]
    J -->|No| M
    M --> N{接続成功?}
    N -->|No| O{CredSSP?}
    O -->|Yes| P[CredSSP構成試行]
    P --> Q{接続成功?}
    Q -->|No| R[警告, 代替プロトコル確認]
    Q -->|Yes| S[インストールメディア検索]
    O -->|No| R
    N -->|Yes| S
    R --> S
    S --> T{setup.exe発見?}
    T -->|No| U[エラー, Continue]
    T -->|Yes| V[Configuration.ini生成]
    V --> W[アクションプランに追加]
    W --> G
    L --> G
    U --> G
    G --> X{複数コンピュータ?}
    X -->|Yes| Y[Invoke-Parallel実行]
    X -->|No| Z[Invoke-DbaAdvancedInstall実行]
    Y --> AA[終了]
    Z --> AA
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | バージョンサポート | SQL Server 2008-2025をサポート | 常時 |
| BR-002 | SA自動生成 | Mixed認証でSaCredential未指定時は128文字パスワード自動生成 | AuthenticationMode = Mixed |
| BR-003 | tempdb最適化 | SQL 2016+ではCPUコア数に基づきtempdbファイル数を設定（最大8） | SQL 2016以上 |
| BR-004 | 瞬時ファイル初期化 | SQL 2016+ではSQLSVCINSTANTFILEINIT設定を使用 | SQL 2016以上 |
| BR-005 | CredSSP自動構成 | Credential指定時はCredSSPがデフォルト、必要に応じて自動構成 | リモート接続時 |
| BR-006 | 並列インストール | 複数コンピュータ時はInvoke-Parallelで並列実行 | SqlInstance >= 2 |
| BR-007 | デフォルト管理者 | AdminAccount未指定時は現在のユーザーをsysadminに設定 | 常時 |
| BR-008 | ブラウザサービス | 名前付きインスタンスはAutomatic、デフォルトインスタンスはManual | 常時 |
| BR-009 | Evaluation版 | ProductID未指定時はEvaluation版でインストール | 常時 |
| BR-010 | X86パラメータ | SQL 2022以降ではX86パラメータを削除 | SQL 2022以上 |

### バージョンマッピング

| Version | Canonic Version |
|---------|-----------------|
| 2008 | 10.0 |
| 2008R2 | 10.50 |
| 2012 | 11.0 |
| 2014 | 12.0 |
| 2016 | 13.0 |
| 2017 | 14.0 |
| 2019 | 15.0 |
| 2022 | 16.0 |
| 2025 | 17.0 |

### 機能テンプレート

| Feature | 含まれる機能 |
|---------|-------------|
| Default | Engine, Replication, FullText, Tools |
| All | すべての利用可能な機能 |

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

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

| 操作 | 対象 | 操作種別 | 概要 |
|-----|-----|---------|------|
| インストール | ファイルシステム | CREATE | データベースファイル、システムファイル作成 |
| ポート設定 | レジストリ | UPDATE | TCP/IPポート設定変更 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | PathNotSet | インストールメディアパス未設定 | Set-DbatoolsConfigまたは-Path指定 |
| - | VersionNotSupported | 未サポートバージョン指定 | サポートバージョンを指定 |
| - | PendingReboot | 保留中の再起動あり | コンピュータを再起動 |
| - | ConnectionFailed | リモート接続失敗 | 認証プロトコル、資格情報を確認 |
| - | SetupNotFound | setup.exe未発見 | インストールメディアパスを確認 |
| 3010 | RebootRequired | インストール後再起動が必要 | コンピュータを再起動 |

### リトライ仕様

認証プロトコル失敗時はCredSSP自動構成を試行。それでも失敗時は代替プロトコル使用を確認。

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

SQL Serverインストールはsetup.exe内部でトランザクション管理。本機能はオーケストレーションのみ。

## パフォーマンス要件

- 並列インストール対応（Throttleで制御、デフォルト50）
- ローカルキャッシュによるsetup.exe検索の効率化

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

- SA資格情報の自動生成による強力なパスワード
- CredSSP認証によるネットワーク共有アクセス
- サービスアカウントパスワードはコマンドライン引数で渡される
- 瞬時ファイル初期化によるセキュリティと性能のトレードオフ

## 備考

- インストールメディアは展開済みである必要がある（ISOファイル不可）
- CredSSP構成はdbatools設定で無効化可能
- SupportsShouldProcess対応（WhatIf/Confirm）
- 管理者権限での実行が必要

---

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

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

### 推奨読解順序

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

出力されるオブジェクトの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Install-DbaInstance.ps1 | `public/Install-DbaInstance.ps1` | .OUTPUTSコメント（262-288行目）で出力プロパティを確認 |

**読解のコツ**: デフォルト表示プロパティとその他のプロパティを区別する。

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

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

**主要処理フロー**:
- **Read-IniFile**: Configuration.iniをハッシュテーブルに変換
- **Write-IniFile**: ハッシュテーブルをConfiguration.iniに書き出し
- **Update-ServiceCredential**: サービスアカウント設定を処理

#### Step 3: バージョンと機能処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Install-DbaInstance.ps1 | `public/Install-DbaInstance.ps1` | 491-505行目 バージョン変換 |
| 3-2 | Install-DbaInstance.ps1 | `public/Install-DbaInstance.ps1` | 507-523行目 機能リスト構築 |
| 3-3 | Install-DbaInstance.ps1 | `public/Install-DbaInstance.ps1` | 525-529行目 SA自動生成 |

#### Step 4: 構成ファイル生成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Install-DbaInstance.ps1 | `public/Install-DbaInstance.ps1` | 673-740行目 Configuration.ini生成 |
| 4-2 | Install-DbaInstance.ps1 | `public/Install-DbaInstance.ps1` | 769-795行目 バージョン固有設定 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | Install-DbaInstance.ps1 | `public/Install-DbaInstance.ps1` | 892-911行目 並列インストール処理 |

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

```
Install-DbaInstance
    │
    ├─ begin
    │      ├─ Read-IniFile（内部関数）
    │      ├─ Write-IniFile（内部関数）
    │      ├─ Update-ServiceCredential（内部関数）
    │      └─ Get-Content（コンポーネント定義読み込み）
    │
    └─ process
           ├─ Resolve-DbaNetworkName
           │
           ├─ Test-PendingReboot
           │
           ├─ Initialize-CredSSP
           │
           ├─ Find-SqlInstanceSetup
           │
           ├─ Get-DbaCmObject
           │      └─ Win32_processor（CPU情報）
           │
           ├─ Write-IniFile
           │      └─ Configuration.ini生成
           │
           └─ Invoke-DbaAdvancedInstall / Invoke-Parallel
                  └─ setup.exe実行
```

### データフロー図

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

Version ───────────────▶ バージョン変換 ─────────▶ canonicVersion
        │                                              │
        ▼                                              ▼
Feature ───────────────▶ 機能リスト構築 ─────────▶ featureList
        │                                              │
        ▼                                              ▼
SqlInstance ───────────▶ 名前解決 ─────────────▶ fullComputerName
        │                                              │
        ▼                                              ▼
Credential ────────────▶ 認証テスト ─────────────▶ 接続確立
        │                                              │
        ▼                                              ▼
Path ──────────────────▶ Find-SqlInstanceSetup ──▶ setupFile
        │                                              │
        ▼                                              ▼
Configuration/          ▶ Configuration.ini生成 ──▶ configFile
ConfigurationFile              │
        │                      ▼
        ▼               アクションプラン
EngineCredential/              │
AgentCredential etc.           ▼
        │               Invoke-DbaAdvancedInstall
        ▼                      │
                               ▼
                        PSCustomObject（インストール結果）
                               │
                               ▼
                        パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Install-DbaInstance.ps1 | `public/Install-DbaInstance.ps1` | ソース | メイン機能実装 |
| Invoke-DbaAdvancedInstall.ps1 | `private/functions/Invoke-DbaAdvancedInstall.ps1` | ソース | 実際のインストール実行（依存先） |
| Find-SqlInstanceSetup.ps1 | `private/functions/Find-SqlInstanceSetup.ps1` | ソース | setup.exe検索（依存先） |
| Initialize-CredSSP.ps1 | `private/functions/Initialize-CredSSP.ps1` | ソース | CredSSP構成（依存先） |
| dbatools-sqlinstallationcomponents.json | `bin/dbatools-sqlinstallationcomponents.json` | データ | 機能コンポーネント定義 |
