# 機能設計書 61-New-DbaDacOption

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `New-DbaDacOption` コマンドレットの機能設計書です。DACパッケージのエクスポート/パブリッシュ操作に使用するオプションオブジェクトを生成する機能について、その仕様と実装詳細を記述します。

### 本機能の処理概要

`New-DbaDacOption` は、Microsoft SQL Server Data-tier Application Framework (DacFx) で使用されるオプションオブジェクトを生成するコマンドレットです。DACPACまたはBACPACパッケージのエクスポートやパブリッシュ操作に必要な設定を行うためのオブジェクトを作成します。

**業務上の目的・背景**：SQL Serverデータベースの移行、展開、バックアップといった作業において、DACパッケージ（DACPAC/BACPAC）を使用する際には多くの設定オプションが存在します。本機能は、これらのオプションをPowerShellから容易に設定できるようにし、スクリプト化やCI/CDパイプラインへの組み込みを可能にします。SMO アセンブリ名を覚える必要がなくなり、開発者の生産性向上に寄与します。

**機能の利用シーン**：
- データベーススキーマのDACPACエクスポート時のオプション設定
- BACPACによるデータエクスポート時のオプション設定
- DACPACをターゲットデータベースにデプロイする際のオプション設定
- Visual Studio SSDT プロジェクトで作成したパブリッシュプロファイルの読み込みと活用

**主要な処理内容**：
1. Type（Dacpac/Bacpac）とAction（Export/Publish）に基づいて適切なDacFxオプションオブジェクトを選択
2. 指定されたPropertyハッシュテーブルからプロパティを設定してオブジェクトを生成
3. Publishアクション時はPublishXmlプロファイルからDeployOptionsを読み込み可能
4. 生成したオプションオブジェクトをパイプライン経由で後続コマンドに受け渡し

**関連システム・外部連携**：
- Microsoft.SqlServer.Dac アセンブリ（DacFx Framework）
- DacProfile XML ファイル（Visual Studio SSDT で生成）

**権限による制御**：
- 本機能自体は特別な権限を必要としません（オプションオブジェクトの生成のみ）
- 生成されたオプションを使用するExport/Publish操作ではSQL Server接続権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLI | 主画面 | PowerShellコマンドラインからの直接実行 |

## 機能種別

オブジェクト生成処理（ファクトリパターン）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Type | string | No | パッケージタイプ（Dacpac/Bacpac）。デフォルト: Dacpac | ValidateSet('Dacpac', 'Bacpac') |
| Action | string | Yes | 操作タイプ（Export/Publish） | ValidateSet('Publish', 'Export') |
| PublishXml | string | No | DACパブリッシュプロファイルXMLファイルパス | ファイル存在チェック |
| Property | hashtable | No | オプションオブジェクトに設定するプロパティ | - |
| EnableException | switch | No | 例外を有効にするフラグ | - |

### 入力データソース

- ユーザー指定のパラメータ値
- PublishXml ファイル（指定時のみ）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| - | Microsoft.SqlServer.Dac.DacExtractOptions | Type=Dacpac, Action=Export時の出力 |
| - | Microsoft.SqlServer.Dac.DacExportOptions | Type=Bacpac, Action=Export時の出力 |
| - | Microsoft.SqlServer.Dac.PublishOptions | Type=Dacpac, Action=Publish時の出力 |
| - | Microsoft.SqlServer.Dac.DacImportOptions | Type=Bacpac, Action=Publish時の出力 |

### 出力先

PowerShellパイプライン（オブジェクト出力）

## 処理フロー

### 処理シーケンス

```
1. ShouldProcess確認
   └─ 処理実行の確認（WhatIf/Confirm対応）
2. Actionの判定
   └─ Export または Publish のいずれかを判定
3. Typeの判定
   └─ Dacpac または Bacpac のいずれかを判定
4. オプションオブジェクトの生成
   └─ 適切なDacFx型のインスタンスを作成
5. プロパティの設定（Propertyパラメータ指定時）
   └─ ハッシュテーブルの値をオブジェクトに反映
6. PublishXml読み込み（Publish+Dacpac+PublishXml指定時）
   └─ DacProfile.Load()でプロファイルを読み込みDeployOptionsを設定
7. オブジェクト出力
   └─ パイプラインにオプションオブジェクトを出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Action判定}
    B -->|Export| C{Type判定}
    B -->|Publish| D{Type判定}
    C -->|Dacpac| E[DacExtractOptions生成]
    C -->|Bacpac| F[DacExportOptions生成]
    D -->|Dacpac| G[PublishOptions生成]
    D -->|Bacpac| H[DacImportOptions生成]
    G --> I{PublishXml指定?}
    I -->|Yes| J[DacProfile読み込み]
    J --> K[DeployOptions設定]
    I -->|No| L{DeployOptions in Property?}
    L -->|Yes| M[PropertyからDeployOptions設定]
    L -->|No| N[空のDeployOptions設定]
    K --> O[オブジェクト出力]
    M --> O
    N --> O
    E --> O
    F --> O
    H --> O
    O --> P[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | Typeデフォルト | Typeが指定されない場合はDacpacをデフォルトとする | Type未指定時 |
| BR-02 | PublishXml優先 | PublishXmlが指定された場合、PropertyのDeployOptionsより優先される | PublishXml指定時 |
| BR-03 | GenerateDeploymentScript初期化 | Publish時にGenerateDeploymentScriptが未指定の場合はfalseで初期化 | Action=Publish, Type=Dacpac |

### 計算ロジック

該当なし

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

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

本機能はデータベースへの直接アクセスを行いません。

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | オブジェクト生成失敗 | DacFxアセンブリが利用不可 | dbatools.libraryの再インストール |
| - | プロファイル読み込み失敗 | PublishXmlファイルが不正/存在しない | ファイルパスとXML構造を確認 |

### リトライ仕様

リトライ処理なし

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

該当なし（データベース操作なし）

## パフォーマンス要件

- 軽量なオブジェクト生成のみのため、ミリ秒単位で完了

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

- PublishXmlファイルに接続文字列やパスワードが含まれる可能性があるため、ファイルのアクセス権限管理が必要
- Propertyハッシュテーブルに機密情報を含める場合はセキュアな取り扱いが必要

## 備考

- DacFxライブラリはdbatools.libraryパッケージに含まれている
- SQL Server 2005以降に対応

---

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

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

### 推奨読解順序

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

DacFxで使用される各種オプションオブジェクトの型を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Microsoft.SqlServer.Dac.dll | (dbatools.library内) | DacExtractOptions, DacExportOptions, PublishOptions, DacImportOptions の各クラス構造 |

**読解のコツ**: DacFxは.NETライブラリであり、各オプションクラスのプロパティ一覧はMicrosoft Docsで確認可能。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaDacOption.ps1 | `public/New-DbaDacOption.ps1` | コマンドレット全体の構造とパラメータ定義 |

**主要処理フロー**:
1. **104-114行目**: パラメータ定義（CmdletBinding, ValidateSet等）
2. **115-116行目**: process ブロック開始、ShouldProcess確認
3. **117-127行目**: 内部関数 New-DacObject の定義
4. **129-161行目**: Action/Typeに応じたオブジェクト生成ロジック

#### Step 3: オブジェクト生成ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaDacOption.ps1 | `public/New-DbaDacOption.ps1` | New-DacObject内部関数の実装 |

**主要処理フロー**:
- **117-127行目**: New-DacObject関数 - New-Objectを使用してDacFx型のインスタンスを生成
- **130-135行目**: Export時の分岐処理（Dacpac -> DacExtractOptions, Bacpac -> DacExportOptions）
- **136-161行目**: Publish時の分岐処理（より複雑なPublishOptions/DacImportOptionsの生成）
- **139-146行目**: PublishXml指定時のDacProfile読み込み処理
- **148-152行目**: PropertyハッシュテーブルからのDeployOptions生成

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

```
New-DbaDacOption (public/New-DbaDacOption.ps1)
    │
    ├─ New-DacObject (内部関数)
    │      └─ New-Object (PowerShell組み込み)
    │           └─ Microsoft.SqlServer.Dac.* (DacFxアセンブリ)
    │
    └─ [Microsoft.SqlServer.Dac.DacProfile]::Load() (PublishXml読み込み時)
```

### データフロー図

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

Type ─────────────┐
                  │
Action ───────────┼──▶ New-DbaDacOption ──▶ DacExtractOptions
                  │    (オブジェクト選択・生成)         / DacExportOptions
PublishXml ───────┤                                    / PublishOptions
                  │                                    / DacImportOptions
Property ─────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaDacOption.ps1 | `public/New-DbaDacOption.ps1` | ソース | メイン実装ファイル |
| New-DbaDacOption.Tests.ps1 | `tests/New-DbaDacOption.Tests.ps1` | テスト | 単体テスト |
| Export-DbaDacPackage.ps1 | `public/Export-DbaDacPackage.ps1` | ソース | 生成オプションの使用先（Export） |
| Publish-DbaDacPackage.ps1 | `public/Publish-DbaDacPackage.ps1` | ソース | 生成オプションの使用先（Publish） |
