# 画面設計書 126-電源プラン

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける電源プラン管理機能の設計仕様を定義する。SQL Serverホストマシンの電源プラン設定を取得、テスト、変更し、パフォーマンスの最適化を支援する。

### 本画面の処理概要

**業務上の目的・背景**：SQL Serverのパフォーマンスは、WindowsのPower Plan設定に大きく影響される。「バランス」や「省電力」モードでは、CPUのクロック周波数が動的に制限され、クエリ応答時間の遅延やスループットの低下を引き起こす。Microsoftは、SQL Serverホストに「高パフォーマンス」電源プランを推奨している。本機能群は、電源プラン設定の監査、ベストプラクティス準拠の検証、必要に応じた設定変更を自動化する。

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

**主要な操作・処理内容**：
1. **Get-DbaPowerPlan**: Win32_PowerPlan（root\cimv2\power名前空間）を照会してアクティブな電源プランを取得
2. **Test-DbaPowerPlan**: アクティブな電源プランを推奨プラン（デフォルト: High Performance）と比較してベストプラクティス準拠を判定
3. **Set-DbaPowerPlan**: PowerSetActiveScheme Windows APIを使用して電源プランを変更

**画面遷移**：本機能はCLIコマンドであり、GUI画面遷移は存在しない。Get-DbaPowerPlan → Test-DbaPowerPlan → Set-DbaPowerPlanの順でパイプライン処理が可能。

**権限による表示制御**：
- ローカルコンピュータの情報取得には管理者権限を推奨
- リモートコンピュータの操作にはWMIアクセス権限とPowerShellリモーティング権限が必要
- 電源プランの変更には管理者権限が必須

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 137 | Get-DbaPowerPlan | 主機能 | 電源プランの取得 |
| 228 | Set-DbaPowerPlan | 主機能 | 電源プランの設定 |
| 253 | Test-DbaPowerPlan | 補助機能 | 電源プランのテスト |

## 画面種別

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

## URL/ルーティング

PowerShellコマンドレット:
- `Get-DbaPowerPlan`
- `Test-DbaPowerPlan`
- `Set-DbaPowerPlan`

## 入出力項目

### Get-DbaPowerPlan パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| ComputerName | DbaInstance[] | Yes | - | 情報を取得するコンピュータ名 |
| Credential | PSCredential | No | - | 代替Windows資格情報 |
| List | switch | No | $false | 全電源プランを表示 |
| EnableException | switch | No | $false | 例外を有効化 |

### Test-DbaPowerPlan パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| ComputerName | DbaInstance[] | Yes | - | テスト対象のコンピュータ名 |
| Credential | PSCredential | No | - | 代替Windows資格情報 |
| PowerPlan | string | No | High Performance | テスト対象の推奨電源プラン |
| EnableException | switch | No | $false | 例外を有効化 |

### Set-DbaPowerPlan パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| ComputerName | DbaInstance[] | Yes | - | 設定対象のコンピュータ名 |
| Credential | PSCredential | No | - | 代替Windows資格情報 |
| PowerPlan | string | No | High Performance | 設定する電源プラン名 |
| EnableException | switch | No | $false | 例外を有効化 |
| WhatIf | switch | No | - | 実行内容のプレビュー |
| Confirm | switch | No | - | 実行前の確認 |

## 表示項目

### Get-DbaPowerPlan 出力プロパティ（デフォルト）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| PowerPlan | string | アクティブな電源プラン名 |

### Get-DbaPowerPlan 出力プロパティ（-List指定時）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceId | string | 電源プランのGUID |
| PowerPlan | string | 電源プラン名 |
| IsActive | bool | アクティブかどうか |

### Test-DbaPowerPlan 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| ActiveInstanceId | string | アクティブな電源プランのGUID |
| ActivePowerPlan | string | アクティブな電源プラン名 |
| RecommendedInstanceId | string | 推奨電源プランのGUID |
| RecommendedPowerPlan | string | 推奨電源プラン名 |
| IsBestPractice | bool | ベストプラクティスに準拠しているか |

### Set-DbaPowerPlan 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| PreviousInstanceId | string | 変更前の電源プランGUID |
| PreviousPowerPlan | string | 変更前の電源プラン名 |
| ActiveInstanceId | string | 現在の電源プランGUID |
| ActivePowerPlan | string | 現在の電源プラン名 |
| IsChanged | bool | 変更されたかどうか |

## イベント仕様

### 1-電源プラン取得（Get-DbaPowerPlan）

アクティブな電源プランまたは全電源プランを取得する。

**処理フロー**:
1. `Test-ElevationRequirement`で管理者権限を確認
2. `Resolve-DbaNetworkName`でコンピュータ名を解決
3. `Get-DbaCmObject -ClassName Win32_PowerPlan -Namespace "root\cimv2\power"`で電源プラン取得
4. Listパラメータ指定時は全電源プランを返す
5. 未指定時はIsActive=Trueの電源プランのみ返す
6. InstanceIDからGUIDを抽出（{...}形式から純粋なGUIDへ変換）
7. PSCustomObjectを構築してSelect-DefaultViewで出力

### 2-電源プランテスト（Test-DbaPowerPlan）

電源プランがベストプラクティスに準拠しているか検証する。

**処理フロー**:
1. `Get-DbaPowerPlan -List`で全電源プランを取得
2. PowerPlanパラメータ指定時はその名前で推奨プランを検索
3. 未指定時はHigh Performance（GUID: 8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c）を推奨プランとする
4. 推奨プランが見つからない場合はエラーメッセージを設定
5. アクティブな電源プランのInstanceIDと推奨プランのInstanceIDを比較
6. 一致すればIsBestPractice=True、不一致ならFalse
7. PSCustomObjectを構築してSelect-DefaultViewで出力

### 3-電源プラン設定（Set-DbaPowerPlan）

電源プランを変更する。

**処理フロー**:
1. `Test-DbaPowerPlan`で現在の状態と推奨プランを確認
2. 推奨プランが存在しない場合はエラーで終了
3. 既にベストプラクティスに準拠している場合はスキップ
4. ShouldProcessで変更確認
5. `Resolve-DbaNetworkName`でコンピュータ名を解決
6. `Invoke-Command2`で`PowerSetActiveScheme` Windows APIを呼び出し
7. 戻り値が0でなければエラー
8. 成功時はIsChanged=Trueを設定
9. PSCustomObjectを構築してSelect-DefaultViewで出力

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

本機能はSQL Serverデータベースにはアクセスしない。WMI経由でWindowsシステム設定を取得・変更する。

### 操作別影響一覧

| 操作（イベント） | 対象リソース | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaPowerPlan | Win32_PowerPlan | READ | 電源プラン情報の読み取り |
| Test-DbaPowerPlan | Win32_PowerPlan | READ | 電源プラン情報の読み取り |
| Set-DbaPowerPlan | Windows Power Settings | UPDATE | 電源プランの変更 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ | 発生条件 |
|-------------|------|---------|---------|
| - | Error | "Can't get Power Plan Info for $computer. Unsupported operating system." | 名前空間が見つからない |
| - | Error | "Can't get Power Plan Info for $computer. Login failure for $($Credential.UserName)." | 認証失敗 |
| - | Error | "Can't get Power Plan Info for $computer. Check logs for more details." | その他のエラー |
| - | Error | "You do not have the Power Plan '$PowerPlan' installed on $computer. Skipping." | 指定プランが存在しない |
| - | Error | "Couldn't set the requested Power Plan '$powerPlanRequested' on $computer (ReturnCode: $returnCode)." | API呼び出し失敗 |
| - | Verbose | "PowerPlan on $computer is already set to $powerPlanRequested. Skipping." | 既に設定済み |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 名前解決失敗 | Stop-Functionでエラーを出力し、次のコンピュータの処理を継続 |
| WMI名前空間エラー | 非サポートOSとしてエラーを出力 |
| 認証失敗 | ログイン失敗エラーを出力 |
| 指定電源プランが存在しない | スキップして次のコンピュータへ |
| PowerSetActiveScheme失敗 | 戻り値と共にエラーを出力 |

## 備考

- High Performance電源プランのGUIDは`8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c`（全Windowsで共通）
- 電源プラン検出が失敗した場合、PowerPlanプロパティは"Unknown"となる
- Set-DbaPowerPlanはSupportsShouldProcessを実装しており、-WhatIfと-Confirmが使用可能
- Win32_PowerPlanは`root\cimv2\power`名前空間に存在（通常のroot\cimv2ではない）
- 電源プラン変更にはpowrprof.dllのPowerSetActiveScheme関数を使用

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaPowerPlan.ps1 | `public/Get-DbaPowerPlan.ps1` | 行120-126, 136-141のPSCustomObjectで出力構造を確認 |
| 1-2 | Test-DbaPowerPlan.ps1 | `public/Test-DbaPowerPlan.ps1` | 行143-151のPSCustomObjectで出力構造を確認 |
| 1-3 | Set-DbaPowerPlan.ps1 | `public/Set-DbaPowerPlan.ps1` | 行132-139のPSCustomObjectで出力構造を確認 |

**読解のコツ**: InstanceIDの形式変換（{GUID}からGUIDへ）に注意。

#### Step 2: エントリーポイントを理解する（Get-DbaPowerPlan）

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

**主要処理フロー**:
1. **84行**: Test-ElevationRequirementで権限確認
2. **86-92行**: Resolve-DbaNetworkNameでコンピュータ名解決
3. **94-101行**: Get-DbaCmObject用のsplatパラメータ構築
4. **105-115行**: Win32_PowerPlanの取得とエラーハンドリング
5. **117-127行**: Listパラメータ指定時の全プラン出力
6. **128-142行**: アクティブプランのみの出力

#### Step 3: Test-DbaPowerPlanを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Test-DbaPowerPlan.ps1 | `public/Test-DbaPowerPlan.ps1` | processブロック（行103-153） |

**主要処理フロー**:
1. **96-100行**: High PerformanceのデフォルトGUIDを設定
2. **106-116行**: Get-DbaPowerPlan -Listで全プラン取得
3. **118-132行**: 推奨プランの決定（カスタムまたはHigh Performance）
4. **134-141行**: IsBestPractice判定
5. **143-151行**: 出力オブジェクト構築

#### Step 4: Set-DbaPowerPlanを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Set-DbaPowerPlan.ps1 | `public/Set-DbaPowerPlan.ps1` | processブロック（行108-179） |

**主要処理フロー**:
1. **112行**: Test-DbaPowerPlanで現在状態を取得
2. **123-130行**: 推奨プランの存在確認
3. **141-145行**: 既にベストプラクティスの場合のスキップ
4. **147-175行**: 電源プラン変更処理
5. **148-154行**: PowerSetActiveScheme呼び出し用ScriptBlock
6. **165行**: Invoke-Command2でリモート実行

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

```
Get-DbaPowerPlan
    |
    +-- Test-ElevationRequirement
    |
    +-- Resolve-DbaNetworkName
    |
    +-- Get-DbaCmObject -ClassName Win32_PowerPlan
    |      +-- Namespace: root\cimv2\power
    |
    +-- [PSCustomObject] 出力
    |
    +-- Select-DefaultView

Test-DbaPowerPlan
    |
    +-- Get-DbaPowerPlan -List
    |      +-- 全電源プラン取得
    |
    +-- 推奨プラン決定
    |      +-- PowerPlanパラメータまたはHigh Performance GUID
    |
    +-- IsBestPractice判定
    |
    +-- [PSCustomObject] 出力
    |
    +-- Select-DefaultView

Set-DbaPowerPlan
    |
    +-- Test-DbaPowerPlan
    |      +-- 現在状態と推奨プランの取得
    |
    +-- [既にベストプラクティスの場合] スキップ
    |
    +-- Resolve-DbaNetworkName
    |
    +-- Invoke-Command2
    |      +-- PowerSetActiveScheme (powrprof.dll)
    |
    +-- [PSCustomObject] 出力
    |
    +-- Select-DefaultView
```

### データフロー図

```
[Get-DbaPowerPlan]

ComputerName ──────────> Resolve-DbaNetworkName ──────────>
                                |
                                v
                        Get-DbaCmObject ──────────────────>
                        (Win32_PowerPlan)
                        (Namespace: root\cimv2\power)
                                |
                                v
List ──────────────────> 分岐処理 ─────────────────────────>
                                |
                        +-------+-------+
                        |               |
                        v               v
                    全プラン        アクティブのみ
                        |               |
                        v               v
                        PSCustomObject ────────────────────> 出力

---

[Test-DbaPowerPlan]

ComputerName ──────────> Get-DbaPowerPlan -List ──────────> 全電源プラン
                                |
                                v
PowerPlan ─────────────> 推奨プラン決定 ──────────────────>
                        (指定 or High Performance)
                                |
                                v
                        InstanceID比較 ───────────────────> IsBestPractice
                                |
                                v
                        PSCustomObject ────────────────────> 出力

---

[Set-DbaPowerPlan]

ComputerName ──────────> Test-DbaPowerPlan ───────────────> 現在状態
                                |
                                v
                        [IsBestPractice?] ────────────────>
                                |
                        +-------+-------+
                        |               |
                        v               v
                    True            False
                   (スキップ)        (変更)
                        |               |
                        |               v
                        |       Invoke-Command2 ──────────>
                        |       (PowerSetActiveScheme)
                        |               |
                        v               v
                        PSCustomObject ────────────────────> 出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaPowerPlan.ps1 | `public/Get-DbaPowerPlan.ps1` | ソース | 電源プラン取得 |
| Test-DbaPowerPlan.ps1 | `public/Test-DbaPowerPlan.ps1` | ソース | 電源プランテスト |
| Set-DbaPowerPlan.ps1 | `public/Set-DbaPowerPlan.ps1` | ソース | 電源プラン設定 |
| Get-DbaCmObject.ps1 | `internal/functions/Get-DbaCmObject.ps1` | 内部関数 | WMI/CIMオブジェクト取得 |
| Resolve-DbaNetworkName.ps1 | `internal/functions/Resolve-DbaNetworkName.ps1` | 内部関数 | ネットワーク名解決 |
| Invoke-Command2.ps1 | `internal/functions/Invoke-Command2.ps1` | 内部関数 | リモートコマンド実行 |
| Test-ElevationRequirement.ps1 | `internal/functions/Test-ElevationRequirement.ps1` | 内部関数 | 管理者権限確認 |
