# 画面設計書 16-Agentサーバー設定

## 概要

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

### 本画面の処理概要

本機能は、SQL Server Agent のサーバー全体の設定（サービス状態、ログレベル、ジョブ履歴設定、サービスアカウント等）を管理します。複数インスタンスの設定監査、トラブルシューティング、コンプライアンスやマイグレーション計画のための環境設定ドキュメント化に使用されます。

**業務上の目的・背景**：SQL Server Agent の全体設定を一元的に確認・管理する必要があります。SSMS で各インスタンスに個別接続する代わりに、複数インスタンスの Agent 構成を標準化されたビューで取得できます。

**画面へのアクセス方法**：PowerShell コンソールまたはスクリプトから以下のコマンドを実行してアクセスします。
- `Get-DbaAgentServer` - Agent サーバー設定の取得
- `Set-DbaAgentServer` - Agent サーバー設定の変更
- `Copy-DbaAgentServer` - Agent サーバー設定のインスタンス間コピー

**主要な操作・処理内容**：
1. SQL Server Agent のサービス設定・状態情報を取得
2. ジョブ履歴保持設定の変更
3. Agent ログレベルの設定
4. ソースサーバーから宛先サーバーへの設定移行

**画面遷移**：本機能はCLIコマンドです。

**権限による表示制御**：sysadmin 権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 494 | Get-DbaAgentServer | 主機能 | SQLエージェントサーバー設定の取得 |
| 520 | Set-DbaAgentServer | 主機能 | SQLエージェントサーバー設定の変更 |
| 481 | Copy-DbaAgentServer | 補助機能 | エージェントサーバー設定のコピー |

## 画面種別

詳細 / 設定

## URL/ルーティング

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

## 入出力項目

### Get-DbaAgentServer パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象のSQL Serverインスタンス |
| SqlCredential | PSCredential | No | 代替認証情報 |
| EnableException | switch | No | 例外を有効化 |

## 表示項目

### Get-DbaAgentServer 出力

| 項目名 | 説明 |
|--------|------|
| ComputerName | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | SQL Serverインスタンス名 |
| SqlInstance | 完全なSQL Serverインスタンス名 |
| AgentDomainGroup | Agent用Active Directoryドメイングループ |
| AgentLogLevel | Agentエラーログの詳細レベル |
| AgentMailType | 使用するメールシステム（SqlAgentMail/DatabaseMail） |
| AgentShutdownWaitTime | 再起動時のAgent終了待機時間（秒） |
| ErrorLogFile | Agentエラーログファイルのフルパス |
| IdleCpuDuration | CPUアイドル判定持続時間（秒） |
| IdleCpuPercentage | CPUアイドル判定閾値（%） |
| IsCpuPollingEnabled | CPUアイドル条件監視有効/無効 |
| JobServerType | サーバーロール（Master/Target等） |
| LoginTimeout | Agent接続タイムアウト（秒） |
| JobHistoryIsEnabled | ジョブ履歴収集有効/無効（計算値） |
| MaximumHistoryRows | ジョブ履歴最大行数（-1で無制限） |
| MaximumJobHistoryRows | ジョブ別最大履歴行数 |
| ServiceAccount | Agentサービス実行アカウント |
| ServiceStartMode | サービス起動モード（Automatic/Manual/Disabled） |
| SqlAgentAutoStart | SQL Server起動時に自動開始 |
| SqlAgentRestart | 予期せず停止時に自動再起動 |
| SqlServerRestart | SQL Serverサービス再起動可能 |
| State | Agentサービス状態（Running/Stopped等） |
| SysAdminOnly | sysadminのみアクセス可能 |

## イベント仕様

### 1-Agentサーバー設定取得

**処理フロー**:
1. `Connect-DbaInstance` でSQL Serverインスタンスに接続
2. `$server.JobServer` でJobServerオブジェクトを取得
3. `Add-Member` でComputerName/InstanceName/SqlInstanceを追加
4. `JobHistoryIsEnabled` を ScriptProperty として追加（MaximumHistoryRows != -1 で true）
5. `Select-DefaultView` で整形して出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaAgentServer | - | SELECT（SMO経由） | Agent設定の取得 |
| Set-DbaAgentServer | msdb設定 | UPDATE | Agent設定の更新 |

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|---------------|------|---------------|
| Error | 接続失敗 | "Failure" (ConnectionError) |

## 備考

- `JobHistoryIsEnabled` は `MaximumHistoryRows` から計算される ScriptProperty
- MaximumHistoryRows = -1 の場合、ジョブ履歴収集は無効（false）
- JobServer オブジェクトは多数の追加プロパティ（Jobs、Alerts、Operators等のコレクション）を持つ

---

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

### 推奨読解順序

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

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaAgentServer.ps1 | `public/Get-DbaAgentServer.ps1` | 108-114行: パラメータ定義 |
| 2-2 | Get-DbaAgentServer.ps1 | `public/Get-DbaAgentServer.ps1` | 124行: $server.JobServer でJobServer取得 |
| 2-3 | Get-DbaAgentServer.ps1 | `public/Get-DbaAgentServer.ps1` | 131行: JobHistoryIsEnabled の ScriptProperty |

**主要処理フロー**:
- **124行**: `$jobServer = $server.JobServer` でJobServerオブジェクト取得
- **126行**: デフォルト表示プロパティ定義
- **131行**: `JobHistoryIsEnabled` は `MaximumHistoryRows` から計算

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

```
Get-DbaAgentServer
    |
    +-- Connect-DbaInstance (接続確立)
    |
    +-- $server.JobServer (JobServer取得)
    |
    +-- Add-Member (カスタムプロパティ追加)
    |       |
    |       +-- ComputerName
    |       +-- InstanceName
    |       +-- SqlInstance
    |       +-- JobHistoryIsEnabled (ScriptProperty)
    |
    +-- Select-DefaultView (出力整形)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaAgentServer.ps1 | `public/Get-DbaAgentServer.ps1` | ソース | Agent設定取得のメインコマンド |
| Set-DbaAgentServer.ps1 | `public/Set-DbaAgentServer.ps1` | ソース | Agent設定変更コマンド |
| Copy-DbaAgentServer.ps1 | `public/Copy-DbaAgentServer.ps1` | ソース | Agent設定コピーコマンド |
