# 通知設計書 8-New-DbaDbMailAccount

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `New-DbaDbMailAccount` コマンドの設計仕様を記述したものである。このコマンドはSQL Serverインスタンスに新しいDatabase Mailアカウントを作成するための機能を提供する。

### 本通知の処理概要

`New-DbaDbMailAccount` は、SQL ServerのDatabase Mailアカウントを作成するPowerShellコマンドである。SMTPサーバー設定、送信者アドレス、認証情報などを含むメールアカウントを設定できる。これにより、自動化されたメール通知、アラート、レポート配信の基盤を構築できる。

**業務上の目的・背景**：Database Mailアカウントは、SQL Serverからのメール送信の実体となる設定である。sp_send_dbmailストアドプロシージャを使用したメール送信に必須であり、ジョブ失敗通知、バックアップ完了アラート、スケジュールレポート配信などの自動化された運用通知に不可欠である。このコマンドは、新規サーバーのセットアップ、環境標準化、自動化スクリプトでのアカウント作成を支援する。

**通知の送信タイミング**：このコマンドはアカウント作成時に一度だけ実行される。作成されたアカウントは後続のメール送信に使用される。

**通知の受信者**：該当なし（設定作成コマンド）。作成されたアカウントを使用してメール送信が行われた場合、そのメールの受信者がアカウント設定に基づいて決定される。

**通知内容の概要**：作成されたMailAccountオブジェクトを返す。このオブジェクトには、ComputerName、InstanceName、SqlInstance、Id、Name、DisplayName、Description、EmailAddress、ReplyToAddress、IsBusyAccount、MailServersが含まれる。

**期待されるアクション**：アカウント作成後、DBAはプロファイルへの関連付け、テストメール送信、本番環境への展開などを行う。

## 通知種別

該当なし - 本コマンドはDatabase Mailアカウントを作成するための設定コマンドであり、通知送信機能は持たない。

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 該当なし（設定作成コマンド） |
| 優先度 | 該当なし |
| リトライ | 該当なし |

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

該当なし - このコマンドは設定作成専用であり、通知送信は行わない。

## 通知テンプレート

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

### メール通知の場合

該当なし

### 本文テンプレート

該当なし

### 添付ファイル

該当なし

## テンプレート変数

該当なし

## 送信トリガー・条件

### トリガー一覧

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

### 送信抑止条件

該当なし（設定作成コマンド）

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[コマンド実行] --> B[foreach: 各SqlInstanceを処理]
    B --> C[Connect-DbaInstance接続 MinimumVersion=10]
    C -->|成功| D{MailServer検証}
    C -->|失敗| E[Stop-Function: ConnectionError]
    D -->|MailServer指定あり| F{メールサーバー存在?}
    D -->|MailServer指定なし| G[アカウント作成処理]
    F -->|No & Forceなし| H[Stop-Function: サーバー不存在]
    F -->|Yes or Force| G
    G --> I[ShouldProcess確認]
    I -->|Yes| J[MailAccountオブジェクト作成]
    J --> K[プロパティ設定]
    K --> L[Create実行]
    L --> M[MailServerリネーム]
    M --> N[Alter・Refresh]
    N --> O[Add-Member: プロパティ追加]
    O --> P[Select-DefaultView: 既定プロパティ選択]
    P --> Q[パイプラインに出力]
    I -->|No| R{次のinstance?}
    H --> R
    Q --> R
    R -->|Yes| B
    R -->|No| S[終了]
    E --> R
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| Get-DbaDbMailServer | メールサーバー存在確認 | MailServerパラメータ検証 |

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

該当なし（作成処理のため参照は検証目的のみ）

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| msdb.dbo.sysmail_account | INSERT | 新規アカウントレコード作成 |
| msdb.dbo.sysmail_server | INSERT/UPDATE | SMTPサーバー設定 |

#### 作成されるアカウント情報

| 操作 | 項目（プロパティ名） | 設定値 | 備考 |
|-----|-----------------|-------|------|
| CREATE | Name | $Account | 必須、一意 |
| CREATE | DisplayName | $DisplayName（既定: $Account） | Fromフィールドに表示 |
| CREATE | Description | $Description | オプション |
| CREATE | EmailAddress | $EmailAddress | 必須 |
| CREATE | ReplyToAddress | $ReplyToAddress | オプション |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| ConnectionError | SQL Serverへの接続失敗 | Stop-Functionで警告出力後、次のインスタンスへ継続 |
| MinimumVersion | SQL Server 2008未満 | Connect-DbaInstance -MinimumVersion 10で自動チェック |
| MailServerNotFound | 指定メールサーバーが存在しない | -Force未指定時はStop-Function、指定時は継続 |
| CreateFailure | アカウント作成失敗 | Stop-Functionでエラー出力後、次へ継続 |
| OutputFailure | 出力処理失敗 | Stop-Functionでエラー出力後、次へ継続 |

### リトライ仕様

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

## 配信設定

### レート制限

該当なし（設定作成コマンド）

### 配信時間帯

該当なし

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

- SQL Server への接続には Windows認証、SQL Server認証、Active Directory認証がサポートされる
- SqlCredentialパラメータで代替資格情報を指定可能
- sysadmin権限が必要（SQL Server 2008以上）
- 作成されるアカウントにはSMTPサーバー認証情報が含まれる可能性がある
- ShouldProcess（-WhatIf, -Confirm）をサポート

## 備考

- SQL Server 2008以上が必要（MinimumVersion 10）
- SQL Server Management Objects (SMO) を使用してアカウント作成
- 出力オブジェクトはMicrosoft.SqlServer.Management.Smo.Mail.MailAccount型
- DisplayNameは未指定時にAccount名と同じ値が設定される
- MailServerパラメータで既存のSMTPサーバーを検証（-Force で検証スキップ可能）
- 作成後にプロファイルへの関連付けが別途必要

---

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

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

### 推奨読解順序

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

出力されるMailAccountオブジェクトの構造を理解することが重要。

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

**読解のコツ**: MailAccountオブジェクトを返す。Id、Name、DisplayName、Description、EmailAddress、ReplyToAddress、IsBusyAccount、MailServersが既定表示プロパティ。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaDbMailAccount.ps1 | `public/New-DbaDbMailAccount.ps1` | 行100-116: パラメータ定義。SqlInstance、SqlCredential、Account、DisplayName、Description、EmailAddress、ReplyToAddress、MailServer、Force、EnableException |

**主要処理フロー**:
1. **行118**: foreachで各SqlInstanceを処理
2. **行119-122**: Connect-DbaInstance -MinimumVersion 10で接続（SQL Server 2008以上）
3. **行125-128**: MailServer指定時、Get-DbaDbMailServerで存在確認
4. **行131**: ShouldProcess確認
5. **行132-141**: New-Object Microsoft.SqlServer.Management.SMO.Mail.MailAccountでオブジェクト作成、プロパティ設定、Create()実行
6. **行143-150**: MailServerリネーム、Alter()、Refresh()、Add-Member、Select-DefaultView

#### Step 3: SMOオブジェクト操作を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaDbMailAccount.ps1 | `public/New-DbaDbMailAccount.ps1` | 行133-138: SMO MailAccountオブジェクトの作成とプロパティ設定 |
| 3-2 | New-DbaDbMailAccount.ps1 | `public/New-DbaDbMailAccount.ps1` | 行143-146: MailServersコレクションのリネームとAlter |

**主要処理フロー**:
- **行133**: New-Objectでコンストラクタ呼び出し（$server.Mail, $Account）
- **行134-137**: DisplayName、Description、EmailAddress、ReplyToAddress設定
- **行138**: Create()でデータベースに永続化
- **行144**: MailServers.Item().Rename()でサーバー名変更
- **行145**: Alter()で変更を永続化
- **行146**: Refresh()でオブジェクト更新

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

```
New-DbaDbMailAccount
    │
    ├─ Connect-DbaInstance (-MinimumVersion 10)
    │      └─ SMO Server接続確立
    │
    ├─ Test-Bound -ParameterName MailServer
    │      └─ Get-DbaDbMailServer (存在確認)
    │
    ├─ ShouldProcess (WhatIf/Confirm)
    │
    ├─ New-Object Microsoft.SqlServer.Management.SMO.Mail.MailAccount
    │      ├─ プロパティ設定
    │      │      ├─ DisplayName
    │      │      ├─ Description
    │      │      ├─ EmailAddress
    │      │      └─ ReplyToAddress
    │      │
    │      └─ Create() (データベースに永続化)
    │
    ├─ MailServers.Item().Rename() (サーバー名変更)
    │
    ├─ Alter() / Refresh()
    │
    ├─ Add-Member (カスタムプロパティ追加)
    │
    └─ Select-DefaultView (既定表示プロパティ設定)
```

### データフロー図

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

SqlInstance[]        ───▶  Connect-DbaInstance    ───▶  Server オブジェクト
Account (string)                   │
EmailAddress (string)              ▼
                          New-Object MailAccount   ───▶  MailAccount オブジェクト
                                  │
                                  ├── DisplayName設定
                                  ├── Description設定
                                  ├── EmailAddress設定
                                  └── ReplyToAddress設定
                                  │
                                  ▼
                          Create()                 ───▶  msdb永続化
                                  │
                                  ▼
                          MailServers.Rename()     ───▶  サーバー名設定
                                  │
                                  ▼
                          Alter() / Refresh()      ───▶  更新完了
                                  │
                                  ▼
                          Select-DefaultView       ───▶  MailAccount出力
                                                         (パイプライン)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaDbMailAccount.ps1 | `public/New-DbaDbMailAccount.ps1` | ソース | メインコマンド実装 |
| New-DbaDbMailAccount.Tests.ps1 | `tests/New-DbaDbMailAccount.Tests.ps1` | テスト | Pesterユニットテスト |
| Get-DbaDbMailAccount.ps1 | `public/Get-DbaDbMailAccount.ps1` | ソース | 関連: アカウント取得 |
| Get-DbaDbMailServer.ps1 | `public/Get-DbaDbMailServer.ps1` | ソース | 依存: サーバー存在確認 |
| Remove-DbaDbMailAccount.ps1 | `public/Remove-DbaDbMailAccount.ps1` | ソース | 関連: アカウント削除 |
| New-DbaDbMailProfile.ps1 | `public/New-DbaDbMailProfile.ps1` | ソース | 関連: プロファイル作成 |
