# 画面設計書 251-AdHoc最適化テスト

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `Test-DbaOptimizeForAdHoc` コマンドに関する画面設計書です。このコマンドは、SQL Serverの「Optimize for Ad-Hoc Workloads」構成設定が推奨値で構成されているかをテストします。

### 本画面の処理概要

**業務上の目的・背景**：SQL Serverでは、アドホッククエリが多く実行される環境において、プランキャッシュの肥大化が発生する可能性があります。「Optimize for Ad-Hoc Workloads」設定を有効にすることで、1回限りのアドホッククエリに対して完全な実行プランではなくコンパイル済みプランスタブのみを格納し、メモリ圧迫を軽減してパフォーマンスを向上させることができます。このコマンドは、DBAがSQL Serverインスタンスの構成を監査し、ベストプラクティスに従っているかを確認するために使用されます。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから `Test-DbaOptimizeForAdHoc` コマンドを実行します。複数のSQL Serverインスタンスをパイプラインで渡すことも可能です。

**主要な操作・処理内容**：
1. 指定されたSQL Serverインスタンスへの接続を確立
2. `sp_configure` から「Optimize for Ad-Hoc Workloads」設定の現在値を取得
3. 現在値と推奨値（1：有効）を比較
4. 比較結果と推奨事項を含むオブジェクトを出力

**画面遷移**：CLIコマンドのため画面遷移はありません。出力結果は他のコマンド（`Set-DbaSpConfigure` など）にパイプラインで渡すことができます。

**権限による表示制御**：SQL Serverインスタンスへの接続権限と `sp_configure` の読み取り権限が必要です。VIEW SERVER STATE権限が推奨されます。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 251 | Test-DbaOptimizeForAdHoc | 主機能 | AdHoc最適化設定のテスト実行 |
| 100 | Get-DbaSpConfigure | 補助機能 | sp_configure設定値の取得に使用 |
| 101 | Set-DbaSpConfigure | 遷移先機能 | 設定変更時に使用可能 |

## 画面種別

診断・テスト出力（CLIコマンド）

## URL/ルーティング

該当なし（PowerShell CLIコマンド）

## 入出力項目

### 入力パラメーター

| パラメーター名 | 型 | 必須 | 説明 |
|---------------|---|-----|------|
| SqlInstance | DbaInstance[] | Yes | 対象SQL Serverインスタンス名（複数指定可、パイプライン入力対応） |
| SqlCredential | PSCredential | No | 代替認証情報（Windows認証、SQL認証、Azure AD対応） |
| EnableException | switch | No | 例外を直接スローするかどうか（デフォルト: false） |

### 出力項目

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| ComputerName | string | SQL Serverインスタンスのコンピューター名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| CurrentOptimizeAdHoc | int | 現在の設定値（0: 無効、1: 有効） |
| RecommendedOptimizeAdHoc | int | 推奨設定値（常に1） |
| Notes | string | 設定に関するガイダンスメッセージ |

## 表示項目

CLIコマンドのため、表示項目は出力オブジェクトのプロパティに依存します。

## イベント仕様

### 1-コマンド実行

コマンド実行時に以下の処理が行われます：

1. 各SQL Serverインスタンスに対して `Connect-DbaInstance` で接続（MinimumVersion 10指定）
2. SMO経由で `$server.Configuration.OptimizeAdhocWorkloads.ConfigValue` を取得
3. 推奨値（1）と比較し、ノートメッセージを設定
4. PSCustomObjectを出力（パイプラインへ即時出力）

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| コマンド実行 | sys.configurations | SELECT | sp_configure設定値の読み取りのみ |

### テーブル別更新項目詳細

このコマンドは読み取り専用であり、データベースの更新は行いません。

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|--------------|------|---------------|
| 情報（Notes） | 設定値が1の場合 | "Configuration is already set as recommended." |
| 情報（Notes） | 設定値が0の場合 | "Recommended configuration is 1 (enabled)." |
| エラー | 接続失敗時 | "Failure" + ConnectionError詳細 |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| 接続エラー | Stop-Functionで処理を中断し、警告メッセージを表示（EnableException無効時） |
| SQL Server 2008未満 | Connect-DbaInstanceのMinimumVersion制約により接続失敗 |
| 権限不足 | sp_configure読み取り時にエラー、警告メッセージを表示 |

## 備考

- SQL Server 2008（バージョン10）以上が必要です
- この機能はSQL Server 2008で導入された「Optimize for Ad-Hoc Workloads」オプションをテストします
- 詳細情報: https://msdn.microsoft.com/en-us/library/cc645587.aspx
- 設定変更には `Set-DbaSpConfigure` コマンドを使用してください

---

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

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

### 推奨読解順序

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

このコマンドはシンプルな構造で、入力パラメーターと出力オブジェクトのみで構成されています。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Test-DbaOptimizeForAdHoc.ps1 | `public/Test-DbaOptimizeForAdHoc.ps1` | 出力PSCustomObjectの構造（行91-98） |

**読解のコツ**: PowerShellのPSCustomObjectは即時出力されるため、戻り値を変数に格納せず直接パイプラインに流れます。

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

処理の起点となるファイル・関数を特定します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaOptimizeForAdHoc.ps1 | `public/Test-DbaOptimizeForAdHoc.ps1` | 関数定義全体（行1-101） |

**主要処理フロー**:
1. **行67-70**: begin ブロックでメッセージ定数と推奨値を初期化
2. **行74-79**: foreach ループでSQL Serverインスタンスに接続
3. **行82**: SMOを使用して現在の設定値を取得
4. **行85-89**: 設定値と推奨値を比較しノートを設定
5. **行91-98**: PSCustomObjectを作成して出力

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | SQL Server接続処理、MinimumVersion制約 |
| 3-2 | Stop-Function.ps1 | `internal/functions/flowcontrol/Stop-Function.ps1` | エラー処理の仕組み |

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

```
Test-DbaOptimizeForAdHoc
    │
    ├─ Connect-DbaInstance
    │      └─ MinimumVersion 10 (SQL 2008+)
    │
    └─ $server.Configuration.OptimizeAdhocWorkloads.ConfigValue
           └─ SMO ServerConfiguration プロパティ
```

### データフロー図

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

SqlInstance ───▶ Connect-DbaInstance ───▶ SMO Server
                           │
                           ▼
                 Configuration.OptimizeAdhocWorkloads
                           │
                           ▼
                      比較処理 ───▶ PSCustomObject
                           │
                           ▼
                      パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Test-DbaOptimizeForAdHoc.ps1 | `public/Test-DbaOptimizeForAdHoc.ps1` | ソース | メイン関数定義 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
| Stop-Function.ps1 | `internal/functions/flowcontrol/Stop-Function.ps1` | ソース | エラーハンドリング |
