# 機能設計書 94-Get-DbaCmObject

## 概要

本ドキュメントは、WMI/CIMを使用してSQL ServerホストからWindowsシステム情報を取得するGet-DbaCmObjectコマンドの機能設計書である。

### 本機能の処理概要

Get-DbaCmObjectは、SQL ServerホストのWindows Management Instrumentation（WMI）またはCommon Information Model（CIM）クラスをクエリし、ハードウェア、オペレーティングシステム、サービス、パフォーマンスカウンターなどのシステムレベル情報を収集する機能である。複数の接続プロトコルを自動的にフォールバックし、各サーバーに対して動作するプロトコルを記憶して最適化する。

**業務上の目的・背景**：SQL Serverの監視を補完するホストレベル情報（メモリ、CPU使用率、ディスク容量、Windowsサービス状態など）の収集が必要となる。本機能はインテリジェントな接続キャッシュと認証管理により、複数サーバーにわたる一括操作を効率化する。

**機能の利用シーン**：SQL Serverホストのハードウェア情報収集、Windowsサービスの状態確認、パフォーマンスカウンターの取得、OS情報の監査、およびSQL Serverインフラストラクチャの包括的なインベントリ作成時に利用される。

**主要な処理内容**：
1. 指定されたWMI/CIMクラスまたはクエリの実行準備
2. 接続プロトコルの優先順位に従った自動フォールバック（CIM over WinRM → CIM over DCOM → WMI → PowerShell Remoting）
3. 認証情報の検証とキャッシュ管理
4. CIMエラーの解析と適切なエラーメッセージの生成
5. 成功した接続プロトコルの記憶と次回接続の最適化

**関連システム・外部連携**：WMI/CIM経由でWindowsシステム情報にアクセス。dbatoolsの接続キャッシュシステム（ConnectionHost）を使用。

**権限による制御**：対象コンピュータのWMI/CIMへのアクセス権限が必要。無効な認証情報はキャッシュされ再利用されない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | コマンドラインインターフェース | 主画面 | PowerShellコンソールまたはスクリプトから実行 |

## 機能種別

データ取得（WMI/CIMを通じたシステム情報の読み取り）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ClassName | String | Yes* | WMI/CIMクラス名（Classパラメータセット） | Queryと排他 |
| Query | String | Yes* | WQLクエリ文字列（Queryパラメータセット） | ClassNameと排他 |
| ComputerName | DbaCmConnectionParameter[] | No | 対象コンピュータ（デフォルト: ローカル） | パイプライン入力可能 |
| Credential | PSCredential | No | 代替認証情報 | - |
| Namespace | String | No | WMI名前空間（デフォルト: root\cimv2） | - |
| DoNotUse | ManagementConnectionType[] | No | 除外する接続プロトコル | CimRM, CimDCOM, Wmi, PowerShellRemoting |
| Force | Switch | No | タイムアウト保護をバイパス | - |
| SilentlyContinue | Switch | No | 接続失敗を非終了エラーに変換 | - |
| EnableException | Switch | No | 例外処理を有効化 | - |

### 入力データソース

ターゲットコンピュータのWMI/CIMクラス（例：Win32_OperatingSystem, Win32_ComputerSystem, Win32_Service等）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (動的) | ManagementObject / CimInstance | クエリされたWMI/CIMクラスに依存する |

出力プロパティはクエリ対象のクラスによって異なる：
- Win32_OperatingSystem: Name, Caption, Version, BuildNumber, FreePhysicalMemory等
- Win32_ComputerSystem: Name, Domain, Manufacturer, Model, TotalPhysicalMemory等
- Win32_Service: Name, DisplayName, State, StartMode等

### 出力先

PowerShellパイプラインに直接出力される

## 処理フロー

### 処理シーケンス

```
1. Begin処理：設定値の読み込みと内部関数定義
   └─ Resolve-CimError関数を定義
2. Process処理：各コンピュータに対してループ
   └─ 接続オブジェクトの検証と認証情報取得
3. 接続プロトコルの選択とフォールバック
   └─ CimRM → CimDCOM → Wmi → PowerShellRemoting
4. WMI/CIMクエリの実行
   └─ クラス名またはWQLクエリを実行
5. 結果のキャッシュと出力
   └─ 成功したプロトコルを記憶し結果を返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[設定読み込み・関数定義]
    B --> C{各ComputerNameをループ}
    C --> D[認証情報取得]
    D --> E{認証情報有効?}
    E -->|No| F[Stop-Function]
    F --> C
    E -->|Yes| G[接続タイプ選択]
    G --> H{CimRM試行}
    H -->|成功| I[結果出力・成功記録]
    H -->|失敗| J{CimDCOM試行}
    J -->|成功| I
    J -->|失敗| K{WMI試行}
    K -->|成功| I
    K -->|失敗| L{PSRemoting試行}
    L -->|成功| I
    L -->|失敗| M[すべて失敗・エラー]
    I --> C
    M --> C
    C -->|完了| N[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-94-1 | プロトコルフォールバック | CimRM→CimDCOM→Wmi→PowerShellRemotingの順で試行 | 接続時 |
| BR-94-2 | 無効認証情報のキャッシュ | 無効な認証情報はキャッシュされ再利用されない | 認証失敗時 |
| BR-94-3 | 成功プロトコルの記憶 | 成功したプロトコルを記憶して次回優先使用 | 接続成功時 |
| BR-94-4 | 接続キャッシュ管理 | グローバル設定でキャッシュ無効化可能 | キャッシュ更新時 |

### 計算ロジック

該当なし

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

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

本機能はSQL Serverデータベースに直接アクセスしない。WMI/CIMを通じてWindowsシステム情報を取得する。

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 2 | アクセス拒否 | 名前空間/クラスへのアクセス権限なし | 権限確認を促すメッセージ |
| 3 | 無効な名前空間 | 指定されたNamespaceが存在しない | 正しい名前空間を指定 |
| 5 | 無効なクラス名 | 指定されたClassNameが存在しない | クラス名を確認 |
| HRESULT 0x8007052e | 認証エラー | 無効な認証情報 | 認証情報をキャッシュして再利用しない |

### リトライ仕様

接続プロトコルのフォールバックにより、異なるプロトコルで自動的にリトライされる。

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

読み取り専用操作のため、トランザクション制御は不要。

## パフォーマンス要件

- 接続キャッシュにより、同一サーバーへの再接続時のパフォーマンスを最適化
- 成功したプロトコルの記憶により、次回接続時に最適なプロトコルから開始

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

- 無効な認証情報は自動的にキャッシュから除外
- WMI/CIMへのアクセス権限が必要
- Forceスイッチでタイムアウト保護をバイパス可能

## 備考

- Test-DbaCmConnectionで事前テストと最適な接続方法の構成が可能
- DoNotUseパラメータで特定のプロトコルを明示的に除外可能

---

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

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

### 推奨読解順序

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

出力されるオブジェクトはWMI/CIMクラスに依存する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaCmObject.ps1 | `public/Get-DbaCmObject.ps1` | 60-74行目の.OUTPUTSセクション |

**読解のコツ**: 出力プロパティはクエリ対象のWMI/CIMクラスに依存する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaCmObject.ps1 | `public/Get-DbaCmObject.ps1` | 86-104行目のparam block |

**主要処理フロー**:
1. **86-104行目**: パラメータ定義（ClassName/Queryのパラメータセット）
2. **106-245行目**: begin block（設定読み込み、Resolve-CimError関数定義）
3. **246-441行目**: process block（接続とクエリ実行）

#### Step 3: エラー解析を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaCmObject.ps1 | `public/Get-DbaCmObject.ps1` | 114-241行目のResolve-CimError関数 |

**主要処理フロー**:
- **165-186行目**: CIMエラーコードとメッセージのマッピング
- **193-220行目**: HRESULT別の詳細エラー処理

#### Step 4: プロトコルフォールバックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaCmObject.ps1 | `public/Get-DbaCmObject.ps1` | 291-439行目のswitch文 |

**主要処理フロー**:
- **292-320行目**: CimRM接続試行
- **323-351行目**: CimDCOM接続試行
- **354-406行目**: WMI接続試行
- **409-437行目**: PowerShellRemoting接続試行

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

```
Get-DbaCmObject
    │
    ├─ begin
    │      └─ Resolve-CimError (内部関数定義)
    │
    └─ process
           ├─ connection.GetCredential() (認証情報取得)
           ├─ connection.GetConnectionType() (プロトコル選択)
           │
           ├─ CimRM
           │      ├─ GetCimRMInstance / QueryCimRMInstance
           │      └─ ReportSuccess / AddGoodCredential
           │
           ├─ CimDCOM
           │      ├─ GetCimDCOMInstance / QueryCimDCOMInstance
           │      └─ ReportSuccess / AddGoodCredential
           │
           ├─ Wmi
           │      ├─ Get-WmiObject
           │      └─ ReportSuccess / AddGoodCredential
           │
           └─ PowerShellRemoting
                  ├─ Invoke-Command2
                  └─ ReportSuccess / AddGoodCredential
```

### データフロー図

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

ClassName/Query ───▶ プロトコル選択    ───▶ CimRM試行
ComputerName                │                  │
Credential                  ▼                  ▼
                    接続キャッシュ確認   CimDCOM試行
                           │                  │
                           ▼                  ▼
                    認証情報検証         WMI試行
                           │                  │
                           ▼                  ▼
                    WMI/CIMクエリ   PSRemoting試行
                           │                  │
                           ▼                  ▼
                    結果出力         ManagementObject /
                    キャッシュ更新   CimInstance
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaCmObject.ps1 | `public/Get-DbaCmObject.ps1` | ソース | メイン機能実装 |
| ConnectionHost.cs | `library/Dataplat.Dbatools/Connection/ConnectionHost.cs` | ソース | 接続キャッシュ管理 |
| ManagementConnection.cs | `library/Dataplat.Dbatools/Connection/ManagementConnection.cs` | ソース | 接続オブジェクト |
| Invoke-Command2.ps1 | `private/functions/Invoke-Command2.ps1` | ソース | リモートコマンド実行 |
