# 機能設計書 240-Test-DbaConnection

## 概要

本ドキュメントは、dbatools PowerShellモジュールのTest-DbaConnection関数に関する機能設計書です。この関数はSQL Server接続性を検証し、包括的な接続診断情報を収集します。

### 本機能の処理概要

**業務上の目的・背景**：SQL Server管理作業や自動化スクリプトの実行前に、対象インスタンスへの接続が可能であることを確認する必要があります。本機能は、SQL接続テストだけでなく、認証情報、ネットワーク構成、TCPポート、ローカルPowerShell環境データなどの詳細な診断情報を収集し、接続問題のトラブルシューティングを支援します。

**機能の利用シーン**：自動化スクリプト実行前の接続検証時、複数インスタンスへのアクセス検証時、接続問題のトラブルシューティング時、環境診断レポート作成時に使用されます。

**主要な処理内容**：
1. ローカル環境情報の収集（OS、PowerShell、CLR、SMOバージョン等）
2. 対象サーバーの名前解決（Resolve-DbaNetworkName）
3. PSRemotingテスト（オプション）
4. Pingテスト
5. SQL Server接続テスト
6. 認証方式・スキームの取得
7. TCPポート情報の取得
8. 診断結果のオブジェクト出力

**関連システム・外部連携**：SQL Server Management Objects (SMO)、PowerShell Remoting、ICMP Ping、Get-DbaTcpPort、Test-DbaConnectionAuthScheme、Resolve-DbaNetworkNameを使用します。

**権限による制御**：SQL Serverへの接続権限が必要です。TCPポート取得やPSRemotingには追加の権限が必要な場合があります。

## 関連画面

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

## 機能種別

接続テスト・診断処理（Connection Test / Diagnostic）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | パイプライン入力対応 |
| Credential | PSCredential | No | OS認証用資格情報（PSRemoting/TCPポート取得用） | - |
| SqlCredential | PSCredential | No | SQL Server認証用資格情報 | - |
| SkipPSRemoting | switch | No | PSRemotingテストをスキップ | - |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- PowerShellコマンドライン引数

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | インスタンス名（デフォルトはMSSQLSERVER） |
| SqlInstance | string | SMOインスタンス名 |
| SqlVersion | string | SQL Serverバージョン番号 |
| ConnectingAsUser | string | 接続に使用したログイン名 |
| ConnectSuccess | bool | SQL接続成功フラグ |
| AuthType | string | 認証タイプ（Windows/SQL Authentication） |
| AuthScheme | string | 認証スキーム（KERBEROS/NTLM/SQL等） |
| TcpPort | int/ErrorRecord | TCPポート番号またはエラー |
| IPAddress | string | サーバーのIPアドレス |
| NetBiosName | string | サーバーのFQDN |
| IsPingable | bool | Ping応答フラグ |
| PSRemotingAccessible | bool/ErrorRecord | PSRemoting接続可否またはエラー |
| DomainName | string | Active Directoryドメイン名 |
| LocalWindows | string | ローカルOSバージョン |
| LocalPowerShell | string | ローカルPowerShellバージョン |
| LocalCLR | string | ローカルCLRバージョン |
| LocalSMOVersion | string | ローカルSMOバージョン |
| LocalDomainUser | bool | ドメインユーザーで実行中か |
| LocalRunAsAdmin | bool | 管理者権限で実行中か |
| LocalEdition | string | PowerShellエディション |

### 出力先

- パイプラインにPSCustomObjectとして出力

## 処理フロー

### 処理シーケンス

```
1. 各インスタンスの処理
   ├─ ローカル環境情報収集
   │   └─ OS、PowerShell、CLR、SMO、実行コンテキスト
   ├─ ネットワーク名解決
   │   └─ Resolve-DbaNetworkName
   ├─ PSRemotingテスト（オプション）
   │   └─ Invoke-Command2
   ├─ Pingテスト
   │   └─ System.Net.NetworkInformation.Ping
   ├─ SQL Server接続テスト
   │   └─ Connect-DbaInstance
   ├─ 追加情報取得（接続成功時）
   │   ├─ 認証タイプ判定
   │   ├─ TCPポート取得
   │   └─ 認証スキーム取得
   └─ 結果オブジェクト生成
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[各インスタンスをループ]
    B --> C[ローカル環境情報収集]
    C --> D[ネットワーク名解決]
    D --> E{解決成功?}
    E -->|No| F[エラー・次へ]
    E -->|Yes| G{SkipPSRemoting?}
    G -->|Yes| H[PSRemotingスキップ]
    G -->|No| I[PSRemotingテスト]
    H --> J[Pingテスト]
    I --> J
    J --> K[SQL Server接続テスト]
    K --> L{接続成功?}
    L -->|No| M[ConnectSuccess=false]
    L -->|Yes| N[認証タイプ判定]
    N --> O[TCPポート取得]
    O --> P[認証スキーム取得]
    P --> Q[結果オブジェクト生成]
    M --> Q
    Q --> R{次のインスタンス?}
    R -->|Yes| B
    R -->|No| S[終了]
    F --> R
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | Windows認証判定 | ログイン名に\が含まれる場合Windows認証 | 接続成功時 |
| BR-002 | Pingタイムアウト | Pingのタイムアウトは1000ms | 常時 |
| BR-003 | PSRemotingスキップ | SkipPSRemoting指定時はテストを省略 | SkipPSRemoting時 |
| BR-004 | 接続失敗時 | SQL接続失敗でもその他の情報は収集 | 接続失敗時 |

### 計算ロジック

- LocalDomainUser = ($env:computername -ne $env:USERDOMAIN)
- LocalRunAsAdmin = WindowsPrincipal.IsInRole(Administrator)

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 認証スキーム取得 | sys.dm_exec_connections | SELECT | Test-DbaConnectionAuthScheme経由 |
| TCPポート取得 | sys.dm_tcp_listener_states | SELECT | Get-DbaTcpPort経由 |

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

読み取り専用でデータ変更はありません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Server接続失敗 | インスタンス名・認証情報確認 |
| NetworkError | ネットワークエラー | 名前解決失敗 | サーバー名・ネットワーク確認 |
| PSRemotingError | Remoting エラー | PSRemoting失敗 | WinRM設定・ファイアウォール確認 |

### リトライ仕様

リトライ処理は実装されていません。エラー発生時は該当フィールドにエラー情報を格納して処理を継続します。

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

読み取り専用のため、トランザクション管理は不要です。

## パフォーマンス要件

- 各インスタンスは順次処理
- ネットワーク遅延がテスト時間に影響
- Pingタイムアウトは1000ms

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

- SqlCredential/Credential使用時はSecureStringで資格情報を保護
- PSRemoting権限が必要な場合あり
- 管理者権限の検出はローカル環境情報として収集

## 備考

- 複数インスタンスの一括テストが可能（パイプライン対応）
- 接続失敗時も可能な限り診断情報を収集

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Test-DbaConnection.ps1 | `public/Test-DbaConnection.ps1` | パラメータ定義（129-136行目） |
| 1-2 | Test-DbaConnection.ps1 | `public/Test-DbaConnection.ps1` | 出力オブジェクト構造（234-256行目） |

**読解のコツ**: 出力オブジェクトには多くのプロパティがあり、それぞれ異なるソースから収集されます。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaConnection.ps1 | `public/Test-DbaConnection.ps1` | process block（137-257行目） |

**主要処理フロー**:
1. **140-143行目**: ループ変数クリア
2. **145-154行目**: ローカル環境情報収集
3. **156-172行目**: ネットワーク名解決（Resolve-DbaNetworkName）
4. **174-186行目**: PSRemotingテスト（Invoke-Command2）
5. **188-198行目**: Pingテスト（System.Net.NetworkInformation.Ping）
6. **200-232行目**: SQL接続テストと追加情報取得
7. **234-256行目**: 結果オブジェクト生成

#### Step 3: ローカル情報収集を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Test-DbaConnection.ps1 | `public/Test-DbaConnection.ps1` | ローカル情報収集（146-154行目） |

**主要処理フロー**:
- **147行目**: Windowsバージョン取得
- **148行目**: PowerShellエディション取得
- **149行目**: PowerShellバージョン取得
- **150行目**: CLRバージョン取得
- **151行目**: SMOバージョン取得
- **152行目**: ドメインユーザー判定
- **153行目**: 管理者権限判定

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

```
Test-DbaConnection
    │
    ├─ Resolve-DbaNetworkName
    │      └─ 名前解決・DNS情報取得
    │
    ├─ Invoke-Command2 (PSRemoting テスト)
    │      └─ Get-ChildItem (リモート実行)
    │
    ├─ System.Net.NetworkInformation.Ping
    │      └─ ICMP Ping テスト
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server 接続
    │
    ├─ Get-DbaTcpPort
    │      └─ TCP ポート取得
    │
    └─ Test-DbaConnectionAuthScheme
           └─ 認証スキーム取得
```

### データフロー図

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

SqlInstance ──────┐
                  │
Credential ───────┼──▶ Test-DbaConnection ─────────────────▶ PSCustomObject
                  │         │                                 (20+ properties)
SqlCredential ────┤         ├─ Resolve-DbaNetworkName
                  │         ├─ Invoke-Command2 (PSRemoting)
SkipPSRemoting ───┘         ├─ Ping.Send
                            ├─ Connect-DbaInstance
                            ├─ Get-DbaTcpPort
                            └─ Test-DbaConnectionAuthScheme

[ローカル環境]                              [リモートSQL Server]
(OS, PS, CLR, SMO) ───▶ 情報収集 ◄─── 接続情報
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Test-DbaConnection.ps1 | `public/Test-DbaConnection.ps1` | ソース | メイン関数実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続ヘルパー |
| Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | ソース | 名前解決ヘルパー |
| Get-DbaTcpPort.ps1 | `public/Get-DbaTcpPort.ps1` | ソース | TCPポート取得 |
| Test-DbaConnectionAuthScheme.ps1 | `public/Test-DbaConnectionAuthScheme.ps1` | ソース | 認証スキーム取得 |
| Invoke-Command2.ps1 | `private/functions/Invoke-Command2.ps1` | ソース | リモート実行ヘルパー |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラー処理ヘルパー |
| Test-DbaConnection.Tests.ps1 | `tests/Test-DbaConnection.Tests.ps1` | テスト | 単体テスト |
