# 通知設計書 1-Get-DbaDbMail

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `Get-DbaDbMail` コマンドの設計仕様を記述したものである。このコマンドはSQL ServerインスタンスからDatabase Mail設定を取得するための機能を提供する。

### 本通知の処理概要

`Get-DbaDbMail` は、SQL ServerのDatabase Mail設定（プロファイル、アカウント、設定値）を包括的に取得するPowerShellコマンドである。このコマンドを使用することで、DBAは複数のSQL Serverインスタンスにわたるメール設定を効率的に監査・ドキュメント化できる。

**業務上の目的・背景**：SQL Serverでは、ジョブ失敗時のアラート、バックアップ完了通知、監視アラートなど、様々な自動通知機能がDatabase Mailに依存している。このコマンドは、これらのメール基盤の構成情報を迅速に取得し、複数サーバー間での設定一貫性の確認、トラブルシューティング、コンプライアンス文書化を支援する。

**通知の送信タイミング**：このコマンド自体は通知を送信しない。Database Mail設定を「取得」するための読み取り専用コマンドである。ユーザーが明示的にコマンドを実行したときにのみ動作する。

**通知の受信者**：該当なし（情報取得コマンド）。出力結果はコマンド実行者（通常はDBA）がPowerShellコンソールまたはスクリプト内で受け取る。

**通知内容の概要**：SQL ServerインスタンスごとにSqlMailオブジェクトを返す。このオブジェクトには、ComputerName、InstanceName、SqlInstance、Profiles（プロファイルコレクション）、Accounts（アカウントコレクション）、ConfigurationValues（設定値）、Propertiesが含まれる。

**期待されるアクション**：取得した情報をもとに、DBAはメール設定の監査、問題のトラブルシューティング、設定のドキュメント化、他サーバーへの設定移行計画の策定などを行う。

## 通知種別

該当なし - 本コマンドはDatabase Mail設定を取得するための情報取得コマンドであり、通知送信機能は持たない。

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 該当なし（情報取得コマンド） |
| 優先度 | 該当なし |
| リトライ | 該当なし |

### 送信先決定ロジック

該当なし - このコマンドは情報取得専用であり、通知送信は行わない。

## 通知テンプレート

該当なし - 通知送信機能なし。

### メール通知の場合

該当なし

### 本文テンプレート

該当なし

### 添付ファイル

該当なし

## テンプレート変数

該当なし

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 手動実行 | ユーザーがコマンドを実行 | なし | 明示的なコマンド実行でのみ動作 |
| パイプライン入力 | SqlInstanceパラメータへの値受け渡し | なし | 複数インスタンスをパイプで処理可能 |

### 送信抑止条件

該当なし（情報取得コマンド）

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[コマンド実行] --> B{SqlInstanceパラメータ}
    B --> C[foreach: 各インスタンスを処理]
    C --> D[Connect-DbaInstance接続]
    D -->|成功| E[server.Mailオブジェクト取得]
    D -->|失敗| F[Stop-Function: ConnectionError]
    E --> G[Add-Member: ComputerName追加]
    G --> H[Add-Member: InstanceName追加]
    H --> I[Add-Member: SqlInstance追加]
    I --> J[Select-DefaultView: 既定プロパティ選択]
    J --> K[パイプラインに出力]
    K --> L{次のインスタンス?}
    L -->|Yes| C
    L -->|No| M[終了]
    F --> L
```

## データベース参照・更新仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| SMO Mail オブジェクト | Database Mail設定全体を取得 | SQL Server Management Objects経由 |
| msdb.dbo.sysmail_profile | プロファイル情報 | SMO経由で間接参照 |
| msdb.dbo.sysmail_account | アカウント情報 | SMO経由で間接参照 |
| msdb.dbo.sysmail_configuration | 設定値 | SMO経由で間接参照 |

### テーブル別参照項目詳細

#### SMO SqlMail オブジェクト

| 参照項目（プロパティ名） | 用途 | 取得条件 |
|-------------------|------|---------|
| Profiles | メールプロファイルコレクション | 常に取得 |
| Accounts | メールアカウントコレクション | 常に取得 |
| ConfigurationValues | 設定値コレクション | 常に取得 |
| Properties | プロパティコレクション | 常に取得 |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| なし | - | 読み取り専用コマンド |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| ConnectionError | SQL Serverへの接続失敗 | Stop-Functionで警告出力後、次のインスタンスへ継続 |
| 一般的な失敗 | Mailオブジェクト取得時のエラー | Stop-Functionでメッセージ出力後、次のインスタンスへ継続 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

該当なし（情報取得コマンド）

### 配信時間帯

該当なし

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

- SQL Server への接続には Windows認証、SQL Server認証、Active Directory認証がサポートされる
- SqlCredentialパラメータで代替資格情報を指定可能
- MFAが必要な場合は事前にConnect-DbaInstanceを使用する
- 取得した情報には機密情報（SMTPサーバー設定など）が含まれる可能性がある

## 備考

- SQL Server Management Objects (SMO) を使用してDatabase Mail設定を取得
- 出力オブジェクトはMicrosoft.SqlServer.Management.Smo.Mail.SqlMail型
- Select-DefaultViewにより既定表示プロパティが設定される
- 詳細情報はGet-DbaDbMailProfile、Get-DbaDbMailAccount、Get-DbaDbMailConfig、Get-DbaDbMailServerで個別に取得可能

---

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

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

### 推奨読解順序

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

SMO（SQL Server Management Objects）のMailオブジェクト階層を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbMail.ps1 | `public/Get-DbaDbMail.ps1` | 行25-38: .OUTPUTSセクションで返却されるオブジェクト型と既定表示プロパティを確認 |

**読解のコツ**: SqlMailオブジェクトはProfiles、Accounts、ConfigurationValues、Propertiesの4つの主要コレクションを持つ。各コレクションは別のGet-DbaDbMail*コマンドで詳細取得可能。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbMail.ps1 | `public/Get-DbaDbMail.ps1` | 行68-74: パラメータ定義。SqlInstance（必須、パイプライン入力可）、SqlCredential、EnableException |

**主要処理フロー**:
1. **行76**: foreachループで各SqlInstanceを処理
2. **行78-82**: Connect-DbaInstanceで接続、失敗時はStop-Functionで継続
3. **行84-85**: $server.MailでSqlMailオブジェクト取得
4. **行86-88**: Add-MemberでComputerName、InstanceName、SqlInstanceプロパティ追加
5. **行89**: Select-DefaultViewで既定プロパティを選択して出力

#### Step 3: 接続処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | SQL Server接続の共通処理 |

**主要処理フロー**:
- **行79**: Connect-DbaInstanceを呼び出し、サーバーオブジェクト取得

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

```
Get-DbaDbMail
    │
    ├─ Connect-DbaInstance
    │      └─ SMO Server接続確立
    │
    ├─ $server.Mail (SqlMailオブジェクト取得)
    │
    ├─ Add-Member (カスタムプロパティ追加)
    │      ├─ ComputerName
    │      ├─ InstanceName
    │      └─ SqlInstance
    │
    └─ Select-DefaultView (既定表示プロパティ設定)
```

### データフロー図

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

SqlInstance[]    ───▶  Connect-DbaInstance    ───▶  Server オブジェクト
                              │
                              ▼
                       $server.Mail取得        ───▶  SqlMail オブジェクト
                              │
                              ▼
                       Add-Member追加          ───▶  拡張SqlMail オブジェクト
                              │                      (ComputerName, InstanceName,
                              ▼                       SqlInstance追加)
                       Select-DefaultView      ───▶  パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbMail.ps1 | `public/Get-DbaDbMail.ps1` | ソース | メインコマンド実装 |
| Get-DbaDbMail.Tests.ps1 | `tests/Get-DbaDbMail.Tests.ps1` | テスト | Pesterユニットテスト |
| Get-DbaDbMailProfile.ps1 | `public/Get-DbaDbMailProfile.ps1` | ソース | 関連: プロファイル詳細取得 |
| Get-DbaDbMailAccount.ps1 | `public/Get-DbaDbMailAccount.ps1` | ソース | 関連: アカウント詳細取得 |
| Get-DbaDbMailConfig.ps1 | `public/Get-DbaDbMailConfig.ps1` | ソース | 関連: 設定値詳細取得 |
| Get-DbaDbMailServer.ps1 | `public/Get-DbaDbMailServer.ps1` | ソース | 関連: メールサーバー詳細取得 |
