# バッチ設計書 16-cleanup.ps1

## 概要

本ドキュメントは、dbatoolsモジュールの古いバージョンをクリーンアップするスクリプトの設計内容を記載したバッチ設計書です。システムにインストールされているdbatoolsモジュールの複数バージョンを検出し、最新バージョン以外をアンインストールするためのユーティリティスクリプトについて説明します。

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

このバッチは、システムにインストールされているdbatoolsモジュールのバージョンを確認し、古いバージョンをアンインストールしてディスク容量を解放します。最新バージョンがインストールされていない場合は、新しいバージョンのインストールも行います。

**業務上の目的・背景**：dbatoolsモジュールは頻繁にアップデートされ、PowerShellのモジュール管理では古いバージョンが自動的に削除されないため、複数バージョンが蓄積してディスク容量を消費します。また、複数バージョンの存在は、モジュールのロード時に予期しない動作を引き起こす可能性があります。本スクリプトは、古いバージョンを安全に削除し、システムをクリーンな状態に保つことを目的としています。

**バッチの実行タイミング**：開発者やDBAが手動で実行します。モジュールのアップデート後や、ディスク容量の整理が必要な際に実行されます。

**主要な処理内容**：
1. 現在インストールされているdbatoolsの全バージョンを取得
2. PowerShell Galleryから最新バージョン情報を取得
3. 各バージョンのインストールスコープ（User/AllUsers）を判定
4. PowerShellプロセス（他のpowershell/pwshプロセス）の検出と終了確認
5. 古いバージョンのアンインストール（WhatIf/Confirmサポート）
6. 最新バージョンがない場合はインストール

**前後の処理との関連**：本スクリプトは独立したユーティリティであり、特定の前後処理はありません。ただし、実行中のPowerShellセッションでdbatoolsを使用している場合は、事前にモジュールをアンロードする必要があります。

**影響範囲**：システムにインストールされているdbatoolsモジュールのファイルとレジストリエントリに影響します。AllUsersスコープのモジュール削除には管理者権限が必要です。

## バッチ種別

ユーティリティ / メンテナンス / クリーンアップ

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（手動実行） |
| 実行時刻 | N/A |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | 手動実行 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| PowerShell | PowerShell 5.1以上またはPowerShell Core 6.0以上 |
| インターネット接続 | PowerShell Galleryへのアクセスが可能であること（最新バージョン確認用） |
| dbatoolsインストール済み | Get-InstalledModuleで取得可能なdbatoolsがインストールされていること |
| 管理者権限（一部） | AllUsersスコープのモジュール削除には管理者権限が必要 |

### 実行可否判定

dbatoolsモジュールがインストールされており、かつ複数バージョンが存在する場合に有効です。単一バージョンのみの場合は、削除対象がないためスキップされます。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| module | string | No | "dbatools" | クリーンアップ対象のモジュール名 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| Get-InstalledModule | PowerShellコマンド | インストール済みモジュール情報 |
| PowerShell Gallery | Web API | 最新バージョン情報 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | 処理状況メッセージ |
| 標準エラー | 警告メッセージ | アンインストール失敗時の警告 |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | N/A（ファイル出力なし） |
| 出力先 | 標準出力のみ |
| 文字コード | UTF-8 |
| 区切り文字 | N/A |

## 処理フロー

### 処理シーケンス

```
1. 実行環境の判定
   └─ PowerShell Core/Desktopの判定
   └─ プロセス名の決定（pwsh/powershell）
   └─ Windows環境の場合は管理者権限チェック

2. PowerShell ISEの確認（Windowsのみ）
   └─ ISEプロセスの検出
   └─ ISE使用中の場合は警告メッセージを返して終了

3. インストール済みバージョンの取得
   └─ Get-InstalledModule dbatools -AllVersions
   └─ 各バージョンのインストール場所を確認
   └─ UserスコープとAllUsersスコープの判定

4. 最新バージョンの確認
   └─ Find-Module dbatoolsでGalleryから最新バージョン取得
   └─ インストール済みバージョンとの比較

5. 古いバージョンの特定
   └─ 最新バージョン未満のバージョンをリストアップ
   └─ アンインストール対象として設定

6. 他のPowerShellプロセスの処理
   └─ 現在のプロセス以外のpowershell/pwshプロセスを検出
   └─ ユーザー確認後にプロセスを終了（ShouldProcess）

7. 古いバージョンのアンインストール
   └─ 各バージョンをUninstall-Moduleで削除
   └─ 管理者権限が必要な場合は警告を出力
   └─ エラー時は警告メッセージを出力して続行

8. 最新バージョンのインストール（必要に応じて）
   └─ 最新バージョンがない場合はInstall-Moduleを実行

9. 完了メッセージ
   └─ "The End"を出力
```

### フローチャート

```mermaid
flowchart TD
    A[スクリプト開始] --> B[実行環境判定]
    B --> C{PowerShell ISE?}
    C -->|Yes| D[警告出力して終了]
    C -->|No| E[インストール済みバージョン取得]
    E --> F[Gallery最新バージョン取得]
    F --> G{複数バージョン存在?}
    G -->|No| H{最新版インストール済み?}
    H -->|Yes| I[アクション不要で終了]
    H -->|No| J[最新版インストール]
    G -->|Yes| K{最新版インストール済み?}
    K -->|Yes| L[古いバージョン特定]
    K -->|No| M[古いバージョン特定 + 最新版必要フラグ]
    L --> N{他のPSプロセス存在?}
    M --> N
    N -->|Yes| O[プロセス終了確認]
    O --> P[プロセス終了]
    N -->|No| Q[古いバージョンアンインストール]
    P --> Q
    Q --> R{管理者権限エラー?}
    R -->|Yes| S[警告出力]
    R -->|No| T{最新版必要?}
    S --> T
    T -->|Yes| J
    T -->|No| U[完了メッセージ]
    J --> U
    U --> V[スクリプト終了]
```

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

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ISEInUse | 環境エラー | PowerShell ISEが実行中の場合 | ISEを閉じてから再実行 |
| AdminRightsRequired | 権限エラー | AllUsersスコープのモジュール削除で管理者権限がない場合 | 管理者権限でPowerShellを起動して再実行 |
| UninstallFailed | アンインストールエラー | モジュールのアンインストールに失敗した場合 | モジュールがロードされていないことを確認、手動で削除 |
| ProcessKillFailed | プロセスエラー | 他のPowerShellプロセスの終了に失敗した場合 | 手動でプロセスを終了してから再実行 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

1. PowerShell ISEエラー：ISEを閉じてから再実行
2. 権限エラー：管理者権限でPowerShellを起動して再実行
3. プロセス終了失敗：タスクマネージャーで対象プロセスを手動終了
4. アンインストール失敗：モジュールディレクトリを手動で削除

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A（ファイル操作のみ） |
| コミットタイミング | 各Uninstall-Module実行後 |
| ロールバック条件 | ロールバック不可（削除されたモジュールは再インストールが必要） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1-10バージョン程度 |
| 目標処理時間 | 1分以内（バージョン数に依存） |
| メモリ使用量上限 | 標準的なPowerShellセッションの範囲内 |

## 排他制御

SupportsShouldProcessとConfirmImpact='High'により、重要な操作（プロセス終了、モジュール削除）には確認プロンプトが表示されます。-WhatIfパラメータでドライラン実行が可能です。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 情報ログ | バージョン取得後 | "The currently installed version(s) of $module is/are: ..." |
| 情報ログ | 最新バージョン取得後 | "The latest version of $module in the PSGallery is: ..." |
| 情報ログ | プロセス終了時 | "Death to the following process(es): ..." |
| 警告ログ | 権限不足時 | "Elevated session is required to uninstall $module version: ..." |
| 警告ログ | アンインストール失敗時 | "Unable to remove $module version [...] due to: ..." |
| 完了ログ | スクリプト終了時 | "The End" |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| N/A | N/A | N/A（手動実行のため監視なし） |

## 備考

- ルートディレクトリ（リポジトリルート）に配置されているユーティリティスクリプトです
- CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')により、-WhatIfと-Confirmがサポートされています
- PowerShell Coreではpwsh、Windows PowerShellではpowershellプロセスを検索します
- Windows環境では、C:\Users配下のインストールはUserスコープ、それ以外はAllUsersスコープと判定されます
- PowerShell ISEで実行すると、ファイルロックの問題が発生する可能性があるため、ISE検出時は処理を中断します
- 他のPowerShellプロセスがモジュールをロードしている可能性があるため、プロセス終了の確認を行います
- 管理者権限がない場合、AllUsersスコープのモジュールは削除できず、警告メッセージが表示されます
