# 画面設計書 260-接続文字列

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `New-DbaConnectionString` および `New-DbaConnectionStringBuilder` コマンドに関する画面設計書です。これらのコマンドは、SQL Serverへの接続文字列を生成および操作するためのユーティリティを提供します。

### 本画面の処理概要

**業務上の目的・背景**：SQL Server接続文字列は複雑で、手動での構築は誤りを招きやすいです。これらのコマンドは、PowerShellのパラメーター形式で必要な接続オプションを指定し、正しい形式の接続文字列を生成します。Windows認証、SQL Server認証、Azure Active Directory認証など様々な認証方式をサポートし、暗号化設定、接続プール、タイムアウトなどの詳細設定も対応します。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから `New-DbaConnectionString` または `New-DbaConnectionStringBuilder` コマンドを実行します。

**主要な操作・処理内容**：
1. パラメーターから接続文字列を構築
2. SMOサーバーオブジェクトから接続文字列を抽出
3. 既存の接続文字列を解析・修正
4. Azure SQL Database向けの設定を自動適用

**画面遷移**：CLIコマンドのため画面遷移はありません。出力された接続文字列は他のアプリケーションやツールで使用できます。

**権限による表示制御**：特に権限は不要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 181 | New-DbaConnectionString | 主機能 | 接続文字列の生成 |
| 182 | New-DbaConnectionStringBuilder | 主機能 | 接続文字列ビルダーの生成 |
| 90 | Connect-DbaInstance | 連携機能 | 接続文字列の抽出元 |

## 画面種別

ユーティリティ・接続文字列生成（CLIコマンド）

## URL/ルーティング

該当なし（PowerShell CLIコマンド）

## 入出力項目

### New-DbaConnectionString 入力パラメーター

| パラメーター名 | 型 | 必須 | 説明 |
|---------------|---|-----|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 接続先SQL Serverインスタンス |
| Credential | PSCredential | No | 認証資格情報 |
| AccessToken | string | No | Azure ADアクセストークン |
| ApplicationIntent | string | No | 接続意図（ReadOnly, ReadWrite） |
| BatchSeparator | string | No | バッチ区切り文字（デフォルト: GO） |
| ClientName | string | No | アプリケーション名（デフォルト: custom connection） |
| ConnectTimeout | int | No | 接続タイムアウト秒数 |
| Database | string | No | 初期データベース |
| EncryptConnection | switch | No | 接続暗号化 |
| FailoverPartner | string | No | フェールオーバーパートナー |
| IsActiveDirectoryUniversalAuth | switch | No | Azure AD MFA認証 |
| LockTimeout | int | No | ロックタイムアウト（未サポート） |
| MaxPoolSize | int | No | 接続プール最大サイズ |
| MinPoolSize | int | No | 接続プール最小サイズ |
| MultipleActiveResultSets | switch | No | MARS有効化 |
| MultiSubnetFailover | switch | No | マルチサブネットフェールオーバー |
| NetworkProtocol | string | No | ネットワークプロトコル |
| NonPooledConnection | switch | No | プーリング無効化 |
| PacketSize | int | No | パケットサイズ |
| PooledConnectionLifetime | int | No | プール接続寿命 |
| SqlExecutionModes | string | No | SQL実行モード（未サポート） |
| StatementTimeout | int | No | ステートメントタイムアウト（未サポート） |
| TrustServerCertificate | switch | No | 証明書検証スキップ |
| WorkstationId | string | No | ワークステーション識別子 |
| Legacy | switch | No | System.Data.SqlClient使用 |
| AppendConnectionString | string | No | 追加接続文字列 |

### New-DbaConnectionStringBuilder 入力パラメーター

| パラメーター名 | 型 | 必須 | 説明 |
|---------------|---|-----|------|
| ConnectionString | string[] | No | 既存接続文字列 |
| ApplicationName | string | No | アプリケーション名（デフォルト: dbatools Powershell Module） |
| DataSource | string | No | SQL Serverインスタンス名 |
| SqlCredential | PSCredential | No | SQL認証資格情報 |
| InitialCatalog | string | No | 初期データベース |
| IntegratedSecurity | switch | No | Windows認証 |
| UserName | string | No | SQLログイン名 |
| Password | string | No | SQLパスワード |
| MultipleActiveResultSets | switch | No | MARS有効化 |
| ColumnEncryptionSetting | string | No | Always Encrypted設定 |
| WorkstationID | string | No | ワークステーション識別子 |
| NonPooledConnection | switch | No | プーリング無効化 |
| Legacy | switch | No | System.Data.SqlClient使用 |
| EnableException | switch | No | 例外を直接スロー |

### New-DbaConnectionString 出力項目

| プロパティ | 型 | 説明 |
|-----------|---|------|
| (文字列) | string | SQL Server接続文字列 |

### New-DbaConnectionStringBuilder 出力項目

Microsoft.Data.SqlClient.SqlConnectionStringBuilder または System.Data.SqlClient.SqlConnectionStringBuilder オブジェクト

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| ApplicationName | string | アプリケーション名 |
| DataSource | string | SQL Serverインスタンス |
| InitialCatalog | string | 初期データベース |
| IntegratedSecurity | bool | Windows認証フラグ |
| UserID | string | SQLログイン名 |
| Password | string | パスワード |
| WorkstationID | string | ワークステーション識別子 |
| MultipleActiveResultSets | bool | MARS有効フラグ |
| ColumnEncryptionSetting | string | Always Encrypted設定 |
| Pooling | bool | プーリング有効フラグ |

## 表示項目

CLIコマンドのため、表示項目は出力オブジェクトのプロパティに依存します。

## イベント仕様

### 1-New-DbaConnectionString実行

1. **新規コードパス（デフォルト）**：
   - sql.connection.legacy設定が$falseの場合に使用
   - 未サポートパラメーター（LockTimeout, StatementTimeout, SqlExecutionModes）の警告表示
   - dbatools設定からデフォルト値を取得
   - SqlConnectionStringBuilderでプロパティを設定
   - Azure接続時は自動で暗号化とタイムアウト設定

2. **レガシーコードパス**：
   - sql.connection.legacy設定が$trueの場合に使用
   - SMO ServerConnectionオブジェクトを使用して構築
   - Azure接続時の認証方式を自動判定

### 2-New-DbaConnectionStringBuilder実行

1. SqlCredentialとUserName/Passwordの排他チェック
2. SqlConnectionStringBuilderオブジェクト作成
3. 各パラメーターに基づいてプロパティ設定
4. ビルダーオブジェクトを返す

### 3-Azure SQL Database自動検出

1. インスタンス名に "database.windows.net" が含まれるか確認
2. 含まれる場合：
   - ConnectTimeoutを30秒に設定
   - Encryptを$trueに設定
   - 資格情報に基づいてAuthenticationを設定

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

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

これらのコマンドはデータベースに接続せず、接続文字列の生成のみを行います。

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|--------------|------|---------------|
| 警告 | LockTimeout指定時 | "Parameter LockTimeout not supported, because it is not part of a connection string." |
| 警告 | StatementTimeout指定時 | "Parameter StatementTimeout not supported, because it is not part of a connection string." |
| 警告 | SqlExecutionModes指定時 | "Parameter SqlExecutionModes not supported, because it is not part of a connection string." |
| エラー | SqlCredentialとUsername両方指定 | "You can only specify SQL Credential or Username/Password, not both." |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| パラメーター競合 | Stop-Functionでメッセージ表示して終了 |
| 接続文字列解析エラー | SqlConnectionStringBuilderが例外をスロー |

## 備考

- Microsoft.Data.SqlClient（新規）とSystem.Data.SqlClient（レガシー）の両方をサポート
- Set-DbatoolsConfig -FullName sql.connection.legacy -Value $true でレガシーモードに切替可能
- Azure SQL Databaseへの接続時は暗号化とタイムアウトが自動設定される
- SMOサーバーオブジェクトをパイプラインで渡すと既存の接続文字列を抽出可能
- AppendConnectionStringで追加パラメーターを接続文字列に付加可能
- 接続プール設定（MaxPoolSize, MinPoolSize, PooledConnectionLifetime）で接続管理を最適化
- ApplicationIntent=ReadOnlyでAlways On可用性グループのセカンダリレプリカに接続可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | New-DbaConnectionString.ps1 | `public/New-DbaConnectionString.ps1` | パラメーター定義（行207-240） |
| 1-2 | New-DbaConnectionStringBuilder.ps1 | `public/New-DbaConnectionStringBuilder.ps1` | パラメーター定義（行109-130） |

**読解のコツ**: SqlConnectionStringBuilderクラスのプロパティ名とPowerShellパラメーターの対応関係を理解することが重要です。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaConnectionString.ps1 | `public/New-DbaConnectionString.ps1` | 関数定義全体（行1-522） |
| 2-2 | New-DbaConnectionStringBuilder.ps1 | `public/New-DbaConnectionStringBuilder.ps1` | 関数定義全体（行1-198） |

**主要処理フロー（New-DbaConnectionString）**:
1. **行241-253**: beginブロックでTest-Azure関数定義
2. **行263-402**: 新規コードパス（sql.connection.legacy=$false）
3. **行269-282**: 未サポートパラメーターの警告
4. **行284-307**: dbatools設定からデフォルト値取得
5. **行313-400**: SqlConnectionStringBuilderでプロパティ設定
6. **行409-519**: レガシーコードパス

**主要処理フロー（New-DbaConnectionStringBuilder）**:
1. **行131-140**: 認証パラメーター検証
2. **行142-147**: SqlConnectionStringBuilder作成
3. **行149-194**: プロパティ設定
4. **行195**: オブジェクト返却

#### Step 3: 認証フローを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaConnectionString.ps1 | `public/New-DbaConnectionString.ps1` | 資格情報処理（行355-378） |
| 3-2 | New-DbaConnectionString.ps1 | `public/New-DbaConnectionString.ps1` | Azure特別設定（行380-388） |

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

```
New-DbaConnectionString
    │
    ├─ Test-Azure (内部関数)
    │      └─ $AzureDomain判定
    │
    ├─ [新規コードパス]
    │      ├─ Test-Bound (各パラメーター検証)
    │      ├─ Get-DbatoolsConfigValue
    │      │      ├─ sql.connection.database
    │      │      ├─ sql.connection.clientname
    │      │      ├─ sql.connection.protocol
    │      │      ├─ sql.connection.packetsize
    │      │      └─ sql.connection.trustcert
    │      │
    │      ├─ [SMOサーバーオブジェクト渡し]
    │      │      ├─ Convert-ConnectionString (Legacy時)
    │      │      └─ New-Object SqlConnectionStringBuilder
    │      │
    │      └─ [インスタンス名渡し]
    │             └─ New-Object SqlConnectionStringBuilder
    │                    └─ プロパティ設定ループ
    │
    └─ [レガシーコードパス]
           └─ New-Object Microsoft.SqlServer.Management.Smo.Server
                  └─ ServerConnection.ConnectionString

New-DbaConnectionStringBuilder
    │
    ├─ Stop-Function (SqlCredential + Username競合時)
    │
    ├─ New-Object SqlConnectionStringBuilder
    │      ├─ Microsoft.Data.SqlClient (デフォルト)
    │      └─ System.Data.SqlClient (Legacy時)
    │
    └─ Test-Bound (各パラメーター検証)
           └─ プロパティ設定
```

### データフロー図

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

SqlInstance ─────────────┐
                         │
Credential ──────────────┼───▶ Test-Azure判定
                         │          │
Database ────────────────┤          ▼
                         │    ┌─────┴─────┐
ConnectTimeout ──────────┤    │  Azure?   │
                         │    └─────┬─────┘
EncryptConnection ───────┤          │
                         │    Yes ──┼── No
                         │          │
                         │    ┌─────┴─────┐
                         │    │ 自動設定  │
                         │    │ Timeout=30│
                         │    │ Encrypt=T │
                         │    │ Auth=AD   │
                         │    └─────┬─────┘
                         │          │
                         ▼          ▼
               SqlConnectionStringBuilder
                         │
                         ▼
                  接続文字列 ─────▶ 他アプリケーション
                                        │
                                        ▼
                                  SQL Server接続
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaConnectionString.ps1 | `public/New-DbaConnectionString.ps1` | ソース | メイン関数（接続文字列生成） |
| New-DbaConnectionStringBuilder.ps1 | `public/New-DbaConnectionStringBuilder.ps1` | ソース | メイン関数（ビルダー生成） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SMOサーバーオブジェクト生成元 |
| Get-DbatoolsConfigValue.ps1 | `public/Get-DbatoolsConfigValue.ps1` | ソース | 設定値取得 |
| Test-Bound.ps1 | `internal/functions/Test-Bound.ps1` | ソース | パラメーターバインド確認 |
| Stop-Function.ps1 | `internal/functions/flowcontrol/Stop-Function.ps1` | ソース | エラーハンドリング |
| Convert-ConnectionString.ps1 | `internal/functions/Convert-ConnectionString.ps1` | ソース | 接続文字列変換（レガシー用） |
