# 画面設計書 207-DACプロファイル

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるDACプロファイル作成機能の設計仕様を定義するものである。

### 本画面の処理概要

DACプロファイル機能は、DACパッケージのデプロイメントで使用する公開プロファイルXMLファイルを生成する機能を提供する。SqlPackage.exeやVisual Studio SSDTプロジェクトで使用できる標準形式のXMLファイルを作成する。

**業務上の目的・背景**：DACパッケージのデプロイメントでは、ターゲットデータベース名、接続文字列、デプロイメントオプションなどの設定が必要である。公開プロファイルを事前に作成しておくことで、デプロイメント時に毎回設定を指定する必要がなくなり、環境ごとの設定を標準化できる。本機能は、SQL Serverインスタンスへの接続情報から自動的にプロファイルXMLを生成し、CI/CDパイプラインや自動化スクリプトでの利用を支援する。

**画面へのアクセス方法**：PowerShellコンソールから`New-DbaDacProfile`コマンドを実行する。

**主要な操作・処理内容**：
1. SQLインスタンスへの接続と接続文字列の取得
2. または直接ConnectionStringの指定
3. データベースごとのプロファイルXML生成
4. PublishOptionsによる追加設定の埋め込み
5. ファイル出力（instancename-database-publish.xml形式）

**画面遷移**：
- 入力元：管理者またはスクリプトからのコマンド実行
- 出力先：Publish-DbaDacPackageへの-PublishXmlパラメータ
- 関連機能：Publish-DbaDacPackage、New-DbaDacOption

**権限による表示制御**：SQLインスタンスへの接続権限が必要（SqlInstance指定時）。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 63 | New-DbaDacProfile | 主機能 | DACプロファイルの作成 |
| 64 | Publish-DbaDacPackage | 利用先機能 | DACパッケージの公開 |
| 61 | New-DbaDacOption | 関連機能 | DACオプションの作成 |

## 画面種別

コマンドラインインターフェース（CLI）/ ヘルパー関数

## URL/ルーティング

```powershell
# SQLインスタンスから生成
New-DbaDacProfile -SqlInstance <インスタンス> -Database <DB名> -Path <出力先>

# 接続文字列から生成
New-DbaDacProfile -ConnectionString <接続文字列> -Database <DB名> -Path <出力先>
```

## 入出力項目

| パラメータ名 | 型 | 必須 | 既定値 | 説明 |
|-------------|-----|------|--------|------|
| SqlInstance | DbaInstance[] | 条件付き | - | 対象SQLインスタンス |
| SqlCredential | PSCredential | No | - | SQL認証用資格情報 |
| Database | string[] | Yes | - | 対象データベース |
| Path | string | No | $home\Documents | 出力ディレクトリ |
| ConnectionString | string[] | 条件付き | - | 直接指定する接続文字列 |
| PublishOptions | hashtable | No | - | 追加デプロイメントオプション |
| EnableException | switch | No | $false | 例外の有効化 |
| WhatIf | switch | No | - | 実行内容のプレビュー |
| Confirm | switch | No | - | 実行確認プロンプト |

## 表示項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピュータ名（接続文字列から抽出） |
| InstanceName | string | インスタンス名（接続文字列から抽出） |
| SqlInstance | string | 完全なインスタンス名 |
| Database | string | データベース名 |
| FileName | string | 生成されたプロファイルファイルパス |
| ConnectionString | string | プロファイルに埋め込まれた接続文字列 |
| ProfileTemplate | string | 生成されたXMLコンテンツ（既定表示から除外） |

## イベント仕様

### 1-プロファイル生成イベント

1. SqlInstanceまたはConnectionStringの検証
2. 出力パスの存在確認
3. SqlInstance指定時：接続と接続文字列の取得
4. ConnectionStringの正規化
5. 各データベースに対するXMLテンプレート生成
6. PublishOptionsの埋め込み（指定時）
7. ファイル出力と結果オブジェクト返却

### 2-テンプレート生成イベント

XMLテンプレートの構造：
```xml
<?xml version="1.0" ?>
<Project ToolsVersion="14.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <TargetDatabaseName>{DB名}</TargetDatabaseName>
    <TargetConnectionString>{接続文字列}</TargetConnectionString>
    <ProfileVersionNumber>1</ProfileVersionNumber>
    {追加オプション}
  </PropertyGroup>
</Project>
```

## データベース更新仕様

本機能はファイル生成のみであり、データベース操作は発生しない。

## メッセージ仕様

| 種別 | メッセージ | 条件 |
|------|----------|------|
| エラー | "You must specify either SqlInstance or ConnectionString" | 両方未指定時 |
| エラー | "$Path doesn't exist or access denied" | パスが存在しない場合 |
| エラー | "Path must be a directory" | パスがディレクトリでない場合 |
| エラー | 接続エラー詳細 | Connect-DbaInstance失敗時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| パラメータ未指定 | Stop-Functionで必須エラー |
| パス不正 | Stop-Functionでパスエラー |
| 接続失敗 | Stop-Functionでエラー記録、Continue |
| ファイル出力失敗 | Stop-Functionでエラー記録、Continue |

## 備考

- 生成されるファイル名は「instancename-database-publish.xml」形式
- 接続文字列からApplication Name等の不要な属性は除去される
- Visual Studio SSDTプロジェクトのPublish機能と互換性あり

---

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

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

### 推奨読解順序

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

出力オブジェクトとXMLテンプレートの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | New-DbaDacProfile.ps1 | `public/New-DbaDacProfile.ps1` | 出力オブジェクト構造（行199-207） |
| 1-2 | New-DbaDacProfile.ps1 | `public/New-DbaDacProfile.ps1` | XMLテンプレート関数（行143-158） |

**読解のコツ**: Get-Template内部関数でXML構造が定義されている点に注目。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaDacProfile.ps1 | `public/New-DbaDacProfile.ps1` | パラメータ定義（行106-117） |

**主要処理フロー**:
1. **行118-121**: beginブロックでパラメータ検証
2. **行123-129**: パス検証
3. **行131-141**: Convert-HashtableToXMLString関数定義
4. **行160-172**: Get-ServerName関数定義
5. **行174-186**: SqlInstance接続処理
6. **行188-214**: プロファイル生成ループ

#### Step 3: 接続文字列処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaDacProfile.ps1 | `public/New-DbaDacProfile.ps1` | 接続文字列の正規化（行184） |

**主要処理フロー**:
- **行184**: Application Nameなどの属性を除去
- **行160-172**: Get-ServerNameで接続文字列からサーバー名を抽出

#### Step 4: ファイル出力を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | New-DbaDacProfile.ps1 | `public/New-DbaDacProfile.ps1` | ファイル出力（行194-214） |

**主要処理フロー**:
- **行195**: DbaInstanceオブジェクト作成
- **行196**: ファイルパス構築
- **行198**: XMLテンプレートのファイル出力
- **行199-207**: 結果オブジェクト作成

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

```
New-DbaDacProfile
    |
    +-- begin{}
    |      +-- パラメータ検証 (SqlInstance or ConnectionString)
    |      +-- パス検証 (Test-Path)
    |      +-- 内部関数定義
    |             +-- Convert-HashtableToXMLString
    |             +-- Get-Template
    |             +-- Get-ServerName
    |
    +-- process{}
           +-- SqlInstance処理
           |      +-- Connect-DbaInstance
           |      +-- 接続文字列取得・正規化
           |
           +-- foreach ConnectionString
                  +-- foreach Database
                         +-- Get-Template (XML生成)
                         +-- Get-ServerName
                         +-- ファイルパス構築
                         +-- Out-File (XML出力)
                         +-- PSCustomObject作成
```

### データフロー図

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

SqlInstance ------> Connect-DbaInstance ---+
                                           |
                   接続文字列正規化 <------+
                           |
ConnectionString --------->+
                           |
                           v
Database ---------> Get-Template() ----> XML生成
                           |
PublishOptions ----> Convert-HashtableToXMLString
                           |
                           v
Path -----------> ファイル出力 ----> PSCustomObject
                   (instancename-database-publish.xml)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaDacProfile.ps1 | `public/New-DbaDacProfile.ps1` | ソース | メインコマンド実装 |
| Publish-DbaDacPackage.ps1 | `public/Publish-DbaDacPackage.ps1` | ソース | プロファイルの利用先 |
| New-DbaDacOption.ps1 | `public/New-DbaDacOption.ps1` | ソース | オプション作成（関連） |
