# 機能設計書 267-New-DbaDbMailProfile

## 概要

本ドキュメントは、SQL ServerにDatabase Mailプロファイルを作成するNew-DbaDbMailProfileコマンドレットの機能設計を記述する。

### 本機能の処理概要

New-DbaDbMailProfileは、SQL ServerインスタンスにDatabase Mailプロファイルを新規作成するPowerShellコマンドレットである。Database Mailプロファイルは、SQL Serverが通知、アラート、レポートに使用するメールアカウントを整理するためのコンテナとして機能する。複数のメールアカウントをグループ化し、フェイルオーバーシナリオのための優先順位を設定できる。

**業務上の目的・背景**：Database Mailプロファイルは、SQL Serverからメールを送信する際の論理的な送信設定グループである。本コマンドは、完全なメール通知システムの設定、異なる通知タイプの分離（アラート用、レポート用）、メールアカウントの冗長構成といった業務課題を解決する。プロファイル作成時にメールアカウントを関連付けることで、即座に使用可能な状態にできる。

**機能の利用シーン**：
- 新規SQL Server環境でのDatabase Mail初期設定
- 用途別（DBAアラート用、アプリケーション通知用）のプロファイル作成
- メールアカウント冗長化のためのプロファイル設定
- 環境移行時のDatabase Mail設定再構築

**主要な処理内容**：
1. SQL Serverインスタンスへの接続（SQL Server 2008以降が必要）
2. SMOを使用してMailProfileオブジェクトを作成
3. Descriptionを設定（オプション）
4. Create()メソッドでプロファイルを作成
5. メールアカウントを関連付け（オプション、優先順位指定可能）
6. 作成されたプロファイル情報をパイプライン出力

**関連システム・外部連携**：SQL Server Management Objects（SMO）のMicrosoft.SqlServer.Management.Smo.Mail.MailProfileクラスを使用してプロファイルを作成する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 52 | データベースメール | 補助機能 | メールプロファイルの作成 |

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 接続先SQL Serverインスタンス | パイプライン入力対応、SQL Server 2008以降 |
| SqlCredential | PSCredential | No | 代替認証用資格情報 | Windows/SQL認証対応 |
| Profile | string | Yes | 作成するプロファイル名（エイリアス: Name） | 一意である必要あり |
| Description | string | No | プロファイルの説明 | - |
| MailAccountName | string | No | 関連付けるメールアカウント名 | 既存のアカウント名 |
| MailAccountPriority | int | No | メールアカウントの優先順位 | デフォルト: 1（最高優先度） |
| EnableException | switch | No | 例外を直接スローするかどうか | - |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverホスト名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| Id | int | プロファイルの一意識別子 |
| Name | string | プロファイル名 |
| Description | string | プロファイルの説明 |
| IsBusyProfile | bool | 現在メール処理中かどうか |

### 出力先

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

## 処理フロー

### 処理シーケンス

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

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

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

4. MailProfileオブジェクト作成
   └─ New-Object Microsoft.SqlServer.Management.SMO.Mail.MailProfile
   └─ Description設定（指定時）
   └─ Create()メソッドでプロファイル作成

5. メールアカウント関連付け（オプション）
   └─ MailAccountName指定時、AddAccount()でアカウントを追加
   └─ MailAccountPriority未指定時はデフォルト1

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

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[foreachインスタンスループ]
    B --> C[Connect-DbaInstance MinVersion 10]
    C --> D{接続成功?}
    D -->|No| E[Stop-Function継続]
    D -->|Yes| F[ShouldProcess確認]
    F --> G{確認OK?}
    G -->|No| H[スキップ]
    G -->|Yes| I[MailProfileオブジェクト作成]
    I --> J{Description指定?}
    J -->|Yes| K[Description設定]
    J -->|No| L[Create実行]
    K --> L
    L --> M{MailAccountName指定?}
    M -->|Yes| N{MailAccountPriority指定?}
    M -->|No| O[サーバー情報付加]
    N -->|No| P[Priority = 1]
    N -->|Yes| Q[Priority = 指定値]
    P --> R[AddAccount実行]
    Q --> R
    R --> O
    O --> S[結果出力]
    S --> T{次のインスタンス?}
    E --> T
    H --> T
    T -->|Yes| B
    T -->|No| U[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | バージョン要件 | SQL Server 2008以降が必要（MinimumVersion 10） | 常時 |
| BR-002 | プロファイル名一意 | 同一インスタンス内でプロファイル名は一意 | 常時 |
| BR-003 | デフォルト優先順位 | MailAccountPriority未指定時は1（最高優先度） | MailAccountName指定時 |
| BR-004 | 優先順位の意味 | 低い数値ほど高い優先度。フェイルオーバー時に使用 | 複数アカウント関連付け時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| プロファイル作成 | msdb.dbo.sysmail_profile | INSERT | プロファイル情報の登録 |
| アカウント関連付け | msdb.dbo.sysmail_profileaccount | INSERT | プロファイル-アカウント関連付け |

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

#### msdb.dbo.sysmail_profile

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

#### msdb.dbo.sysmail_profileaccount

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | profile_id, account_id, sequence_number | プロファイルID、アカウント名、優先順位 | SMO AddAccount()経由 |

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

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

## パフォーマンス要件

単一プロファイル作成は即時完了

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

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

## 備考

- New-DbaDbMailAccountと組み合わせて使用することが多い
- 作成後、sp_send_dbmailで使用可能
- Author: Ian Lanham (@ilanham)

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: Profileが必須パラメータ。MailAccountNameとMailAccountPriorityはオプションで、アカウント関連付けに使用される。

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

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

**主要処理フロー**:
1. **85-86行目**: SqlInstanceパラメータ（Mandatory、パイプライン入力対応）
2. **88-90行目**: Profileパラメータ（Mandatory、エイリアスName）
3. **91行目**: Descriptionパラメータ（オプション）
4. **92-93行目**: MailAccountName、MailAccountPriorityパラメータ（オプション）

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaDbMailProfile.ps1 | `public/New-DbaDbMailProfile.ps1` | MailProfile作成処理（104-125行目） |

**主要処理フロー**:
- **104行目**: ShouldProcess確認
- **106行目**: New-Object Microsoft.SqlServer.Management.SMO.Mail.MailProfile
- **107-109行目**: Test-BoundでDescription指定確認、設定
- **110行目**: Create()メソッドでプロファイル作成
- **111-116行目**: MailAccountName指定時のアカウント関連付け処理
- **112-114行目**: MailAccountPriority未指定時はデフォルト1
- **115行目**: AddAccount()でアカウント追加（sequenceNumber = 優先順位）
- **117-119行目**: Add-Memberでサーバー情報付加
- **121行目**: Select-DefaultViewで出力

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

```
New-DbaDbMailProfile
    │
    ├─ Connect-DbaInstance（MinimumVersion 10）
    │      └─ SQL Server接続
    │
    ├─ ShouldProcess確認
    │
    ├─ New-Object MailProfile
    │      └─ Test-Bound（Description）
    │      └─ Description設定
    │      └─ Create()
    │
    ├─ Test-Bound（MailAccountName）
    │      └─ AddAccount()（アカウント関連付け）
    │
    ├─ Add-Member（プロパティ付加）
    │
    └─ Select-DefaultView（出力整形）
```

### データフロー図

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

SqlInstance ────────▶ Connect-DbaInstance
                              │
                              ▼
Profile ───────────▶ New-Object MailProfile
                              │
Description ───────▶ プロパティ設定（オプション）
                              │
                              ▼
                        Create()
                              │
MailAccountName ───▶ AddAccount()（オプション）
                              │
MailAccountPriority ─▶（デフォルト1）
                              │
                              ▼
                        Add-Member（サーバー情報付加）
                              │
                              ▼
                     [MailProfile + Properties]
                     - Id
                     - Name
                     - Description
                     - IsBusyProfile
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaDbMailProfile.ps1 | `public/New-DbaDbMailProfile.ps1` | ソース | メイン処理ロジック |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
