# 機能設計書 520-Set-DbaAgentServer

## 概要

本ドキュメントは、SQL Server Agentサービスの設定を変更するdbatools関数「Set-DbaAgentServer」の機能設計書である。

### 本機能の処理概要

Set-DbaAgentServerは、SQL Server Agentサービスの各種設定プロパティを変更する包括的な機能を提供する。

**業務上の目的・背景**：SQL Server Agentは、ジョブスケジューリング、アラート、監視の中核を担うサービスである。エンタープライズ環境では、複数インスタンスのAgent設定を標準化し、適切なログレベル、メールプロファイル、ジョブ履歴保持ポリシー、CPU監視設定などを統一することが重要である。本機能により、SSMSでの手動設定を省略し、複数サーバーへの一括設定が可能になる。

**機能の利用シーン**：
- ジョブ履歴の保持ポリシー設定（MSDB肥大化防止）
- Database Mailプロファイルの設定
- ログレベルの調整（トラブルシューティング時）
- CPU監視設定（アイドル時ジョブ実行用）
- Agentサービスの自動起動/自動再起動設定
- 環境間でのAgent設定の標準化

**主要な処理内容**：
1. 対象SQL Serverインスタンスへの接続
2. JobServerオブジェクトの取得とリフレッシュ
3. 各種設定プロパティの検証と設定
4. SMO Alter()メソッドによる変更のコミット
5. 更新後のJobServer情報の取得と返却

**関連システム・外部連携**：SQL Server JobServer、Database Mail

**権限による制御**：sysadmin権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | SQL Server Management Studio - SQL Agent Properties | 参照画面 | Agentプロパティの確認・編集 |
| - | PowerShell Console | 主画面 | コマンド実行インターフェース |

## 機能種別

データ更新操作 (UPDATE)

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | - |
| SqlCredential | PSCredential | No | 代替認証資格情報 | - |
| InputObject | JobServer[] | No | パイプラインからのJobServerオブジェクト | - |
| AgentLogLevel | object | No | ログレベル | Errors, Warnings, Informational, All等 |
| AgentMailType | object | No | メールタイプ | SqlAgentMail, DatabaseMail |
| AgentShutdownWaitTime | int | No | シャットダウン待機時間（秒） | 5-600 |
| DatabaseMailProfile | string | No | Database Mailプロファイル名 | 存在するプロファイル |
| ErrorLogFile | string | No | エラーログファイルパス | - |
| IdleCpuDuration | int | No | CPU アイドル判定時間（秒） | 20-86400 |
| IdleCpuPercentage | int | No | CPUアイドル判定閾値（%） | 10-100 |
| CpuPolling | string | No | CPU監視有効/無効 | Enabled, Disabled |
| LocalHostAlias | string | No | ローカルホストエイリアス | - |
| LoginTimeout | int | No | ログインタイムアウト（秒） | 5-45 |
| MaximumHistoryRows | int | No | 最大履歴行数 | -1または2-999999 |
| MaximumJobHistoryRows | int | No | ジョブあたり最大履歴行数 | 0または2-999999 |
| NetSendRecipient | string | No | NetSend受信者 | - |
| ReplaceAlertTokens | string | No | アラートトークン置換 | Enabled, Disabled |
| SaveInSentFolder | string | No | 送信済みフォルダに保存 | Enabled, Disabled |
| SqlAgentAutoStart | string | No | Agent自動起動 | Enabled, Disabled |
| SqlAgentMailProfile | string | No | SQL Agent Mailプロファイル | - |
| SqlAgentRestart | string | No | Agent自動再起動 | Enabled, Disabled |
| SqlServerRestart | string | No | SQL Server再起動許可 | Enabled, Disabled |
| WriteOemErrorLog | string | No | OEMエラーログ出力 | Enabled, Disabled |
| EnableException | switch | No | 例外処理を有効化 | - |

### 入力データソース

- Get-DbaAgentServerからのパイプライン入力
- SQL Server JobServerオブジェクト

## 出力仕様

### 出力データ

Get-DbaAgentServerからのJobServerオブジェクト

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Name | string | SQL Serverエージェント名 |
| AgentLogLevel | string | ログレベル |
| DatabaseMailProfile | string | Database Mailプロファイル |
| SqlAgentAutoStart | bool | 自動起動設定 |
| SqlAgentRestart | bool | 自動再起動設定 |

### 出力先

PowerShellパイプライン（Get-DbaAgentServerの出力）

## 処理フロー

### 処理シーケンス

```
1. 初期設定（beginブロック）
   ├─ AgentMailTypeの文字列→整数変換
   ├─ AgentLogLevelの文字列→整数変換
   └─ MaximumHistoryRows/MaximumJobHistoryRowsの範囲検証

2. インスタンス処理（processブロック）
   ├─ 入力検証（InputObjectまたはSqlInstance）
   ├─ Connect-DbaInstanceで接続
   ├─ JobServer.Refresh()
   └─ InputObjectに追加

3. 各JobServerの処理
   ├─ AgentLogLevel設定
   ├─ AgentMailType設定
   ├─ AgentShutdownWaitTime設定
   ├─ DatabaseMailProfile設定（存在確認）
   ├─ ErrorLogFile設定
   ├─ IdleCpuDuration設定
   ├─ IdleCpuPercentage設定
   ├─ IsCpuPollingEnabled設定
   ├─ LocalHostAlias設定
   ├─ LoginTimeout設定
   ├─ MaximumHistoryRows設定
   ├─ MaximumJobHistoryRows設定
   ├─ NetSendRecipient設定
   ├─ ReplaceAlertTokensEnabled設定
   ├─ SaveInSentFolder設定
   ├─ SqlAgentAutoStart設定
   ├─ SqlAgentMailProfile設定
   ├─ SqlAgentRestart設定
   ├─ SqlServerRestart設定
   └─ WriteOemErrorLog設定

4. 変更のコミット
   ├─ ShouldProcess確認
   ├─ Alter()メソッド呼び出し
   └─ Get-DbaAgentServerで結果取得

5. 完了処理（endブロック）
   └─ 完了メッセージ出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[beginブロック: パラメータ変換]
    B --> C[AgentMailType変換]
    C --> D[AgentLogLevel変換]
    D --> E[履歴行数検証]
    E --> F{検証OK?}
    F -->|No| G[エラー: パラメータ不正]
    F -->|Yes| H[processブロック]
    H --> I{InputObject/SqlInstance指定?}
    I -->|No| J[エラー: インスタンス必須]
    I -->|Yes| K[各インスタンスをループ]
    K --> L[Connect-DbaInstance]
    L --> M[JobServer.Refresh]
    M --> N[InputObjectに追加]
    N --> O[各JobServerをループ]
    O --> P[各種プロパティ設定]
    P --> Q{DatabaseMailProfile指定?}
    Q -->|Yes| R{プロファイル存在?}
    R -->|No| S[警告: プロファイル不存在]
    R -->|Yes| T[プロファイル設定]
    Q -->|No| T
    S --> T
    T --> U[ShouldProcess確認]
    U --> V[Alter実行]
    V --> W[Get-DbaAgentServer]
    W --> X{次のJobServer?}
    X -->|Yes| O
    X -->|No| Y{次のインスタンス?}
    Y -->|Yes| K
    Y -->|No| Z[endブロック: 完了メッセージ]
    Z --> AA[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | インスタンス必須 | InputObjectまたはSqlInstanceの指定が必要 | 常時 |
| BR-002 | AgentShutdownWaitTime範囲 | 5-600秒の範囲 | AgentShutdownWaitTime指定時 |
| BR-003 | IdleCpuDuration範囲 | 20-86400秒の範囲 | IdleCpuDuration指定時 |
| BR-004 | IdleCpuPercentage範囲 | 10-100%の範囲 | IdleCpuPercentage指定時 |
| BR-005 | LoginTimeout範囲 | 5-45秒の範囲 | LoginTimeout指定時 |
| BR-006 | MaximumHistoryRows範囲 | -1（無制限）または2-999999 | MaximumHistoryRows指定時 |
| BR-007 | MaximumJobHistoryRows範囲 | 0（無制限）または2-999999 | MaximumJobHistoryRows指定時 |
| BR-008 | DatabaseMailProfile存在確認 | 指定されたプロファイルが存在する必要がある | DatabaseMailProfile指定時 |

### 計算ロジック

**AgentMailTypeの変換**：
- SqlAgentMail → 0
- DatabaseMail → 1

**AgentLogLevelの変換**：
- Errors → 1
- Warnings → 2
- Errors, Warnings → 3
- Informational → 4
- Errors, Informational → 5
- Warnings, Informational → 6
- All → 7

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| Agent設定更新 | msdb.dbo.sysssispackages（など） | UPDATE | Agent設定の更新 |

### テーブル別操作詳細

SQL Server Agentの設定はレジストリとmsdbに保存される。SMO JobServer.Alter()により間接的に更新される。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Stop-Function | MaximumHistoryRowsが範囲外 | -1または2-999999を指定 |
| - | Stop-Function | MaximumJobHistoryRowsが範囲外 | 0または2-999999を指定 |
| - | Stop-Function | InputObjectもSqlInstanceも未指定 | どちらかを指定 |
| - | ConnectionError | インスタンス接続失敗 | 接続情報を確認 |
| - | Warning | DatabaseMailProfileが存在しない | プロファイルを作成 |
| - | Stop-Function | Agent設定変更失敗 | エラーメッセージを確認 |

### リトライ仕様

リトライ機能なし。エラー発生時は-Continueにより次の処理を継続。

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

SMOのAlter()メソッドによる暗黙的トランザクション。

## パフォーマンス要件

特に定義なし。

## セキュリティ考慮事項

- sysadmin権限が必要
- SqlAgentRestart/SqlServerRestart設定はサービス制御に影響
- WhatIf/Confirmパラメータによる事前確認が可能

## 備考

- SQL Server 2000以上に対応
- 履歴制限設定は sp_set_sqlagent_properties ストアドプロシージャと同等
- 履歴無制限: MaximumHistoryRows=-1, MaximumJobHistoryRows=0

---

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

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Microsoft.SqlServer.Management.Smo.Agent.JobServer | SMO | JobServerオブジェクトのプロパティ |

**読解のコツ**: JobServerにはAgentLogLevel、MaximumHistoryRows、IsCpuPollingEnabled、SqlAgentAutoStartなど多くの設定プロパティがある。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Set-DbaAgentServer.ps1 | `public/Set-DbaAgentServer.ps1` | 関数定義、パラメータ、ブロック構造 |

**主要処理フロー**:
1. **210-246行目**: CmdletBinding属性とパラメータ定義
2. **248-268行目**: beginブロック - パラメータ変換と検証
3. **269-414行目**: processブロック - メイン処理
4. **415-417行目**: endブロック - 完了メッセージ

#### Step 3: パラメータ変換と検証を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbaAgentServer.ps1 | `public/Set-DbaAgentServer.ps1` | beginブロックの処理 |

**主要処理フロー**:
- **249-252行目**: AgentMailType変換
- **254-257行目**: AgentLogLevel変換
- **259-267行目**: MaximumHistoryRows/MaximumJobHistoryRows検証

#### Step 4: 設定更新処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Set-DbaAgentServer.ps1 | `public/Set-DbaAgentServer.ps1` | processブロックの設定更新 |

**主要処理フロー**:
- **292-398行目**: 各種プロパティの設定
- **309-316行目**: DatabaseMailProfile存在確認
- **400-411行目**: Alter実行と結果取得

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

```
Set-DbaAgentServer
    │
    ├─ Connect-DbaInstance
    │
    ├─ JobServer.Refresh()
    │
    ├─ Get-DbaDbMail (DatabaseMailProfile検証)
    │
    ├─ JobServer.Alter() (設定コミット)
    │
    └─ Get-DbaAgentServer (結果取得)
```

### データフロー図

```
[入力]                     [処理]                              [出力]

SqlInstance ─────────▶ Connect-DbaInstance
      │                        │
InputObject ─────────▶ JobServer.Refresh()
      │                        │
各種パラメータ ────────▶ beginブロック検証
      │                        │
      ▼                        ▼
                       各プロパティ設定
                       ├─ AgentLogLevel
                       ├─ AgentMailType
                       ├─ AgentShutdownWaitTime
                       ├─ DatabaseMailProfile
                       ├─ ErrorLogFile
                       ├─ IdleCpuDuration/Percentage
                       ├─ IsCpuPollingEnabled
                       ├─ LocalHostAlias
                       ├─ LoginTimeout
                       ├─ MaximumHistoryRows
                       ├─ MaximumJobHistoryRows
                       ├─ NetSendRecipient
                       ├─ ReplaceAlertTokensEnabled
                       ├─ SaveInSentFolder
                       ├─ SqlAgentAutoStart
                       ├─ SqlAgentMailProfile
                       ├─ SqlAgentRestart
                       ├─ SqlServerRestart
                       └─ WriteOemErrorLog
                              │
                              ▼
                         Alter()
                              │
                              ▼
                   Get-DbaAgentServer ───▶ [JobServer出力]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Set-DbaAgentServer.ps1 | `public/Set-DbaAgentServer.ps1` | ソース | メイン関数 |
| Get-DbaAgentServer.ps1 | `public/Get-DbaAgentServer.ps1` | ソース | Agent設定取得 |
| Get-DbaDbMail.ps1 | `public/Get-DbaDbMail.ps1` | ソース | Database Mail設定取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
