# 機能設計書 264-Get-DbaDbMailProfile

## 概要

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

### 本機能の処理概要

Get-DbaDbMailProfileは、SQL ServerインスタンスからDatabase Mailプロファイルとその構成詳細を取得するPowerShellコマンドレットである。プロファイルID、名前、説明、ステータスプロパティなどの詳細な構成情報を返す。環境全体のDatabase Mail構成監査、メール通知問題のトラブルシューティング、コンプライアンスや変更管理のためのメールプロファイル設定文書化に活用される。

**業務上の目的・背景**：Database Mailプロファイルは、SQL Serverからメールを送信する際に使用するメールアカウントをグループ化する論理的なコンテナである。本コマンドは、プロファイル構成の確認、複数サーバー間での設定比較、問題調査時のプロファイル情報取得といった業務課題を解決する。特定のプロファイル名でフィルタリングしたり、特定のプロファイルを除外したりすることで、柔軟な情報取得が可能。

**機能の利用シーン**：
- Database Mailプロファイル一覧の取得
- 特定プロファイルの構成詳細確認
- 複数インスタンス間でのプロファイル設定比較
- テスト用・本番用プロファイルの区別管理
- コンプライアンス監査用の設定文書化

**主要な処理内容**：
1. SqlInstanceパラメータまたはパイプライン入力からDatabase Mailオブジェクトを取得
2. SMOのProfilesコレクションからプロファイル情報を抽出
3. Profile/ExcludeProfileパラメータによるフィルタリング
4. サーバー情報を付加してパイプライン出力

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

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 接続先SQL Serverインスタンス | 有効なインスタンス名 |
| SqlCredential | PSCredential | No | 代替認証用資格情報 | Windows/SQL認証対応 |
| Profile | string[] | No | 取得するプロファイル名（フィルタ） | 複数値対応 |
| ExcludeProfile | string[] | No | 除外するプロファイル名 | 複数値対応 |
| 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 | 完全修飾インスタンス名 |
| ID | int | プロファイルの一意識別子 |
| Name | string | プロファイル名 |
| Description | string | プロファイルの説明 |
| ForceDeleteForActiveProfiles | bool | アクティブ使用中でも強制削除するかどうか |
| IsBusyProfile | bool | 現在メール処理中かどうか |

### 出力先

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

## 処理フロー

### 処理シーケンス

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

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

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

4. 各Database Mailオブジェクトに対して繰り返し
   └─ Profilesコレクションを取得
   └─ Profileフィルターが指定された場合、該当プロファイルのみ抽出
   └─ ExcludeProfileフィルターが指定された場合、該当プロファイルを除外

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

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

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[foreachインスタンスループ]
    B --> C[Get-DbaDbMail呼び出し]
    C --> D[InputObject蓄積]
    D --> E{InputObject存在?}
    E -->|No| F[エラー終了]
    E -->|Yes| G[foreachループ開始]
    G --> H[Profilesコレクション取得]
    H --> I{Profile指定?}
    I -->|Yes| J[Where-Object -In フィルタ]
    I -->|No| K{ExcludeProfile指定?}
    J --> K
    K -->|Yes| L[Where-Object -NotIn フィルタ]
    K -->|No| M[サーバー情報付加]
    L --> M
    M --> N[結果出力]
    N --> O{次のオブジェクト?}
    O -->|Yes| G
    O -->|No| P[終了]
    F --> P
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 入力必須 | SqlInstanceまたはInputObjectのいずれかが必要 | 常時 |
| BR-002 | 名前フィルタ | Profile指定時は完全一致でフィルタリング | Profileパラメータ指定時 |
| BR-003 | 除外フィルタ | ExcludeProfile指定時は該当プロファイルを除外 | ExcludeProfileパラメータ指定時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| プロファイル取得 | msdb.dbo.sysmail_profile | SELECT | SMO経由で内部的に参照 |

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

#### msdb.dbo.sysmail_profile

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

なし（即時エラー終了）

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

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

## パフォーマンス要件

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

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

- 資格情報はPSCredentialオブジェクトで安全に受け渡し
- Windows認証、SQL認証、AD Password認証、AD Integrated認証をサポート
- Database Mailプロファイルへのアクセスには適切な権限が必要

## 備考

- Get-DbaDbMailとのパイプライン連携を推奨
- 複数インスタンスの一括取得には配列またはパイプライン入力を使用
- ProfileとExcludeProfileは併用可能

---

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

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

### 推奨読解順序

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

SMO MailProfileオブジェクトの構造を理解することが重要。

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

**読解のコツ**: InputObjectの型`Microsoft.SqlServer.Management.Smo.Mail.SqlMail[]`がGet-DbaDbMailの出力型と一致することを確認する。

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

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

**主要処理フロー**:
1. **112-114行目**: foreachでSqlInstanceをループし、Get-DbaDbMailでInputObjectを蓄積
2. **116-119行目**: InputObjectが空の場合はStop-Functionで処理終了
3. **121-142行目**: 各mailserverオブジェクトをループ処理

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDbMailProfile.ps1 | `public/Get-DbaDbMailProfile.ps1` | Profiles取得とフィルタリング処理 |

**主要処理フロー**:
- **123行目**: `$mailserver.Profiles`でSMOからプロファイルコレクションを取得
- **125-127行目**: Profileパラメータ指定時のWhere-Object -Inフィルタリング
- **129-131行目**: ExcludeProfileパラメータ指定時のWhere-Object -NotInフィルタリング
- **134-136行目**: サーバー識別情報（ComputerName、InstanceName、SqlInstance）をAdd-Memberで付加
- **138行目**: Select-DefaultViewで出力プロパティを制御

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

```
Get-DbaDbMailProfile
    │
    ├─ Get-DbaDbMail（SqlInstance指定時）
    │      └─ Connect-DbaInstance
    │             └─ SQL Server接続
    │
    ├─ SqlMail.Profiles（SMOプロパティアクセス）
    │      └─ msdb.dbo.sysmail_profileへのクエリ
    │
    ├─ Where-Object（Profile/ExcludeProfileフィルタリング）
    │
    ├─ Add-Member（プロパティ付加）
    │
    └─ Select-DefaultView（出力整形）
```

### データフロー図

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

SqlInstance ────┐
                ├──▶ Get-DbaDbMail ──▶ SqlMail
InputObject ────┘                          │
                                           ▼
                                      Profiles
                                           │
Profile ─────────────────────────▶ Where-Object -In
                                           │
ExcludeProfile ──────────────────▶ Where-Object -NotIn
                                           │
                                           ▼
                                  Add-Member（サーバー情報付加）
                                           │
                                           ▼
                                  Select-DefaultView
                                           │
                                           ▼
                               [MailProfile + Properties]
                               - ID
                               - Name
                               - Description
                               - IsBusyProfile
```

### 関連ファイル一覧

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