# 画面設計書 208-SQLパッケージインストール

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるSqlPackageインストール機能の設計仕様を定義するものである。

### 本画面の処理概要

SQLパッケージインストール機能は、Microsoft SqlPackageユーティリティをダウンロードしてインストールする機能を提供する。SqlPackageは、DACPACのインポート/エクスポートやデータベースデプロイメント自動化に必要な前提ツールである。

**業務上の目的・背景**：SqlPackageはMicrosoftが提供するコマンドラインユーティリティで、DACPACファイルの操作に不可欠である。SQL Server Management Studio（SSMS）をインストールすると付属するが、サーバー環境やCI/CDエージェントではSSMSをインストールせずSqlPackageのみが必要な場合がある。本機能は、SqlPackageを自動でダウンロードし、ポータブル（ZIP）またはMSI形式でインストールすることで、DBAの環境構築を支援する。

**画面へのアクセス方法**：PowerShellコンソールから`Install-DbaSqlPackage`コマンドを実行する。

**主要な操作・処理内容**：
1. 既存インストールの確認
2. プラットフォーム（Windows/Linux/macOS）の検出
3. SqlPackageのダウンロード（ZIP/MSI）
4. インストール（ZIP展開またはMSI実行）
5. インストール結果の検証

**画面遷移**：
- 入力元：管理者またはスクリプトからのコマンド実行
- 出力先：インストールされたSqlPackage（Export-DbaDacPackageなどで利用）
- 関連機能：Export-DbaDacPackage、Publish-DbaDacPackage

**権限による表示制御**：
- CurrentUserスコープ：一般ユーザー権限で実行可能
- AllUsersスコープ/MSI：管理者権限が必要

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 322 | Install-DbaSqlPackage | 主機能 | SqlPackageのインストール |
| 60 | Export-DbaDacPackage | 利用先機能 | DACパッケージのエクスポート |
| 64 | Publish-DbaDacPackage | 利用先機能 | DACパッケージの公開 |

## 画面種別

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

## URL/ルーティング

```powershell
# 基本インストール（CurrentUser、ZIP）
Install-DbaSqlPackage

# システムワイドインストール（AllUsers、MSI）
Install-DbaSqlPackage -Scope AllUsers -Type Msi

# カスタムパス指定
Install-DbaSqlPackage -Path C:\SqlPackage
```

## 入出力項目

| パラメータ名 | 型 | 必須 | 既定値 | 説明 |
|-------------|-----|------|--------|------|
| Path | string | No | dbatoolsデータディレクトリ | インストール先パス |
| Scope | string | No | CurrentUser | スコープ（CurrentUser/AllUsers） |
| Type | string | No | Zip | インストール種別（Zip/Msi） |
| LocalFile | string | No | - | ローカルインストールファイルパス |
| Force | switch | No | $false | 再インストールの強制 |
| EnableException | switch | No | $false | 例外の有効化 |
| WhatIf | switch | No | - | 実行内容のプレビュー |
| Confirm | switch | No | - | 実行確認プロンプト |

### Scope と Type の組み合わせ

| Scope | Type | 対応プラットフォーム | 説明 |
|-------|------|-------------------|------|
| CurrentUser | Zip | Windows/Linux/macOS | ユーザーディレクトリにZIP展開 |
| AllUsers | Zip | Windows | Program Filesに展開（要管理者） |
| AllUsers | Msi | Windows | MSIインストール（要管理者） |

## 表示項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Name | string | 実行ファイル名（sqlpackage/SqlPackage.exe） |
| Path | string | インストールされた実行ファイルの完全パス |
| Installed | bool | インストール成功フラグ |
| Notes | string | 追加情報（スキップ時のメッセージなど） |

## イベント仕様

### 1-インストールイベント

1. 既存インストールの確認（Get-DbaSqlPackagePath）
2. プラットフォーム・パラメータの検証
3. デフォルトパスの決定
4. ダウンロードURL/ファイル名の決定
5. ダウンロード実行（必要な場合）
6. インストール実行（ZIP展開またはMSI実行）
7. Unix環境では実行権限付与（chmod +x）
8. インストール検証と結果返却

### 2-ダウンロードイベント

ダウンロードURL（Type/プラットフォーム別）：
| プラットフォーム | Type | URL |
|----------------|------|-----|
| Windows | Zip | https://aka.ms/sqlpackage-windows |
| Windows | Msi | https://aka.ms/dacfx-msi |
| Linux | Zip | https://aka.ms/sqlpackage-linux |
| macOS | Zip | https://aka.ms/sqlpackage-macos |

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

本機能はファイルシステム操作のみであり、データベース操作は発生しない。

## メッセージ仕様

| 種別 | メッセージ | 条件 |
|------|----------|------|
| エラー | "LocalFile cannot be a URL..." | LocalFileがURLの場合 |
| エラー | "MSI installation is only supported on Windows..." | UnixでMSI指定時 |
| エラー | "AllUsers scope is only supported on Windows..." | UnixでAllUsers指定時 |
| エラー | "MSI installation is only supported for AllUsers scope..." | MSI+CurrentUser指定時 |
| エラー | "...require administrative privileges..." | 管理者権限不足時 |
| エラー | "Couldn't download SqlPackage..." | ダウンロード失敗時 |
| エラー | "LocalFile $LocalFile does not exist." | ローカルファイル不存在時 |
| エラー | "Failed to install SqlPackage from $LocalFile..." | MSIインストール失敗時 |
| エラー | "Unable to extract SqlPackage to $Path..." | ZIP展開失敗時 |
| エラー | "SqlPackage installation failed - SqlPackage.exe not found..." | 検証失敗時 |
| 情報 | "SqlPackage already exists at $installedPath. Skipped..." | 既存インストール時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| URL形式のLocalFile | Stop-Functionでエラー |
| プラットフォーム非対応 | Stop-Functionでエラー |
| 権限不足 | Test-ElevationRequirementでチェック |
| ダウンロード失敗 | Stop-Functionでエラー |
| インストール失敗 | Stop-Functionでエラー |

## 備考

- Windows/.NET 8 ZIPバージョンがデフォルト
- MSIは.NET Frameworkバージョン
- プロキシ環境では自動的に既定のネットワーク資格情報を使用
- Forceスイッチで再ダウンロード・再インストール可能

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Install-DbaSqlPackage.ps1 | `public/Install-DbaSqlPackage.ps1` | 出力オブジェクト構造（行69-78, 128-134, 332-336） |

**読解のコツ**: インストール成功、既存インストール、失敗の3パターンで出力が異なる点に注目。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Install-DbaSqlPackage.ps1 | `public/Install-DbaSqlPackage.ps1` | パラメータ定義（行100-110） |

**主要処理フロー**:
1. **行112**: process{}ブロック開始
2. **行115-118**: LocalFile URLチェック
3. **行120-135**: 既存インストール確認
4. **行139-170**: プラットフォーム・権限検証
5. **行173-189**: デフォルトパス決定
6. **行191-236**: ダウンロード処理
7. **行241-297**: インストール処理
8. **行300-339**: 検証と結果返却

#### Step 3: プラットフォーム検証を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Install-DbaSqlPackage.ps1 | `public/Install-DbaSqlPackage.ps1` | プラットフォーム検証（行139-170） |

**主要処理フロー**:
- **行140-151**: Unix環境での制限チェック（MSI/AllUsers非サポート）
- **行152-169**: Windows環境での組み合わせ検証と権限チェック

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Install-DbaSqlPackage.ps1 | `public/Install-DbaSqlPackage.ps1` | インストール処理（行241-297） |

**主要処理フロー**:
- **行248-265**: MSIインストール（msiexec使用）
- **行266-296**: ZIP展開（Expand-Archive使用）
- **行282-290**: Unix環境でのchmod +x実行

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

```
Install-DbaSqlPackage
    |
    +-- process{}
           +-- 既存インストール確認
           |      +-- Get-DbaSqlPackagePath
           |
           +-- プラットフォーム検証
           |      +-- PSEdition チェック (Unix)
           |      +-- Test-ElevationRequirement (Windows)
           |
           +-- デフォルトパス決定
           |      +-- Get-DbatoolsConfigValue (Path.DbatoolsData)
           |
           +-- ダウンロード
           |      +-- Invoke-TlsWebRequest
           |      +-- プロキシ設定 (失敗時)
           |
           +-- インストール
           |      +-- MSI: Start-Process msiexec
           |      +-- ZIP: Expand-Archive
           |             +-- chmod +x (Unix)
           |
           +-- 検証
                  +-- Test-Path (SqlPackage.exe/sqlpackage)
```

### データフロー図

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

Path (オプション) ----+
                      |
Scope ----------------+----> プラットフォーム検証
                      |           |
Type -----------------+           v
                            ダウンロードURL決定
LocalFile (オプション) -------> |
                                 v
                            ダウンロード
                            (aka.ms/sqlpackage-*)
                                 |
                                 v
                            インストール ----> PSCustomObject
                            (MSI or ZIP)        (Name, Path, Installed)
                                 |
                                 v
                            検証 (Test-Path)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Install-DbaSqlPackage.ps1 | `public/Install-DbaSqlPackage.ps1` | ソース | メインコマンド実装 |
| Export-DbaDacPackage.ps1 | `public/Export-DbaDacPackage.ps1` | ソース | SqlPackageの利用先 |
| Publish-DbaDacPackage.ps1 | `public/Publish-DbaDacPackage.ps1` | ソース | SqlPackageの利用先 |
