# 画面設計書 123-オペレーティングシステム

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるオペレーティングシステム情報取得機能の設計仕様を定義する。SQL Serverホストマシンの詳細なOS情報（バージョン、メモリ構成、電源プラン、タイムゾーン、WSFCクラスター状態等）を包括的に収集する。

### 本画面の処理概要

**業務上の目的・背景**：SQL ServerのパフォーマンスはホストマシンのOS設定に大きく影響される。環境評価、キャパシティプランニング、パフォーマンス問題のトラブルシューティングには、OSバージョン、メモリ構成、電源プラン設定、タイムゾーン、Windows Server Failover Clustering（WSFC）状態などの詳細情報が必要である。本機能は、WMIクラスを照会してこれらの情報を収集し、複数サーバーの一括監査を可能にする。特に電源プランがHigh Performance以外に設定されている場合のCPUスロットリング問題の検出に有用である。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドレットを実行してアクセスする。
```powershell
Get-DbaOperatingSystem -ComputerName <コンピュータ名>
```

**主要な操作・処理内容**：
1. ターゲットコンピュータのネットワーク名解決
2. WS-MANによるリモート接続テスト
3. Invoke-Command2でPowerShellバージョンを取得
4. Win32_OperatingSystemクラスからOS情報を取得
5. Win32_TimeZoneクラスからタイムゾーン情報を取得
6. Win32_PowerPlanクラスからアクティブな電源プランを取得
7. Win32_SystemServicesからWSFCクラスターサービスの存在を確認
8. Get-Language関数でOS言語情報を変換
9. 結果をカスタムオブジェクトとして出力

**画面遷移**：本機能はCLIコマンドであり、GUI画面遷移は存在しない。関連コマンドとして`Get-DbaComputerSystem`でハードウェア情報を取得できる。

**権限による表示制御**：
- ローカルコンピュータの情報取得には管理者権限を推奨
- リモートコンピュータの操作にはWMIアクセス権限とWinRM権限が必要

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 136 | Get-DbaOperatingSystem | 主機能 | オペレーティングシステム情報の取得 |

## 画面種別

CLI（コマンドラインインターフェース） - 単一コマンドレット

## URL/ルーティング

PowerShellコマンドレット:
- `Get-DbaOperatingSystem`

## 入出力項目

### Get-DbaOperatingSystem パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| ComputerName | DbaInstanceParameter[] | No | $env:COMPUTERNAME | 情報を取得するコンピュータ名 |
| Credential | PSCredential | No | - | 代替資格情報 |
| EnableException | switch | No | $false | 例外を有効化 |

## 表示項目

### デフォルト表示プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| Manufacturer | string | コンピュータハードウェア製造元 |
| Organization | string | 組織名 |
| Architecture | string | プロセッサアーキテクチャ（x64/x86） |
| Version | string | Windowsバージョン識別子 |
| OSVersion | string | OSバージョンのフレンドリ名（例：Windows Server 2019 Standard） |
| LastBootTime | DateTime | 最後のシステム起動日時 |
| LocalDateTime | DateTime | システムの現在日時 |
| PowerShellVersion | string | インストールされたPowerShellバージョン |
| TimeZone | string | 現在のタイムゾーン |
| TotalVisibleMemory | DbaSize | 利用可能な物理RAM総量 |
| ActivePowerPlan | string | アクティブな電源プラン名 |
| LanguageNative | string | OSの言語（ネイティブ名） |

### 追加プロパティ（Select-Object *で表示）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| Build | string | Windowsビルド番号 |
| SPVersion | int | サービスパックバージョン |
| InstallDate | DateTime | OSインストール日時 |
| BootDevice | string | ブートデバイス |
| SystemDevice | string | システムデバイス |
| SystemDrive | string | システムドライブレター |
| WindowsDirectory | string | Windowsディレクトリパス |
| PagingFileSize | int | ページングファイルサイズ（KB） |
| FreePhysicalMemory | DbaSize | 空き物理メモリ |
| TotalVirtualMemory | DbaSize | 仮想メモリ総量 |
| FreeVirtualMemory | DbaSize | 空き仮想メモリ |
| Status | string | システム状態 |
| Language | string | OS言語の表示名 |
| LanguageId | int | LCID（ロケールID） |
| LanguageKeyboardLayoutId | string | キーボードレイアウトID |
| LanguageTwoLetter | string | 2文字ISO言語コード |
| LanguageThreeLetter | string | 3文字ISO言語コード |
| LanguageAlias | string | 言語エイリアス名 |
| CodeSet | string | コードセット文字エンコーディング |
| CountryCode | string | 国コード |
| Locale | string | ロケール識別子 |
| IsWsfc | bool/null | WSFCクラスターサービスインストール状態 |
| TimeZoneStandard | string | 標準時タイムゾーン名 |
| TimeZoneDaylight | string | 夏時間タイムゾーン名 |

## イベント仕様

### 1-オペレーティングシステム情報取得（Get-DbaOperatingSystem）

指定されたコンピュータの詳細なOS情報を取得する。

**処理フロー**:
1. `Resolve-DbaNetworkName`でコンピュータ名を解決
2. 名前解決失敗時は警告を出力しスキップ
3. `Test-WSMan`でリモーティング可否を確認
4. リモーティング可能な場合、`Invoke-Command2`でPowerShellバージョンを取得
5. `Get-DbaCmObject -ClassName Win32_OperatingSystem`でOS情報取得
6. `Get-DbaCmObject -ClassName Win32_TimeZone`でタイムゾーン情報取得
7. `Get-DbaCmObject -ClassName Win32_PowerPlan`で電源プラン情報取得
8. `Get-DbaCmObject -Class Win32_SystemServices`でシステムサービス取得
9. ClusSvcサービスの存在でWSFC状態を判定
10. `Get-Language`でOS言語情報を取得
11. 日時フィールドをDbaDateTime型に変換
12. PSCustomObjectを構築してSelect-DefaultViewで出力

## データベース更新仕様

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

### 操作別影響一覧

| 操作（イベント） | 対象リソース | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaOperatingSystem | Win32_OperatingSystem | READ | OS情報の読み取り |
| Get-DbaOperatingSystem | Win32_TimeZone | READ | タイムゾーン情報の読み取り |
| Get-DbaOperatingSystem | Win32_PowerPlan | READ | 電源プラン情報の読み取り |
| Get-DbaOperatingSystem | Win32_SystemServices | READ | システムサービス情報の読み取り |

## メッセージ仕様

| メッセージID | 種別 | メッセージ | 発生条件 |
|-------------|------|---------|---------|
| - | Warning | "Unable to resolve hostname of $computer. Skipping." | 名前解決に失敗 |
| - | Warning | "Remoting not available on $computer. Skipping checks" | WS-MANテスト失敗 |
| - | Warning | "PowerShell Version information not available on $computer." | PSバージョン取得失敗 |
| - | Warning | "Power plan information not available on $computer." | 電源プラン情報取得失敗 |
| - | Warning | "Unable to determine Cluster State of $computer." | WSFC状態判定失敗 |
| - | Error | "Failure collecting OS information on $computer" | OS情報取得失敗 |
| - | Error | "Failure collecting TimeZone information on $computer" | タイムゾーン情報取得失敗 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 名前解決失敗 | 警告メッセージを出力し、次のコンピュータの処理を継続 |
| WMI接続失敗 | Stop-Functionでエラーを出力し処理を中断 |
| 電源プラン取得失敗 | ActivePowerPlanを'Not Available'に設定して続行 |
| WSFC状態取得失敗 | IsWsfcをnullに設定して続行 |
| PowerShellバージョン取得失敗 | PowerShellVersionを'Unavailable'に設定して続行 |

## 備考

- TotalVisibleMemory等のメモリ関連プロパティはDbaSizeオブジェクトで返され、自動的に適切な単位で表示される
- 電源プランがHigh Performance以外の場合、SQL Serverのパフォーマンスに悪影響を与える可能性がある
- IsWsfcがtrueの場合、Windows Server Failover Clusteringサービス（ClusSvc）がインストールされている
- 日時情報はDbaDateTime型に変換され、一貫したフォーマットで表示される

---

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

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

### 推奨読解順序

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

出力オブジェクトのプロパティ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaOperatingSystem.ps1 | `public/Get-DbaOperatingSystem.ps1` | 行196-234のPSCustomObjectでプロパティ構造を確認 |

**読解のコツ**: Win32_OperatingSystem、Win32_TimeZone、Win32_PowerPlanの各WMIクラスからどのプロパティがマッピングされているかを確認する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaOperatingSystem.ps1 | `public/Get-DbaOperatingSystem.ps1` | processブロック（行105-236） |

**主要処理フロー**:
1. **109行**: `Resolve-DbaNetworkName`でコンピュータ名を解決
2. **119-124行**: `Test-WSMan`でリモーティング可否確認
3. **126-132行**: Credentialパラメータの処理
4. **133-143行**: `Invoke-Command2`でPowerShellバージョン取得
5. **145-150行**: `Get-DbaCmObject -ClassName Win32_OperatingSystem`
6. **152-157行**: `Get-DbaCmObject -ClassName Win32_TimeZone`
7. **159-164行**: `Get-DbaCmObject -ClassName Win32_PowerPlan`
8. **166-170行**: アクティブ電源プランの抽出
9. **172行**: `Get-Language`でOS言語情報取得
10. **174-184行**: WSFC状態判定（ClusSvcサービスの存在確認）
11. **186-194行**: 日時フィールドのDbaDateTime変換
12. **196-234行**: 出力オブジェクト構築とSelect-DefaultView

#### Step 3: 内部依存関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaCmObject | `internal/functions/Get-DbaCmObject.ps1` | WMI/CIMオブジェクト取得 |
| 3-2 | Get-Language | `internal/functions/Get-Language.ps1` | OS言語情報変換 |
| 3-3 | Resolve-DbaNetworkName | `internal/functions/Resolve-DbaNetworkName.ps1` | ネットワーク名解決 |

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

```
Get-DbaOperatingSystem
    |
    +-- Resolve-DbaNetworkName
    |      +-- DNS解決 / NetBIOS解決
    |
    +-- Test-WSMan
    |      +-- WS-MAN接続テスト
    |
    +-- Invoke-Command2
    |      +-- $PSVersionTable.PSVersion取得
    |
    +-- Get-DbaCmObject -ClassName Win32_OperatingSystem
    |
    +-- Get-DbaCmObject -ClassName Win32_TimeZone
    |
    +-- Get-DbaCmObject -ClassName Win32_PowerPlan
    |
    +-- Get-DbaCmObject -Class Win32_SystemServices
    |      +-- ClusSvc存在チェック (WSFC判定)
    |
    +-- Get-Language
    |      +-- OSLanguage LCID → 言語情報変換
    |
    +-- [PSCustomObject] 出力オブジェクト構築
    |
    +-- Select-DefaultView
```

### データフロー図

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

ComputerName ──────────> Resolve-DbaNetworkName ─────────>
                                |
                                v
                        Test-WSMan ──────────────────────>
                                |
                                v
                        Invoke-Command2 ─────────────────> PowerShellVersion
                                |
                                v
                        Get-DbaCmObject ─────────────────>
                        (Win32_OperatingSystem)
                                |
                                v
                        Get-DbaCmObject ─────────────────>
                        (Win32_TimeZone)
                                |
                                v
                        Get-DbaCmObject ─────────────────>
                        (Win32_PowerPlan)
                                |
                                v
                        Get-DbaCmObject ─────────────────> IsWsfc
                        (Win32_SystemServices)
                                |
                                v
                        Get-Language ────────────────────> Language*
                                |
                                v
                        PSCustomObject ──────────────────> 出力

[出力オブジェクト]
    ComputerName, OSVersion, Architecture, LastBootTime,
    TotalVisibleMemory, ActivePowerPlan, TimeZone, IsWsfc, ...
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaOperatingSystem.ps1 | `public/Get-DbaOperatingSystem.ps1` | ソース | OS情報取得コマンド |
| Get-DbaCmObject.ps1 | `internal/functions/Get-DbaCmObject.ps1` | 内部関数 | WMI/CIMオブジェクト取得 |
| Get-Language.ps1 | `internal/functions/Get-Language.ps1` | 内部関数 | 言語情報変換 |
| Resolve-DbaNetworkName.ps1 | `internal/functions/Resolve-DbaNetworkName.ps1` | 内部関数 | ネットワーク名解決 |
| Invoke-Command2.ps1 | `internal/functions/Invoke-Command2.ps1` | 内部関数 | リモートコマンド実行 |
