# バッチ設計書 1-dbatools-maintenance.ps1

## 概要

本ドキュメントは、dbatoolsモジュールのメンテナンスタスクをバックグラウンドで実行するRunspaceスクリプト「dbatools-maintenance.ps1」の設計仕様を記載したものである。

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

本スクリプトは、dbatoolsモジュールのメンテナンスタスクを非同期で実行するバックグラウンドRunspaceを管理する。モジュール内部で登録されたメンテナンスタスクを定期的にポーリングし、順次実行することで、メインスレッドのパフォーマンスに影響を与えることなく、バックグラウンドでの定期処理を実現する。

**業務上の目的・背景**：dbatoolsモジュールは多数のSQL Server管理コマンドを提供しており、キャッシュのクリーンアップ、接続プールの管理、一時データの整理などの定期的なメンテナンス処理が必要となる。これらの処理をメインスレッドで同期的に実行すると、ユーザーの操作を妨げる可能性があるため、バックグラウンドRunspaceで非同期に実行する仕組みが必要である。本スクリプトはその中核となるメンテナンスタスクスケジューラとして機能する。

**バッチの実行タイミング**：dbatoolsモジュールのインポート時に自動的に開始され、モジュールがアンロードされるまで継続的に実行される。5秒間隔でMaintenanceHostからタスクをポーリングする。

**主要な処理内容**：
1. private/maintenanceディレクトリ配下のメンテナンススクリプトをドットソースで読み込む
2. バックグラウンドRunspaceを登録・開始する
3. 無限ループでRunspaceの状態を監視し、停止要求があれば終了する
4. MaintenanceHostからGetNextTaskメソッドで次の実行対象タスクを取得する
5. 取得したタスクのScriptBlockを実行し、例外が発生した場合はWrite-Messageでログ出力する
6. タスクのLastExecutionを更新し、実行済みタスクリストに追加する
7. 全タスク処理後、5秒間スリープしてから次のポーリングサイクルを開始する

**前後の処理との関連**：本スクリプトはモジュール初期化時にdbatools.psm1から呼び出される。dbatools-loggingやdbatools-teppasyncacheなど他のバックグラウンドRunspaceと並行して動作する。メンテナンスタスク自体はprivate/maintenanceディレクトリ内の各スクリプトで定義される。

**影響範囲**：dbatoolsモジュール全体のメンテナンス処理に影響する。メモリ使用量、一時ファイル、キャッシュデータなどのクリーンアップ処理がこのスクリプトを通じて実行される。

## バッチ種別

バックグラウンドメンテナンス / タスクスケジューラ

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 継続的（5秒間隔でポーリング） |
| 実行時刻 | モジュールインポート時に開始 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | dbatoolsモジュールのインポート |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| dbatoolsモジュールのロード | dbatools.psm1が正常にインポートされていること |
| .NET Frameworkランタイム | Dataplat.Dbatools.dllが利用可能であること |
| private/maintenanceディレクトリ | メンテナンススクリプトが配置されていること |

### 実行可否判定

Runspaceの状態が"Running"である限り継続実行される。状態が"Running"以外になった場合、ループを抜けて終了処理を行う。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | 本スクリプトは直接パラメータを受け取らない |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| MaintenanceHost | .NETクラス | Dataplat.Dbatools.Maintenance.MaintenanceHostからタスクを取得 |
| private/maintenance/*.ps1 | PowerShellスクリプト | メンテナンスタスク定義スクリプト |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| なし | - | 直接的な出力はない（タスク実行の副作用として各種処理が行われる） |

### 出力ファイル仕様

本スクリプト自体はファイル出力を行わない。実行されるメンテナンスタスクによってはログファイル等が出力される場合がある。

## 処理フロー

### 処理シーケンス

```
1. メンテナンススクリプトの読み込み
   └─ private/maintenanceディレクトリの全.ps1ファイルをドットソースまたはImport-Commandで読み込み
2. バックグラウンドRunspace用ScriptBlockの定義
   └─ $scriptBlockにメインループ処理を定義
3. モジュールのインポート
   └─ dbatoolsモジュールを内部アクセス可能な形式でインポート
4. メインループ開始
   └─ while($true)で無限ループ
5. Runspace状態チェック
   └─ 状態が"Running"以外なら終了
6. タスク取得ループ
   └─ MaintenanceHost.GetNextTask()でタスクを取得
7. タスク実行
   └─ ScriptBlock.Create().Invoke()でタスクを実行
8. エラーハンドリング
   └─ 例外発生時はWrite-Messageでログ出力
9. タスク完了処理
   └─ LastExecutionを更新、タスク名を完了リストに追加
10. スリープ
    └─ 5秒間待機後、次のサイクルへ
11. 終了処理
    └─ SignalStopped()でRunspaceの停止を通知
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[メンテナンススクリプト読み込み]
    B --> C[Runspace登録・開始]
    C --> D[モジュールインポート]
    D --> E{Runspace状態確認}
    E -->|Running| F[タスク取得]
    E -->|停止要求| K[終了処理]
    F --> G{タスクあり?}
    G -->|あり| H[タスク実行]
    H --> I[LastExecution更新]
    I --> F
    G -->|なし| J[5秒スリープ]
    J --> E
    K --> L[SignalStopped]
    L --> M[バッチ終了]
```

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

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

本スクリプト自体はデータベース操作を行わない。実行されるメンテナンスタスクによってはSQL Server接続が行われる場合がある。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | タスク実行エラー | メンテナンスタスクのScriptBlock実行時に例外が発生 | Write-Messageでログ出力後、次のタスクを継続実行 |
| - | モジュールインポートエラー | dbatoolsモジュールのインポートに失敗 | Runspaceが停止する |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0回（タスク単位でのリトライは行わない） |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし（次回ポーリングサイクルで再取得される可能性あり） |

### 障害時対応

タスク実行時のエラーはキャッチされ、ログ出力後に処理が継続される。致命的なエラーが発生した場合はfinallyブロックでSignalStopped()が呼び出され、Runspaceの停止が通知される。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 数件〜十数件のメンテナンスタスク |
| 目標処理時間 | 各タスク数秒以内 |
| メモリ使用量上限 | Runspace単位で数MB程度 |

## 排他制御

Runspaceは単一インスタンスで動作する。タスクの取得はGetNextTask()メソッドで管理され、同一タスクが重複実行されないようtasksDone配列で追跡される。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| エラーログ | タスク実行エラー時 | タスク名、エラーメッセージ、ErrorRecord |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| Runspace状態 | Running以外 | 自動終了処理 |

## 備考

- 本スクリプトはprivate/scripts/配下に配置されている
- serialimportフラグによってドットソース/Import-Commandの使い分けが行われる
- disablerunspaceteppフラグを設定してモジュールをインポートすることで、TEPP機能の無効化を行っている
