# 機能設計書 95-Get-DbaComputerSystem

## 概要

本ドキュメントは、SQL ServerホストのWindowsコンピュータからハードウェアおよびシステム情報を取得するGet-DbaComputerSystemコマンドの機能設計書である。

### 本機能の処理概要

Get-DbaComputerSystemは、SQL ServerをホストするWindowsコンピュータから、プロセッサ詳細、メモリ構成、ドメインメンバーシップ、ハードウェア情報などの包括的なシステム仕様を収集する機能である。

**業務上の目的・背景**：SQL Serverのキャパシティプランニング、インストール前のシステム要件確認、およびパフォーマンス問題のトラブルシューティングにおいて、ホストレベルのハードウェアインベントリデータが必要となる。本機能はCPU詳細、ハイパースレッディング状態、物理メモリ総量、ドメインロールなどを一括取得し、SQL Server環境のドキュメント化や監査に役立つ。

**機能の利用シーン**：SQL Server環境のドキュメント化、インストール/アップグレード前のシステム要件確認、ハードウェア関連のパフォーマンスボトルネック調査、AWS EC2インスタンスのメタデータ取得（クラウド環境）、および複数サーバーのハードウェアインベントリ作成時に利用される。

**主要な処理内容**：
1. 対象コンピュータのネットワーク名解決
2. WMI経由でWin32_ComputerSystemおよびWin32_Processorクラスを照会
3. ハイパースレッディング状態の判定
4. ドメインロール、管理者パスワードステータスの変換
5. オプションでAWS EC2メタデータを取得
6. 保留中の再起動状態を確認

**関連システム・外部連携**：Get-DbaCmObjectを使用してWMI情報を取得。Test-PendingRebootで再起動保留状態を確認。AWS EC2インスタンスの場合はメタデータサービス（169.254.169.254）にアクセス。

**権限による制御**：対象コンピュータへのWMIアクセス権限が必要。リモートコンピュータの場合はPowerShellリモーティング権限も必要。

## 関連画面

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

## 機能種別

データ取得（WMI経由でのシステム情報読み取り）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | DbaInstanceParameter[] | No | 対象コンピュータ（デフォルト: ローカル） | パイプライン入力可能、エイリアス: cn, host, Server |
| Credential | PSCredential | No | 代替認証情報 | - |
| IncludeAws | Switch | No | AWS EC2メタデータを取得 | - |
| EnableException | Switch | No | 例外処理を有効化 | - |

### 入力データソース

- WMI Win32_ComputerSystem クラス
- WMI Win32_Processor クラス
- AWS EC2メタデータサービス（IncludeAws指定時）
- 再起動保留状態チェック関数

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | 解決されたコンピュータ名 |
| Domain | String | 所属ドメイン名 |
| DomainRole | String | ドメインロール（Standalone Workstation等） |
| Manufacturer | String | ハードウェア製造元 |
| Model | String | ハードウェアモデル名 |
| SystemFamily | String | システムファミリー分類 |
| SystemType | String | システムタイプ（例：x64-based PC） |
| ProcessorName | String | プロセッサ名 |
| ProcessorCaption | String | プロセッサ説明 |
| ProcessorMaxClockSpeed | Int32 | 最大プロセッサクロック（MHz） |
| NumberLogicalProcessors | Int32 | 論理プロセッサ数 |
| NumberProcessors | Int32 | 物理プロセッサソケット数 |
| IsHyperThreading | Boolean | ハイパースレッディング有効かどうか |
| TotalPhysicalMemory | DbaSize | 物理メモリ総量 |
| IsSystemManagedPageFile | Boolean | システム管理ページファイルかどうか |
| PendingReboot | Boolean/Null | 再起動保留状態 |

IncludeAws指定時の追加項目：
| 項目名 | 型 | 説明 |
|--------|-----|------|
| AwsAmiId | String | AMI ID |
| AwsIamRoleArn | String | IAMインスタンスプロファイルARN |
| AwsEc2InstanceId | String | EC2インスタンスID |
| AwsEc2InstanceType | String | EC2インスタンスタイプ |
| AwsAvailabilityZone | String | 可用性ゾーン |
| AwsPublicHostName | String | パブリックホスト名 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. コンピュータ名の解決
   └─ Resolve-DbaNetworkNameでFQDNを取得
2. WMI情報の取得
   └─ Get-DbaCmObjectでWin32_ComputerSystemとWin32_Processorを取得
3. 値の変換と計算
   └─ ドメインロール、管理者パスワードステータス、ハイパースレッディング判定
4. AWS EC2メタデータの取得（オプション）
   └─ メタデータサービスから情報取得
5. 再起動保留状態の確認
   └─ Test-PendingRebootで確認
6. 結果オブジェクトの構築と出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{各ComputerNameをループ}
    B --> C[Resolve-DbaNetworkName]
    C --> D{名前解決成功?}
    D -->|No| E[Stop-Function]
    E --> B
    D -->|Yes| F[Get-DbaCmObject Win32_ComputerSystem]
    F --> G[Get-DbaCmObject Win32_Processor]
    G --> H[AdminPasswordStatus変換]
    H --> I[DomainRole変換]
    I --> J[ハイパースレッディング判定]
    J --> K{IncludeAws?}
    K -->|Yes| L[EC2メタデータ取得]
    K -->|No| M[Test-PendingReboot]
    L --> M
    M --> N[PSCustomObject構築]
    N --> O[Select-DefaultView]
    O --> B
    B -->|完了| P[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-95-1 | ハイパースレッディング判定 | NumberOfLogicalProcessors > NumberOfProcessors の場合true | 常時 |
| BR-95-2 | ドメインロール変換 | 0-5の数値を文字列に変換 | 常時 |
| BR-95-3 | AdminPasswordStatus変換 | 0-3の数値を文字列に変換（Unknown含む） | 常時 |
| BR-95-4 | AWS EC2判定 | 169.254.169.254へのアクセス成功でEC2と判定 | IncludeAws指定時 |

### 計算ロジック

ハイパースレッディング判定：
```
IsHyperThreading = (NumberOfLogicalProcessors > NumberOfProcessors)
```

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

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

本機能はSQL Serverデータベースに直接アクセスしない。

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 名前解決エラー | コンピュータ名の解決失敗 | Stop-Functionでスキップして継続 |
| - | WMIアクセスエラー | WMI情報取得失敗 | Stop-Functionでエラー記録 |
| WebException | AWS接続エラー | EC2メタデータサービスアクセス失敗 | 警告メッセージを出力 |

### リトライ仕様

リトライ機構は実装されていない。

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

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

## パフォーマンス要件

WMI呼び出しおよびネットワーク名前解決が主なボトルネック。複数サーバーに対しては順次処理される。

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

- WMIへのアクセス権限が必要
- AWS EC2メタデータはインスタンス内からのみアクセス可能
- Credentialによる代替認証情報の使用をサポート

## 備考

- TotalPhysicalMemoryはDbaSizeオブジェクトとして返却され、人間が読みやすい形式で表示される
- PendingRebootが$nullの場合は再起動状態を確認できなかったことを示す

---

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

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

### 推奨読解順序

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

出力されるPSCustomObjectの構造を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaComputerSystem.ps1 | `public/Get-DbaComputerSystem.ps1` | 184-206行目のPSCustomObject定義 |

**読解のコツ**: 出力プロパティはPSCustomObjectで明示的に定義されている。

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

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

**主要処理フロー**:
1. **93-101行目**: パラメータ定義
2. **102-220行目**: process block（メイン処理）
3. **104-111行目**: 名前解決
4. **113-119行目**: WMI情報取得

#### Step 3: 値の変換処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaComputerSystem.ps1 | `public/Get-DbaComputerSystem.ps1` | 121-138行目のswitch文（ステータス変換） |

**主要処理フロー**:
- **121-128行目**: AdminPasswordStatus変換（0-3 → 文字列）
- **130-138行目**: DomainRole変換（0-5 → 文字列）
- **140-143行目**: ハイパースレッディング判定

#### Step 4: AWS EC2処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaComputerSystem.ps1 | `public/Get-DbaComputerSystem.ps1` | 145-174行目のAWS処理 |

**主要処理フロー**:
- **146-156行目**: EC2判定（169.254.169.254アクセス）
- **158-173行目**: EC2メタデータ取得

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

```
Get-DbaComputerSystem
    │
    ├─ Resolve-DbaNetworkName (名前解決)
    │
    ├─ Get-DbaCmObject
    │      ├─ Win32_ComputerSystem
    │      └─ Win32_Processor
    │
    ├─ Invoke-Command2 (AWS EC2判定、オプション)
    │      └─ Invoke-TlsRestMethod (メタデータ取得)
    │
    ├─ Test-PendingReboot (再起動状態確認)
    │
    └─ Select-DefaultView (出力整形)
```

### データフロー図

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

ComputerName   ───▶ Resolve-DbaNetworkName ───▶ FQDN
                           │
                           ▼
                    Get-DbaCmObject
                    (Win32_ComputerSystem,
                     Win32_Processor)
                           │
                           ▼
                    値変換処理
                    (DomainRole,
                     IsHyperThreading)
                           │
                           ▼
                    AWS EC2メタデータ
                    (オプション)
                           │
                           ▼
                    PSCustomObject  ───▶ システム情報
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaComputerSystem.ps1 | `public/Get-DbaComputerSystem.ps1` | ソース | メイン機能実装 |
| Get-DbaCmObject.ps1 | `public/Get-DbaCmObject.ps1` | ソース | WMI/CIM情報取得 |
| Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | ソース | 名前解決 |
| Test-PendingReboot.ps1 | `private/functions/Test-PendingReboot.ps1` | ソース | 再起動状態確認 |
| Invoke-Command2.ps1 | `private/functions/Invoke-Command2.ps1` | ソース | リモートコマンド実行 |
