# 機能設計書 186-New-DbaConnectionString

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `New-DbaConnectionString` コマンドレットの機能設計書である。このコマンドレットは、PowerShellフレンドリーなパラメータを使用してSQL Server接続文字列を作成する機能を提供する。

### 本機能の処理概要

本機能は、複雑な接続文字列構文を手動で構築する代わりに、馴染みやすいPowerShellパラメータ（-SqlInstance、-Database等）を使用して適切にフォーマットされたSQL Server接続文字列を作成する。Windows認証、SQL Server認証、Azure AD認証、暗号化設定、タイムアウト値、Azure SQL Database固有の設定など、さまざまな認証方法と接続オプションをサポートする。

**業務上の目的・背景**：アプリケーション開発、自動化スクリプト作成、またはSQL Server接続文字列を必要とする外部ツールの設定において、「Data Source」や「Initial Catalog」のような曖昧なキーワードを記憶する必要なく、簡単に接続文字列を生成できる。従来のSystem.Data.SqlClientと最新のMicrosoft.Data.SqlClientプロバイダの両方をサポート。

**機能の利用シーン**：
- カスタムアプリケーション用の接続文字列生成
- 自動化スクリプトでの接続設定
- 外部ツール（ETLツール、監視ツール等）への接続文字列提供
- Azure SQL Database接続用の特別な設定
- 既存SMOサーバーオブジェクトからの接続文字列抽出

**主要な処理内容**：
1. 入力パラメータの検証と処理
2. Azure SQL Databaseの検出と特別処理
3. 認証方法（Windows/SQL/Azure AD）の判定
4. SqlConnectionStringBuilderによる接続文字列構築
5. 各種接続オプションの設定
6. 接続文字列の出力

**関連システム・外部連携**：SQL Server、Azure SQL Database、Microsoft.Data.SqlClient、System.Data.SqlClient

**権限による制御**：接続先SQL Serverへの接続権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 260 | 接続文字列 | 主機能 | 接続文字列の作成 |

## 機能種別

接続管理 / 構成生成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | SQL Serverインスタンス | 必須、パイプラインから入力可能 |
| Credential | PSCredential | No | 代替認証資格情報 | Alias: SqlCredential |
| AccessToken | string | No | Azure ADアクセストークン認証を使用 | - |
| ApplicationIntent | string | No | アプリケーションワークロード（ReadOnly/ReadWrite） | ValidateSet |
| BatchSeparator | string | No | SQLコマンドのバッチ区切り | デフォルトはGO |
| ClientName | string | No | アプリケーション名 | デフォルトは「custom connection」 |
| ConnectTimeout | int | No | 接続タイムアウト（秒） | Azure時は30秒がデフォルト |
| Database | string | No | 初期データベース | Azure SQL Databaseでは必須 |
| EncryptConnection | switch | No | SSL/TLS暗号化を強制 | dbatools設定から取得 |
| FailoverPartner | string | No | データベースミラーリングのフェイルオーバーパートナー | 128文字以下 |
| IsActiveDirectoryUniversalAuth | switch | No | Azure AD MFA認証を有効化 | - |
| LockTimeout | int | No | ロックタイムアウト（非サポート、警告） | - |
| MaxPoolSize | int | No | 最大接続プールサイズ | デフォルト100 |
| MinPoolSize | int | No | 最小接続プールサイズ | デフォルト0 |
| MultipleActiveResultSets | switch | No | MARSを有効化 | - |
| MultiSubnetFailover | switch | No | マルチサブネットフェイルオーバー | - |
| NetworkProtocol | string | No | ネットワークプロトコル | ValidateSet |
| NonPooledConnection | switch | No | 接続プールを無効化 | - |
| PacketSize | int | No | ネットワークパケットサイズ（バイト） | 512-32767 |
| PooledConnectionLifetime | int | No | プール接続の最大有効期間（秒） | - |
| SqlExecutionModes | string | No | SQL実行モード（非サポート、警告） | - |
| StatementTimeout | int | No | ステートメントタイムアウト（非サポート、警告） | - |
| TrustServerCertificate | switch | No | サーバー証明書検証をスキップ | dbatools設定から取得 |
| WorkstationId | string | No | ワークステーション識別子 | - |
| Legacy | switch | No | System.Data.SqlClientを使用 | - |
| AppendConnectionString | string | No | 追加の接続文字列パラメータ | - |

### 入力データソース

- ユーザー入力（パラメータ指定）
- パイプライン入力（SMOサーバーオブジェクト）
- dbatools構成設定（暗号化、証明書信頼等）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ConnectionString | string | 生成されたSQL Server接続文字列 |

### 出力先

PowerShellパイプライン（文字列）

## 処理フロー

### 処理シーケンス

```
1. パラメータのデフォルト値設定
   └─ dbatools設定からデフォルト取得
2. 各SqlInstanceを処理
3. コードパス判定
   └─ sql.connection.legacyフラグによる分岐
4. [新コードパス] SqlConnectionStringBuilder使用
   └─ SMOサーバーオブジェクト処理
   └─ 新規接続文字列構築
5. Azure SQL検出
   └─ database.windows.netドメイン判定
6. 認証方法設定
   └─ Windows認証 / SQL認証 / Azure AD認証
7. 各種接続オプション設定
8. 追加接続文字列の結合
9. 接続文字列の出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Legacy設定?}
    B -->|No| C[新コードパス]
    B -->|Yes| D[レガシーコードパス]
    C --> E{SMOサーバーオブジェクト?}
    E -->|Yes| F[既存接続文字列を取得]
    E -->|No| G[SqlConnectionStringBuilder作成]
    F --> H[オプション適用]
    G --> I{Azure SQL?}
    I -->|Yes| J[Azure固有設定]
    I -->|No| K[オンプレミス設定]
    J --> L[認証方法設定]
    K --> L
    L --> M{Credential指定?}
    M -->|Yes| N[SQL/Azure AD認証]
    M -->|No| O[Windows/AD統合認証]
    N --> P[各種オプション設定]
    O --> P
    P --> Q{AppendConnectionString?}
    Q -->|Yes| R[追加パラメータ結合]
    Q -->|No| S[接続文字列出力]
    R --> S
    H --> S
    D --> T[SMO ServerConnection使用]
    T --> S
    S --> U[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | Azure自動検出 | database.windows.netドメインを検出してAzure設定を適用 | 常時 |
| BR-002 | Azure暗号化必須 | Azure SQL Database接続では暗号化を自動有効化 | Azure検出時 |
| BR-003 | Azureタイムアウト | Azure接続のデフォルトタイムアウトは30秒 | Azure検出時 |
| BR-004 | 非サポートパラメータ警告 | LockTimeout, StatementTimeout, SqlExecutionModesは警告を出力 | パラメータ指定時 |
| BR-005 | プロバイダ選択 | LegacyスイッチでSystem.Data.SqlClient、それ以外はMicrosoft.Data.SqlClient | 常時 |

### 計算ロジック

| 条件 | 認証方法 |
|------|---------|
| Credential + username@domain + Azure | Active Directory Password |
| Credential + username\domain | Windows ConnectAsUser |
| Credential + username（バックスラッシュなし） | SQL Server認証 |
| Azure + Credentialなし | Active Directory Integrated |
| オンプレミス + Credentialなし | Windows統合認証（Integrated Security） |

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

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

本機能は接続文字列の生成のみを行い、直接的なデータベース操作は行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 警告 | LockTimeout指定 | パラメータは接続文字列の一部ではない |
| - | 警告 | StatementTimeout指定 | SqlCommandのCommandTimeoutを使用 |
| - | 警告 | SqlExecutionModes指定 | パラメータは接続文字列の一部ではない |

### リトライ仕様

リトライ処理は実装されていない。

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

トランザクション管理なし（接続文字列生成のみ）

## パフォーマンス要件

接続文字列の生成は即座に完了

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

- 資格情報はPSCredentialで安全に管理
- 接続文字列にパスワードが含まれる場合、ログへの出力に注意
- TrustServerCertificateは開発環境でのみ使用推奨

## 備考

- 生成された接続文字列はSqlClient、ADO.NET、その他の接続文字列を受け入れるツールで使用可能
- Connect-DbaInstanceで接続したSMOオブジェクトからも接続文字列を抽出可能
- localdbインスタンスでは暗号化キーワードはスキップ

---

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

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

### 推奨読解順序

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

パラメータ定義を理解する（多数のパラメータあり）。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | New-DbaConnectionString.ps1 | `public/New-DbaConnectionString.ps1` | 206-240行目のparamブロック |

**読解のコツ**: EncryptConnectionとTrustServerCertificateはGet-DbatoolsConfigValueでデフォルト設定から取得。Aliasが設定されているパラメータ（SqlCredential→Credential）に注意。

#### Step 2: Azure判定関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaConnectionString.ps1 | `public/New-DbaConnectionString.ps1` | 242-253行目のTest-Azure関数 |

**主要処理フロー**:
- **246行目**: $AzureDomainパターン（database.windows.net）との照合

#### Step 3: 新コードパスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaConnectionString.ps1 | `public/New-DbaConnectionString.ps1` | 263-401行目の新コードパス |

**主要処理フロー**:
- **269-282行目**: 非サポートパラメータの警告
- **284-306行目**: デフォルト値設定（dbatools設定から取得）
- **313-325行目**: SMOサーバーオブジェクト処理
- **327-378行目**: SqlConnectionStringBuilderでの接続文字列構築
- **355-378行目**: 認証方法の判定と設定
- **380-388行目**: Azure固有設定

#### Step 4: レガシーコードパスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | New-DbaConnectionString.ps1 | `public/New-DbaConnectionString.ps1` | 409-519行目のレガシーコードパス |

**主要処理フロー**:
- **412-440行目**: Azure SQL検出と前処理
- **446-472行目**: SMO ServerConnectionを使用した設定
- **473-510行目**: Azure認証の特別処理

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

```
New-DbaConnectionString
    │
    ├─ Get-DbatoolsConfigValue
    │      └─ デフォルト設定の取得
    │
    ├─ Test-Azure (内部関数)
    │      └─ Azureドメイン判定
    │
    ├─ [新コードパス]
    │      ├─ Microsoft.Data.SqlClient.SqlConnectionStringBuilder
    │      │      または
    │      └─ System.Data.SqlClient.SqlConnectionStringBuilder
    │
    └─ [レガシーコードパス]
           └─ Microsoft.SqlServer.Management.Smo.Server
                  └─ ConnectionContext
```

### データフロー図

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

SqlInstance ─────────▶ インスタンス検証
                              │
                              ▼
                       Test-Azure
                              │
                       ┌──────┴──────┐
                       ▼             ▼
                    Azure         オンプレ
                       │             │
                       ▼             ▼
Credential ──────────▶ 認証設定
Database ────────────▶ SqlConnectionStringBuilder
EncryptConnection ────▶    │
ConnectTimeout ───────▶    │
その他オプション ─────▶    │
                              │
                              ▼
AppendConnectionString ▶ 結合
                              │
                              ▼
                       接続文字列 ──────────────────▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaConnectionString.ps1 | `public/New-DbaConnectionString.ps1` | ソース | メイン機能の実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SMO接続（パイプライン入力元） |
