# 画面設計書 14-Agentスケジュール管理

## 概要

本ドキュメントは、SQL Server Agent スケジュールの作成・取得・設定・削除・コピー機能を提供するコマンド群の設計仕様を記述したものです。

### 本画面の処理概要

本機能は、SQL Server Agent の共有スケジュールを管理します。共有スケジュールは複数のジョブで再利用可能で、メンテナンスウィンドウの標準化やスケジュール管理のオーバーヘッド削減に役立ちます。

**業務上の目的・背景**：SQL Server Agent ジョブの実行タイミングを一元管理するため、共有スケジュールの作成・管理が必要です。スケジュールの監査、ドキュメント化、自動実行パターンのトラブルシューティングに使用されます。

**画面へのアクセス方法**：PowerShell コンソールまたはスクリプトから以下のコマンドを実行してアクセスします。
- `Get-DbaAgentSchedule` - スケジュール設定の取得
- `New-DbaAgentSchedule` - スケジュールの新規作成
- `Set-DbaAgentSchedule` - スケジュールの設定変更
- `Remove-DbaAgentSchedule` - スケジュールの削除
- `Copy-DbaAgentSchedule` - スケジュールのインスタンス間コピー

**主要な操作・処理内容**：
1. SQL Server インスタンスからスケジュール設定一覧を取得し、人間が読める説明を生成
2. 新規スケジュールの作成（日次、週次、月次、相対月次等）
3. 既存スケジュールの頻度・時刻設定の更新
4. 不要なスケジュールの削除
5. ソースサーバーから宛先サーバーへのスケジュール設定の移行

**画面遷移**：本機能はCLIコマンドであり、他のコマンドとパイプライン連携が可能です。

**権限による表示制御**：SQLAgentOperatorRole または sysadmin 権限が必要です。Express Edition では SQL Agent が存在しないため、エラーメッセージが表示されます。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 493 | Get-DbaAgentSchedule | 主機能 | SQLエージェントスケジュールの取得 |
| 503 | New-DbaAgentSchedule | 主機能 | SQLエージェントスケジュールの新規作成 |
| 511 | Remove-DbaAgentSchedule | 主機能 | SQLエージェントスケジュールの削除 |
| 519 | Set-DbaAgentSchedule | 補助機能 | SQLエージェントスケジュールの設定変更 |
| 480 | Copy-DbaAgentSchedule | 補助機能 | スケジュールのコピー |

## 画面種別

一覧 / 登録 / 編集 / 削除

## URL/ルーティング

PowerShell コマンドとして提供（CLIベース）

## 入出力項目

### Get-DbaAgentSchedule パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象のSQL Serverインスタンス |
| SqlCredential | PSCredential | No | 代替認証情報 |
| Schedule | string[] | No | 取得するスケジュール名 |
| ScheduleUid | string[] | No | スケジュールUID |
| Id | int[] | No | スケジュールID |
| EnableException | switch | No | 例外を有効化 |

## 表示項目

### Get-DbaAgentSchedule 出力

| 項目名 | 説明 |
|--------|------|
| ComputerName | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | SQL Serverインスタンス名 |
| SqlInstance | 完全なSQL Serverインスタンス名 |
| ScheduleName | スケジュール名 |
| ActiveStartDate | 有効開始日 |
| ActiveStartTimeOfDay | 有効開始時刻 |
| ActiveEndDate | 有効終了日（9999年は無期限） |
| ActiveEndTimeOfDay | 有効終了時刻 |
| DateCreated | 作成日時 |
| FrequencyTypes | 頻度タイプ（Once/Daily/Weekly/Monthly等） |
| FrequencyInterval | 頻度間隔 |
| FrequencySubDayTypes | サブ日頻度タイプ |
| FrequencySubDayInterval | サブ日間隔 |
| FrequencyRecurrenceFactor | 繰り返し係数 |
| FrequencyRelativeIntervals | 相対間隔（First/Second/Third/Fourth/Last） |
| IsEnabled | 有効/無効 |
| JobCount | 使用ジョブ数 |
| Description | スケジュール説明（自動生成） |
| ScheduleUid | スケジュールUID |

## イベント仕様

### 1-スケジュール取得

**処理フロー**:
1. `Connect-DbaInstance` でSQL Serverインスタンスに接続
2. Express Editionチェック
3. `$server.JobServer.SharedSchedules.Refresh()` で最新データを取得
4. Name/ScheduleUid/Id でフィルタリング
5. `Get-ScheduleDescription` で人間が読める説明を生成
6. `Select-DefaultView` で整形して出力

### 2-スケジュール説明生成

内部関数 `Get-ScheduleDescription` の処理:
1. FrequencyTypes に応じて説明文を構築
2. Daily: 「day」または「X day(s)」
3. Weekly: 曜日ビットマスクを解析して曜日名を列挙
4. Monthly: 「month on day X」
5. MonthlyRelative: First/Second/Third/Fourth/Last + 曜日
6. サブ日タイプ（秒/分/時）の説明追加
7. 開始日・終了日の説明追加

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaAgentSchedule | msdb.dbo.sysschedules | SELECT | スケジュール設定の取得 |
| New-DbaAgentSchedule | msdb.dbo.sysschedules | INSERT | スケジュールの新規作成 |
| Set-DbaAgentSchedule | msdb.dbo.sysschedules | UPDATE | スケジュール設定の更新 |
| Remove-DbaAgentSchedule | msdb.dbo.sysschedules | DELETE | スケジュールの削除 |

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|---------------|------|---------------|
| Error | Express Edition | "$($server.Edition) does not support SQL Server Agent. Skipping $server." |
| Error | 接続失敗 | "Failure" (ConnectionError) |

## 備考

- FrequencyInterval のビットマスク: 日=1, 月=2, 火=4, 水=8, 木=16, 金=32, 土=64
- ActiveEndDate.Year = 9999 は終了日未設定を意味する
- 説明文はカルチャ設定に応じた日付・時刻フォーマットで生成される

---

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaAgentSchedule.ps1 | `public/Get-DbaAgentSchedule.ps1` | 50-82行: .OUTPUTS セクションでSharedScheduleオブジェクト構造を確認 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaAgentSchedule.ps1 | `public/Get-DbaAgentSchedule.ps1` | 108-117行: パラメータ定義 |
| 2-2 | Get-DbaAgentSchedule.ps1 | `public/Get-DbaAgentSchedule.ps1` | 119-286行: Get-ScheduleDescription内部関数 |

**主要処理フロー**:
- **141-146行**: FrequencyTypesに応じた基本説明の構築
- **175-206行**: 週次スケジュールの曜日ビットマスク解析
- **267-271行**: サブ日タイプ（秒/分/時）の説明追加

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

```
Get-DbaAgentSchedule
    |
    +-- Connect-DbaInstance (接続確立)
    |
    +-- Express Editionチェック
    |
    +-- $server.JobServer.SharedSchedules.Refresh()
    |
    +-- Filter: -Schedule, -ScheduleUid, -Id
    |
    +-- Get-ScheduleDescription (説明生成)
    |       |
    |       +-- FrequencyTypes解析
    |       +-- 曜日ビットマスク解析
    |       +-- サブ日タイプ処理
    |
    +-- Select-DefaultView (出力整形)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaAgentSchedule.ps1 | `public/Get-DbaAgentSchedule.ps1` | ソース | スケジュール取得のメインコマンド |
| New-DbaAgentSchedule.ps1 | `public/New-DbaAgentSchedule.ps1` | ソース | スケジュール作成コマンド |
| Set-DbaAgentSchedule.ps1 | `public/Set-DbaAgentSchedule.ps1` | ソース | スケジュール設定変更コマンド |
| Remove-DbaAgentSchedule.ps1 | `public/Remove-DbaAgentSchedule.ps1` | ソース | スケジュール削除コマンド |
| Copy-DbaAgentSchedule.ps1 | `public/Copy-DbaAgentSchedule.ps1` | ソース | スケジュールコピーコマンド |
