# 機能設計書 641-Get-DbaPageFileSetting

## 概要

本ドキュメントは、SQL ServerホストコンピュータからWindowsページファイル設定を取得するdbatools PowerShellコマンド「Get-DbaPageFileSetting」の機能設計書です。

### 本機能の処理概要

Get-DbaPageFileSettingは、SQL ServerホストコンピュータのWindowsページファイル設定をCIM/WMI経由で取得し、パフォーマンス分析やキャパシティプランニングに必要な情報を提供するコマンドです。

**業務上の目的・背景**：SQL Serverのパフォーマンスは、ホストOSのページファイル設定に大きく影響されます。メモリ不足時にSQL Serverがページファイルを使用する際、不適切な設定はパフォーマンス低下の原因となります。本機能により、DBAはSQL Serverインフラストラクチャ全体のページファイル構成を迅速に確認し、ベストプラクティスに沿った設定かどうかを検証できます。

**機能の利用シーン**：
- 新規SQL Server構築時のホスト設定検証
- パフォーマンス問題発生時のトラブルシューティング
- 定期的なインフラストラクチャ健全性チェック
- SQL Serverマイグレーション前後の設定確認
- キャパシティプランニングのためのベースライン収集

**主要な処理内容**：
1. 対象コンピュータへのCIM接続を確立（Get-DbaCmObjectを使用）
2. win32_computersystemクラスからページファイルの自動管理設定を取得
3. 自動管理が無効の場合、win32_pagefile、win32_pagefileUsage、win32_pagefileSettingからページファイル詳細を取得
4. 取得情報を構造化されたPageFileSettingオブジェクトとして出力

**関連システム・外部連携**：
- Windows Management Instrumentation (WMI) / Common Information Model (CIM)
- リモートコンピュータへの管理者権限でのアクセスが必要

**権限による制御**：対象コンピュータに対するローカル管理者権限が必要です。適切な権限がない場合、接続エラーが発生します。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLI専用 | 主機能 | コマンドライン実行のみ |

## 機能種別

データ取得（SELECT相当） / システム情報収集

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | DbaInstance[] | No | 対象コンピュータ名（デフォルト: ローカルコンピュータ） | DbaInstance型として有効であること |
| Credential | PSCredential | No | リモート接続用の資格情報 | 有効なPSCredentialオブジェクト |
| EnableException | switch | No | エラー時に例外をスローするかどうか | - |

### 入力データソース

- パイプライン入力: ValueFromPipeline, ValueFromPipelineByPropertyName でComputerNameを受け入れ
- 直接パラメータ指定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | 対象コンピュータ名 |
| AutoPageFile | bool | ページファイルがWindows自動管理かどうか |
| FileName | string | ページファイルの論理名（自動管理時はnull） |
| Status | string | ページファイルのステータス（通常"OK"、自動管理時はnull） |
| SystemManaged | bool | InitialSizeとMaximumSizeの両方が0かどうか（自動管理時はnull） |
| LastModified | DateTime | ページファイルの最終更新日時（自動管理時はnull） |
| LastAccessed | DateTime | ページファイルの最終アクセス日時（自動管理時はnull） |
| AllocatedBaseSize | int | 現在の割り当てサイズ（MB）（自動管理時はnull） |
| InitialSize | int | 初期サイズ（MB）（自動管理時はnull） |
| MaximumSize | int | 最大サイズ（MB）（自動管理時はnull） |
| PeakUsage | int | システム起動後のピーク使用量（MB）（自動管理時はnull） |
| CurrentUsage | int | 現在の使用量（MB）（自動管理時はnull） |

### 出力先

パイプライン出力（Dataplat.Dbatools.Computer.PageFileSetting型オブジェクト）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証とデフォルト値設定
   └─ ComputerNameが未指定の場合、ローカルコンピュータを使用

2. 各コンピュータに対してループ処理
   └─ foreachでComputerName配列を処理

3. CIM/WMI接続の確立
   └─ Get-DbaCmObjectを使用してwin32_computersystemクエリを実行

4. 自動管理フラグの確認
   ├─ automaticmanagedpagefileがfalseの場合
   │   └─ win32_pagefile, win32_pagefileUsage, win32_pagefileSettingを取得
   └─ automaticmanagedpagefileがtrueの場合
       └─ 詳細情報取得をスキップ

5. PageFileSettingオブジェクトの生成と出力
   ├─ 自動管理でない場合: 全プロパティに値を設定
   └─ 自動管理の場合: AutoPageFileのみtrue、他はnull
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[ComputerName配列をループ]
    B --> C{接続成功?}
    C -->|No| D[Stop-Function でエラー出力]
    D --> B
    C -->|Yes| E[win32_computersystemを取得]
    E --> F{AutoPageFile?}
    F -->|Yes| G[AutoPageFile=true のオブジェクト出力]
    F -->|No| H[win32_pagefile等を取得]
    H --> I[各ページファイルをループ]
    I --> J[PageFileSettingオブジェクト生成]
    J --> K[オブジェクト出力]
    K --> I
    G --> B
    B --> L[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 自動管理判定 | AutoPageFileがtrueの場合、詳細情報はnullとする | 常時 |
| BR-002 | システム管理判定 | InitialSize=0かつMaximumSize=0の場合、SystemManaged=true | AutoPageFile=falseの場合 |
| BR-003 | デフォルト対象 | ComputerName未指定時はローカルコンピュータを対象 | パラメータ未指定時 |

### 計算ロジック

- SystemManaged = (InitialSize -eq 0) -and (MaximumSize -eq 0)
- サイズ関連の値はすべてMB単位

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

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

本機能はデータベースに対する操作を行いません。Windows WMI/CIMへのクエリのみを実行します。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | リモートコンピュータへの接続失敗 | 資格情報とネットワーク接続を確認 |
| - | PermissionError | WMIアクセス権限不足 | 対象コンピュータの管理者権限を取得 |

### リトライ仕様

Get-DbaCmObject内部で複数の接続プロトコル（CIM over WinRM、CIM over DCOM、WMI、PowerShell Remoting）を順次試行

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

該当なし（読み取り専用操作）

## パフォーマンス要件

- 単一コンピュータ: 通常1-3秒
- 複数コンピュータ: 順次処理のため、台数に比例

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

- 対象コンピュータに対するローカル管理者権限が必要
- 資格情報はPSCredentialオブジェクトとして安全に受け渡し
- WMI/CIM接続にはWindows認証が使用される

## 備考

- SQL Server 2022環境でのローカルテストでは結果が返らない場合があるため、CI/CD環境（AppVeyor）でのテストが推奨される
- ページファイルの自動管理が有効な場合、詳細設定は取得できない

---

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

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

### 推奨読解順序

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

PageFileSettingクラスの構造を理解することで、出力データの全体像を把握できます。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | PageFileSetting型定義 | dbatools.libraryで定義 | Dataplat.Dbatools.Computer.PageFileSetting型の構造 |

**読解のコツ**: このクラスはdbatools.libraryで定義されているため、ソースコード内ではNew-Objectで生成されるプロパティから構造を把握します。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaPageFileSetting.ps1 | `public/Get-DbaPageFileSetting.ps1` | メインコマンドの実装 |

**主要処理フロー**:
1. **68-73行目**: パラメータ定義（ComputerName、Credential、EnableException）
2. **74行目**: processブロック開始
3. **75行目**: ComputerNameに対するforeachループ開始
4. **76-80行目**: Get-DbaCmObject用のsplatハッシュテーブル作成
5. **82-91行目**: try-catchでCIM接続とデータ取得
6. **93-130行目**: 自動管理フラグに基づく条件分岐とオブジェクト生成

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaCmObject.ps1 | `public/Get-DbaCmObject.ps1` | WMI/CIMクエリの実行ロジック |

**主要処理フロー**:
- **1-85行目**: ヘルプとパラメータ定義
- WMI/CIM接続の自動フォールバック機構
- 資格情報キャッシュ機能

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

```
Get-DbaPageFileSetting
    │
    ├─ Get-DbaCmObject (win32_computersystem)
    │      └─ CIM/WMI接続の自動フォールバック
    │
    ├─ [条件] AutoPageFile = false の場合
    │      ├─ Get-DbaCmObject (win32_pagefile)
    │      ├─ Get-DbaCmObject (win32_pagefileUsage)
    │      └─ Get-DbaCmObject (win32_pagefileSetting)
    │
    └─ New-Object Dataplat.Dbatools.Computer.PageFileSetting
```

### データフロー図

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

ComputerName ─────────┐
                      │
Credential ───────────┼──▶ Get-DbaCmObject ─────────────▶ PageFileSetting
                      │         │                              オブジェクト
EnableException ──────┘         │
                                ▼
                    ┌─────────────────────────┐
                    │ WMI/CIM クエリ          │
                    │ - win32_computersystem  │
                    │ - win32_pagefile        │
                    │ - win32_pagefileUsage   │
                    │ - win32_pagefileSetting │
                    └─────────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaPageFileSetting.ps1 | `public/Get-DbaPageFileSetting.ps1` | ソース | メインコマンド実装 |
| Get-DbaCmObject.ps1 | `public/Get-DbaCmObject.ps1` | ソース | WMI/CIMクエリ実行の共通関数 |
| Get-DbaPageFileSetting.Tests.ps1 | `tests/Get-DbaPageFileSetting.Tests.ps1` | テスト | ユニットテスト・統合テスト |
