# 機能設計書 217-Set-DbaCmConnection

## 概要

本ドキュメントは、リモートコンピューター管理接続設定を構成するSet-DbaCmConnection関数の機能設計書です。

### 本機能の処理概要

Set-DbaCmConnectionは、dbatoolsがCIM、WMI、PowerShellリモーティングを介してリモートSQL Serverホストコンピューターを管理するために使用する接続オブジェクトを構成します。この関数は、まだキャッシュされていないコンピューターの新しい接続レコードを作成するか、以前に接続したホストの既存の接続設定を変更します。

**業務上の目的・背景**：SQL Serverホストマシンへのリモート管理（サービス管理、ファイル操作、システム情報収集など）では、様々な接続プロトコル（CIM/WMI/PowerShellリモーティング）と認証設定が必要です。本機能は、接続動作の一括構成、資格情報キャッシュの管理、リモート接続問題のトラブルシューティングを支援します。

**機能の利用シーン**：
- 複数のSQL Serverホストに対する接続設定を一括で構成する場合
- 認証問題のトラブルシューティングを行う場合
- 特定の接続プロトコル（CIM/WMI）を無効化または有効化する場合
- 資格情報キャッシュをクリアまたはリセットする場合

**主要な処理内容**：
1. 接続オブジェクトの取得または作成
2. 構成リセット/接続状態リセット/資格情報リセット（指定時）
3. 資格情報の追加/削除/クリア
4. 接続プロパティの設定
5. 接続オブジェクトのキャッシュへの書き込み

**関連システム・外部連携**：
- CIM（WinRM/DCOM）
- WMI
- PowerShell Remoting

**権限による制御**：対象コンピューターへのリモート管理権限が必要です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIインターフェース | 主画面 | コマンドライン実行 |

## 機能種別

構成管理 / 接続管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | DbaCmConnectionParameter[] | No | 対象コンピューター名 | デフォルト: ローカルコンピューター |
| Credential | PSCredential | No | 登録する資格情報 | PSCredential型 |
| UseWindowsCredentials | switch | No | Windows認証を使用 | スイッチ型 |
| OverrideExplicitCredential | switch | No | キャッシュ資格情報を優先 | スイッチ型 |
| OverrideConnectionPolicy | switch | No | グローバル接続ポリシーを上書き | スイッチ型 |
| DisabledConnectionTypes | ManagementConnectionType | No | 無効化する接続タイプ | None/CIM/WMI/PowerShellRemoting |
| DisableBadCredentialCache | switch | No | 失敗資格情報のキャッシュを無効化 | スイッチ型 |
| DisableCimPersistence | switch | No | CIMセッション永続化を無効化 | スイッチ型 |
| DisableCredentialAutoRegister | switch | No | 成功資格情報の自動保存を無効化 | スイッチ型 |
| EnableCredentialFailover | switch | No | 資格情報フェールオーバーを有効化 | スイッチ型 |
| WindowsCredentialsAreBad | switch | No | Windows資格情報を非機能としてマーク | スイッチ型 |
| CimWinRMOptions | WSManSessionOptions | No | WinRMセッションオプション | CimSessionOptionオブジェクト |
| CimDCOMOptions | DComSessionOptions | No | DCOMセッションオプション | CimSessionOptionオブジェクト |
| AddBadCredential | PSCredential[] | No | 不正資格情報リストに追加 | PSCredential配列 |
| RemoveBadCredential | PSCredential[] | No | 不正資格情報リストから削除 | PSCredential配列 |
| ClearBadCredential | switch | No | 不正資格情報リストをクリア | スイッチ型 |
| ClearCredential | switch | No | キャッシュ資格情報をクリア | スイッチ型 |
| ResetCredential | switch | No | 資格情報を完全リセット | スイッチ型 |
| ResetConnectionStatus | switch | No | 接続状態をリセット | スイッチ型 |
| ResetConfiguration | switch | No | 構成をデフォルトにリセット | スイッチ型 |
| EnableException | switch | No | 例外を有効化 | スイッチ型 |
| WhatIf | switch | No | 実行シミュレーション | スイッチ型 |
| Confirm | switch | No | 確認プロンプト | スイッチ型 |

### 入力データソース

- コマンドライン引数
- Get-DbaCmConnectionからのパイプライン入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ManagementConnection | Dataplat.Dbatools.Connection.ManagementConnection | 接続オブジェクト |

### 出力先

- パイプライン出力
- 接続キャッシュへの保存

## 処理フロー

### 処理シーケンス

```
1. 入力パラメータ解析
   └─ DbaCmConnectionParameterの解析

2. 接続オブジェクト取得
   └─ 既存接続またはパラメータから取得

3. リセット処理（指定時）
   ├─ ResetConfiguration: デフォルト構成に復元
   ├─ ResetConnectionStatus: 接続状態をUnknownに
   └─ ResetCredential: 全資格情報をクリア

4. 資格情報処理
   ├─ ClearBadCredential: 不正資格情報リストクリア
   ├─ ClearCredential: キャッシュ資格情報クリア
   ├─ RemoveBadCredential: 特定資格情報を削除
   └─ AddBadCredential: 特定資格情報を追加

5. プロパティ設定
   └─ Test-Boundで指定されたプロパティを設定

6. キャッシュ書き込み
   └─ ConnectionHost.Connectionsに保存

7. 接続オブジェクト出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[パラメータ解析]
    B --> C{解析成功?}
    C -->|No| D[エラー、次へ継続]
    C -->|Yes| E{ResetConfiguration?}

    E -->|Yes| F[RestoreDefaultConfiguration]
    E -->|No| G{ResetConnectionStatus?}
    F --> G

    G -->|Yes| H[接続状態をUnknownに]
    G -->|No| I{ResetCredential?}
    H --> I

    I -->|Yes| J[全資格情報クリア]
    I -->|No| K[個別資格情報処理]
    J --> L[プロパティ設定]
    K --> L

    L --> M[CimSessionOption設定]
    M --> N{キャッシュ無効?}
    N -->|No| O[ConnectionHost.Connections保存]
    N -->|Yes| P[スキップ]

    O --> Q[接続オブジェクト出力]
    P --> Q
    D --> R{次のコンピューター?}
    Q --> R
    R -->|Yes| B
    R -->|No| S[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | デフォルトコンピューター | 未指定時はローカルコンピューター | ComputerName未指定 |
| BR-002 | パラメータセット | CredentialとUseWindowsCredentialsは排他 | 常時 |
| BR-003 | リセット優先順位 | ResetCredentialはClear操作に優先 | 両方指定時 |
| BR-004 | CimSessionOptionデフォルト | 未設定時はタイムアウト付きオプションを設定 | CimOptions未設定時 |
| BR-005 | キャッシュ無効時 | キャッシュ無効設定時は保存をスキップ | Cache.Disable.All=true |

### 計算ロジック

該当なし

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

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

該当なし（データベース操作なし）

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 入力解析失敗 | ComputerName解析に失敗 | 警告メッセージ、次のコンピューターへ継続 |

### リトライ仕様

リトライは行いません。エラー発生時は次のコンピューターへ継続処理します。

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

該当なし（メモリ内キャッシュ操作）

## パフォーマンス要件

特になし。接続設定変更は軽量な操作です。

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

- 資格情報はメモリ内キャッシュに保存される
- セキュリティ上の理由で資格情報の自動キャッシュを無効化可能
- 不正資格情報の記録によりアカウントロックアウトを防止

## 備考

- Export-Clixml/Import-Clixmlで接続設定を永続化可能
- プロファイルでの自動構成に使用可能

---

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

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

### 推奨読解順序

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

接続管理で使用されるデータ構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ManagementConnection型 | `Dataplat.Dbatools.Connection` | 接続オブジェクトの構造 |

**読解のコツ**: ManagementConnectionはCIM/WMI/PowerShellリモーティングの接続状態と資格情報を保持します。

#### Step 2: パラメータ定義を理解する

関数のパラメータ構造を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Set-DbaCmConnection.ps1 | `public/Set-DbaCmConnection.ps1` 165-192行目 | パラメータ定義、パラメータセット |

**主要処理フロー**:
1. **166-169行目**: ComputerNameパラメータ（デフォルト: $env:COMPUTERNAME）
2. **170-172行目**: Credentialパラメータ（Credentialセット）
3. **173行目**: UseWindowsCredentialsパラメータ（Windowsセット）

#### Step 3: リセット処理を理解する

各種リセット処理のロジックを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbaCmConnection.ps1 | `public/Set-DbaCmConnection.ps1` 208-249行目 | リセット処理ロジック |

**主要処理フロー**:
- **208-212行目**: ResetConfiguration - RestoreDefaultConfiguration()呼び出し
- **214-226行目**: ResetConnectionStatus - 接続状態をUnknownに、日時をリセット
- **228-249行目**: ResetCredential/ClearBadCredential/ClearCredential処理

#### Step 4: プロパティ設定とキャッシュ保存を理解する

プロパティ設定とキャッシュ操作を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Set-DbaCmConnection.ps1 | `public/Set-DbaCmConnection.ps1` 259-287行目 | プロパティ設定、キャッシュ保存 |

**主要処理フロー**:
- **259-270行目**: Test-Boundによる条件付きプロパティ設定
- **271-280行目**: CimWinRMOptions/CimDCOMOptionsのデフォルト設定
- **283-286行目**: キャッシュへの書き込み（無効時はスキップ）
- **287行目**: 接続オブジェクト出力

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

```
Set-DbaCmConnection
    │
    ├─ Get-DbatoolsConfigValue (キャッシュ無効設定取得)
    │
    ├─ DbaCmConnectionParameter (パラメータ解析)
    │
    ├─ ManagementConnection.RestoreDefaultConfiguration()
    │
    ├─ ManagementConnection.KnownBadCredentials.Clear()
    │
    ├─ ManagementConnection.AddBadCredential()
    │
    ├─ ManagementConnection.RemoveBadCredential()
    │
    ├─ New-DbaCimSessionOptionWithTimeout
    │
    ├─ ConnectionHost.Connections (キャッシュ保存)
    │
    └─ Stop-Function (エラー処理)
```

### データフロー図

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

ComputerName       ───▶ 接続オブジェクト取得   ───▶
     +                        │
設定パラメータ                ▼
               ───▶ リセット処理           ───▶
                    (Configuration/Status/Credential)
                              │
                              ▼
               ───▶ プロパティ設定         ───▶
                              │
                              ▼
               ───▶ キャッシュ保存         ───▶ ManagementConnection
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Set-DbaCmConnection.ps1 | `public/Set-DbaCmConnection.ps1` | ソース | メイン関数 |
| Get-DbaCmConnection.ps1 | `public/Get-DbaCmConnection.ps1` | ソース | 接続取得 |
| New-DbaCmConnection.ps1 | `public/New-DbaCmConnection.ps1` | ソース | 接続作成 |
| Test-Bound.ps1 | `private/functions/Test-Bound.ps1` | ソース | パラメータ指定確認 |
| Get-DbatoolsConfigValue.ps1 | `public/Get-DbatoolsConfigValue.ps1` | ソース | 設定値取得 |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラー処理 |
