# 機能設計書 137-Get-DbaPowerPlan

## 概要

本ドキュメントは、dbatools PowerShellモジュールの`Get-DbaPowerPlan`コマンドレットに関する機能設計書です。このコマンドレットは、SQL Serverホストマシンの Windows電源プラン構成を取得し、High Performance設定を確認する機能を提供します。

### 本機能の処理概要

**業務上の目的・背景**：SQL Serverのパフォーマンスは、Windowsの電源管理設定に大きく影響されます。「バランス」や「省電力」モードでは、CPUの周波数が動的に変更されたり、アイドル時にプロセッサがスリープ状態になったりするため、データベースの応答時間に悪影響を与える可能性があります。Microsoftは、SQL Serverホストには「高パフォーマンス」電源プランの使用を推奨しています。本機能は、SQL Serverホストの電源プラン設定を監査し、ベストプラクティスへの準拠を確認できます。

**機能の利用シーン**：
- SQL Serverホストの電源プラン監査時
- パフォーマンス問題のトラブルシューティング時
- 環境アセスメント・ヘルスチェック時
- 複数サーバー間の構成比較時

**主要な処理内容**：
1. コンピュータ名の名前解決
2. WMI/CIMで電源プラン情報（Win32_PowerPlan）を取得
3. デフォルトでアクティブな電源プランのみ返却
4. -List指定時はすべての利用可能な電源プランを返却

**関連システム・外部連携**：
- WMI/CIM（Win32_PowerPlan、root\cimv2\power名前空間）
- Get-DbaCmObject（dbatools内部関数）

**権限による制御**：リモートコンピュータへの管理者権限が必要です。

## 関連画面

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

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

## 機能種別

データ取得 / 構成監査

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | DbaInstance[] | Yes | 電源プランを確認するコンピュータ名 | パイプライン入力可、Mandatory |
| Credential | PSCredential | No | リモートコンピュータへの代替資格情報 | - |
| List | switch | No | すべての利用可能な電源プランを表示 | - |
| EnableException | switch | No | 例外処理を有効化 | - |

### 入力データソース

- WMI/CIM: Win32_PowerPlan（root\cimv2\power名前空間）

## 出力仕様

### 出力データ（デフォルト）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピュータ名 |
| PowerPlan | string | アクティブな電源プラン名（例: "High Performance", "Balanced"） |

### 出力データ（-List指定時）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピュータ名 |
| PowerPlan | string | 電源プラン名 |
| IsActive | bool | この電源プランがアクティブかどうか |

### 内部保持プロパティ（非表示）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| InstanceId | string | 電源プランのGUID |
| Credential | PSCredential | 使用した資格情報 |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. 各ComputerNameに対して処理
   ├─ Test-ElevationRequirement（管理者権限確認）
   ├─ Resolve-DbaNetworkNameで名前解決
   │
   ├─ Get-DbaCmObjectでWin32_PowerPlan取得
   │     └─ 名前空間: root\cimv2\power
   │
   └─ 出力
         ├─ -List指定時: 全プランをIsActive付きで出力
         └─ デフォルト: アクティブプランのみ出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{各ComputerNameに対して}
    B --> C[Test-ElevationRequirement]
    C --> D[Resolve-DbaNetworkName]
    D --> E{名前解決成功?}
    E -->|No| F[Stop-Function・スキップ]
    F --> B
    E -->|Yes| G[Get-DbaCmObject Win32_PowerPlan]
    G --> H{取得成功?}
    H -->|No| I[Stop-Function]
    I --> B
    H -->|Yes| J{-List指定?}
    J -->|Yes| K[全プラン出力]
    J -->|No| L[アクティブプランのみ]
    K --> M[Select-DefaultView]
    L --> N[Select-DefaultView]
    M --> B
    N --> B
    B -->|完了| O[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | デフォルトはアクティブのみ | -Listなしの場合、IsActive=trueのプランのみ返却 | List未指定時 |
| BR-002 | InstanceID抽出 | GUIDをInstanceIDから抽出（{...}部分） | 常時 |
| BR-003 | 未検出時はUnknown | アクティブプランが特定できない場合、ElementName='Unknown' | アクティブプランなし時 |
| BR-004 | 名前空間指定 | Win32_PowerPlanはroot\cimv2\power名前空間に存在 | 常時 |

### 計算ロジック

InstanceID抽出：
- `$powerPlan.InstanceID.Split('{')[1].Split('}')[0]`
- 例: `Microsoft:PowerPlan\{8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c}` → `8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c`

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 名前空間エラー | root\cimv2\power名前空間未対応OS | Stop-Function（Unsupported OS） |
| - | 認証エラー | 資格情報でのログイン失敗 | Stop-Function（Login failure） |
| - | 接続エラー | WMIへの接続失敗 | Stop-Function |
| - | 名前解決エラー | ホスト名解決失敗 | Stop-Function |

### リトライ仕様

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

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

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

## パフォーマンス要件

- 各コンピュータに対してWMIクエリ1回
- 通常数秒以内で完了

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

- リモートコンピュータへの管理者権限が必要
- 資格情報はSecureStringとして保護

## 備考

- SQL Serverでは「High Performance」電源プランを推奨
- 「Balanced」モードではCPUスロットリングが発生する可能性がある
- Set-DbaPowerPlanコマンドで電源プランを変更可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaPowerPlan.ps1 | `public/Get-DbaPowerPlan.ps1` | 120-127行目: -List時の出力構造 |
| 1-2 | Get-DbaPowerPlan.ps1 | `public/Get-DbaPowerPlan.ps1` | 136-142行目: デフォルト時の出力構造 |

**読解のコツ**: -ListスイッチによってIsActiveプロパティの表示有無が変わる点に注目。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaPowerPlan.ps1 | `public/Get-DbaPowerPlan.ps1` | 74-80行目: パラメータ定義 |

**主要処理フロー**:
1. **75-76行目**: ComputerNameはMandatoryパラメータ
2. **78行目**: -Listスイッチで全プラン表示モード

#### Step 3: メイン処理フローを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaPowerPlan.ps1 | `public/Get-DbaPowerPlan.ps1` | 83-86行目: 名前解決処理 |
| 3-2 | Get-DbaPowerPlan.ps1 | `public/Get-DbaPowerPlan.ps1` | 105-115行目: Win32_PowerPlan取得とエラー処理 |
| 3-3 | Get-DbaPowerPlan.ps1 | `public/Get-DbaPowerPlan.ps1` | 117-142行目: 出力分岐処理 |

**主要処理フロー**:
- **84行目**: Test-ElevationRequirementで権限確認
- **86行目**: Resolve-DbaNetworkNameで名前解決
- **106行目**: Get-DbaCmObjectでWin32_PowerPlan取得（名前空間: root\cimv2\power）
- **117-127行目**: -List時は全プラン、119行目でInstanceID抽出
- **129行目**: デフォルトはIsActive='True'でフィルタ

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

```
Get-DbaPowerPlan
    │
    └─ process ブロック
           │
           └─ foreach ($computer in $ComputerName)
                  │
                  ├─ Test-ElevationRequirement
                  │
                  ├─ Resolve-DbaNetworkName
                  │      └─ [失敗時] Stop-Function
                  │
                  ├─ Get-DbaCmObject (Win32_PowerPlan)
                  │      └─ Namespace: root\cimv2\power
                  │      └─ [失敗時] Stop-Function (エラー種別判定)
                  │
                  └─ 出力分岐
                         │
                         ├─ [-List] 全プラン + IsActive
                         │      └─ Select-DefaultView (-Property ComputerName, PowerPlan, IsActive)
                         │
                         └─ [デフォルト] アクティブプランのみ
                                └─ Select-DefaultView (-Property ComputerName, PowerPlan)
```

### データフロー図

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

ComputerName ───────▶ Resolve-DbaNetworkName
                            │
                            ▼
                     Get-DbaCmObject
                            │
                   Win32_PowerPlan ──▶ 電源プラン一覧
                            │
                            ▼
                     フィルタ処理
                            │
            [-List] 全プラン ──┼──▶ PSCustomObject (全プラン)
        [デフォルト] アクティブのみ ──▶ PSCustomObject (アクティブのみ)
                            │
                            ▼
                     Select-DefaultView ───────▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaPowerPlan.ps1 | `public/Get-DbaPowerPlan.ps1` | ソース | メイン処理 |
| Set-DbaPowerPlan.ps1 | `public/Set-DbaPowerPlan.ps1` | ソース | 電源プラン設定（関連） |
| Test-DbaPowerPlan.ps1 | `public/Test-DbaPowerPlan.ps1` | ソース | 電源プランテスト（関連） |
| Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | ソース | 名前解決 |
| Get-DbaCmObject.ps1 | `private/functions/Get-DbaCmObject.ps1` | ソース | WMI/CIMクエリ |
| Test-ElevationRequirement.ps1 | `private/functions/Test-ElevationRequirement.ps1` | ソース | 管理者権限確認 |
| Select-DefaultView.ps1 | `private/functions/Select-DefaultView.ps1` | ソース | デフォルト表示制御 |
