# 機能設計書 62-New-DbaDacPackage

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `New-DbaDacPackage` コマンドレットの機能設計書です。SQLソースファイルからDACPACパッケージを作成する機能について、その仕様と実装詳細を記述します。

### 本機能の処理概要

`New-DbaDacPackage` は、SQLソースファイルからDACPAC（Data-tier Application Package）を生成するコマンドレットです。MSBuild、Visual Studio、.NET SDKを必要とせず、純粋なPowerShellベースでデータベースプロジェクトのビルドワークフローを実現します。

**業務上の目的・背景**：従来、DACPACパッケージの作成にはVisual Studio SSDTプロジェクトとMSBuildが必要でしたが、本機能によりVisual Studioがない環境でも、またLinuxやmacOSなどのクロスプラットフォーム環境でもDACPACを生成できるようになります。CI/CDパイプラインでのデータベーススキーマ管理、開発環境の簡素化に大きく貢献します。

**機能の利用シーン**：
- Visual Studioのない環境でのDACPAC作成
- CI/CDパイプラインでの自動化されたデータベーススキーマビルド
- クロスプラットフォーム（Windows/Linux/macOS）でのデータベース開発
- 複数のSQLファイルから単一のデプロイ可能パッケージを生成

**主要な処理内容**：
1. 指定ディレクトリからSQLファイルを収集（再帰的スキャン対応）
2. TSqlModelを使用してSQLファイルを解析・検証
3. モデルの検証エラー・警告を収集
4. DacPackageExtensions.BuildPackageでDACPACファイルを生成
5. ビルド結果（成功/失敗、オブジェクト数、エラー情報等）を出力

**関連システム・外部連携**：
- Microsoft.SqlServer.Dac.Model.TSqlModel（DacFx Framework）
- Microsoft.SqlServer.Dac.DacPackageExtensions
- ファイルシステム（SQLソースファイル、出力DACPAC）

**権限による制御**：
- ソースディレクトリの読み取り権限
- 出力ディレクトリへの書き込み権限
- SQL Server接続は不要（純粋にローカル処理）

## 関連画面

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

## 機能種別

ファイル処理 / パッケージ生成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Path | string | Yes | SQLファイルを含むディレクトリまたは.sqlprojファイルのパス | パス存在チェック |
| OutputPath | string | No | 生成するDACPACファイルの出力パス | - |
| DacVersion | version | No | DACPACパッケージのバージョン。デフォルト: 1.0.0.0 | - |
| DacDescription | string | No | パッケージに埋め込む説明文 | - |
| DatabaseName | string | No | データベース名。デフォルト: ディレクトリ名 | - |
| Recursive | switch | No | サブディレクトリも検索するフラグ | - |
| SqlServerVersion | string | No | ターゲットSQL Serverバージョン。デフォルト: Sql160 | ValidateSet |
| Filter | string | No | ファイルフィルタパターン。デフォルト: *.sql | - |
| EnableException | switch | No | 例外を有効にするフラグ | - |

### 入力データソース

- ファイルシステム上のSQLソースファイル（.sql）
- （将来実装予定）.sqlproj プロジェクトファイル

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | ビルドを実行したコンピュータ名 |
| Path | string | 生成されたDACPACファイルの完全パス |
| Database | string | パッケージに設定されたデータベース名 |
| DatabaseName | string | データベース名（Database と同値） |
| Version | string | パッケージバージョン（例: 1.0.0.0） |
| FileCount | int | 処理されたSQLファイル数 |
| ObjectCount | int | コンパイルされたデータベースオブジェクト数 |
| Duration | prettytimespan | ビルド処理時間 |
| Success | bool | ビルド成功/失敗フラグ |
| Errors | string[] | エラーメッセージ配列 |
| Warnings | string[] | 警告メッセージ配列 |

### 出力先

- PowerShellパイプライン（PSCustomObject）
- ファイルシステム（DACPACファイル）

## 処理フロー

### 処理シーケンス

```
1. DacFx型の利用可能性確認
   └─ TSqlModel型がロードされているか確認
2. パス解決
   └─ 指定パスをフルパスに解決
3. SQLファイル収集
   └─ ディレクトリからフィルタに一致するファイルを取得
4. TSqlModelの作成
   └─ 指定SQLServerVersionでモデルを初期化
5. SQLファイルの処理
   └─ 各ファイルを読み込みモデルに追加
6. モデルの検証
   └─ Validate()でエラー・警告を収集
7. オブジェクトカウント
   └─ ユーザー定義オブジェクト数を取得
8. DACPAC生成（エラーがない場合）
   └─ BuildPackage()でDACPACファイル作成
9. 結果出力
   └─ ビルド結果オブジェクトを出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{DacFx利用可能?}
    B -->|No| C[Stop-Function]
    B -->|Yes| D[パス解決]
    D --> E{パス存在?}
    E -->|No| C
    E -->|Yes| F{ディレクトリ?}
    F -->|Yes| G[SQLファイル収集]
    F -->|No| H{.sqlproj?}
    H -->|Yes| I[未実装エラー]
    H -->|No| C
    G --> J{ファイル数 > 0?}
    J -->|No| C
    J -->|Yes| K[TSqlModel作成]
    K --> L[SQLファイル処理ループ]
    L --> M[モデル検証]
    M --> N[オブジェクトカウント]
    N --> O{エラーあり?}
    O -->|Yes| P[失敗結果出力]
    O -->|No| Q[DACPAC生成]
    Q --> R[成功結果出力]
    P --> S[終了]
    R --> S
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | デフォルトバージョン | DacVersionが指定されない場合は1.0.0.0を使用 | DacVersion未指定時 |
| BR-02 | デフォルトデータベース名 | DatabaseNameが指定されない場合はディレクトリ名を使用 | DatabaseName未指定時 |
| BR-03 | デフォルト出力パス | OutputPathが指定されない場合はカレントディレクトリにDatabaseName.dacpacを生成 | OutputPath未指定時 |
| BR-04 | エラー時はDACPAC生成しない | 検証エラーがある場合はDACPACを生成せず失敗結果を返す | エラー発生時 |
| BR-05 | デフォルトSQLServerVersion | 指定なしの場合はSql160（SQL Server 2022）をターゲット | SqlServerVersion未指定時 |

### 計算ロジック

該当なし

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

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

本機能はデータベースへの直接アクセスを行いません（ローカルファイル処理のみ）。

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | DacFx型利用不可 | dbatools.libraryが正しくロードされていない | dbatools.libraryの再インストール |
| - | パス未発見 | 指定パスが存在しない | パスを確認 |
| - | SQLファイルなし | 指定ディレクトリにSQLファイルがない | パスとフィルタを確認 |
| - | .sqlproj未対応 | .sqlprojファイルが指定された | ディレクトリパスを使用 |
| - | TSqlModel作成失敗 | DacFxライブラリの問題 | DacFxバージョンを確認 |
| - | 検証エラー | SQLファイルに構文エラー等 | エラー内容を確認し修正 |
| - | DACPAC生成失敗 | ファイル書き込み権限等 | 出力パスの権限を確認 |

### リトライ仕様

リトライ処理なし

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

該当なし（ファイル処理のみ）

## パフォーマンス要件

- 処理時間はSQLファイル数とサイズに依存
- 大規模プロジェクトでも数分以内に完了を想定
- Durationプロパティで実際の処理時間を確認可能

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

- ソースファイルに機密情報（パスワード等）を含めないよう注意
- 出力DACPACファイルにも同様の情報が含まれる可能性

## 備考

- .sqlproj ファイルのパースは将来実装予定
- Publish-DbaDacPackageとパイプライン連携可能

---

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

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

### 推奨読解順序

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

出力されるPSCustomObjectの構造と、DacFxの主要クラスを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | New-DbaDacPackage.ps1 | `public/New-DbaDacPackage.ps1` | 415-427行目: 出力オブジェクトの構造定義 |

**読解のコツ**: PSCustomObjectの各プロパティが何を表すかを把握し、Publish-DbaDacPackageへのパイプライン連携を意識する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaDacPackage.ps1 | `public/New-DbaDacPackage.ps1` | 186-199行目: パラメータ定義とバリデーション |

**主要処理フロー**:
1. **186-199行目**: パラメータ定義（Path必須、各種デフォルト値）
2. **201-220行目**: begin ブロック - DacFx型チェック、パス解決
3. **222-428行目**: process ブロック - メイン処理

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaDacPackage.ps1 | `public/New-DbaDacPackage.ps1` | SQLファイル収集とモデル構築 |

**主要処理フロー**:
- **230-259行目**: パスの種別判定（ディレクトリ or .sqlproj）とSQLファイル収集
- **280-298行目**: TSqlModel作成（SqlServerVersionに応じた初期化）
- **300-327行目**: SQLファイルのモデルへの追加処理
- **329-360行目**: モデル検証とオブジェクトカウント
- **383-410行目**: DACPAC生成処理（BuildPackage呼び出し）

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

```
New-DbaDacPackage (public/New-DbaDacPackage.ps1)
    │
    ├─ Get-ChildItem (SQLファイル収集)
    │
    ├─ New-Object Microsoft.SqlServer.Dac.Model.TSqlModel
    │      └─ TSqlModel.AddObjects() (各SQLファイル追加)
    │
    ├─ TSqlModel.Validate() (モデル検証)
    │
    ├─ TSqlModel.GetObjects() (オブジェクトカウント)
    │
    └─ [Microsoft.SqlServer.Dac.DacPackageExtensions]::BuildPackage()
           └─ 出力: .dacpac ファイル
```

### データフロー図

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

SQLファイル群 ───▶ TSqlModel.AddObjects() ──┐
(*.sql)                                     │
                                            ▼
Path ─────────────▶ ファイル収集 ────▶ モデル構築 ────▶ 検証 ────▶ BuildPackage
                                            │                        │
DatabaseName ─────▶                         ▼                        ▼
DacVersion ───────▶                   PackageMetadata          .dacpac ファイル
                                                                     │
                                                                     ▼
                                                              PSCustomObject
                                                              (ビルド結果)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaDacPackage.ps1 | `public/New-DbaDacPackage.ps1` | ソース | メイン実装ファイル |
| New-DbaDacPackage.Tests.ps1 | `tests/New-DbaDacPackage.Tests.ps1` | テスト | 単体テスト |
| Publish-DbaDacPackage.ps1 | `public/Publish-DbaDacPackage.ps1` | ソース | 生成DACPACのデプロイ先 |
| Export-DbaDacPackage.ps1 | `public/Export-DbaDacPackage.ps1` | ソース | 既存DBからのDACPAC抽出（別アプローチ） |
