# 機能設計書 239-Test-DbaCmConnection

## 概要

本ドキュメントは、dbatools PowerShellモジュールのTest-DbaCmConnection関数に関する機能設計書です。この関数はリモートコンピュータ管理の接続性を複数のプロトコルでテストし、最適な接続方法をキャッシュします。

### 本機能の処理概要

**業務上の目的・背景**：SQL Server管理作業ではリモートコンピュータへの接続が頻繁に必要になります。しかし、環境によって使用可能なプロトコル（CIM、WMI、PowerShell Remoting等）が異なります。本機能は複数のプロトコルをテストし、最も信頼性の高い接続方法を特定してキャッシュすることで、後続の管理コマンドの実行を最適化します。

**機能の利用シーン**：リモートサーバーへの初回接続前の接続性確認時、接続問題のトラブルシューティング時、環境内でどのプロトコルが利用可能か確認する場合、他のdbatoolsコマンド（Get-DbaCmObject、Invoke-DbaCmMethod等）の前処理として使用されます。

**主要な処理内容**：
1. 対象コンピュータへの接続オブジェクト取得/作成
2. 資格情報の検証（不正資格情報キャッシュの処理）
3. 以下のプロトコルをテスト：
   - CIM over WinRM
   - CIM over DCOM
   - WMI
   - PowerShell Remoting
4. 結果をキャッシュに保存

**関連システム・外部連携**：CIM (Common Information Model)、WMI (Windows Management Instrumentation)、PowerShell Remotingを使用します。

**権限による制御**：対象コンピュータへの管理者権限が必要です。プロトコルによって必要な権限レベルが異なります。

## 関連画面

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

## 機能種別

接続テスト処理（Connectivity Test / Diagnostic）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | DbaCmConnectionParameter[] | No | テスト対象のコンピュータ名（デフォルト：ローカル） | パイプライン入力対応 |
| Credential | PSCredential | No | リモート接続用資格情報 | - |
| Type | ManagementConnectionType[] | No | テストするプロトコル（デフォルト：全て） | 有効値のみ |
| Force | switch | No | 不正資格情報キャッシュを無視して再テスト | - |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- PowerShellコマンドライン引数

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | テスト対象のコンピュータ名（小文字） |
| CimRM | string | CIM over WinRMテスト結果（"Success"/"Error"） |
| CimDCOM | string | CIM over DCOMテスト結果（"Success"/"Error"） |
| Wmi | string | WMIテスト結果（"Success"/"Error"） |
| PowerShellRemoting | string | PS Remotingテスト結果（"Success"/"Error"） |

### 追加プロパティ（ConnectionManagerオブジェクト）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| LastCimRM | DateTime | 最後のCIM over WinRMテスト日時 |
| LastCimDCOM | DateTime | 最後のCIM over DCOMテスト日時 |
| LastWmi | DateTime | 最後のWMIテスト日時 |
| LastPowerShellRemoting | DateTime | 最後のPS Remotingテスト日時 |
| KnownBadCredentials | Collection | 失敗した資格情報のコレクション |
| DisableBadCredentialCache | Boolean | 不正資格情報キャッシュの無効化フラグ |

### 出力先

- パイプラインにConnectionManagerオブジェクトとして出力
- 接続キャッシュに自動保存（disable_cache設定で無効化可能）

## 処理フロー

### 処理シーケンス

```
1. 設定値取得
   └─ キャッシュ無効化設定の確認
2. 各コンピュータの処理
   ├─ 接続オブジェクト取得
   ├─ 資格情報キャッシュ確認
   │   └─ Forceでキャッシュクリア可能
   └─ プロトコルテスト（Type指定に応じて）
       ├─ CimRM テスト
       ├─ CimDCOM テスト
       ├─ Wmi テスト
       └─ PowerShellRemoting テスト
3. 結果キャッシュ保存
4. 結果オブジェクト出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[設定値取得]
    B --> C[各コンピュータをループ]
    C --> D{入力検証OK?}
    D -->|No| E[エラー・次へ]
    D -->|Yes| F[接続オブジェクト取得]
    F --> G{不正資格情報キャッシュあり?}
    G -->|Yes| H{Force?}
    H -->|No| I[スキップ・次へ]
    H -->|Yes| J[キャッシュクリア]
    G -->|No| K[プロトコルテスト開始]
    J --> K
    K --> L{CimRM指定?}
    L -->|Yes| M[CimRMテスト]
    L -->|No| N{CimDCOM指定?}
    M --> N
    N -->|Yes| O[CimDCOMテスト]
    N -->|No| P{Wmi指定?}
    O --> P
    P -->|Yes| Q[Wmiテスト]
    P -->|No| R{PSRemoting指定?}
    Q --> R
    R -->|Yes| S[PSRemotingテスト]
    R -->|No| T[結果キャッシュ保存]
    S --> T
    T --> U[結果出力]
    U --> V{次のコンピュータ?}
    V -->|Yes| C
    V -->|No| W[終了]
    E --> V
    I --> V
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 認証失敗でテスト中断 | 認証エラー発生時は残りのプロトコルテストをスキップ | 認証失敗時 |
| BR-002 | 不正資格情報キャッシュ | 失敗した資格情報を記録し再使用を防止 | 認証失敗時 |
| BR-003 | Force処理 | 不正資格情報キャッシュをクリアして再テスト | Force指定時 |
| BR-004 | 結果自動キャッシュ | テスト結果は自動的にキャッシュされる | キャッシュ有効時 |
| BR-005 | ユーザー向け関数 | dbatools内部からは呼び出さない（ユーザーツール用） | 常時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベース操作なし（OS接続テストのみ） |

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

データベース操作はありません。Win32_OperatingSystem WMIクラスを使用して接続テストを実行します。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| InvalidArgument | 入力エラー | コンピュータ名解析失敗 | 正しい名前を指定 |
| BadCredentials | 認証エラー | 資格情報が無効 | 正しい資格情報を指定/Force使用 |
| ConnectionFailed | 接続エラー | プロトコル接続失敗 | ネットワーク/ファイアウォール確認 |

### リトライ仕様

リトライ処理は実装されていません。各プロトコルは1回ずつテストされます。

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

トランザクション管理は不要です（接続テストのみ）。

## パフォーマンス要件

- 各プロトコルのテストにはネットワーク遅延が影響
- キャッシュにより後続のコマンドは最適化される

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

- 対象コンピュータへの管理者権限が必要
- Credential使用時はSecureStringで資格情報を保護
- 不正資格情報は自動キャッシュされ再使用を防止
- グローバル設定によりプロトコル制限が可能（本関数はバイパス）

## 備考

- dbatools内部からは呼び出さない（ユーザーツール専用）
- 結果はGet-DbaCmObject、Invoke-DbaCmMethodで自動使用される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Test-DbaCmConnection.ps1 | `public/Test-DbaCmConnection.ps1` | パラメータ定義（90-97行目） |
| 1-2 | Test-DbaCmConnection.ps1 | `public/Test-DbaCmConnection.ps1` | 出力オブジェクト（OUTPUTS定義52-71行目） |

**読解のコツ**: Dataplat.Dbatools.Connection.ManagementConnectionTypeはdbatoolsの内部型で、接続プロトコルを定義するEnumです。

#### Step 2: ヘルパー関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaCmConnection.ps1 | `public/Test-DbaCmConnection.ps1` | begin block - ヘルパー関数定義（98-246行目） |

**主要処理フロー**:
1. **106-140行目**: Test-ConnectionCimRM - CIM over WinRMテスト
2. **142-176行目**: Test-ConnectionCimDCOM - CIM over DCOMテスト
3. **178-209行目**: Test-ConnectionWmi - WMIテスト
4. **211-245行目**: Test-ConnectionPowerShellRemoting - PS Remotingテスト

#### Step 3: メイン処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Test-DbaCmConnection.ps1 | `public/Test-DbaCmConnection.ps1` | process block（248-336行目） |

**主要処理フロー**:
- **250行目**: 入力検証
- **256行目**: 接続オブジェクト取得
- **262-267行目**: 不正資格情報キャッシュ処理
- **271-331行目**: プロトコルテストループ（switch文）
- **334行目**: キャッシュ保存
- **335行目**: 結果出力

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

```
Test-DbaCmConnection
    │
    ├─ Test-ConnectionCimRM (内部関数)
    │      └─ GetCimRMInstance (Win32_OperatingSystem)
    │
    ├─ Test-ConnectionCimDCOM (内部関数)
    │      └─ GetCimDComInstance (Win32_OperatingSystem)
    │
    ├─ Test-ConnectionWmi (内部関数)
    │      └─ Get-WmiObject (Win32_OperatingSystem)
    │
    └─ Test-ConnectionPowerShellRemoting (内部関数)
           └─ Invoke-Command (Get-WmiObject)
```

### データフロー図

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

ComputerName ─────┐
                  │
Credential ───────┼──▶ Test-DbaCmConnection ─────────────▶ ConnectionManager
                  │         │                              (ComputerName,
Type ─────────────┤         ├─ Test-ConnectionCimRM         CimRM,
                  │         ├─ Test-ConnectionCimDCOM       CimDCOM,
Force ────────────┘         ├─ Test-ConnectionWmi           Wmi,
                            └─ Test-ConnectionPSRemoting    PowerShellRemoting)

[Connection Cache] ◄───── 結果保存 ─────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Test-DbaCmConnection.ps1 | `public/Test-DbaCmConnection.ps1` | ソース | メイン関数実装 |
| Get-DbaCmObject.ps1 | `public/Get-DbaCmObject.ps1` | ソース | キャッシュを使用する関連機能 |
| Invoke-DbaCmMethod.ps1 | `public/Invoke-DbaCmMethod.ps1` | ソース | キャッシュを使用する関連機能 |
| Write-Message.ps1 | `private/functions/Write-Message.ps1` | ソース | メッセージ出力ヘルパー |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラー処理ヘルパー |
