# 機能設計書 266-New-DbaDbMailAccount

## 概要

本ドキュメントは、SQL ServerにDatabase Mailアカウントを作成するNew-DbaDbMailAccountコマンドレットの機能設計を記述する。

### 本機能の処理概要

New-DbaDbMailAccountは、SQL ServerインスタンスにDatabase Mailアカウントを新規作成するPowerShellコマンドレットである。Database Mailアカウントは、SQL Serverがメールを送信する際に使用するメール設定（SMTPサーバー、送信元アドレス、認証情報）を定義する。自動メンテナンス通知、ジョブ失敗アラート、スケジュールレポート配信などの自動化されたメール通知の設定に不可欠。

**業務上の目的・背景**：SQL Serverの自動通知機能を有効にするには、まずDatabase Mailアカウントを設定する必要がある。本コマンドは、新規サーバー環境でのDatabase Mail初期設定、アプリケーション別のメールアカウント分離、SMTPサーバー変更に伴うアカウント再作成といった業務課題を解決する。PowerShellからの一括設定により、複数サーバーへの効率的な展開が可能。

**機能の利用シーン**：
- 新規SQL Server環境でのDatabase Mail初期設定
- 用途別（アラート用、レポート用）のメールアカウント作成
- 環境移行時のDatabase Mail設定再構築
- 自動化スクリプトによる複数サーバーへの一括設定

**主要な処理内容**：
1. SQL Serverインスタンスへの接続（SQL Server 2008以降が必要）
2. SMOを使用してMailAccountオブジェクトを作成
3. DisplayName、Description、EmailAddress、ReplyToAddressを設定
4. Create()メソッドでアカウントを作成
5. MailServerを関連付け（Rename処理でサーバー名を設定）
6. 作成されたアカウント情報をパイプライン出力

**関連システム・外部連携**：SQL Server Management Objects（SMO）のMicrosoft.SqlServer.Management.Smo.Mail.MailAccountクラスを使用してアカウントを作成する。Get-DbaDbMailServerを呼び出してメールサーバーの存在確認を行う。

**権限による制御**：Database Mailアカウント作成には、sysadminサーバーロールのメンバーシップが必要。SQL Server 2008以降のバージョンが必要（MinimumVersion 10）。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 52 | データベースメール | 補助機能 | メールアカウントの作成 |

## 機能種別

データ作成（INSERT）/ 構成設定

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 接続先SQL Serverインスタンス | パイプライン入力対応、SQL Server 2008以降 |
| SqlCredential | PSCredential | No | 代替認証用資格情報 | Windows/SQL認証対応 |
| Account | string | Yes | 作成するアカウント名（エイリアス: Name） | 一意である必要あり |
| DisplayName | string | No | From欄に表示される名前 | デフォルト: Account名 |
| Description | string | No | アカウントの説明 | - |
| EmailAddress | string | Yes | 送信元メールアドレス | 有効なメールアドレス形式 |
| ReplyToAddress | string | No | 返信先メールアドレス | 有効なメールアドレス形式 |
| MailServer | string | No | SMTPサーバー名 | デフォルト: インスタンス名 |
| Force | switch | No | メールサーバー検証をスキップ | - |
| EnableException | switch | No | 例外を直接スローするかどうか | - |

### 入力データソース

- SqlInstance: ユーザー指定（パイプライン入力対応）
- Account/EmailAddress: ユーザー必須入力
- その他: オプションパラメータ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverホスト名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| Id | int | アカウントの一意識別子 |
| Name | string | アカウント名 |
| DisplayName | string | From欄に表示される名前 |
| Description | string | アカウントの説明 |
| EmailAddress | string | 送信元メールアドレス |
| ReplyToAddress | string | 返信先メールアドレス |
| IsBusyAccount | bool | 現在メール処理中かどうか |
| MailServers | Collection | 関連付けられたメールサーバー |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 入力パラメータの検証
   └─ SqlInstance、Account、EmailAddressが必須

2. SQL Serverへの接続
   └─ Connect-DbaInstance（MinimumVersion 10 = SQL Server 2008以降）

3. メールサーバー検証（オプション）
   └─ MailServer指定時、Get-DbaDbMailServerで存在確認
   └─ -Force指定時は検証をスキップ

4. ShouldProcess確認
   └─ WhatIf/Confirm対応

5. MailAccountオブジェクト作成
   └─ New-Object Microsoft.SqlServer.Management.SMO.Mail.MailAccount
   └─ DisplayName、Description、EmailAddress、ReplyToAddressを設定
   └─ Create()メソッドでアカウント作成

6. メールサーバー関連付け
   └─ MailServers.Item().Rename()でサーバー名を設定
   └─ Alter()で変更を適用
   └─ Refresh()で最新状態を取得

7. 結果の出力
   └─ サーバー情報を付加してパイプライン出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[foreachインスタンスループ]
    B --> C[Connect-DbaInstance MinVersion 10]
    C --> D{接続成功?}
    D -->|No| E[Stop-Function継続]
    D -->|Yes| F{MailServer指定?}
    F -->|Yes| G{サーバー存在確認}
    F -->|No| H[ShouldProcess確認]
    G -->|存在しない & !Force| I[Stop-Function継続]
    G -->|存在 or Force| H
    H --> J{確認OK?}
    J -->|No| K[スキップ]
    J -->|Yes| L[MailAccountオブジェクト作成]
    L --> M[プロパティ設定]
    M --> N[Create実行]
    N --> O{作成成功?}
    O -->|No| P[Stop-Function継続]
    O -->|Yes| Q[MailServer Rename]
    Q --> R[Alter/Refresh]
    R --> S[サーバー情報付加]
    S --> T[結果出力]
    T --> U{次のインスタンス?}
    E --> U
    I --> U
    K --> U
    P --> U
    U -->|Yes| B
    U -->|No| V[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | バージョン要件 | SQL Server 2008以降が必要（MinimumVersion 10） | 常時 |
| BR-002 | アカウント名一意 | 同一インスタンス内でアカウント名は一意 | 常時 |
| BR-003 | メールサーバー検証 | 指定されたMailServerの存在を確認（-Forceで回避可能） | MailServer指定時 |
| BR-004 | デフォルトDisplayName | DisplayName未指定時はAccount名を使用 | DisplayName未指定時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| アカウント作成 | msdb.dbo.sysmail_account | INSERT | アカウント情報の登録 |
| サーバー関連付け | msdb.dbo.sysmail_server | UPDATE | メールサーバー名の更新 |

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

#### msdb.dbo.sysmail_account

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name, display_name, description, email_address, replyto_address | パラメータ値 | SMO Create()経由 |

#### msdb.dbo.sysmail_server

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | servername | MailServerパラメータ値 | SMO Rename()/Alter()経由 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | SQL Serverに接続できない | 接続設定・資格情報を確認 |
| - | バージョンエラー | SQL Server 2005以前 | SQL Server 2008以降にアップグレード |
| - | サーバー未存在 | MailServerが存在しない | -Force使用または正しいサーバー名を指定 |
| - | 作成エラー | アカウント作成失敗 | 権限・重複名を確認 |

### リトライ仕様

なし（即時エラー終了、-Continue指定で次インスタンスへ継続）

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

SMO経由での操作のため、内部的にトランザクション管理される

## パフォーマンス要件

単一アカウント作成は即時完了

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

- sysadmin権限が必要
- 資格情報はPSCredentialオブジェクトで安全に受け渡し
- SupportsShouldProcess対応（WhatIf/Confirm）
- ConfirmImpact: Low

## 備考

- New-DbaDbMailProfileと組み合わせて使用することが多い
- 作成後、プロファイルへの関連付けが必要

---

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

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

### 推奨読解順序

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

SMO MailAccountオブジェクトの構造と作成プロセスを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | New-DbaDbMailAccount.ps1 | `public/New-DbaDbMailAccount.ps1` | .OUTPUTSセクション（69-92行目）で出力プロパティを確認 |
| 1-2 | New-DbaDbMailAccount.ps1 | `public/New-DbaDbMailAccount.ps1` | パラメータ定義（100-116行目）で必須/オプションを確認 |

**読解のコツ**: Account、EmailAddressが必須パラメータ。DisplayNameはデフォルトでAccount名が使用される点に注目。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaDbMailAccount.ps1 | `public/New-DbaDbMailAccount.ps1` | processブロック（117行目）とCmdletBinding属性（100行目） |

**主要処理フロー**:
1. **102-103行目**: SqlInstanceパラメータ（Mandatory、パイプライン入力対応）
2. **105-106行目**: Accountパラメータ（Mandatory、エイリアスName）
3. **110-111行目**: EmailAddressパラメータ（Mandatory）
4. **118-123行目**: Connect-DbaInstance（MinimumVersion 10）

#### Step 3: 検証ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaDbMailAccount.ps1 | `public/New-DbaDbMailAccount.ps1` | メールサーバー存在確認処理（125-129行目） |

**主要処理フロー**:
- **125行目**: Test-Boundでパラメータ指定確認
- **126行目**: Get-DbaDbMailServerでサーバー存在確認
- **126-128行目**: 存在しない場合かつ-Forceなしの場合、Stop-Function

#### Step 4: 作成処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | New-DbaDbMailAccount.ps1 | `public/New-DbaDbMailAccount.ps1` | MailAccount作成処理（131-154行目） |

**主要処理フロー**:
- **131行目**: ShouldProcess確認
- **133行目**: New-Object Microsoft.SqlServer.Management.SMO.Mail.MailAccount
- **134-137行目**: プロパティ設定（DisplayName、Description、EmailAddress、ReplyToAddress）
- **138行目**: Create()メソッドでアカウント作成
- **144行目**: MailServers.Item().Rename()でサーバー名設定
- **145-146行目**: Alter()とRefresh()で変更適用
- **147-149行目**: Add-Memberでサーバー情報付加
- **150行目**: Select-DefaultViewで出力

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

```
New-DbaDbMailAccount
    │
    ├─ Connect-DbaInstance（MinimumVersion 10）
    │      └─ SQL Server接続
    │
    ├─ Test-Bound（MailServer指定確認）
    │
    ├─ Get-DbaDbMailServer（サーバー存在確認）
    │
    ├─ ShouldProcess確認
    │
    ├─ New-Object MailAccount
    │      └─ プロパティ設定
    │      └─ Create()
    │
    ├─ MailServers.Item().Rename()
    │      └─ Alter()
    │      └─ Refresh()
    │
    ├─ Add-Member（プロパティ付加）
    │
    └─ Select-DefaultView（出力整形）
```

### データフロー図

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

SqlInstance ────────▶ Connect-DbaInstance
                              │
                              ▼
Account ───────────▶ New-Object MailAccount
                              │
DisplayName ───────▶ プロパティ設定
                              │
EmailAddress ──────▶         │
                              │
ReplyToAddress ────▶         │
                              │
Description ───────▶         │
                              ▼
                        Create()
                              │
MailServer ────────▶ MailServers.Rename()
                              │
                              ▼
                        Alter() / Refresh()
                              │
                              ▼
                        Add-Member（サーバー情報付加）
                              │
                              ▼
                     [MailAccount + Properties]
                     - Id
                     - Name
                     - DisplayName
                     - EmailAddress
                     - MailServers
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaDbMailAccount.ps1 | `public/New-DbaDbMailAccount.ps1` | ソース | メイン処理ロジック |
| Get-DbaDbMailServer.ps1 | `public/Get-DbaDbMailServer.ps1` | ソース | メールサーバー存在確認 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
