# 機能設計書 185-New-DbaCmConnection

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `New-DbaCmConnection` コマンドレットの機能設計書である。このコマンドレットは、CIM/WMIプロトコルを使用したリモートコンピュータ管理用の接続オブジェクトを作成および構成する機能を提供する。

### 本機能の処理概要

本機能は、SQL Server環境でのリモートコンピュータ管理を最適化するための接続オブジェクトを作成する。CIMおよびWMIプロトコルを使用した接続の資格情報、優先プロトコル（CIM over WinRMまたはDCOM）、フェイルオーバー動作などを事前に構成し、キャッシュに保存する。これにより、複数のSQL Serverインスタンスに対してdbtoolsコマンドを実行する際の認証エラーを削減し、パフォーマンスを向上させる。

**業務上の目的・背景**：リモートSQL Serverホストに対してdbtoolsコマンドを実行する際、各接続で認証方法やプロトコルの自動検出が行われる。これは繰り返し実行される場合に非効率であり、認証エラーが発生する可能性もある。本機能により、接続設定を事前に構成してキャッシュし、後続の操作で再利用することで効率化を実現する。

**機能の利用シーン**：
- 複数のSQL Serverホストへの一括接続設定
- 特定の認証方法やプロトコルの強制
- CIM/WMI接続の事前構成
- 接続キャッシュの管理
- ファイアウォールでブロックされたプロトコルの無効化

**主要な処理内容**：
1. コンピュータ名の検証と解決
2. ManagementConnectionオブジェクトの作成
3. 資格情報、プロトコル設定の適用
4. CIMセッションオプションの構成
5. 接続キャッシュへの登録
6. 接続オブジェクトの返却

**関連システム・外部連携**：CIM/WMI、WinRM、DCOM、dbatools接続キャッシュ

**権限による制御**：リモートコンピュータへの管理者権限またはWMI/CIMアクセス権が必要

## 関連画面

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

## 機能種別

接続管理 / 構成管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | DbaCmConnectionParameter[] | No | 接続を作成するコンピュータ名 | パイプラインから入力可能、デフォルトはローカル |
| Credential | PSCredential | No | 登録する資格情報 | ParameterSet=Credential |
| UseWindowsCredentials | switch | No | 現在のWindows資格情報を使用 | ParameterSet=Windows |
| OverrideExplicitCredential | switch | No | 明示的資格情報よりキャッシュを優先 | - |
| DisabledConnectionTypes | ManagementConnectionType | No | 無効にする接続プロトコル | デフォルトはNone |
| DisableBadCredentialCache | switch | No | 失敗した資格情報のキャッシュを無効化 | - |
| DisableCimPersistence | switch | No | CIMセッションの再利用を無効化 | - |
| DisableCredentialAutoRegister | switch | No | 成功した資格情報の自動登録を無効化 | - |
| EnableCredentialFailover | switch | No | 失敗時にキャッシュされた資格情報を使用 | - |
| WindowsCredentialsAreBad | switch | No | Windows資格情報を無効としてマーク | ParameterSet=Credential |
| CimWinRMOptions | WSManSessionOptions | No | CIM over WinRMのセッションオプション | - |
| CimDCOMOptions | DComSessionOptions | No | DCOM CIMのセッションオプション | - |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- ユーザー入力（パラメータ指定）
- パイプライン入力（ComputerName）
- dbatools構成設定（キャッシュ無効化設定）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | 接続先コンピュータ名 |
| Credentials | PSCredential | 認証用資格情報 |
| UseWindowsCredentials | bool | Windows資格情報使用フラグ |
| OverrideExplicitCredential | bool | 明示的資格情報オーバーライドフラグ |
| DisabledConnectionTypes | ManagementConnectionType | 無効化された接続タイプ |
| DisableBadCredentialCache | bool | 不正資格情報キャッシュ無効化フラグ |
| DisableCimPersistence | bool | CIM永続化無効化フラグ |
| DisableCredentialAutoRegister | bool | 資格情報自動登録無効化フラグ |
| WindowsCredentialsAreBad | bool | Windows資格情報無効フラグ |
| CimWinRMOptions | WSManSessionOptions | WinRMセッションオプション |
| CimDCOMOptions | DComSessionOptions | DCOMセッションオプション |

### 出力先

PowerShellパイプライン（Dataplat.Dbatools.Connection.ManagementConnectionオブジェクト）

## 処理フロー

### 処理シーケンス

```
1. beginブロック処理
   └─ キャッシュ無効化設定の取得
2. processブロック処理
   └─ 各ComputerNameを処理
3. コンピュータ名検証
   └─ DbaCmConnectionParameterの検証
4. ManagementConnectionオブジェクト作成
   └─ New-Objectで接続オブジェクト生成
5. 各種設定の適用
   └─ Credential/UseWindowsCredentials
   └─ OverrideExplicitCredential
   └─ DisabledConnectionTypes
   └─ DisableBadCredentialCache
   └─ DisableCimPersistence
   └─ DisableCredentialAutoRegister
   └─ WindowsCredentialsAreBad
   └─ CimWinRMOptions/CimDCOMOptions
6. 接続キャッシュへの登録（無効化されていない場合）
7. 接続オブジェクトの出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[キャッシュ無効化設定取得]
    B --> C[各ComputerNameを処理]
    C --> D{ShouldProcess?}
    D -->|No| E[スキップ]
    D -->|Yes| F{ComputerName有効?}
    F -->|No| G[Stop-Function]
    F -->|Yes| H[ManagementConnection作成]
    H --> I[Credential設定]
    I --> J[UseWindowsCredentials設定]
    J --> K[各種フラグ設定]
    K --> L[CIMオプション設定]
    L --> M{キャッシュ有効?}
    M -->|Yes| N[ConnectionHostに登録]
    M -->|No| O[スキップ]
    N --> P[接続オブジェクト出力]
    O --> P
    E --> P
    G --> P
    P --> Q[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | キャッシュ上書き | 同名コンピュータの既存接続は新規設定で上書き | 常時 |
| BR-002 | 自動キャッシュ | キャッシュが無効化されていない限り自動的にキャッシュに登録 | デフォルト動作 |
| BR-003 | デフォルトCIMオプション | 未指定時はNew-DbaCimSessionOptionWithTimeoutでデフォルト生成 | CIMオプション未指定時 |
| BR-004 | 相互排他パラメータ | CredentialとUseWindowsCredentialsは排他（ParameterSet） | 常時 |

### 計算ロジック

特になし

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

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

本機能は接続オブジェクトの作成のみを行い、直接的なデータベース操作は行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| InvalidArgument | 入力エラー | コンピュータ名の解決失敗 | 正しいコンピュータ名を指定 |

### リトライ仕様

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

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

トランザクション管理なし（接続オブジェクトの作成とキャッシュ登録のみ）

## パフォーマンス要件

- 接続オブジェクトの作成は即座に完了
- キャッシュにより後続の接続操作が高速化

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

- 資格情報はPSCredentialで安全に管理
- キャッシュされた接続情報はセッション内でのみ有効
- 不正資格情報のキャッシュを無効化可能

## 備考

- 作成された接続オブジェクトはGet-DbaCmObjectなどで自動的に使用される
- 通常はdbtoolsコマンドが自動的にデフォルト接続を作成するため、本コマンドはオプション
- 特定の認証やプロトコル設定が必要な場合に使用

---

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

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

### 推奨読解順序

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

パラメータ定義と出力型を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | New-DbaCmConnection.ps1 | `public/New-DbaCmConnection.ps1` | 144-175行目のparamブロック |

**読解のコツ**: ParameterSetName（Credential/Windows）で資格情報の指定方法が分かれている。DisabledConnectionTypesはdbatools独自のManagementConnectionType型。

#### Step 2: 初期化処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaCmConnection.ps1 | `public/New-DbaCmConnection.ps1` | 176-181行目のbeginブロック |

**主要処理フロー**:
- **180行目**: Get-DbatoolsConfigValueでキャッシュ無効化設定を取得

#### Step 3: 接続オブジェクト作成処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaCmConnection.ps1 | `public/New-DbaCmConnection.ps1` | 182-218行目のprocessブロック |

**主要処理フロー**:
- **184行目**: ShouldProcess確認
- **185行目**: コンピュータ名検証
- **188行目**: ManagementConnectionオブジェクト作成
- **189-210行目**: 各種プロパティの設定（Test-Boundでバインド確認）
- **212-215行目**: キャッシュへの登録（ConnectionHost.Connections）

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

```
New-DbaCmConnection
    │
    ├─ Get-DbatoolsConfigValue
    │      └─ キャッシュ無効化設定の取得
    │
    ├─ New-Object ManagementConnection
    │      └─ 接続オブジェクトの生成
    │
    ├─ New-DbaCimSessionOptionWithTimeout
    │      └─ CIMセッションオプションのデフォルト生成
    │
    └─ [Dataplat.Dbatools.Connection.ConnectionHost]::Connections
           └─ 接続キャッシュへの登録
```

### データフロー図

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

ComputerName ─────────▶ 検証・解決
Credential ───────────▶ ManagementConnection
UseWindowsCredentials ▶    オブジェクト作成
                              │
                              ▼
各種フラグ ───────────▶ プロパティ設定
CimWinRMOptions ──────▶    │
CimDCOMOptions ───────▶    │
                              │
                              ▼
                       ConnectionHost.Connections
                       (キャッシュ登録)
                              │
                              ▼
                       ManagementConnection ─────────▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaCmConnection.ps1 | `public/New-DbaCmConnection.ps1` | ソース | メイン機能の実装 |
| Get-DbaCmConnection.ps1 | `public/Get-DbaCmConnection.ps1` | ソース | 接続の取得 |
| Remove-DbaCmConnection.ps1 | `public/Remove-DbaCmConnection.ps1` | ソース | 接続の削除 |
| Set-DbaCmConnection.ps1 | `public/Set-DbaCmConnection.ps1` | ソース | 接続の更新 |
| Get-DbaCmObject.ps1 | `public/Get-DbaCmObject.ps1` | ソース | 接続を使用したCIMオブジェクト取得 |
