# 機能設計書 265-Get-DbaDbMailServer

## 概要

本ドキュメントは、SQL ServerのDatabase MailアカウントからSMTPサーバー構成を取得するGet-DbaDbMailServerコマンドレットの機能設計を記述する。

### 本機能の処理概要

Get-DbaDbMailServerは、SQL ServerのDatabase Mailアカウントに設定されているSMTPサーバーの詳細構成情報を取得するPowerShellコマンドレットである。ポート番号、SSL設定、認証方法、接続詳細などのメールサーバー設定を取得でき、メールインフラの監査、配信問題のトラブルシューティング、環境全体のDatabase Mail構成文書化に活用される。

**業務上の目的・背景**：Database Mailの配信問題の多くはSMTPサーバー設定に起因する。本コマンドは、SMTPサーバー接続設定の確認、ポート・SSL設定の検証、認証情報の確認、複数環境間での設定比較といった業務課題を解決する。特にメール配信障害時には、実際のSMTPサーバー設定を素早く確認することで原因特定を効率化できる。

**機能の利用シーン**：
- メール配信障害時のSMTPサーバー設定確認
- Database Mail構成の文書化・監査
- 複数インスタンス間でのSMTP設定比較
- SSL/TLS設定の検証
- 認証設定（Windows認証/基本認証）の確認

**主要な処理内容**：
1. SqlInstanceパラメータまたはパイプライン入力からDatabase Mailオブジェクトを取得
2. Get-DbaDbMailAccountを呼び出してアカウント情報を取得
3. 各アカウントのMailServersコレクションからSMTPサーバー情報を抽出
4. Server/Accountパラメータによるフィルタリング
5. サーバー情報を付加してパイプライン出力

**関連システム・外部連携**：SQL Server Management Objects（SMO）のMicrosoft.SqlServer.Management.Smo.Mail.MailServerクラスを使用してSMTPサーバー情報にアクセスする。Get-DbaDbMailおよびGet-DbaDbMailAccountコマンドと連携してパイプライン処理が可能。

**権限による制御**：Database Mailアカウント構成の読み取りには、msdbデータベースへの適切なアクセス権限が必要。sysadminサーバーロールまたはDatabaseMailUserRoleデータベースロールのメンバーシップが必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 52 | データベースメール | 補助機能 | メールサーバーの取得 |

## 機能種別

データ取得（SELECT）/ 構成情報参照

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 接続先SQL Serverインスタンス | 有効なインスタンス名 |
| SqlCredential | PSCredential | No | 代替認証用資格情報 | Windows/SQL認証対応 |
| Server | string[] | No | 取得するSMTPサーバー名（エイリアス: Name） | 複数値対応 |
| Account | string[] | No | 関連するDatabase Mailアカウント名でフィルタ | 複数値対応 |
| InputObject | Microsoft.SqlServer.Management.Smo.Mail.SqlMail[] | No | パイプライン入力用Database Mailオブジェクト | Get-DbaDbMailからの入力 |
| EnableException | switch | No | 例外を直接スローするかどうか | - |

### 入力データソース

- SqlInstance: ユーザー指定またはパイプライン入力
- InputObject: Get-DbaDbMailコマンドからのパイプライン入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverホスト名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| Account | string | 関連するDatabase Mailアカウント名 |
| Name | string | SMTPサーバー名/ホスト名 |
| Port | int | SMTPポート番号（通常25, 465, 587） |
| EnableSsl | bool | SSL/TLS暗号化が有効かどうか |
| ServerType | string | サーバータイプ（通常"SMTP"） |
| UserName | string | SMTP認証用ユーザー名 |
| UseDefaultCredentials | bool | Windows認証を使用するかどうか |
| NoCredentialChange | bool | 資格情報変更ポリシー |

### 出力先

パイプライン出力（Microsoft.SqlServer.Management.Smo.Mail.MailServer型、追加プロパティ付き）

## 処理フロー

### 処理シーケンス

```
1. 入力パラメータの検証
   └─ SqlInstanceまたはInputObjectのいずれかが必要

2. Database Mailオブジェクトの取得
   └─ SqlInstanceが指定された場合、Get-DbaDbMailを呼び出し
   └─ InputObjectが指定された場合、そのまま使用

3. 入力検証
   └─ InputObjectが空の場合、処理終了

4. 各Database Mailオブジェクトに対して繰り返し
   └─ Get-DbaDbMailAccountを呼び出してアカウント取得
   └─ 各アカウントのMailServersコレクションを取得
   └─ Serverフィルターが指定された場合、該当サーバーのみ抽出

5. 出力プロパティの付加
   └─ ComputerName、InstanceName、SqlInstance、Accountを追加

6. 結果の出力
   └─ Select-DefaultViewで既定表示プロパティを設定
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance指定?}
    B -->|Yes| C[Get-DbaDbMail呼び出し]
    B -->|No| D[InputObject使用]
    C --> E[InputObject取得]
    D --> E
    E --> F{InputObject存在?}
    F -->|No| G[エラー終了]
    F -->|Yes| H[foreachループ開始]
    H --> I[Get-DbaDbMailAccount呼び出し]
    I --> J[MailServers取得]
    J --> K{Server指定?}
    K -->|Yes| L[Where-Object フィルタ]
    K -->|No| M{servers存在?}
    L --> M
    M -->|Yes| N[サーバー情報付加]
    M -->|No| O[次のオブジェクト処理]
    N --> P[結果出力]
    P --> O
    O --> Q{次のオブジェクト?}
    Q -->|Yes| H
    Q -->|No| R[終了]
    G --> R
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 入力必須 | SqlInstanceまたはInputObjectのいずれかが必要 | 常時 |
| BR-002 | アカウントフィルタ | Account指定時は該当アカウントのサーバーのみ取得 | Accountパラメータ指定時 |
| BR-003 | サーバーフィルタ | Server指定時は完全一致でフィルタリング | Serverパラメータ指定時 |
| BR-004 | Account情報付加 | 出力にAccount名（親アカウント名）を付加 | 常時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| サーバー取得 | msdb.dbo.sysmail_account | SELECT | SMO経由でアカウント情報参照 |
| サーバー取得 | msdb.dbo.sysmail_server | SELECT | SMO経由でサーバー設定参照 |

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

#### msdb.dbo.sysmail_server

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | servertype, servername, port, enable_ssl, username, use_default_credentials | 全件またはフィルタ条件 | SMO経由で読み取り専用アクセス |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 接続エラー | SQL Serverに接続できない | 接続設定・資格情報を確認 |
| - | 入力エラー | サーバー未指定 | SqlInstanceまたはInputObjectを指定 |
| - | 処理エラー | MailServers取得失敗 | 権限・Database Mail設定を確認 |

### リトライ仕様

なし（即時エラー終了）

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

読み取り専用操作のため、明示的なトランザクション制御なし

## パフォーマンス要件

SMOオブジェクトアクセスのため、大量インスタンス処理時は逐次処理となる

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

- 資格情報はPSCredentialオブジェクトで安全に受け渡し
- Windows認証、SQL認証、AD Password認証、AD Integrated認証をサポート
- SMTP認証パスワードは出力に含まれない（セキュリティ保護）
- ユーザー名は出力に含まれるため、出力の取り扱いに注意

## 備考

- Get-DbaDbMailとのパイプライン連携を推奨
- 複数インスタンスの一括取得には配列またはパイプライン入力を使用
- ServerパラメータはNameのエイリアスとしても機能

---

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

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

### 推奨読解順序

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

SMO MailServerオブジェクトとMailAccountの関係を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbMailServer.ps1 | `public/Get-DbaDbMailServer.ps1` | .OUTPUTSセクション（47-65行目）で出力プロパティを確認 |
| 1-2 | Get-DbaDbMailServer.ps1 | `public/Get-DbaDbMailServer.ps1` | パラメータ定義（89-99行目）でInputObject型とフィルタを確認 |

**読解のコツ**: MailServerはMailAccountの子オブジェクトであり、`$servers.Parent.Name`でアカウント名を取得している点に注目。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbMailServer.ps1 | `public/Get-DbaDbMailServer.ps1` | processブロック（100行目）が処理のエントリーポイント |

**主要処理フロー**:
1. **101-103行目**: SqlInstance指定時にGet-DbaDbMailでInputObjectを取得
2. **105-108行目**: InputObjectが空の場合はStop-Functionで処理終了
3. **110-129行目**: 各mailserverオブジェクトをループ処理

#### Step 3: コア処理ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDbMailServer.ps1 | `public/Get-DbaDbMailServer.ps1` | アカウント取得とMailServers処理 |

**主要処理フロー**:
- **112行目**: `Get-DbaDbMailAccount`でアカウントオブジェクトを取得（Accountフィルタ適用）
- **113行目**: `$accounts.MailServers`でSMTPサーバーコレクションを取得
- **115-117行目**: Serverパラメータ指定時のWhere-Objectフィルタリング
- **119-123行目**: サーバー識別情報（ComputerName、InstanceName、SqlInstance、Account）をAdd-Memberで付加
- **123行目**: `$servers.Parent.Name`で親アカウント名を取得
- **124行目**: Select-DefaultViewで出力プロパティを制御

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

```
Get-DbaDbMailServer
    │
    ├─ Get-DbaDbMail（SqlInstance指定時）
    │      └─ Connect-DbaInstance
    │             └─ SQL Server接続
    │
    ├─ Get-DbaDbMailAccount（Account フィルタ適用）
    │      └─ SqlMail.Accounts
    │             └─ msdb.dbo.sysmail_accountへのクエリ
    │
    ├─ MailAccount.MailServers（SMOプロパティアクセス）
    │      └─ msdb.dbo.sysmail_serverへのクエリ
    │
    ├─ Where-Object（Server フィルタリング）
    │
    ├─ Add-Member（プロパティ付加）
    │
    └─ Select-DefaultView（出力整形）
```

### データフロー図

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

SqlInstance ────┐
                ├──▶ Get-DbaDbMail ──▶ SqlMail
InputObject ────┘                          │
                                           ▼
Account ───────────────────────▶ Get-DbaDbMailAccount
                                           │
                                           ▼
                                      MailServers
                                           │
Server ────────────────────────▶ Where-Object フィルタ
                                           │
                                           ▼
                                  Add-Member（サーバー・アカウント情報付加）
                                           │
                                           ▼
                                  Select-DefaultView
                                           │
                                           ▼
                               [MailServer + Properties]
                               - Account
                               - Name (SMTPサーバー)
                               - Port
                               - EnableSsl
                               - ServerType
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbMailServer.ps1 | `public/Get-DbaDbMailServer.ps1` | ソース | メイン処理ロジック |
| Get-DbaDbMailAccount.ps1 | `public/Get-DbaDbMailAccount.ps1` | ソース | メールアカウント取得 |
| Get-DbaDbMail.ps1 | `public/Get-DbaDbMail.ps1` | ソース | Database Mailオブジェクト取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
