# 機能設計書 136-Get-DbaOperatingSystem

## 概要

本ドキュメントは、dbatools PowerShellモジュールの`Get-DbaOperatingSystem`コマンドレットに関する機能設計書です。このコマンドレットは、SQL Serverホストマシンから包括的なWindowsオペレーティングシステム情報を取得する機能を提供します。

### 本機能の処理概要

**業務上の目的・背景**：SQL Serverのパフォーマンスと安定性は、ホストOSの構成に大きく依存します。OSバージョン、メモリ構成、電源プラン、タイムゾーン、クラスター構成などの情報は、環境アセスメント、キャパシティプランニング、パフォーマンストラブルシューティングに不可欠です。本機能は、ローカルまたはリモートのWindowsコンピュータから詳細なOS情報を収集し、SQL Server環境の包括的な理解を支援します。

**機能の利用シーン**：
- SQL Server環境アセスメント・監査時
- キャパシティプランニング・リソース見積もり時
- パフォーマンス問題のトラブルシューティング時
- 複数サーバー間の構成比較時
- フェイルオーバークラスター構成の確認時

**主要な処理内容**：
1. コンピュータ名の名前解決
2. WMI/CIMでOS情報（Win32_OperatingSystem）を取得
3. WMI/CIMでタイムゾーン情報（Win32_TimeZone）を取得
4. WMI/CIMで電源プラン情報（Win32_PowerPlan）を取得
5. PowerShellバージョン情報をリモート取得
6. クラスターサービス状態を確認
7. すべての情報をPSCustomObjectとして出力

**関連システム・外部連携**：
- WMI/CIM（Win32_OperatingSystem, Win32_TimeZone, Win32_PowerPlan, Win32_SystemServices）
- PowerShell Remoting（Invoke-Command2）
- Get-DbaCmObject（dbatools内部関数）

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

## 関連画面

本機能はコマンドラインツールであり、画面機能マッピングに該当する関連画面はありません。

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | PowerShellコマンドラインで実行 |

## 機能種別

データ取得 / システム情報収集

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | DbaInstanceParameter[] | No | OS情報を取得するコンピュータ名。デフォルトはローカル | パイプライン入力可、エイリアス: cn, host, Server |
| Credential | PSCredential | No | リモートコンピュータへの代替資格情報 | - |
| EnableException | switch | No | 例外処理を有効化 | - |

### 入力データソース

- WMI/CIM: Win32_OperatingSystem（OS情報）
- WMI/CIM: Win32_TimeZone（タイムゾーン）
- WMI/CIM: Win32_PowerPlan（電源プラン）
- WMI/CIM: Win32_SystemServices（クラスターサービス）
- PowerShell Remoting: $PSVersionTable.PSVersion

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 | デフォルト表示 |
|--------|-----|------|--------------|
| ComputerName | string | コンピュータ名 | Yes |
| Manufacturer | string | ハードウェア製造元 | Yes |
| Organization | string | 組織名 | Yes |
| Architecture | string | プロセッサアーキテクチャ（x64/x86） | Yes |
| Version | string | Windowsバージョン | Yes |
| Build | string | ビルド番号 | No |
| OSVersion | string | OS表示名（例: Windows Server 2019 Standard） | Yes |
| SPVersion | int | サービスパックバージョン | No |
| InstallDate | datetime | OSインストール日時 | No |
| LastBootTime | datetime | 最終起動日時 | Yes |
| LocalDateTime | datetime | システムのローカル日時 | Yes |
| PowerShellVersion | string | PowerShellバージョン | Yes |
| TimeZone | string | タイムゾーン表示名 | Yes |
| TimeZoneStandard | string | 標準時間名 | No |
| TimeZoneDaylight | string | 夏時間名 | No |
| BootDevice | string | ブートデバイス | No |
| SystemDevice | string | システムデバイス | No |
| SystemDrive | string | システムドライブ | No |
| WindowsDirectory | string | Windowsディレクトリ | No |
| PagingFileSize | int | ページファイルサイズ(KB) | No |
| TotalVisibleMemory | DbaSize | 合計物理メモリ | Yes |
| FreePhysicalMemory | DbaSize | 空き物理メモリ | No |
| TotalVirtualMemory | DbaSize | 合計仮想メモリ | No |
| FreeVirtualMemory | DbaSize | 空き仮想メモリ | No |
| ActivePowerPlan | string | アクティブな電源プラン | Yes |
| Status | string | システムステータス | No |
| Language | string | OS言語名 | No |
| LanguageId | int | 言語ID(LCID) | No |
| LanguageKeyboardLayoutId | int | キーボードレイアウトID | No |
| LanguageTwoLetter | string | 2文字言語コード | No |
| LanguageThreeLetter | string | 3文字言語コード | No |
| LanguageAlias | string | 言語エイリアス | No |
| LanguageNative | string | ネイティブ言語名 | Yes |
| CodeSet | string | コードセット | No |
| CountryCode | string | 国コード | No |
| Locale | string | ロケール | No |
| IsWsfc | bool | Windowsフェイルオーバークラスタリング有効か | No |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. 各ComputerNameに対して処理
   ├─ Resolve-DbaNetworkNameで名前解決
   ├─ Test-WSManでWSMan接続テスト
   │
   ├─ PowerShellバージョン取得
   │     └─ Invoke-Command2でリモート取得
   │
   ├─ Win32_OperatingSystem取得
   │     └─ Get-DbaCmObjectでWMI/CIMクエリ
   │
   ├─ Win32_TimeZone取得
   │     └─ Get-DbaCmObjectでWMI/CIMクエリ
   │
   ├─ Win32_PowerPlan取得
   │     └─ Get-DbaCmObjectでWMI/CIMクエリ
   │
   ├─ 言語情報取得
   │     └─ Get-Language内部関数
   │
   ├─ クラスターサービス確認
   │     └─ Win32_SystemServicesでClusSvc検索
   │
   └─ PSCustomObject出力
         └─ Select-DefaultViewでデフォルト表示制御
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{各ComputerNameに対して}
    B --> C[Resolve-DbaNetworkName]
    C --> D{名前解決成功?}
    D -->|No| E[警告・スキップ]
    E --> B
    D -->|Yes| F[Test-WSMan]
    F --> G[Get-DbaCmObject Win32_OperatingSystem]
    G --> H{OS取得成功?}
    H -->|No| I[Stop-Function]
    I --> B
    H -->|Yes| J[Get-DbaCmObject Win32_TimeZone]
    J --> K[Get-DbaCmObject Win32_PowerPlan]
    K --> L[Win32_SystemServices クラスター確認]
    L --> M[Get-Language]
    M --> N[PSCustomObject構築]
    N --> O[Select-DefaultView]
    O --> B
    B -->|完了| P[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 名前解決必須 | Resolve-DbaNetworkNameで名前解決失敗時はスキップ | 常時 |
| BR-002 | メモリサイズ変換 | KB単位をDbaSize型（バイト変換）で出力 | 常時 |
| BR-003 | 電源プラン不取得時 | 'Not Available'を設定 | 電源プラン取得失敗時 |
| BR-004 | PowerShellバージョン不明 | WSMan無効時は'Unknown'、取得失敗時は'Unavailable' | 該当時 |
| BR-005 | クラスター判定 | ClusSvcサービスの存在でIsWsfcを判定 | 常時 |

### 計算ロジック

メモリサイズ変換：
- WMIのTotalVisibleMemorySize（KB単位）を1024倍してバイトに変換
- [DbaSize]型でフォーマット（GB, MB等の自動変換）

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

本機能はデータベースへの直接操作を行いません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 名前解決エラー | ホスト名解決失敗 | 警告出力・スキップ |
| - | OS情報取得エラー | Win32_OperatingSystem取得失敗 | Stop-Function |
| - | タイムゾーン取得エラー | Win32_TimeZone取得失敗 | Stop-Function |
| - | 電源プラン取得エラー | Win32_PowerPlan取得失敗 | 警告出力・値をnull |
| - | クラスター確認エラー | Win32_SystemServices取得失敗 | 警告出力・IsWsfc=null |

### リトライ仕様

リトライ処理は実装されていません。

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

データベース操作がないため、トランザクション管理は不要です。

## パフォーマンス要件

- 各コンピュータに対してWMIクエリ4-5回実行
- リモートコンピュータへのアクセスはネットワーク状況に依存
- 通常数秒以内で完了

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

- リモートコンピュータへのWindows管理者権限が必要
- 資格情報はSecureStringとして保護
- WMI/CIMアクセスにはDCOMまたはWSManが必要

## 備考

- デフォルト表示は12項目に制限、`Select-Object *`で全項目表示可能
- DbaSize型はGB/MB/KB等の単位を自動選択して表示
- 日時情報はDbaDateTime型で一貫したフォーマット

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaOperatingSystem.ps1 | `public/Get-DbaOperatingSystem.ps1` | 196-234行目: PSCustomObject構築 |

**読解のコツ**: DbaSize型とDbaDateTime型によるデータフォーマットに注目。

#### Step 2: データ収集処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaOperatingSystem.ps1 | `public/Get-DbaOperatingSystem.ps1` | 109-117行目: 名前解決処理 |
| 2-2 | Get-DbaOperatingSystem.ps1 | `public/Get-DbaOperatingSystem.ps1` | 126-132行目: Get-DbaCmObjectパラメータ構築 |
| 2-3 | Get-DbaOperatingSystem.ps1 | `public/Get-DbaOperatingSystem.ps1` | 145-150行目: Win32_OperatingSystem取得 |
| 2-4 | Get-DbaOperatingSystem.ps1 | `public/Get-DbaOperatingSystem.ps1` | 152-157行目: Win32_TimeZone取得 |
| 2-5 | Get-DbaOperatingSystem.ps1 | `public/Get-DbaOperatingSystem.ps1` | 159-164行目: Win32_PowerPlan取得 |

**主要処理フロー**:
1. **109行目**: Resolve-DbaNetworkNameで名前解決
2. **120行目**: Test-WSManでWSMan接続確認
3. **133-143行目**: PowerShellバージョン取得（Invoke-Command2）
4. **146行目**: Get-DbaCmObjectでWin32_OperatingSystem取得

#### Step 3: 補助処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaOperatingSystem.ps1 | `public/Get-DbaOperatingSystem.ps1` | 172行目: Get-Language関数呼び出し |
| 3-2 | Get-DbaOperatingSystem.ps1 | `public/Get-DbaOperatingSystem.ps1` | 174-184行目: クラスターサービス確認 |

**主要処理フロー**:
- **172行目**: Get-LanguageでOSLanguageからカルチャ情報取得
- **176行目**: Win32_SystemServicesでClusSvcの存在確認

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

```
Get-DbaOperatingSystem
    │
    └─ process ブロック
           │
           └─ foreach ($computer in $ComputerName)
                  │
                  ├─ Resolve-DbaNetworkName
                  │
                  ├─ Test-WSMan
                  │
                  ├─ [WSMan有効時] Invoke-Command2
                  │      └─ $PSVersionTable.PSVersion
                  │
                  ├─ Get-DbaCmObject (Win32_OperatingSystem)
                  │
                  ├─ Get-DbaCmObject (Win32_TimeZone)
                  │
                  ├─ Get-DbaCmObject (Win32_PowerPlan)
                  │
                  ├─ Get-Language
                  │
                  ├─ Get-DbaCmObject (Win32_SystemServices)
                  │
                  └─ PSCustomObject出力
                         └─ Select-DefaultView
```

### データフロー図

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

ComputerName ───────▶ Resolve-DbaNetworkName
                            │
                            ▼
                     Get-DbaCmObject
                            │
    Win32_OperatingSystem ──┼──▶ OS情報
    Win32_TimeZone ─────────┼──▶ タイムゾーン
    Win32_PowerPlan ────────┼──▶ 電源プラン
    Win32_SystemServices ───┼──▶ クラスター状態
                            │
    Invoke-Command2 ────────┼──▶ PSバージョン
                            │
    Get-Language ───────────┼──▶ 言語情報
                            │
                            ▼
                     PSCustomObject ───────▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaOperatingSystem.ps1 | `public/Get-DbaOperatingSystem.ps1` | ソース | メイン処理 |
| Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | ソース | 名前解決 |
| Get-DbaCmObject.ps1 | `private/functions/Get-DbaCmObject.ps1` | ソース | WMI/CIMクエリ |
| Invoke-Command2.ps1 | `private/functions/Invoke-Command2.ps1` | ソース | リモート実行 |
| Get-Language.ps1 | `private/functions/Get-Language.ps1` | ソース | 言語情報取得 |
| Select-DefaultView.ps1 | `private/functions/Select-DefaultView.ps1` | ソース | デフォルト表示制御 |
