# 画面設計書 91-接続テスト

## 概要

本ドキュメントはdbatools PowerShellモジュールにおける接続テスト機能（Test-DbaConnection、Test-DbaConnectionAuthScheme）の画面設計書です。

### 本画面の処理概要

**業務上の目的・背景**：
SQL Server環境の管理において、インスタンスへの接続性の確認は最も基本的かつ重要な作業です。本機能は、SQL Serverインスタンスへの接続テストを実行し、接続の成否、認証スキーム（Kerberos/NTLM）、ネットワーク設定、ローカル環境情報などの包括的な診断情報を取得します。これにより、接続問題のトラブルシューティング、自動化スクリプト実行前の事前検証、複数インスタンスへのアクセス検証を効率的に行うことができます。特にKerberos認証の問題診断やSPN設定の検証に有用です。

**画面へのアクセス方法**：
PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスします。
- `Test-DbaConnection -SqlInstance <インスタンス名>`
- `Test-DbaConnectionAuthScheme -SqlInstance <インスタンス名>`

**主要な操作・処理内容**：
1. SQL Serverインスタンスへの接続テストを実行し、接続成功/失敗を判定
2. 認証タイプ（Windows認証/SQL認証）と認証スキーム（Kerberos/NTLM）の取得
3. TCPポート番号の検出とネットワーク情報（IPアドレス、DNS名）の収集
4. Pingテストによる基本的なネットワーク到達性の確認
5. PSRemotingアクセス可否のテスト（オプションでスキップ可能）
6. ローカル環境情報（PowerShellバージョン、CLR、SMOバージョン等）の収集

**画面遷移**：
本機能は他の画面への遷移元として機能することが多い。接続テスト成功後、Get-DbaDatabase、Get-DbaLogin等の他のdbatools機能へと遷移して本格的な管理作業を行う。Connect-DbaInstance画面から呼び出されることも多い。

**権限による表示制御**：
- SQL Server接続には対象インスタンスへの適切なログイン権限が必要
- PSRemotingテストにはリモートコンピュータへの管理者権限が必要
- TCPポート検出にはCredentialパラメータでの資格情報指定が推奨される

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 240 | Test-DbaConnection | 主機能 | 接続テストの実行 |
| 241 | Test-DbaConnectionAuthScheme | 補助機能 | 認証スキームのテスト |
| 327 | Connect-DbaInstance | 遷移先機能 | SQLインスタンスへの接続 |
| 369 | Get-DbaTcpPort | API連携 | TCPポート情報の取得 |

## 画面種別

CLI（コマンドラインインターフェース）/ 診断

## URL/ルーティング

PowerShellコマンド:
- `Test-DbaConnection`
- `Test-DbaConnectionAuthScheme`

## 入出力項目

### Test-DbaConnection

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | いいえ | テスト対象のSQL Serverインスタンス |
| Credential | PSCredential | いいえ | コンピュータレベルアクセス用のWindows資格情報 |
| SqlCredential | PSCredential | いいえ | SQL Server接続用の代替資格情報 |
| SkipPSRemoting | switch | いいえ | PSRemotingテストをスキップ |
| EnableException | switch | いいえ | 例外を有効化 |

### Test-DbaConnectionAuthScheme

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | はい | テスト対象のSQL Serverインスタンス |
| SqlCredential | PSCredential | いいえ | SQL Server接続用の代替資格情報 |
| Kerberos | switch | いいえ | Kerberos認証かどうかをTrue/Falseで返す |
| Ntlm | switch | いいえ | NTLM認証かどうかをTrue/Falseで返す |
| EnableException | switch | いいえ | 例外を有効化 |

## 表示項目

### Test-DbaConnection 出力

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

### Test-DbaConnectionAuthScheme 出力（デフォルト）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | サーバー名 |
| Transport | string | ネットワークトランスポートタイプ |
| AuthScheme | string | 認証スキーム |

## イベント仕様

### 1-接続テスト実行

1. 入力パラメータの検証
2. ローカル環境情報（Windows/PowerShell/CLR/SMOバージョン）の収集
3. Resolve-DbaNetworkNameでネットワーク名解決を実行
4. PSRemotingテスト実行（SkipPSRemoting未指定時）
5. Pingテストの実行
6. Connect-DbaInstanceでSQL Server接続
7. 認証タイプの判定（ユーザー名に\が含まれるか）
8. Get-DbaTcpPortでTCPポート取得
9. Test-DbaConnectionAuthSchemeで認証スキーム取得
10. 結果オブジェクトの生成と出力

### 2-認証スキームテスト実行

1. Connect-DbaInstanceでSQL Server接続（MinimumVersion 9）
2. sys.dm_exec_connectionsからセッション情報をクエリ
3. -Kerberosまたは-Ntlmスイッチに応じて結果をフィルタリング
4. 結果オブジェクトの生成と出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 認証スキーム取得 | sys.dm_exec_connections | SELECT | 現在のセッション接続情報を取得 |

### テーブル別更新項目詳細

#### sys.dm_exec_connections

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | session_id | @@SPID | 現在のセッションID |
| SELECT | auth_scheme | - | 認証スキーム（KERBEROS/NTLM） |
| SELECT | net_transport | - | ネットワークトランスポート |
| SELECT | encrypt_option | - | 暗号化オプション |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 |
|-------------|------|---------------|
| MSG001 | 情報 | Getting local environment information |
| MSG002 | 情報 | Checking remote access |
| MSG003 | 情報 | Checking remote access will be skipped |
| MSG004 | 情報 | Testing ping to {ComputerName} |
| MSG005 | エラー | Unable to resolve server information |
| MSG006 | エラー | Failure (ConnectionError) |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| ネットワーク名解決失敗 | Stop-Functionでエラー出力し、処理を継続 |
| SQL Server接続失敗 | connectSuccessをfalseに設定し、エラー出力 |
| TCPポート取得失敗 | エラー情報をtcpportプロパティに格納 |
| 認証スキーム取得失敗 | エラー情報をauthschemeプロパティに格納 |
| PSRemotingアクセス失敗 | エラー情報をremotingプロパティに格納 |

## 備考

- SQL Server 2005以降が必要（Test-DbaConnectionAuthSchemeはMinimumVersion 9を指定）
- Kerberos認証の確認はSPN設定の検証に重要
- PSRemotingテストはICMPやWinRM設定の影響を受ける

---

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

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

### 推奨読解順序

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

出力されるPSCustomObjectの構造と、sys.dm_exec_connectionsから取得するデータを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Test-DbaConnection.ps1 | `public/Test-DbaConnection.ps1` | 234-256行目の出力オブジェクト構造を確認 |
| 1-2 | Test-DbaConnectionAuthScheme.ps1 | `public/Test-DbaConnectionAuthScheme.ps1` | 119-129行目のSQLクエリを確認 |

**読解のコツ**: PSCustomObjectのプロパティ定義から、どのような情報が収集されるかを把握する。

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

各コマンドのパラメータバインディングと処理開始点を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaConnection.ps1 | `public/Test-DbaConnection.ps1` | 129-136行目のparamブロックでパラメータを確認 |
| 2-2 | Test-DbaConnectionAuthScheme.ps1 | `public/Test-DbaConnectionAuthScheme.ps1` | 107-116行目のparamブロックでパラメータを確認 |

**主要処理フロー**:
1. **137行目**: processブロック開始、foreachでSqlInstanceをループ
2. **146-154行目**: ローカル環境情報の収集
3. **169行目**: Resolve-DbaNetworkNameでネットワーク名解決
4. **190-198行目**: Pingテストの実行
5. **200-232行目**: SQL Server接続と情報収集

#### Step 3: ネットワーク名解決を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | DNS解決とFQDN取得のロジック |

**主要処理フロー**:
- **169行目**: Resolve-DbaNetworkName呼び出し
- ComputerName、IPAddress、DNSHostName、Domain等を返す

#### Step 4: SQL Server接続を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | SQL Server接続の基本ロジック |

**主要処理フロー**:
- **201行目**: Connect-DbaInstance呼び出し
- SMOオブジェクトを通じてSQL Serverに接続

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

```
Test-DbaConnection
    │
    ├─ Resolve-DbaNetworkName
    │      └─ DNS/NetBIOS解決
    │
    ├─ Invoke-Command2 (PSRemotingテスト)
    │
    ├─ System.Net.NetworkInformation.Ping
    │
    ├─ Connect-DbaInstance
    │      └─ SMO接続確立
    │
    ├─ Get-DbaTcpPort
    │      └─ TCPポート取得
    │
    └─ Test-DbaConnectionAuthScheme
           └─ sys.dm_exec_connections クエリ

Test-DbaConnectionAuthScheme
    │
    └─ Connect-DbaInstance (MinimumVersion 9)
           └─ $server.Query(SQL)
```

### データフロー図

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

SqlInstance ───────▶ Resolve-DbaNetworkName ──▶ ComputerName, IPAddress
                            │
                     ┌──────▼──────┐
                     │  Pingテスト  │──────────▶ IsPingable
                     └─────────────┘
                            │
                     ┌──────▼──────┐
                     │ PSRemoting  │──────────▶ PSRemotingAccessible
                     └─────────────┘
                            │
                     ┌──────▼──────┐
                     │ SQL接続     │──────────▶ ConnectSuccess, AuthType
                     └─────────────┘
                            │
           ┌────────────────┼────────────────┐
           ▼                ▼                ▼
    Get-DbaTcpPort  Test-DbaConnection   $server.Version
           │           AuthScheme             │
           ▼                │                ▼
       TcpPort         AuthScheme        SqlVersion

                      ▼ 最終出力 ▼
              [PSCustomObject出力]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Test-DbaConnection.ps1 | `public/Test-DbaConnection.ps1` | ソース | メイン接続テスト機能 |
| Test-DbaConnectionAuthScheme.ps1 | `public/Test-DbaConnectionAuthScheme.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ポート取得 |
