# 機能設計書 494-Get-DbaAgentServer

## 概要

本ドキュメントは、SQL Server Agent サーバー構成情報の取得機能 `Get-DbaAgentServer` の設計仕様を記載する。

### 本機能の処理概要

SQL Server Agent サービスの詳細な構成情報と状態を取得する機能である。サービスの状態、ログ設定、ジョブ履歴設定、サービスアカウントなどの情報を一元的に取得できる。

**業務上の目的・背景**：SQL Server Agent は自動化ジョブの実行基盤であり、その構成設定は運用品質に直結する。複数インスタンスにまたがる Agent 構成の監査、ジョブ実行失敗時のトラブルシューティング、移行計画のための環境設定ドキュメント作成において、Agent サーバー設定の一括取得が必要となる。本機能により、SSMS で個別に確認していた Agent 設定を PowerShell から効率的に収集・比較できる。

**機能の利用シーン**：
- 複数インスタンスにおける Agent 構成の一括監査
- ジョブ実行失敗時のトラブルシューティング（ログ設定確認等）
- 移行計画における環境設定の文書化
- コンプライアンス要件に対する Agent 設定確認
- Agent サービスアカウントの確認

**主要な処理内容**：
1. 対象 SQL Server インスタンスへの接続
2. JobServer オブジェクトの取得
3. 拡張プロパティ（JobHistoryIsEnabled）の動的追加
4. 結果の出力

**関連システム・外部連携**：SQL Server Management Objects (SMO) を使用して SQL Server Agent の JobServer オブジェクトから情報を取得する。

**権限による制御**：SQL Server への接続権限が必要。Agent 構成情報の取得には適切な権限が必要となる。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 16 | Agentサーバー設定 | 主画面 | SQLエージェントサーバー設定の取得 |

## 機能種別

データ取得（SELECT）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQLServerインスタンス。パイプライン入力可能 | 必須、配列対応 |
| SqlCredential | PSCredential | No | 代替認証情報 | Windows/SQL認証/AD対応 |
| EnableException | switch | No | 例外処理の制御フラグ | - |

### 入力データソース

- SQL Server インスタンスへの SMO 接続
- `$server.JobServer` オブジェクト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピューター名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| AgentDomainGroup | string | SQL Server Agent の AD ドメイングループ |
| AgentLogLevel | enum | Agent ログレベル（Errors/Warnings/Informational等） |
| AgentMailType | enum | Agent メールシステム（SqlAgentMail/DatabaseMail） |
| AgentShutdownWaitTime | int | Agent シャットダウン待機時間（秒） |
| ErrorLogFile | string | Agent エラーログファイルパス |
| IdleCpuDuration | int | アイドルCPU判定時間（秒） |
| IdleCpuPercentage | int | アイドルCPU閾値（%） |
| IsCpuPollingEnabled | bool | CPUアイドル監視有効フラグ |
| JobServerType | enum | ジョブサーバータイプ（Master/Target等） |
| LoginTimeout | int | ログインタイムアウト（秒） |
| JobHistoryIsEnabled | bool | ジョブ履歴有効フラグ（計算プロパティ） |
| MaximumHistoryRows | int | 最大履歴行数（-1=無制限） |
| MaximumJobHistoryRows | int | ジョブ単位最大履歴行数 |
| MsxAccountCredentialName | string | MSX アカウント資格情報名 |
| MsxAccountName | string | MSX アカウント名 |
| MsxServerName | string | MSX サーバー名 |
| Name | string | JobServer 名 |
| NetSendRecipient | string | NetSend 送信先 |
| ServiceAccount | string | Agent サービスアカウント |
| ServiceStartMode | enum | サービス起動モード（Automatic/Manual/Disabled） |
| SqlAgentAutoStart | bool | SQL Server 起動時の Agent 自動起動 |
| SqlAgentMailProfile | string | SQL Agent メールプロファイル名 |
| SqlAgentRestart | bool | Agent 自動再起動フラグ |
| SqlServerRestart | bool | SQL Server 再起動可能フラグ |
| State | enum | サービス状態（Running/Stopped等） |
| SysAdminOnly | bool | sysadmin 限定アクセスフラグ |

### 出力先

PowerShell パイプラインへの出力（`Microsoft.SqlServer.Management.Smo.Agent.JobServer` オブジェクト）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ SqlInstance の必須チェック
2. インスタンスループ開始
   └─ 各 SqlInstance に対して処理
3. SQL Server 接続
   └─ Connect-DbaInstance で接続確立
4. JobServer 取得
   └─ $server.JobServer を取得
5. プロパティ付与
   └─ ComputerName, InstanceName, SqlInstance, JobHistoryIsEnabled の追加
6. 結果出力
   └─ Select-DefaultView でデフォルトプロパティ表示
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[パラメータ受け取り]
    B --> C{SqlInstance ループ}
    C --> D[Connect-DbaInstance]
    D --> E{接続成功?}
    E -->|No| F[Stop-Function でエラー]
    F --> C
    E -->|Yes| G[JobServer 取得]
    G --> H[拡張プロパティ付与]
    H --> I[JobHistoryIsEnabled 計算]
    I --> J[Select-DefaultView 出力]
    J --> C
    C -->|終了| K[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-494-01 | JobHistoryIsEnabled 計算 | MaximumHistoryRows が -1 の場合は false、それ以外は true | 常時 |
| BR-494-02 | シンプルな取得 | フィルタ機能なし、全ての Agent 設定を取得 | 常時 |

### 計算ロジック

**JobHistoryIsEnabled プロパティ**:
```powershell
switch ($this.MaximumHistoryRows) {
    -1 { $false }
    default { $true }
}
```
- MaximumHistoryRows = -1: ジョブ履歴が無効（履歴を保持しない）
- MaximumHistoryRows >= 0: ジョブ履歴が有効

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| Agent 設定取得 | msdb.dbo.syssubsystems 等 | SELECT | Agent 設定情報の取得（SMO経由） |

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

SMO JobServer オブジェクトを通じて Agent 設定を取得。直接的なテーブルアクセスは SMO が抽象化。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Server への接続失敗 | Stop-Function で Continue、次のインスタンスへ |

### リトライ仕様

リトライ処理は実装されていない。接続エラー時は次のインスタンスの処理へ継続する。

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

読み取り専用操作のため、トランザクション管理は不要。

## パフォーマンス要件

- 各インスタンスへの接続は順次処理
- JobServer オブジェクトの取得は軽量な操作

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

- SQL Server への接続には SqlCredential による認証情報指定が可能
- Windows 認証、SQL Server 認証、Active Directory 認証をサポート
- MFA 対応は Connect-DbaInstance を事前に使用する必要あり
- ServiceAccount 情報はサービスアカウント名を含むため、出力結果の取り扱いに注意

## 備考

- Select-DefaultView により、デフォルトでは主要プロパティのみ表示される
- 全プロパティを確認するには `Select-Object *` を使用
- パイプライン入力により複数インスタンスの一括処理が可能
- Express Edition でも接続は成功するが、Agent 関連機能は制限される

---

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

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

### 推奨読解順序

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

SMO の JobServer オブジェクト構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaAgentServer.ps1 | `public/Get-DbaAgentServer.ps1` | 126行目のデフォルト表示プロパティ定義 |

**読解のコツ**: JobServer は SQL Server Agent の設定を表す SMO オブジェクト。多数のプロパティを持ち、デフォルト表示では主要なものだけが選択される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaAgentServer.ps1 | `public/Get-DbaAgentServer.ps1` | 108-114行目のパラメータ定義、116行目の process ブロック開始 |

**主要処理フロー**:
1. **117行目**: foreach ($instance in $SqlInstance) でインスタンスループ開始
2. **119行目**: Connect-DbaInstance で SMO 接続確立
3. **124行目**: $jobServer = $server.JobServer で JobServer 取得
4. **128-131行目**: 拡張プロパティの追加
5. **133行目**: Select-DefaultView で出力

#### Step 3: 拡張プロパティを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaAgentServer.ps1 | `public/Get-DbaAgentServer.ps1` | 128-131行目の Add-Member による拡張プロパティ追加 |

**主要処理フロー**:
- **128行目**: ComputerName プロパティ追加（Parent.ComputerName から取得）
- **129行目**: InstanceName プロパティ追加（Parent.ServiceName から取得）
- **130行目**: SqlInstance プロパティ追加（Parent.DomainInstanceName から取得）
- **131行目**: JobHistoryIsEnabled ScriptProperty 追加（MaximumHistoryRows に基づく計算）

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

```
Get-DbaAgentServer
    │
    ├─ Connect-DbaInstance
    │      └─ SMO 接続確立
    │
    ├─ Stop-Function
    │      └─ エラー処理
    │
    ├─ $server.JobServer
    │      └─ Agent JobServer オブジェクト取得
    │
    ├─ Add-Member
    │      ├─ NoteProperty: ComputerName, InstanceName, SqlInstance
    │      └─ ScriptProperty: JobHistoryIsEnabled
    │
    └─ Select-DefaultView
           └─ デフォルト表示プロパティ設定
```

### データフロー図

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

SqlInstance ───────────┬─► Connect-DbaInstance ───────────► SMO Server オブジェクト
SqlCredential ─────────┘                                            │
                                                                    ▼
                                                        $server.JobServer
                                                                    │
                                                                    ▼
                                                     Add-Member (拡張プロパティ)
                                                     ├─ ComputerName
                                                     ├─ InstanceName
                                                     ├─ SqlInstance
                                                     └─ JobHistoryIsEnabled (計算)
                                                                    │
                                                                    ▼
                                                      Select-DefaultView ───────► JobServer オブジェクト
                                                                                  (拡張プロパティ付き)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaAgentServer.ps1 | `public/Get-DbaAgentServer.ps1` | ソース | メイン機能実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server 接続ヘルパー |
| Stop-Function.ps1 | `internal/functions/Stop-Function.ps1` | ソース | エラー処理ヘルパー |
| Select-DefaultView.ps1 | `internal/functions/Select-DefaultView.ps1` | ソース | デフォルト表示設定 |
