# バッチ設計書 14-install-dbatools-library.ps1

## 概要

本ドキュメントは、dbatools.libraryモジュールのインストールスクリプトの設計内容を記載したバッチ設計書です。dbatoolsモジュールの依存ライブラリであるdbatools.libraryを、PowerShell GalleryまたはGitHub Releasesからインストールするためのスクリプトについて説明します。

### 本バッチの処理概要

このバッチは、dbatools.libraryモジュールを指定されたバージョンでインストールします。設定ファイルからバージョン情報を読み取り、PowerShell Galleryからのインストールを優先的に試行し、失敗した場合はGitHub Releasesからダウンロードしてインストールします。

**業務上の目的・背景**：dbatoolsモジュールは、dbatools.libraryという依存モジュールを必要とします。このライブラリにはSQL Server Management Objects (SMO)などの.NETアセンブリが含まれており、dbatoolsの動作に不可欠です。特にCI/CD環境やクリーンな開発環境では、このライブラリを自動的にインストールする必要があります。また、プレビュー版を含む特定バージョンの管理も重要であり、本スクリプトはバージョン管理とインストールの自動化を実現します。

**バッチの実行タイミング**：GitHub ActionsワークフローやAppVeyor CIのセットアップフェーズ、または開発者が手動でモジュールをセットアップする際に実行されます。

**主要な処理内容**：
1. 設定ファイル（dbatools-library-version.json）からターゲットバージョンを読み取り
2. 既存インストールの確認（-Forceオプションがない場合はスキップ）
3. プレビュー版の判定（preview、main-数字パターンの検出）
4. PowerShell Galleryからのインストール試行（安定版の場合）
5. GitHub Releasesからのダウンロードとインストール（Gallery失敗時またはプレビュー版の場合）
6. クロスプラットフォーム対応のインストールパス決定（Windows/Linux/macOS）
7. インストール結果の検証とモジュールインポートテスト

**前後の処理との関連**：本スクリプトは、dbatoolsモジュールのImport-Module実行前に実行される必要があります。CI/CDパイプラインでは、テスト実行前のセットアップフェーズで実行されます。

**影響範囲**：PowerShellモジュールパスにdbatools.libraryモジュールをインストールします。スコープに応じて、CurrentUserまたはAllUsersのモジュールディレクトリに影響します。

## バッチ種別

セットアップ / インストール / CI/CDスクリプト

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（手動またはCI/CDトリガー） |
| 実行時刻 | N/A |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | 手動実行 / GitHub Actions / AppVeyor |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| PowerShell | PowerShell 5.1以上またはPowerShell Core 6.0以上 |
| インターネット接続 | PowerShell GalleryまたはGitHub Releasesへのアクセスが可能であること |
| 設定ファイル | .github/dbatools-library-version.jsonが存在すること |
| 書き込み権限 | 指定スコープのモジュールディレクトリへの書き込み権限があること |

### 実行可否判定

設定ファイルが存在し、ターゲットバージョンが指定されている場合に実行されます。既にターゲットバージョンがインストール済みの場合は、-Forceオプションがない限りスキップされます。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| ConfigPath | string | No | .github/dbatools-library-version.json | バージョン設定ファイルのパス |
| Force | switch | No | $false | インストール済みでも再インストールする |
| Scope | string | No | CurrentUser | インストールスコープ（CurrentUser/AllUsers） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| dbatools-library-version.json | JSON | インストールするバージョン情報を含む設定ファイル |
| PowerShell Gallery | Web API | モジュールのダウンロード元（優先） |
| GitHub Releases | Web API | モジュールのダウンロード元（フォールバック） |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | ログメッセージ | インストール進捗とステータス |
| モジュールディレクトリ | PowerShellモジュール | インストールされたdbatools.library |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | dbatools.library（モジュールディレクトリ） |
| 出力先 | $env:USERPROFILE\Documents\PowerShell\Modules (Windows CurrentUser) |
| | $env:ProgramFiles\PowerShell\Modules (Windows AllUsers) |
| | ~/.local/share/powershell/Modules (Unix CurrentUser) |
| | /usr/local/share/powershell/Modules (Unix AllUsers) |
| 文字コード | UTF-8 |
| 区切り文字 | N/A |

## 処理フロー

### 処理シーケンス

```
1. 初期化
   └─ Write-Log関数の定義
   └─ Get-CrossPlatformTempPath関数の定義
   └─ Test-ModuleInstalled関数の定義
   └─ Install-FromPowerShellGallery関数の定義
   └─ Install-FromGitHubRelease関数の定義

2. 設定読み込み
   └─ ConfigPathの存在確認
   └─ JSONファイルからバージョン情報を取得
   └─ ターゲットバージョンのログ出力

3. インストール済み確認
   └─ Test-ModuleInstalledで既存インストールをチェック
   └─ インストール済みかつ-Forceなしの場合はスキップ

4. プレビュー版判定
   └─ バージョン文字列のパターンマッチ（preview、main-数字）
   └─ プレビュー版の場合はGitHub Releasesに直接移行

5. PowerShell Galleryインストール試行（安定版）
   └─ Install-ModuleでGalleryからインストール
   └─ AllowPrereleaseオプションの設定（プレビュー版の場合）

6. GitHub Releasesインストール（フォールバックまたはプレビュー版）
   └─ リリースURLの構築
   └─ ZIPファイルのダウンロード
   └─ 一時ディレクトリへの展開
   └─ モジュールディレクトリへのコピー
   └─ PSModulePathへの追加

7. インストール検証
   └─ Get-Module -ListAvailableでの確認
   └─ Import-Moduleテスト
   └─ 結果のログ出力
```

### フローチャート

```mermaid
flowchart TD
    A[スクリプト開始] --> B[設定ファイル読み込み]
    B --> C{ファイル存在?}
    C -->|No| D[エラー終了]
    C -->|Yes| E[バージョン情報取得]
    E --> F{既にインストール済み?}
    F -->|Yes, -Forceなし| G[スキップ終了]
    F -->|No または -Force| H{プレビュー版?}
    H -->|Yes| I[GitHub Releasesから直接インストール]
    H -->|No| J[PowerShell Galleryからインストール試行]
    J --> K{Gallery成功?}
    K -->|Yes| L[インストール検証]
    K -->|No| I
    I --> M{GitHub成功?}
    M -->|Yes| L
    M -->|No| N[エラー終了]
    L --> O[モジュールインポートテスト]
    O --> P[完了ログ出力]
    P --> Q[正常終了]
```

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

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

本スクリプトはデータベース操作を行いません。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| N/A | N/A | N/A | データベース操作なし |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConfigNotFound | 設定ファイルエラー | 設定ファイルが存在しない場合 | 設定ファイルパスを確認 |
| GalleryInstallFailed | Galleryエラー | PowerShell Galleryからのインストールに失敗 | GitHub Releasesにフォールバック |
| GitHubDownloadFailed | ダウンロードエラー | GitHub Releasesからのダウンロードに失敗 | ネットワーク接続とURLを確認 |
| ModuleNotFound | インストールエラー | インストール後にモジュールが見つからない | インストールパスとPSModulePathを確認 |
| ManifestInvalid | マニフェストエラー | モジュールマニフェストが無効 | ダウンロードファイルの整合性を確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし、フォールバック方式を採用） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A（Gallery失敗時はGitHubへフォールバック） |

### 障害時対応

1. PowerShell Gallery失敗時は自動的にGitHub Releasesからのインストールを試行
2. 両方失敗した場合はエラーログを出力して終了コード1で終了
3. 手動対応として、直接GitHub Releasesからモジュールをダウンロードして手動インストール可能

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A（ファイル操作のみ） |
| コミットタイミング | N/A |
| ロールバック条件 | インストール失敗時に一時ファイルを削除 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1モジュール |
| 目標処理時間 | 2分以内（ネットワーク状況に依存） |
| メモリ使用量上限 | 500MB（ZIPファイル展開時の一時使用） |

## 排他制御

同一システムで複数のインストールプロセスが同時実行されることは想定していません。必要に応じて、呼び出し元で排他制御を行ってください。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | スクリプト開始時 | "Starting dbatools.library installation process..." |
| 情報ログ | 各ステップ実行時 | ターゲットバージョン、インストールスコープ、ダウンロードURL等 |
| 成功ログ | インストール成功時 | "Successfully installed dbatools.library version X from Y" |
| 警告ログ | フォールバック時 | "Failed to install from PowerShell Gallery: ..." |
| エラーログ | インストール失敗時 | "Installation failed: ..." |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 終了コード | 0以外 | CI/CDパイプラインの通知設定 |
| 処理時間 | 5分超過 | CI/CDパイプラインのタイムアウト |

## 備考

- クロスプラットフォーム対応（Windows、Linux、macOS）
- プレビュー版の自動判定機能あり（バージョン文字列にpreviewまたはmain-数字を含む場合）
- Windowsでは、PowerShell CoreとWindows PowerShellの両方のモジュールパスにインストール可能
- GitHub Release URLパターン: https://github.com/dataplat/dbatools.library/releases/download/v{version}/dbatools.library.zip
- ダウンロード時はProgressPreferenceをSilentlyContinueに設定してパフォーマンスを向上
- インストール後、モジュールのインポートテストを実行して動作確認を行う
