# 画面設計書 282-CM接続管理

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるComputer Management（CM）接続管理機能群の設計仕様を定義します。CM接続は、SQL ServerホストマシンへのCIM/WMI/PowerShellリモーティング接続を管理し、Windowsサービス、レジストリ、ファイルシステムへのリモートアクセスを可能にします。

### 本画面の処理概要

**業務上の目的・背景**：SQL Serverの管理においては、データベースエンジンへのSQL接続だけでなく、ホストマシンのWindowsレベルでの情報取得・操作が必要となる場面が多くあります（サービス管理、ディスクスペース確認、OS情報取得など）。CM接続管理機能は、これらのリモート接続を効率的に管理し、認証情報のキャッシュ、最適なプロトコルの自動選択、接続失敗時の自動フォールバックなどを提供します。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから、以下のコマンドのいずれかを実行します：
- `Get-DbaCmConnection` - キャッシュ済み接続の取得
- `New-DbaCmConnection` - 新規接続の作成
- `Set-DbaCmConnection` - 接続設定の変更
- `Remove-DbaCmConnection` - 接続の削除
- `Test-DbaCmConnection` - 接続テスト

**主要な操作・処理内容**：
1. **接続取得（Get-DbaCmConnection）**：キャッシュされたCM接続オブジェクトをフィルタリングして取得
2. **接続作成（New-DbaCmConnection）**：新しいCM接続オブジェクトを作成しキャッシュに登録
3. **接続設定（Set-DbaCmConnection）**：既存接続の設定変更（認証情報、プロトコル、キャッシュ動作など）
4. **接続削除（Remove-DbaCmConnection）**：キャッシュから接続を削除
5. **接続テスト（Test-DbaCmConnection）**：4つのプロトコル（CimRM、CimDCOM、Wmi、PowerShellRemoting）での接続性を検証

**画面遷移**：CM接続管理コマンドは、`Get-DbaCmObject`などのCMオブジェクト取得コマンドから暗黙的に利用されます。明示的な接続管理は通常オプションですが、認証問題のトラブルシューティングや特定のプロトコル設定が必要な場合に使用します。

**権限による表示制御**：リモートコンピュータへの接続には、対象マシンでの管理者権限または適切なWMI/CIM権限が必要です。ローカルキャッシュの操作自体には特別な権限は不要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 93 | Get-DbaCmConnection | 主機能 | キャッシュ済みCM接続の取得 |
| 185 | New-DbaCmConnection | 主機能 | 新規CM接続の作成・キャッシュ登録 |
| 217 | Set-DbaCmConnection | 補助機能 | CM接続設定の変更 |
| 201 | Remove-DbaCmConnection | 主機能 | CM接続のキャッシュからの削除 |
| 239 | Test-DbaCmConnection | 補助機能 | CM接続プロトコルのテスト |
| 94 | Get-DbaCmObject | 遷移先機能 | CM接続を使用したWMI/CIMオブジェクト取得 |

## 画面種別

管理（Management） / キャッシュ管理

## URL/ルーティング

PowerShellコマンド群:
- `Get-DbaCmConnection` - https://dbatools.io/Get-DbaCmConnection
- `New-DbaCmConnection` - https://dbatools.io/New-DbaCmConnection
- `Set-DbaCmConnection` - https://dbatools.io/Set-DbaCmConnection
- `Remove-DbaCmConnection` - https://dbatools.io/Remove-DbaCmConnection
- `Test-DbaCmConnection` - https://dbatools.io/Test-DbaCmConnection

## 入出力項目

### Get-DbaCmConnection パラメータ

| パラメータ名 | 必須 | 型 | デフォルト値 | 説明 |
|-------------|------|-----|-------------|------|
| ComputerName | No | String[] | * | コンピュータ名フィルター（ワイルドカード対応） |
| UserName | No | String | * | ユーザー名フィルター（ワイルドカード対応） |
| EnableException | No | Switch | $false | 例外を有効化 |

### New-DbaCmConnection パラメータ

| パラメータ名 | 必須 | 型 | デフォルト値 | 説明 |
|-------------|------|-----|-------------|------|
| ComputerName | No | DbaCmConnectionParameter[] | $env:COMPUTERNAME | 対象コンピュータ |
| Credential | No | PSCredential | - | 認証情報 |
| UseWindowsCredentials | No | Switch | - | 現在のWindows認証を使用 |
| OverrideExplicitCredential | No | Switch | - | キャッシュ認証を優先 |
| DisabledConnectionTypes | No | ManagementConnectionType | None | 無効化するプロトコル |
| DisableBadCredentialCache | No | Switch | - | 失敗認証のキャッシュを無効化 |
| DisableCimPersistence | No | Switch | - | CIMセッション再利用を無効化 |
| DisableCredentialAutoRegister | No | Switch | - | 成功認証の自動登録を無効化 |
| EnableCredentialFailover | No | Switch | - | 認証フェールオーバーを有効化 |
| WindowsCredentialsAreBad | No | Switch | - | Windows認証を無効とマーク |
| CimWinRMOptions | No | WSManSessionOptions | - | WinRMセッションオプション |
| CimDCOMOptions | No | DComSessionOptions | - | DCOMセッションオプション |
| WhatIf | No | Switch | - | 実行内容のプレビュー |
| Confirm | No | Switch | - | 確認プロンプト |
| EnableException | No | Switch | $false | 例外を有効化 |

### Set-DbaCmConnection パラメータ

| パラメータ名 | 必須 | 型 | デフォルト値 | 説明 |
|-------------|------|-----|-------------|------|
| ComputerName | No | DbaCmConnectionParameter[] | $env:COMPUTERNAME | 対象コンピュータ |
| Credential | No | PSCredential | - | 認証情報 |
| UseWindowsCredentials | No | Switch | - | Windows認証を使用 |
| OverrideExplicitCredential | No | Switch | - | キャッシュ認証を優先 |
| OverrideConnectionPolicy | No | Switch | - | グローバルポリシーを上書き |
| DisabledConnectionTypes | No | ManagementConnectionType | None | 無効化するプロトコル |
| AddBadCredential | No | PSCredential[] | - | 失敗認証リストに追加 |
| RemoveBadCredential | No | PSCredential[] | - | 失敗認証リストから削除 |
| ClearBadCredential | No | Switch | - | 失敗認証リストをクリア |
| ClearCredential | No | Switch | - | 認証情報をクリア |
| ResetCredential | No | Switch | - | 認証情報を完全リセット |
| ResetConnectionStatus | No | Switch | - | 接続ステータスをリセット |
| ResetConfiguration | No | Switch | - | 設定をデフォルトに戻す |
| EnableException | No | Switch | $false | 例外を有効化 |

### Remove-DbaCmConnection パラメータ

| パラメータ名 | 必須 | 型 | デフォルト値 | 説明 |
|-------------|------|-----|-------------|------|
| ComputerName | Yes | DbaCmConnectionParameter[] | - | 削除対象コンピュータ |
| WhatIf | No | Switch | - | 実行内容のプレビュー |
| Confirm | No | Switch | - | 確認プロンプト |
| EnableException | No | Switch | $false | 例外を有効化 |

### Test-DbaCmConnection パラメータ

| パラメータ名 | 必須 | 型 | デフォルト値 | 説明 |
|-------------|------|-----|-------------|------|
| ComputerName | No | DbaCmConnectionParameter[] | $env:COMPUTERNAME | テスト対象コンピュータ |
| Credential | No | PSCredential | - | テストに使用する認証情報 |
| Type | No | ManagementConnectionType[] | CimRM,CimDCOM,Wmi,PowerShellRemoting | テストするプロトコル |
| Force | No | Switch | - | 失敗済み認証のリテスト |
| EnableException | No | Switch | $false | 例外を有効化 |

## 表示項目

### Get-DbaCmConnection 出力

| プロパティ | 型 | 説明 |
|-----------|-----|------|
| ComputerName | String | 接続先コンピュータ名 |
| Available | Boolean | 接続可能かどうか |
| User | String | 使用されているユーザー名 |
| OverrideExplicitCredential | Boolean | 明示的認証を上書きするか |
| DisabledConnectionTypes | ManagementConnectionType | 無効化されたプロトコル |
| Credentials | PSCredential | キャッシュされた認証情報 |
| UseWindowsCredentials | Boolean | Windows認証を使用するか |
| CimRM | ConnectionResult | CIM/WinRM接続テスト結果 |
| CimDCOM | ConnectionResult | CIM/DCOM接続テスト結果 |
| Wmi | ConnectionResult | WMI接続テスト結果 |
| PowerShellRemoting | ConnectionResult | PSリモーティング接続テスト結果 |

### Test-DbaCmConnection 出力

| プロパティ | 型 | 説明 |
|-----------|-----|------|
| ComputerName | String | テスト対象コンピュータ名 |
| CimRM | String | CIM/WinRMテスト結果（Success/Error） |
| CimDCOM | String | CIM/DCOMテスト結果（Success/Error） |
| Wmi | String | WMIテスト結果（Success/Error） |
| PowerShellRemoting | String | PSリモーティングテスト結果（Success/Error） |
| LastCimRM | DateTime | 最終CimRMテスト日時 |
| LastCimDCOM | DateTime | 最終CimDCOMテスト日時 |
| LastWmi | DateTime | 最終WMIテスト日時 |
| LastPowerShellRemoting | DateTime | 最終PSリモーティングテスト日時 |

## イベント仕様

### 1-Get-DbaCmConnection実行時

1. 接続キャッシュ `[Dataplat.Dbatools.Connection.ConnectionHost]::Connections` からエントリを取得
2. `ComputerName`パラメータでフィルタリング（ワイルドカードマッチング）
3. `UserName`パラメータでフィルタリング（Credentials.UserNameをマッチング）
4. マッチする接続オブジェクトをパイプラインに出力

### 2-New-DbaCmConnection実行時

1. `ShouldProcess`確認（WhatIf/Confirm対応）
2. 新しい`ManagementConnection`オブジェクトを作成
3. 指定されたパラメータで接続オブジェクトを構成
4. CimWinRMOptions/CimDCOMOptionsが未指定の場合、`New-DbaCimSessionOptionWithTimeout`でデフォルト値を設定
5. キャッシュが有効な場合、`ConnectionHost.Connections`に登録
6. 接続オブジェクトを出力

### 3-Set-DbaCmConnection実行時

1. `ShouldProcess`確認
2. 既存接続または新規接続オブジェクトを取得
3. `ResetConfiguration`が指定された場合、デフォルト設定に戻す
4. `ResetConnectionStatus`が指定された場合、全プロトコルステータスをUnknownに
5. 認証リセット/クリア処理を実行
6. 新しい設定値を適用
7. キャッシュに書き込み
8. 更新された接続オブジェクトを出力

### 4-Remove-DbaCmConnection実行時

1. `ShouldProcess`確認（ConfirmImpact = 'High'）
2. 指定されたコンピュータ名でキャッシュを検索
3. 見つかった場合、`ConnectionHost.Connections.Remove()`で削除
4. 削除結果をVerboseログに出力

### 5-Test-DbaCmConnection実行時

1. 失敗認証のキャッシュ処理（DisableBadCredentialCache確認）
2. 各プロトコルタイプに対してテスト実行:
   - CimRM: `GetCimRMInstance`で`Win32_OperatingSystem`を取得
   - CimDCOM: `GetCimDComInstance`で`Win32_OperatingSystem`を取得
   - Wmi: `Get-WmiObject`で`Win32_OperatingSystem`を取得
   - PowerShellRemoting: `Invoke-Command`でリモートWMIクエリ実行
3. 各テスト結果（Success/Error）とタイムスタンプを記録
4. 認証失敗時は失敗認証キャッシュに追加
5. 接続オブジェクトをキャッシュに保存
6. テスト結果を出力

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

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

本コマンド群はデータベースを操作しません。メモリ上の接続キャッシュのみを更新します。

| 操作（イベント） | 対象 | 操作種別 | 概要 |
|----------------|------|---------|------|
| New-DbaCmConnection | ConnectionHost.Connections | INSERT | 新規接続をキャッシュに追加 |
| Set-DbaCmConnection | ConnectionHost.Connections | UPDATE | 既存接続の設定を更新 |
| Remove-DbaCmConnection | ConnectionHost.Connections | DELETE | キャッシュから接続を削除 |
| Test-DbaCmConnection | ConnectionHost.Connections | UPDATE | テスト結果で接続情報を更新 |
| Get-DbaCmConnection | ConnectionHost.Connections | SELECT | キャッシュから接続を読み取り |

### キャッシュ更新詳細

#### ConnectionHost.Connections（Dictionary<string, ManagementConnection>）

| 操作 | キー | 値 | 備考 |
|-----|------|-----|------|
| INSERT/UPDATE | ComputerName（小文字） | ManagementConnectionオブジェクト | キャッシュ無効化時は更新しない |
| DELETE | ComputerName | - | ContainsKey確認後に削除 |

## メッセージ仕様

| 種別 | コマンド | 条件 | メッセージ |
|------|---------|------|-----------|
| Error | 全般 | 入力解釈失敗 | "Failed to interpret input: {入力値}" |
| Error | 全般 | コンピュータ名解釈失敗 | "Failed to interpret computername input: {入力値}" |
| Verbose | New-DbaCmConnection | キャッシュ書き込み | "Writing connection to cache" |
| Verbose | New-DbaCmConnection | キャッシュ無効時 | "Skipping writing to cache, since the cache has been disabled." |
| Verbose | Remove-DbaCmConnection | 削除成功 | "Successfully removed {コンピュータ名}" |
| Verbose | Remove-DbaCmConnection | 接続なし | "Not found: {コンピュータ名}" |
| Important | Test-DbaCmConnection | 認証失敗 | "[{コンピュータ名}] The credentials supplied proved to be invalid. Skipping further tests" |
| Error | Test-DbaCmConnection | 失敗認証使用 | "[{コンピュータ名}] The credentials supplied are on the list of known bad credentials, skipping. Use -Force to override this." |

## 例外処理

| コマンド | 例外状況 | 処理 |
|---------|---------|------|
| Get-DbaCmConnection | 入力解釈失敗 | Stop-Functionで処理継続 |
| New-DbaCmConnection | コンピュータ名解釈失敗 | Stop-FunctionでContinue |
| Set-DbaCmConnection | コンピュータ名解釈失敗 | Stop-FunctionでContinue |
| Remove-DbaCmConnection | コンピュータ名解釈失敗 | Stop-FunctionでContinue |
| Test-DbaCmConnection | 入力解釈失敗 | Stop-FunctionでContinue |
| Test-DbaCmConnection | 認証失敗（Force未指定） | Stop-FunctionでContinue |

## 備考

- 接続キャッシュは`ComputerManagement.Cache.Disable.All`構成値で無効化可能
- 接続プロトコルの優先順位: CimRM > CimDCOM > Wmi > PowerShellRemoting
- 認証情報のキャッシュ動作は複数の構成オプションで制御可能
- Friedrich Weinmann (@FredWeinmann) が開発

---

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

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

### 推奨読解順序

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

CM接続の中核となるデータ構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaCmConnection.ps1 | `public/Get-DbaCmConnection.ps1` | 出力型ManagementConnectionのプロパティ定義（23-47行目） |
| 1-2 | New-DbaCmConnection.ps1 | `public/New-DbaCmConnection.ps1` | ManagementConnectionのプロパティ一覧（104-121行目） |

**読解のコツ**: `Dataplat.Dbatools.Connection.ManagementConnection`クラスはC#で定義されたdbatools内部クラスです。PowerShellコマンドはこのオブジェクトを操作します。

#### Step 2: キャッシュ構造を理解する

接続キャッシュの仕組みを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaCmConnection.ps1 | `public/Get-DbaCmConnection.ps1` | ConnectionHost.Connectionsへのアクセス（90行目） |
| 2-2 | New-DbaCmConnection.ps1 | `public/New-DbaCmConnection.ps1` | キャッシュへの書き込み（212-214行目） |

**主要処理フロー**:
1. **90行目（Get）**: `ConnectionHost.Connections.Values`から全接続を取得しWhere-Objectでフィルタ
2. **214行目（New）**: `ConnectionHost.Connections[$computerName] = $connection`でキャッシュに書き込み

#### Step 3: 各コマンドの処理フローを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaCmConnection.ps1 | `public/Get-DbaCmConnection.ps1` | process関数（87-92行目）のシンプルなフィルタリング |
| 3-2 | New-DbaCmConnection.ps1 | `public/New-DbaCmConnection.ps1` | process関数（182-218行目）の接続作成ロジック |
| 3-3 | Set-DbaCmConnection.ps1 | `public/Set-DbaCmConnection.ps1` | process関数（200-290行目）の設定更新ロジック |
| 3-4 | Remove-DbaCmConnection.ps1 | `public/Remove-DbaCmConnection.ps1` | process関数（63-76行目）の削除ロジック |
| 3-5 | Test-DbaCmConnection.ps1 | `public/Test-DbaCmConnection.ps1` | ヘルパー関数（106-246行目）と接続テスト（248-336行目） |

#### Step 4: 接続テストの詳細を理解する

Test-DbaCmConnectionの4つのプロトコルテストを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Test-DbaCmConnection.ps1 | `public/Test-DbaCmConnection.ps1` | Test-ConnectionCimRM関数（106-140行目） |
| 4-2 | Test-DbaCmConnection.ps1 | `public/Test-DbaCmConnection.ps1` | Test-ConnectionCimDCOM関数（142-176行目） |
| 4-3 | Test-DbaCmConnection.ps1 | `public/Test-DbaCmConnection.ps1` | Test-ConnectionWmi関数（178-209行目） |
| 4-4 | Test-DbaCmConnection.ps1 | `public/Test-DbaCmConnection.ps1` | Test-ConnectionPowerShellRemoting関数（211-245行目） |

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

```
CM接続管理コマンド群
    |
    |-- Get-DbaCmConnection
    |       |
    |       +-- [ConnectionHost]::Connections.Values (読み取り)
    |
    |-- New-DbaCmConnection
    |       |
    |       |-- New-Object ManagementConnection
    |       |-- New-DbaCimSessionOptionWithTimeout
    |       +-- [ConnectionHost]::Connections[$name] = $conn (書き込み)
    |
    |-- Set-DbaCmConnection
    |       |
    |       |-- ManagementConnection.RestoreDefaultConfiguration()
    |       |-- 各種プロパティ設定
    |       +-- [ConnectionHost]::Connections[$name] = $conn (更新)
    |
    |-- Remove-DbaCmConnection
    |       |
    |       +-- [ConnectionHost]::Connections.Remove($name) (削除)
    |
    +-- Test-DbaCmConnection
            |
            |-- Test-ConnectionCimRM (Win32_OperatingSystem via CIM/WinRM)
            |-- Test-ConnectionCimDCOM (Win32_OperatingSystem via CIM/DCOM)
            |-- Test-ConnectionWmi (Get-WmiObject)
            |-- Test-ConnectionPowerShellRemoting (Invoke-Command)
            +-- [ConnectionHost]::Connections[$name] = $conn (結果保存)
```

### データフロー図

```
[入力]                          [キャッシュ]                    [出力]

ComputerName ────────────────┐
                             |
Credential ──────────────────┼──▶ [ConnectionHost]::Connections
                             |     Dictionary<string, ManagementConnection>
UseWindowsCredentials ───────┤           |
                             |           |
DisabledConnectionTypes ─────┤           ▼
                             |    ┌─────────────────────────────────┐
CimWinRMOptions ─────────────┘    │ ManagementConnection            │
                                  │  - ComputerName                 │
                                  │  - Credentials                  │
                                  │  - UseWindowsCredentials        │
                                  │  - CimRM (Success/Error/Unknown)│
                                  │  - CimDCOM                      │──▶ Get-DbaCmConnection
                                  │  - Wmi                          │    出力オブジェクト
                                  │  - PowerShellRemoting           │
                                  │  - LastCimRM (DateTime)         │
                                  │  - DisabledConnectionTypes      │
                                  │  - KnownBadCredentials[]        │
                                  └─────────────────────────────────┘

                                           │
                                           ▼
                            Get-DbaCmObject / Invoke-DbaCmMethod
                            （CM接続を自動的に使用）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaCmConnection.ps1 | `public/Get-DbaCmConnection.ps1` | ソース | キャッシュ済み接続の取得（96行） |
| New-DbaCmConnection.ps1 | `public/New-DbaCmConnection.ps1` | ソース | 新規接続の作成（223行） |
| Set-DbaCmConnection.ps1 | `public/Set-DbaCmConnection.ps1` | ソース | 接続設定の変更（294行） |
| Remove-DbaCmConnection.ps1 | `public/Remove-DbaCmConnection.ps1` | ソース | 接続の削除（80行） |
| Test-DbaCmConnection.ps1 | `public/Test-DbaCmConnection.ps1` | ソース | 接続テスト（341行） |
| Get-DbaCmObject.ps1 | `public/Get-DbaCmObject.ps1` | ソース | CM接続を使用するWMI/CIM取得（関連） |
| ConnectionHost | 内部C#クラス | ライブラリ | 接続キャッシュの静的管理クラス |
| ManagementConnection | 内部C#クラス | ライブラリ | 接続情報を保持するクラス |
