# 機能設計書 201-Remove-DbaCmConnection

## 概要

本ドキュメントは、dbatools PowerShellモジュールのRemove-DbaCmConnection関数の機能設計を定義する。この関数は、dbatoolsのキャッシュされた接続オブジェクトを削除するための機能を提供する。

### 本機能の処理概要

Remove-DbaCmConnectionは、dbatoolsがリモートコンピュータ管理操作（Windowsサービス、レジストリ、ファイルシステムへのアクセスなど）に使用するキャッシュされたWindows ManagementおよびCIM接続オブジェクトをクリアする機能である。

**業務上の目的・背景**：dbatoolsコマンドをリモートサーバーに対して実行すると、パフォーマンス向上と認証オーバーヘッド削減のために接続が自動的にキャッシュされる。しかし、資格情報の変更、接続の陳腐化、トラブルシューティング時に新規認証が必要な場合など、キャッシュのクリアが必要になる場面がある。この関数はそのようなケースで使用される。

**機能の利用シーン**：
- 資格情報（パスワード）を変更した後、古いキャッシュを削除して新しい認証情報で再接続する場合
- ネットワーク問題発生後、接続を再確立する必要がある場合
- リモートコンピュータ管理のトラブルシューティング時に、接続状態をリセットしたい場合
- セッション終了時にセキュリティ上の理由でキャッシュをクリアする場合

**主要な処理内容**：
1. ComputerNameパラメータで指定されたコンピュータ名を解釈
2. dbatoolsの内部接続キャッシュ（ConnectionHost.Connections）から該当する接続を検索
3. ShouldProcess確認後、接続をキャッシュから削除
4. 削除結果をVerboseメッセージとして出力

**関連システム・外部連携**：
- Dataplat.Dbatools.Connection.ConnectionHost：dbatools内部の接続キャッシュを管理するクラス
- Get-DbaCmConnection：キャッシュされた接続を取得する関連コマンド
- Set-DbaCmConnection：接続設定を構成する関連コマンド

**権限による制御**：特別な権限は不要。ただし、dbatoolsモジュールがロードされている必要がある。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 282 | CM接続管理 | 主画面 | CM接続の削除 |

## 機能種別

データ削除（キャッシュクリア）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | DbaCmConnectionParameter[] | Yes | キャッシュから削除する接続のコンピュータ名。Get-DbaCmConnectionからパイプ入力可能 | 接続パラメータとして解釈可能であること |
| EnableException | switch | No | 例外を直接スローするかどうか。デフォルトはフレンドリーな警告メッセージ | - |

### 入力データソース

- パラメータ入力：ComputerName（コンピュータ名の文字列または接続オブジェクト）
- パイプライン入力：Get-DbaCmConnectionの出力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| なし | - | このコマンドはパイプラインに出力を返さない |

### 出力先

- 画面表示：Verboseメッセージとして削除結果を表示
- dbatoolsの内部接続キャッシュ：該当接続が削除される

## 処理フロー

### 処理シーケンス

```
1. 処理開始のログ出力
   └─ Write-Message -Level InternalComment
2. バインドされたパラメータのログ出力
   └─ Write-Message -Level Verbose
3. 各ComputerNameについてループ処理
   └─ 3.1 接続オブジェクトの検証
       └─ Success=falseの場合、Stop-FunctionでエラーをスキップしてContinue
   └─ 3.2 削除対象の接続情報をログ出力
       └─ Write-Message -Level VeryVerbose
   └─ 3.3 ShouldProcess確認
       └─ Confirm/WhatIfの処理
   └─ 3.4 接続キャッシュに存在確認
       └─ ConnectionHost.Connections.ContainsKey()
   └─ 3.5 存在する場合は削除
       └─ ConnectionHost.Connections.Remove()
   └─ 3.6 結果のログ出力
       └─ 成功時/未検出時でメッセージを分岐
4. 処理終了のログ出力
   └─ Write-Message -Level InternalComment
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[開始ログ出力]
    B --> C{ComputerNameループ}
    C -->|次のコンピュータ| D{接続解釈成功?}
    D -->|No| E[エラーログ出力]
    E --> C
    D -->|Yes| F[削除対象ログ出力]
    F --> G{ShouldProcess?}
    G -->|No| C
    G -->|Yes| H{キャッシュに存在?}
    H -->|Yes| I[接続を削除]
    I --> J[成功ログ出力]
    J --> C
    H -->|No| K[未検出ログ出力]
    K --> C
    C -->|完了| L[終了ログ出力]
    L --> M[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-201-01 | 接続解釈検証 | ComputerNameパラメータは有効な接続パラメータとして解釈できなければならない | 常時 |
| BR-201-02 | 存在確認 | 削除前にキャッシュ内の存在を確認し、存在しない場合は警告のみでエラーとしない | 常時 |
| BR-201-03 | 確認プロンプト | ShouldProcessをサポートし、ConfirmImpact=Highで実行前に確認を求める | Confirm未指定時 |

### 計算ロジック

特になし

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

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

本機能はデータベースを操作しない。dbatoolsの内部メモリキャッシュのみを操作する。

| 操作 | 対象 | 操作種別 | 概要 |
|-----|-----|---------|------|
| 接続削除 | ConnectionHost.Connections | DELETE | メモリ内キャッシュからの接続オブジェクト削除 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| InvalidArgument | 引数エラー | ComputerNameの解釈に失敗 | 正しいコンピュータ名または接続オブジェクトを指定 |

### リトライ仕様

リトライ処理は実装されていない。

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

本機能はデータベーストランザクションを使用しない。メモリキャッシュ操作は即座に適用される。

## パフォーマンス要件

- 処理は即時完了（メモリ操作のみ）
- 大量の接続を一括削除する場合も、パフォーマンス影響は最小限

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

- キャッシュされた接続情報には認証情報が含まれる可能性があるため、不要な接続は適時削除することが推奨される
- ConfirmImpact=Highにより、誤操作による全接続削除を防止

## 備考

- Get-DbaCmConnection | Remove-DbaCmConnection で全キャッシュクリアが可能
- Friedrich Weinmann (@FredWeinmann) により作成

---

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

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

### 推奨読解順序

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

dbatoolsの接続キャッシュ管理の仕組みを理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ConnectionHost.cs | `bin/projects/dbatools/dbatools/Connection/ConnectionHost.cs` | Connectionsディクショナリの構造を理解 |

**読解のコツ**: DbaCmConnectionParameterは接続パラメータを抽象化した型で、コンピュータ名文字列や接続オブジェクトを統一的に扱える。

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

Remove-DbaCmConnection.ps1の構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Remove-DbaCmConnection.ps1 | `public/Remove-DbaCmConnection.ps1` | 関数全体の処理フロー |

**主要処理フロー**:
1. **59-62行目**: begin ブロックでログ出力
2. **64-65行目**: 接続オブジェクトの検証
3. **67-74行目**: ShouldProcess確認と接続削除

#### Step 3: 関連機能を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaCmConnection.ps1 | `public/Get-DbaCmConnection.ps1` | キャッシュされた接続の取得方法 |
| 3-2 | Set-DbaCmConnection.ps1 | `public/Set-DbaCmConnection.ps1` | 接続設定の構成方法 |

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

```
Remove-DbaCmConnection
    │
    ├─ Write-Message
    │      └─ ログ出力
    │
    ├─ Stop-Function
    │      └─ エラー処理とスキップ
    │
    └─ [Dataplat.Dbatools.Connection.ConnectionHost]::Connections
           └─ ContainsKey() / Remove()
```

### データフロー図

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

ComputerName ───────▶ パラメータ検証 ───────▶ エラーメッセージ
    │                        │                    (検証失敗時)
    │                        ▼
    │                 ShouldProcess確認
    │                        │
    │                        ▼
    └────────────────▶ キャッシュ検索
                             │
                             ▼
                    ┌────────────────┐
                    │ Connections    │
                    │ Dictionary     │
                    └────────────────┘
                             │
                             ▼
                        接続削除
                             │
                             ▼
                    Verboseメッセージ ───────▶ コンソール出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Remove-DbaCmConnection.ps1 | `public/Remove-DbaCmConnection.ps1` | ソース | メイン関数実装 |
| Get-DbaCmConnection.ps1 | `public/Get-DbaCmConnection.ps1` | ソース | 接続取得（パイプライン入力元） |
| Set-DbaCmConnection.ps1 | `public/Set-DbaCmConnection.ps1` | ソース | 接続設定構成 |
| ConnectionHost.cs | `bin/projects/dbatools/dbatools/Connection/ConnectionHost.cs` | ソース | 接続キャッシュ管理クラス |
